夜雨聆风01 什么是 ACP？
如果你用过 Claude Code、Codex 或 OpenCode 等 AI 编程助手，可能会遇到一个问题：每个助手都有自己的 CLI 工具，如何统一管理？
OpenClaw 的答案是：ACP（Agent Communication Protocol，智能体通信协议）。
简单理解，ACP 就是 OpenClaw 与外部 AI 编程助手之间的"电话线"——它让 OpenClaw 能够统一调用各种编程助手，而你只需要通过 Telegram、飞书或 Slack 发送一条消息即可。
用户请求 OpenClaw 外部 AI 助手
"帮我写代码" → Gateway + ACP → Claude Code/Codex/OpenCode
ACP 能做什么？
✅ AI 编程（代码生成、Bug 修复、重构） ✅ 代码审查（PR review、问题分析） ✅ 项目开发（新功能开发、模块改造） ✅ 迭代编码（多轮对话、持续优化）
ACP 不适合什么？
❌ 简单的一行代码修复（直接用 edit 工具更高效） ❌ 读取代码（直接用 read 工具） ❌ 非编程任务（查股票、搜新闻等有其他专用工具）
02 Harness 架构：给 AI 套上"缰绳"
Harness 是什么？
Harness 原意是"马具"、"挽具"。在 AI 工程中，它指的是：
一套用于控制、引导、利用 AI 能力的框架系统
想象一下：一匹千里马（AI 能力）虽然力量强大，但需要缰绳和马车（Harness）才能拉车耕地、转化为实际生产力。
OpenClaw ACP Harness 架构
┌─────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Telegram │ │ Feishu │ │ Slack │ │
│ │ Channel │ │ Channel │ │ Channel │ │
│ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ ACP Harness │ │
│ │ (编排调度层) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Codex ACP │ │ Claude Code │ │ Pi ACP │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Codex CLI │ │Claude Code │ │ Pi CLI │ │
│ │ (PTY) │ │ (PTY) │ │ (PTY) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
Harness 的 5 大核心职责：
协议转换 — Telegram/飞书消息 → ACP 协议格式 会话管理 — 创建/复用 Session，路由到对应 Agent 流式输出管理 — Agent 输出 → 缓冲/格式化 → 推送给用户 工具调用协调 — Agent 请求工具 → 调用 OpenClaw 工具 → 返回结果 错误处理与重试 — Agent 崩溃自动重启/切换备用 Agent
03 两种运行模式：一次性 vs 持久会话
模式一：一次性运行（mode: "run"）
任务完成后自动销毁会话，适合独立任务。
sessions_spawn({
runtime: "acp",
mode: "run",
agentId: "claude-code",
task: "重构这个模块",
cleanup: "delete"// 完成后清理
})
适用场景：
单次代码生成 PR 审查（临时工作目录） 独立脚本编写
模式二：持久会话（mode: "session"）
保持会话状态，支持多轮对话。
sessions_spawn({
runtime: "acp",
mode: "session",
agentId: "claude-code",
thread: true, // 绑定到 Discord/Telegram 线程
task: "帮我开发一个功能"
})
适用场景：
复杂项目开发（需多轮沟通） 持续重构 需要用户反馈的迭代任务
两种模式对比
04 支持哪些 AI 编程助手？
| Claude Code | npm install -g @anthropic-ai/claude-code | |
| Codex | npm install -g @openai/codex | |
| OpenCode | npm install -g opencode | |
| Pi | ||
| Gemini CLI |
配置方法
在 ~/.openclaw/openclaw.json 中配置允许的 Agent：
{
"acp": {
"allowedAgents": ["claude-code", "codex", "opencode"],
"defaultAgent": "claude-code"
}
}
05 实战案例：用 AI 开发五子棋游戏
光说不练假把式。让我们来看一个完整的实战案例——用 OpenCode 开发一个五子棋 CLI 游戏。
开发需求
执行命令
cd /Users/mengxi/.openclaw/agents/tianqi/workspace
opencode --model "aliyunbailian/qwen3.5-plus" run "
15x15 的五子棋 CLI 游戏用 Python 创建。
保存路径：games/gomoku/gomoku.py
要求：
1. 15x15 标准棋盘
2. 双人对战（黑●先手、白○后手）
3. 五子连珠判定（横·竖·斜）
4. 坐标输入（例：H8, A1, O15）
5. 游戏历史显示
6. 无效着法拒绝
7. 胜利时消息显示
README.md 也请创建（玩法说明、功能列表）。
代码质量：类型提示、文档字符串、错误处理、200 行以上。
"
遇到的坑与解决方案
坑 1：模型找不到
ProviderModelNotFoundError: Model not found: opencode/glm-4.7-free
解决：用 --model 参数直接指定可用模型
坑 2：配置缓存不生效
Error: Model not found: openrouter/minimax/minimax-m2.5-free
解决：config.json 修改后 opencode 有缓存，用 --model 直接指定可绕过
坑 3：API Key 缺失
Error: Google Generative AI API key is missing
解决：使用已注册且配置好 API Key 的 qwen3.5-plus 模型
成果验证
# 行数确认
wc -l games/gomoku/gomoku.py
# 输出：570 行 ✅
# 语法检查
python3 -m py_compile games/gomoku/gomoku.py
# 输出：Syntax check passed ✅
# 函数/类数量
grep -c "def \|class " games/gomoku/gomoku.py
# 输出：22
# 类型提示数量
grep -c '\-> ' games/gomoku/gomoku.py
# 输出：19
# 测试运行
echo -e "H8\nH9\nG8\nJ8\nH7\nq" | python3 gomoku.py
# 输出：游戏画面显示、正常运行 ✅
代码质量指标
06 注意事项：安全与性能
安全事项
1. 工作空间隔离
ACP 会话在独立目录中运行 避免在 ~/clawd工作区中 spawn agent敏感项目用 cwd参数明确指定路径
2. 权限控制
ACP agent 以当前用户权限运行 避免执行破坏性命令（rm、格式化等） 重要操作前备份代码
3. Token 消耗
外部 AI 助手按 Token 计费 复杂任务可能消耗大量 Token 建议先用 mode: "run"测试
性能优化
1. 并发控制
maxConcurrentSessions限制并发数避免同时 spawn 过多会话
2. 会话清理
一次性任务设置 cleanup: "delete"定期清理临时工作目录
3. 超时设置
长任务设置 runTimeoutSeconds避免会话无限期挂起
07 常见问题排查
问题速查表
agentId not found | ||
CLI not found | npm install -g <agent> | |
Permission denied | ||
Timeout | runTimeoutSeconds | |
Session failed |
诊断命令
# 检查 ACP 配置
cat ~/.openclaw/openclaw.json | grep -A 20 '"acp"'
# 检查 agent 是否安装
which claude-code
which codex
which opencode
# 检查 ACP 后端状态
openclaw status
# 查看会话日志
cat ~/.openclaw/logs/acp-*.log
08 ACP vs Subagent：有什么区别？
| 执行者 | ||
| 适用场景 | ||
| 配置要求 | ||
| 工作空间 | ||
| 多轮对话 | ||
| 编程能力 |
简单总结：
写代码、改 Bug、做项目 → 用 ACP 查资料、整数据、写文档 → 用 Subagent
09 最佳实践：如何高效使用 ACP？
模型选择建议
| qwen3.5-plus | ||
| claude-sonnet-4-6 | ||
| gemini-3.1-pro-preview |
任务描述怎么写？
✅ 推荐写法：
15x15 的五子棋 CLI 游戏用 Python 创建。
保存路径：games/gomoku/gomoku.py
要求：
1. 15x15 标准棋盘
2. 双人对战（黑●先手、白○后手）
3. 五子连珠判定（横·竖·斜）
4. 坐标输入（例：H8, A1, O15）
5. 游戏历史显示
6. 无效着法拒绝
7. 胜利时消息显示
代码质量：类型提示、文档字符串、错误处理、200 行以上。
❌ 不推荐写法：
五子棋给我做一个
后台运行与日志查看
# 后台运行
opencode --model "xxx" run "<任务>" 2>&1 &
# 日志查看
process poll --sessionId <会话 ID> --timeout 120000
10 总结
ACP 是 OpenClaw 与外部 AI 编程助手集成的核心协议层，通过 Harness 架构实现了协议转换、会话管理、流式输出、工具协调及错误处理等核心功能。
关键要点：
两种模式：run（一次性）适合简单任务，session（持久）适合复杂项目 多个助手：支持 Claude Code、Codex、OpenCode 等主流编程助手 安全第一：工作空间隔离、权限控制、Token 消耗管理 高效实践：选好模型、写好任务描述、合理设置超时
最后送大家一句话：
Harness 之本质 = 缰绳 + 马车
有马（AI 能力）无 Harness，则力量难以引导； 有 Harness 无马，则空有框架无执行力。
OpenClaw ACP Harness，正是将 Codex、Claude Code 等外部 Agent 之力， 通过协议适配、会话路由、流式输出，转化为实际生产力。
参考资料：
OpenClaw 官方文档： ~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/docs/ACP 路由器技能： acp-router/SKILL.md编码助手技能： coding-agent/SKILL.md
觉得有用？欢迎点赞、在看、转发三连！ 🙏
#AI #开源 #编程助手 #ClaudeCode #Codex #OpenCode #ACP #自动化开发 #技术架构
