1. 为什么需要 OpenClaw ACP Agents 统一调度

如果你同时用 Claude Code 写业务代码、Codex 做代码审查、Gemini CLI 查文档，大概率经历过这种场景：三个终端窗口来回切，每个 CLI 的 API Key 各配一份，上下文对不上，任务跑到一半忘了在哪个窗口。OpenClaw ACP Agents 要解决的就是这个问题——它把多个编码智能体收进一个统一调度层，用一套配置、一个 Key 入口管理全部 CLI。

ACP 全称 Agent Client Protocol，是 OpenClaw 用于接入外部编程工具的标准协议层。它和 MCP 的分工很明确：MCP 管的是模型与外部工具/数据源的连接，ACP 管的是智能体之间的任务调度。acpx 插件是 ACP 的核心实现，用 TypeScript 编写，支持 Claude Code、Codex、Gemini CLI、Cursor、Kimi、Qwen Code 等 10 多个编码智能体。你可以在一个 OpenClaw 实例里同时挂载它们，通过自然语言或/acp命令切换调用。

这套方案适合谁？三类人：一是手上同时维护多个 AI 编码工具的开发者，想省掉重复配置；二是团队里需要统一管理 API 额度和权限的负责人；三是想把编码智能体接入消息平台（Discord、Telegram、飞书）做远程协作的人。本文从零搭建，交付可复制的settings.json/config.toml骨架，以及用 TaoToken 统一 Key 接入的完整步骤，最后给出验证多 Agent 切换的具体命令。

2. TaoToken 前置：统一 Key 与 acpx 环境准备

2.1 为什么用 TaoToken 做统一入口

acpx 本身不绑定模型供应商，它只负责调度 CLI。但每个 CLI 背后都需要 API Key：Claude Code 要 Anthropic Key，Codex 要 OpenAI Key，Gemini CLI 要 Google Key。三套 Key 意味着三套计费、三套额度监控、三套泄露风险。TaoToken 提供的是统一 API 入口，一个 Key 覆盖多家模型，省掉在三个平台之间切换的麻烦。

TaoToken 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

API 端点（不带 UTM）：https://taotoken.net/api

你需要先在控制台创建一个 API Key，后面配置 acpx 时统一填这个 Key。控制台地址：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

2.2 环境检查清单

动手前确认三件事：

第一，OpenClaw Gateway 已安装并运行。执行openclaw --version，输出应为openclaw/2026.4.1或更高。如果没装，先按官方文档完成基础安装。

第二，Node.js 18+ 环境。node -v确认版本，低于 18 先升级，acpx 依赖较新的运行时特性。

第三，目标 CLI 已安装。本文以 Claude Code、Codex、Gemini CLI 三个为例，你需要确保这三个 CLI 在终端里能独立跑起来。如果某个 CLI 还没装，先装好再继续，acpx 只负责调度，不负责安装底层工具。

2.3 安装 acpx 插件

acpx 有两种使用方式，推荐全局安装：

# 全局安装（推荐） npm install -g acpx@latest # 或者不安装直接用 npx acpx@latest --version

安装完成后，在 OpenClaw 中启用 acpx 插件：

openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true

这两条命令做完，acpx 就挂载到 OpenClaw 上了。接下来配置统一 Key。

3. 可复制配置：settings.json 与 config.toml 骨架

3.1 统一 Key 的环境变量写法

acpx 读取各 CLI 的 Key 时，支持环境变量注入。用 TaoToken 的统一 Key 替换原来的三套 Key，在~/.bashrc或~/.zshrc里加：

# TaoToken 统一 Key export TAOTOKEN_API_KEY="sk-你的TaoToken密钥" # 各 CLI 指向 TaoToken 端点 export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="$TAOTOKEN_API_KEY" export OPENAI_BASE_URL="https://taotoken.net/api" export OPENAI_API_KEY="$TAOTOKEN_API_KEY" export GOOGLE_API_BASE="https://taotoken.net/api" export GOOGLE_API_KEY="$TAOTOKEN_API_KEY"

