通过 ACP 把编码任务委托给 CLI 工具

让 Octop 专家借助 Agent Client Protocol（ACP），把编码任务委托给外部 AI 编程 CLI。

Octop 可以通过内置的 acp_runner 工具，把编码子任务委托给外部 AI 编程 CLI——OpenCode、Claude Code、CodeBuddy、Codex、Kimi Code、Cursor CLI、Pi，或你自定义的工具。流程是：在运行 Octop 的机器上安装好 CLI，在 ACP 页面启用它，为专家开启 acp_runner 工具，然后在对话中请专家调用它来完成任务。通信走 stdio JSON-RPC，Octop 不提供 HTTP 形式的 ACP 端点。

​

配置步骤

1. 安装 CLI 工具

   在运行 octop run 的同一台机器上，安装你要用的 Runner 对应的 CLI。例如：

   # OpenCode
   npm install -g opencode
   
   # Claude Code（通过 npx，无需安装）
   npx -y @zed-industries/claude-agent-acp
   
   # Codex（通过 npx，无需安装）
   npx -y @zed-industries/codex-acp
   
   # Pi ACP 适配器（通过 npx，无需安装）
   npx -y pi-acp
   

   安装 Kimi Code 后可使用 kimi 命令。安装 Cursor CLI 后可使用 agent 命令。

2. 在 CLI 里配好模型

   每个 CLI 工具都跑在自己的模型和凭据上，与 Octop 相互独立。启用之前，先在 CLI 内部配好模型和鉴权——例如运行 opencode auth login 并选好模型，或完成 claude / codex 的登录。如果 CLI 没有可用的模型，Runner 虽然能启动，但不会返回有用的结果。

3. 打开 ACP 页面

   在侧边栏打开 ACP。该页面仅管理员可见。

4. 启用需要的 Runner

   打开需要使用的 Runner 卡片开关。Runner 配置对该账号下所有专家共享。

   
5. 为专家启用 acp_runner 工具

   在顶部切换到目标专家，然后打开同一页面底部的启用 ACP Runner 工具。与 Runner 配置不同，这个开关按专家单独生效。

6. 在对话中委托任务

   在聊天中让专家使用 acp_runner，例如「用 acp_runner 调 opencode 找到 README 并总结一下」。专家会自行管理会话生命周期，权限确认会内联显示在对话中。

​

内置 Runner

Runner ID	命令	参数
opencode	opencode	acp
codebuddy	codebuddy	--acp
claude_code	npx	-y、@zed-industries/claude-agent-acp
codex	npx	-y、@zed-industries/codex-acp
kimi_code	kimi	acp
cursor_cli	agent	acp
pi	npx	-y、pi-acp

内置 Runner 无法删除。点击 ACP 页面的添加 Runner 可以添加自定义 Runner。

​

acp_runner 工具的动作

当专家使用 acp_runner 时，会通过这些动作驱动外部工具：

动作	说明
action=list	列出已启用的 Runner 和当前会话状态
action=start	新建会话：指定 runner + message（可选 cwd）
action=message	在已有会话中继续追加消息
action=respond	用确切的选项 id 回应 [permission_required] 提示
action=status	查询会话是打开还是在等待权限确认
action=close	结束会话

外部工具的权限确认会内联显示在对话中。你可以自己选一个选项，也可以让专家用选项 id 调 action=respond。

如果 octop run 启动环境的 PATH 中找不到 Runner 可执行文件（以系统服务方式运行时很常见），请在 Runner 的命令字段填写绝对路径，例如用 /usr/local/bin/opencode 代替 opencode。

​

排查

启动 Runner 报 “Unknown runner”

ACP 服务的缓存是进程级的。添加自定义 Runner 后，需要重启 octop run 才会生效。

外部 Runner 没有返回任何文本

该 CLI 很可能没有配置可用的模型，或存在鉴权、配额问题。请先在 CLI 内部配好模型，并检查它自身的登录状态，例如运行 codebuddy auth status，或确认相关服务的 API 密钥有效。

Kimi Code、Cursor CLI 或 Pi 无法启动

先在 Octop 主机上直接运行对应内置命令。Kimi Code 需要 kimi 及其登录流程；Cursor CLI 需要运行 agent login 或设置 CURSOR_API_KEY；Pi 需要 Node.js，首次执行 npx -y pi-acp 时还需要联网下载适配器。