> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过 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。例如：

```bash theme={null}
# 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](https://github.com/MoonshotAI/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 配置对该账号下所有专家共享。

![ACP Runner](https://mintcdn.com/octop/P_aBdthWeK4YndCE/images/ui-acp.png?fit=max\&auto=format\&n=P_aBdthWeK4YndCE\&q=85\&s=f31f43da7480cd4c9dba4538d2b0367d)

**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`。

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

## 排查

> [accordion] 启动 Runner 报 “Unknown runner”
>
> ACP 服务的缓存是进程级的。添加自定义 Runner 后，需要重启 `octop run` 才会生效。

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.