CLI 参考 · 引擎与运行

引擎

当前支持三类引擎：

引擎	说明
Claude Code	复用你本机 Claude Code 的完整能力：技能、命令、MCP、登录态等
Codex	通过 codex app-server 驱动，支持流式输出、工具调用、逐次权限确认与会话续接
ACP	一类引擎：任何实现 Agent Client Protocol 的智能体（opencode、hermes、Gemini CLI、Copilot CLI、Cursor…）都能驱动，启动命令由你在新建智能体时填写

平台只做上面这三类引擎，CLI 也只探测这三类（按引擎注册表驱动）——不会探测尚未接通的引擎。想用其他智能体（Cursor、Gemini CLI、OpenCode…），走 ACP 一类引擎填启动命令即可，不需要平台逐个单独适配。

「平台能驱动哪些引擎」由 CLI 自己的引擎注册表决定，并在主机上线时上报给平台——所以升级 CLI 后新增的引擎支持会自动生效，不必等平台改版。

• 新建智能体时选择引擎，智能体将使用该主机上对应引擎的能力运行
• 你本机引擎的配置会被智能体复用：Claude Code 读 ~/.claude（技能、命令、MCP、登录态），Codex 读 ~/.codex
• CLI 会检测本机是否安装了所选引擎（如 claude / codex 是否在 PATH 中）；未安装时提示确认
• ACP 例外：平台无从探测背后的智能体，故 ACP 在每台主机上都可选，由你在新建智能体时填写启动命令（见下）

ACP（通用引擎接入）

ACP（Agent Client Protocol）是一类引擎，不是一个具体引擎。 它是编辑器与编码智能体之间的开放标准协议，很多智能体都实现了它；平台对接 ACP 后，这些智能体都能被驱动，不必为每个单独适配。

因为「背后是哪个智能体」由你决定，平台无法事先探测，所以：

• 新建智能体时，ACP 在每台主机上都可选（判断权交给你）
• 选择 ACP 后必须填写 Agent ACP 启动命令，平台用它在会话工作目录里启动引擎进程
• ACP 智能体不会出现在「已探测执行引擎」列表里（本机探测不到具体是哪个智能体）

常见 Agent 的 ACP 启动命令（务必以各 Agent 官方文档为准）：

Agent	启动命令
OpenCode	opencode acp
hermes	hermes acp（或 hermes-acp）
Gemini CLI	gemini --acp
GitHub Copilot CLI	copilot --acp --stdio
Cursor	agent acp
Devin	devin acp
Trae	traecli acp serve
Claude Code（社区适配器）	npx @zed-industries/claude-code-acp

前提：该命令已安装在主机上、能直接在终端运行，且首次运行所需的登录与配置已完成。

限制

• ACP 暂不支持在线切换模型（各智能体的模型配置各不相同）——「自定义模型」只作用于 Claude Code 与 Codex
• ACP 不读取本机历史会话（各家落盘格式不同）
• 权限确认走 ACP 的标准审批请求；具体何时询问由该智能体自身的策略决定（见下方权限确认）

智能体如何运行

一次会话的完整链路：

你在网页对话
  → 平台定位智能体绑定的主机与工作目录
  → 下发运行任务到该主机上的 CLI
  → CLI 在会话工作目录里启动引擎执行
  → 引擎的思考/增量/工具调用/权限请求逐帧回传
  → 网页实时流式展示
  → 运行完成后统计 Token 与模型并持久化

你的网页只是前端，真正干活的是你机器上由 CLI 拉起的引擎进程。

工作目录

• 会话运行在「主机根目录（-dir）+ 智能体选择的相对子目录 + .raagent/workdir-<会话ID>」下，每个会话独立，互不干扰
• 会话中的文件面板、工具读写都发生在这个目录
• 删除会话时，对应工作目录会被回收

权限确认

引擎需要调用工具或修改文件时，会发出权限请求：

• 网页端会弹出确认卡片，由使用者同意或拒绝
• 拒绝后引擎不会执行该操作

不同引擎的权限模型不同，确认的粒度会有差异：

• Claude Code 按工具能力逐个询问（执行命令、写文件、改文件各自成一次请求）
• Codex 按「沙箱范围 × 何时询问」两个维度控制。以默认档为例，工作区内的只读操作会自动放行，越界操作与文件改动会弹确认；选择「自动」档则不再询问
• ACP 由该智能体自己决定何时发起审批（不同 Agent 策略不同）；平台把审批请求统一渲染成确认卡片，同意 / 拒绝都会如实回传给智能体

无论哪种引擎，拒绝后该次操作都不会执行，引擎会带着这个结果继续对话。

并发

一台主机默认最多同时运行 10 个任务，达到上限后新任务会排队等待。可用 -concur <N> 或环境变量 RAAGENT_MAX_CONCUR 调整（命令行优先；daemon install -concur 会持久化）。详见安装与连接 - 最大并发控制。

引擎异常

• 引擎未安装：CLI 会提示确认引擎已安装并在 PATH 中
• 引擎进程异常退出：该次运行记为失败，并回传错误信息

常见排查

主机在线但智能体不可用 确认该智能体绑定的主机就是当前这台、引擎已安装，且智能体处于启用状态。

对话一直「运行中」 查看主机并发是否已满；确认 CLI 进程存活、引擎能正常启动。