• 简体中文

      • 通过 ACP 把编码任务委托给 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 端点。

      配置步骤

      安装 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 命令。

      在 CLI 里配好模型

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

      打开 ACP 页面

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

      启用需要的 Runner

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

      ACP Runner

      ACP Runner

      为专家启用 acp_runner 工具

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

      在对话中委托任务

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

      内置 Runner

      Runner ID命令参数
      opencodeopencodeacp
      codebuddycodebuddy--acp
      claude_codenpx-y、@zed-industries/claude-agent-acp
      codexnpx-y、@zed-industries/codex-acp
      kimi_codekimiacp
      cursor_cliagentacp
      pinpx-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 时还需要联网下载适配器。