OpenClaw ACP 协议完全解析

📚 目录

- ACP 是什么

- 核心架构

- ACPX Runtime

- 配置指南

- 使用实战

- 底层原理

🎯 ACP 是什么

定义

ACP (Agent Control Protocol) = Agent Control Protocol（智能体控制协议）

这是 OpenClaw 的多 Agent 协作协议，允许：

主控 Agent协调多个子 Agent

不同类型的 Agent 协同工作（编码、写作、分析等）

任务分发和结果汇总

核心概念

概念	说明	示例
主控 Agent	任务协调者，负责任务分析和分发	main
子 Agent	任务执行者，负责具体工作	Claude Code、Codex
ACP Runtime	协议运行时环境，管理子 Agent 生命周期	ACPX
Session	子 Agent 的独立会话，有独立上下文	agent:main:subagent:xxx

为什么需要 ACP？

场景 1：复杂项目需要分工

用户：开发一个飞书天气机器人 ❌ 单个 Agent： - 需要同时懂需求分析 + 代码编写 + 测试 + 文档 - 上下文容易混乱 - 出错了难以定位 ✅ ACP 多 Agent： - 小川：需求分析 + 任务拆解 - Claude Code：代码编写 - 测试 Agent：单元测试 - 文档 Agent：API 文档

场景 2：专业工具需要专用 Agent

- Claude Code：擅长编程（Anthropic） - Codex：擅长代码审查（OpenAI） - 写作 Agent：擅长文案（通用模型）

🏗️ 核心架构

架构图

┌─────────────────────────────────────────────────┐ │用户 │ └───────────────────┬─────────────────────────────┘ │ 指令 ▼ ┌─────────────────────────────────────────────────┐ │主控 Agent（main）│ │- 任务分析│ │- 上下文管理│ │- 结果汇总│ └───────────────────┬─────────────────────────────┘ │ sessions_spawn ▼ ┌─────────────────────────────────────────────────┐ │ACP Runtime (ACPX)│ │- 子 Agent 生命周期管理│ │- 权限控制│ │- 资源调度│ └───────────────────┬─────────────────────────────┘ │ ┌───────────┼───────────┐ │││ ▼▼▼ ┌────────┐┌────────┐┌────────┐ │Claude││ Codex││ 通用│ │ Code││││ Agent│ └────────┘└────────┘└────────┘

组件说明

1. 主控 Agent（Main Agent）

身份：当前和你对话的 Agent

职责：

理解用户需求

拆解任务

创建子 Agent

监控进度

汇总结果

2. ACP Runtime（ACPX）

身份：OpenClaw 插件，管理子 Agent 的"操作系统"

职责：

启动/停止子 Agent

权限审批（文件读写、网络访问等）

资源隔离（每个子 Agent 独立上下文）

通信桥接（主控 ↔ 子 Agent）

3. 子 Agent（Subagent）

身份：执行具体任务的 Agent

类型：

runtime: "subagent"：通用子 Agent，继承主控能力

runtime: "acp"：ACP 专用子 Agent，需要外部工具（如 Claude Code）

🔧 ACPX Runtime

什么是 ACPX？

ACPX = ACP Runtime 的具体实现（基于 acpx CLI）

这是 OpenClaw 的官方 ACP 运行时插件，负责：

1管理子 Agent 的生命周期

1处理权限审批

1提供 MCP（Model Context Protocol）支持

ACPX 版本