改完执行source ~/.zshrc生效。这样三个 CLI 都走同一个端点、同一个 Key，计费和额度在 TaoToken 控制台统一看。

3.2 settings.json 骨架

OpenClaw 的智能体级别配置放在settings.json，路径通常是~/.openclaw/settings.json。下面是三个 Agent 的完整骨架：

{ "agents": { "list": [ { "id": "claude", "runtime": { "type": "acp", "acp": { "agent": "claude", "backend": "acpx", "mode": "persistent", "cwd": "/workspace/project", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "${TAOTOKEN_API_KEY}" } } } }, { "id": "codex", "runtime": { "type": "acp", "acp": { "agent": "codex", "backend": "acpx", "mode": "persistent", "cwd": "/workspace/project", "env": { "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "${TAOTOKEN_API_KEY}" } } } }, { "id": "gemini", "runtime": { "type": "acp", "acp": { "agent": "gemini", "backend": "acpx", "mode": "persistent", "cwd": "/workspace/project", "env": { "GOOGLE_API_BASE": "https://taotoken.net/api", "GOOGLE_API_KEY": "${TAOTOKEN_API_KEY}" } } } } ] } }

关键字段说明：mode选persistent表示会话保持，适合多轮协作；选run则是一次性执行，任务完成即结束。cwd是智能体的工作目录，三个 Agent 可以指向同一个项目目录，也可以分开。

3.3 config.toml 骨架

如果你用的是 TOML 格式的配置（部分 OpenClaw 版本默认），等价写法如下：

[acp] enabled = true backend = "acpx" defaultAgent = "codex" maxConcurrentSessions = 8 permissionMode = "approve-reads" [acp.allowedAgents] claude = true codex = true gemini = true [plugins.entries.acpx] enabled = true [plugins.entries.acpx.config] permissionMode = "approve-reads" nonInteractivePermissions = "fail" sessionTtlMinutes = 120 [agents.claude] runtime.type = "acp" runtime.acp.agent = "claude" runtime.acp.backend = "acpx" runtime.acp.mode = "persistent" runtime.acp.cwd = "/workspace/project" [agents.codex] runtime.type = "acp" runtime.acp.agent = "codex" runtime.acp.backend = "acpx" runtime.acp.mode = "persistent" runtime.acp.cwd = "/workspace/project" [agents.gemini] runtime.type = "acp" runtime.acp.agent = "gemini" runtime.acp.backend = "acpx" runtime.acp.mode = "persistent" runtime.acp.cwd = "/workspace/project"

permissionMode建议先用approve-reads，读操作自动批准，写操作需要确认。等跑通后再按需调整。

3.4 权限模式对照

切换命令：

openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

4. 验证请求：多 Agent 切换与调用实测

4.1 健康检查

配置写完后，先跑诊断命令确认 acpx 状态：

/acp doctor

这个命令会检查 acpx 插件是否加载、可用智能体列表、权限配置是否生效。输出里应该能看到 claude、codex、gemini 三个 Agent 都处于 ready 状态。如果某个 Agent 显示 not found，说明对应的 CLI 没装好或者环境变量没生效。

4.2 烟雾测试

用一个最小任务验证链路通不通：

/acp spawn codex --mode run --task "echo 'ACP is working'"

成功的响应里会包含LIVE-acp-spawn-ok标识。如果看到这个，说明 Codex 这条链路已经打通。同样的方式测另外两个：

/acp spawn claude --mode run --task "print hello from claude" /acp spawn gemini --mode run --task "print hello from gemini"

4.3 持久化会话与切换

烟雾测试通过后，创建持久化会话做多轮协作：

# 创建 Codex 持久化会话 /acp spawn codex --mode persistent --thread auto --cwd /workspace/project # 查看当前会话状态 /acp status # 发送引导指令 /acp steer prioritize error handling and add logging # 切换到 Claude Code /acp spawn claude --mode persistent --cwd /workspace/project # 再切回 Codex /acp status

/acp status会列出所有活跃会话，包括 agentId、会话 UUID、当前状态。切换时不需要关闭前一个会话，acpx 支持多会话并发，maxConcurrentSessions默认 8，够用。

4.4 流式进度回传

想让执行日志实时回传，在 spawn 时加streamTo参数：

{ "task": "分析代码库并生成测试报告", "runtime": "acp", "agentId": "codex", "streamTo": "parent", "streamLogPath": "/tmp/codex.log" }

这样你可以在 OpenClaw 对话窗口里实时看到 Codex 的执行日志，同时日志也落盘到/tmp/codex.log，方便事后排查。

4.5 核心命令速查

5. 本篇常见错排查

5.1 spawn 提示后端未配置

报错信息通常是backend not configured或acpx plugin not found。原因有两个：acpx 插件没装，或者装了但没启用。按顺序执行：

openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true openclaw restart

重启后重新跑/acp doctor确认。

5.2 权限被阻止，任务无法执行

智能体请求写文件或执行 Shell 命令时被拦，说明permissionMode太严。测试阶段临时切到approve-all：

openclaw config set plugins.entries.acpx.config.permissionMode approve-all

生产环境再切回approve-reads。注意nonInteractivePermissions设为fail时，后台任务遇到权限请求会直接报错中止；设为deny则静默跳过需要权限的操作继续执行。

5.3 线程绑定失败

--thread auto在部分平台不支持，比如某些 Telegram 群组没有话题功能。改用--thread off：

/acp spawn codex --mode persistent --thread off --cwd /workspace/project

绑定配置里的match字段要跟实际平台参数对齐，Discord 用channel+peer.id，Telegram 用chatId+topicId。

5.4 会话无法恢复

会话过期了。默认sessionTtlMinutes是 120 分钟，空闲超时后会话自动解除。调大这个值：

openclaw config set plugins.entries.acpx.config.sessionTtlMinutes 480

或者用/acp status确认会话是否还在活跃列表里。

5.5 智能体 CLI 未找到

/acp doctor显示某个 Agent 是 not found，说明底层 CLI 没装或者不在 PATH 里。分别验证：

which claude which codex which gemini

哪个没输出就装哪个。装完后重启 OpenClaw Gateway，让 acpx 重新扫描。

5.6 Key 不生效导致 401

如果 CLI 能跑但请求返回 401，检查环境变量是否真的注入了。在 spawn 的env字段里显式写死 Key 做测试：

"env": { "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的实际Key" }

如果这样能通，说明是 shell 环境变量没source或者 OpenClaw 进程没继承。用openclaw restart重启网关进程。

6. 长期编码与 Agent 协作的接入建议

跑通三个 Agent 的切换之后，下一步是把这套配置固化下来。如果你打算长期用 acpx 做多 CLI 协同，建议关注 Coding Plan 的额度管理，统一 Key 的好处在这里体现得最明显——一个控制台看所有 Agent 的消耗，不用在三个平台之间对账。Coding Plan 入口：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各 CLI 的端点配置细节和常见问题。API Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，可以创建多个 Key 做项目隔离。

如果你更习惯在对话界面里直接验证模型效果，模型对话入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，不用配 CLI 就能测。

最后提醒一个实操细节：acpx 的cwd字段建议每个 Agent 指向独立目录，避免多个 Agent 同时写同一个文件造成冲突。如果确实需要协作同一个项目，用/acp steer做任务分派，让 Claude Code 负责编码、Codex 负责审查、Gemini CLI 负责查文档，各干各的，最后汇总。这套流程跑顺之后，你会发现多 CLI 协同的效率提升不在单个工具的能力上，而在调度层省掉的那些切换成本。