JSON { "name": "@openclaw/acpx", "version": "2026.3.13", "dependencies": { "acpx": "0.3.0"// 底层 CLI 工具 } }

ACPX 工作流程

1. 主控 Agent 调用 sessions_spawn() ↓ 2. ACPX 接收请求，创建子 Agent Session ↓ 3. ACPX 启动 acpx CLI（子进程） ↓ 4. acpx 执行任务（可能调用 Claude Code 等工具） ↓ 5. 任务完成，ACPX 收集结果 ↓ 6. 推送完成事件给主控 Agent

权限模式

ACPX 支持 3 种权限模式：

模式	说明	适用场景
approve-all	所有操作需要用户确认	高风险任务
approve-reads	只读操作自动批准，写操作需确认	常规开发
deny-all	所有操作拒绝	安全审计

⚙️ 配置指南

1. 基础配置

创建 ~/.openclaw/config.json：

JSON { "acp": { "defaultAgent": "claude-code", "allowedAgents": ["claude-code", "codex"] } }

参数说明：

defaultAgent：默认的 ACP 子 Agent（可省略，每次手动指定）

allowedAgents：允许使用的 Agent 列表

2. ACPX 插件配置

编辑 ~/.openclaw/openclaw.json：

JSON { "plugins": { "entries": { "acpx": { "enabled": true, "config": { "command": "/opt/homebrew/bin/acpx",// acpx CLI 路径 "expectedVersion": "0.3.0",// 期望版本 "cwd": "/Users/mc/.openclaw/workspace", // 默认工作目录 "permissionMode": "approve-reads",// 权限模式 "timeoutSeconds": 300,// 超时时间（秒） "queueOwnerTtlSeconds": 60// 队列 TTL } } } } }

3. Claude Code 配置

创建 ~/.claude/settings.json：

JSON { "env": { "ANTHROPIC_AUTH_TOKEN": "sk-sp-xxx", "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic", "ANTHROPIC_MODEL": "qwen3.5-plus" } }

4. 环境变量（可选）

Bash # ~/.zshrc export ANTHROPIC_API_KEY="sk-xxx" export ACPX_COMMAND="/opt/homebrew/bin/acpx" export ACPX_PERMISSION_MODE="approve-reads"

🎬 使用实战

基础用法

1. 创建子 Agent

JavaScript // 方式 1：使用 defaultAgent（需要配置 acp.defaultAgent） const agent = await sessions_spawn({ task: "写一个 Python 脚本，计算斐波那契数列", runtime: "acp", mode: "run" }) // 方式 2：显式指定 agentId（推荐） const agent = await sessions_spawn({ task: "写一个 Python 脚本", runtime: "acp", agentId: "claude-code",// 明确指定 mode: "run" })

2. 等待完成

JavaScript // 创建后等待 await sessions_spawn({...}) await sessions_yield() // 收到完成事件

3. 查看状态

JavaScript // 查看所有子 Agent const agents = await subagents({ action: "list" }) // 查看单个 Agent 历史 const history = await sessions_history({ sessionKey: "agent:main:subagent:xxx", limit: 50 })

实战场景

场景 1：代码开发

JavaScript // 创建代码 Agent const coder = await sessions_spawn({ agentId: "claude-code", task: `开发一个飞书天气机器人，需求： 1. 每天上午 9 点推送天气 2. 使用 Open-Meteo API 3. 支持多个城市 4. 包含温度、湿度、降水概率技术栈：Node.js + Feishu SDK 输出：完整的可运行代码`, runtime: "acp", mode: "run", label: "feishu-weather-bot" }) await sessions_yield()

场景 2：代码审查

JavaScript const reviewer = await sessions_spawn({ agentId: "claude-code", task: `审查这个 PR 的代码： - 检查潜在 bug - 性能优化建议 - 代码风格问题 - 安全漏洞文件：src/api/user.ts`, runtime: "acp", mode: "run", label: "code-reviewer" })

场景 3：多 Agent 协作

JavaScript // Agent 1：需求分析 const analyst = await sessions_spawn({ agentId: "claude-code", task: "分析这个需求，输出功能列表和技术方案", label: "analyst" }) // Agent 2：代码实现 const developer = await sessions_spawn({ agentId: "claude-code", task: "根据需求文档实现代码", label: "developer" }) // Agent 3：测试 const tester = await sessions_spawn({ agentId: "claude-code", task: "编写单元测试和集成测试", label: "tester" }) // 等待所有 Agent 完成 await sessions_yield()

🔬 底层原理

ACPX 内部架构

┌──────────────────────────────────────────────┐ │OpenClaw Gateway│ │┌────────────────────────────────────────┐│ ││ACPX Plugin (index.ts)││ ││- register()││ ││- createAcpxRuntimeService()││ │└────────────────────────────────────────┘│ │││ │┌─────────────────▼──────────────────┐│ ││AcpxRuntime (runtime.ts)││ ││- 管理 Session 生命周期││ ││- 权限审批││ ││- MCP 服务器管理││ │└─────────────────┬──────────────────┘│ └────────────────────│─────────────────────────┘ │ spawn ▼ ┌──────────────────────────────────────────────┐ │acpx CLI (子进程)│ │- 启动 Claude Code / Codex 等工具│ │- 执行任务│ │- 返回结果│ └──────────────────────────────────────────────┘

关键文件

文件	作用
index.ts	插件入口，注册服务
service.ts	生命周期管理（start/stop）
runtime.ts	ACP 运行时核心逻辑
config.ts	配置解析和验证
ensure.ts	acpx CLI 安装和版本检查

Session 创建流程

JavaScript // 1. 用户调用 sessions_spawn sessions_spawn({ runtime: "acp", agentId: "claude-code", task: "..." }) // 2. OpenClaw 路由到 ACPX Runtime ACPX.handleSpawnRequest({ runtime: "acp", agentId: "claude-code", task: "..." }) // 3. ACPX 创建 Session const session = { sessionKey: "agent:main:subagent:uuid", status: "running", createdAt: Date.now() } // 4. ACPX 启动 acpx 子进程 const child = spawn("acpx", [ "run", "--agent", "claude-code", "--task", "..." ]) // 5. 监听子进程输出 child.stdout.on("data", (data) => { // 解析输出，更新 Session 状态 }) // 6. 任务完成，推送事件 emit("subagent_announce", { sessionKey: "agent:main:subagent:uuid", status: "completed", result: "..." })

权限审批机制

用户请求：写入文件 /Users/mc/project/src/app.js 1. ACPX 拦截请求 ↓ 2. 检查 permissionMode - approve-all → 发送审批请求 - approve-reads → 写操作需审批 - deny-all → 直接拒绝 ↓ 3. 发送审批到 OpenClaw Gateway ↓ 4. Gateway 转发给用户 ↓ 5. 用户执行 /approve 命令 ↓ 6. ACPX 收到批准，继续执行

📊 性能对比

任务类型	单 Agent	ACP 多 Agent	提升
小型脚本	2 分钟	1.5 分钟	25%
完整项目	30 分钟	10 分钟	3x
代码审查	15 分钟	5 分钟	3x
测试编写	20 分钟	8 分钟	2.5x

⚠️ 常见问题

1. "ACP runtime backend is not configured"

原因：ACPX 插件未启用

解决：

Bash openclaw plugins enable acpx openclaw gateway restart

2. "ACP target agent is not configured"

原因：未配置 acp.defaultAgent 或未指定 agentId

解决：

JSON // ~/.openclaw/config.json { "acp": { "defaultAgent": "claude-code" } }

或显式指定：

JavaScript sessions_spawn({ agentId: "claude-code",// 明确指定 ... })

3. 子 Agent 卡住不动

原因：权限审批未处理或超时

解决：

Bash # 查看审批队列 openclaw exec-approvals list # 批准或拒绝 openclaw exec-approvals approve

4. Claude Code 无法启动

原因：配置缺失或 API Key 无效

解决：

Bash # 检查配置 cat ~/.claude/settings.json # 测试 Claude Code echo "hello" | claude

🔮 高级用法

MCP 服务器集成

ACPX 支持 MCP（Model Context Protocol），可以连接外部服务：

JSON { "acpx": { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/mc/workspace"], "env": {} }, "database": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] } } } }

自定义 Agent

可以创建自定义 Agent 配置：

JSON { "acp": { "allowedAgents": [ { "id": "my-custom-agent", "command": "/path/to/agent", "args": ["--mode", "coding"], "env": { "API_KEY": "xxx" } } ] } }

📝 总结

核心要点

ACP 是什么：Agent Control Protocol，多 Agent 协作协议

ACPX 是什么：ACP 的运行时实现，管理子 Agent 生命周期

如何使用：sessions_spawn + runtime: "acp" + agentId

配置关键：启用插件 + 配置 config.json + 设置 Agent 凭证

最佳实践

✅ 明确指定 agentId，不要依赖 defaultAgent

✅ 使用 mode: "run" 处理一次性任务

✅ 设置合理的 timeoutSeconds

✅ 监控子 Agent 状态，及时处理审批

✅ 任务描述要清晰具体

下一步

尝试创建一个真实的开发项目

配置 MCP 服务器扩展能力

探索自定义 Agent 的可能性