OpenClaw ACP 协议:让 AI 编程助手真正协同工作的秘密

你有没有遇到过这种情况：在 Discord 或 Telegram 里跟 Claude Code 聊得正起劲，换个设备就丢了上下文？或者让 Codex 跑任务，回头找不到输出在哪？

ACP 就是解决这个问题的。它让 OpenClaw 能像管理普通聊天会话一样，管理 Claude Code、Codex、Gemini CLI 这些编程助手的会话——跨设备、持久化、可追溯。

一句话总结

ACP 是 OpenClaw 与外部编程助手之间的通信协议。有了它，你可以：

1. 在任意聊天渠道（Discord、Telegram、WhatsApp 等）调用编程助手
2. 把助手绑定到特定线程，后续消息自动路由
3. 跨设备恢复会话，不丢上下文
4. 统一管理多个助手的权限、模型、超时等配置

为什么需要 ACP

在 ACP 之前，用 Claude Code 或 Codex 大概是这样：

• 打开终端，运行命令
• 在那个终端窗口里交互
• 关掉窗口，会话就没了
• 换台电脑，从头开始

问题在于：编程助手被绑在终端里。你想在手机上查看进度？不行。你想让团队成员接着你的会话继续？不行。你想把某个任务的会话归档下来以后复盘？自己想办法。

ACP 把这个限制打破了。编程助手不再属于某个终端，而是属于 OpenClaw Gateway——一个你可以在任何地方访问的控制平面。

ACP 怎么工作

核心概念

用户消息 → OpenClaw Gateway → ACP Backend (acpx) → 编程助手 (Claude Code/Codex/...)                                          ↓                            会话状态持久化，跨设备可恢复

几个角色：

• Gateway：OpenClaw 的控制中心，负责路由消息、管理会话
• ACP Backend：具体实现协议的插件，官方提供 acpx
• Harness Agent：被调用的编程助手，如 Claude Code、Codex、Gemini CLI

启动一个 ACP 会话

最简单的方式是在聊天里发命令：

/acp spawn codex --mode persistent --thread auto

这条命令会：

1. 启动一个 Codex 会话
2. 设置为持久模式（不会自动结束）
3. 绑定到当前线程（如果支持）

之后你在那个线程发的所有消息，都会被路由到这个 Codex 会话。

线程绑定：最强特性

线程绑定是 ACP 最实用的功能。想象一下：

1. 你在 Discord 创建了一个线程叫"重构用户模块"
2. 在线程里执行 /acp spawn codex --thread auto
3. 之后的讨论、任务、输出都在这个线程里
4. 团队成员随时加入查看进度
5. 你下班回家，用手机打开同一个线程继续

这不是幻想，现在就能做到。

与 Claude Code 协作实战

Claude Code 是 Anthropic 官方的 AI 编程助手。通过 ACP，你可以在 OpenClaw 里直接调用它。

前置准备

1. 安装 OpenClaw（略过，假设你已经有了）
2. 启用 ACP 插件：

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

3. 配置允许的助手列表：

{  acp: {    enabled: true,    backend: "acpx",    defaultAgent: "claude",    allowedAgents: ["claude", "codex", "gemini"],  },}

场景一：一次性任务

在聊天里直接说：

用 Claude Code 帮我分析一下这个项目的测试覆盖率

OpenClaw 会自动识别意图，启动一个临时的 Claude Code 会话，执行任务，返回结果。

场景二：持久编程会话

如果你要做一个较大的任务：

/acp spawn claude --mode persistent --thread auto --cwd /workspace/my-project

然后你就可以在那个线程里持续跟 Claude Code 交互，就像在终端里一样，但好处是：

• 会话持久化，不怕中断
• 跨设备访问
• 团队可以协作

场景三：恢复之前的会话

假设你昨天用 Codex 做了一半的任务：

/acp sessions

查看最近的会话列表，找到 session key，然后继续。或者通过 sessions_spawn 工具指定 resumeSessionId。

最佳实践

1. 用线程隔离任务

每开始一个新任务，创建新线程并绑定 ACP 会话。这样任务之间不干扰，历史清晰可查，方便交接。

2. 设置合理的超时

编程任务可能很耗时，但也可能卡住。建议：

/acp timeout 600

设置 10 分钟超时，超时会自动结束，避免浪费资源。

3. 权限策略要谨慎

ACP 会话可以执行 shell 命令和修改文件。权限配置有两种思路：

• approve-all：完全信任，适合个人使用
• approve-reads：只允许读操作，写入需要手动确认

在配置文件里设置：

{  plugins: {    entries: {      acpx: {        config: {          permissionMode: "approve-all",        },      },    },  },}

4. 善用 `/acp status` 检查状态

不确定会话跑到哪了？

/acp status

可以看到当前模型、运行状态、已用时间等信息。

5. 用 `/acp steer` 调整方向

助手跑偏了？不用取消重来：

/acp steer 暂停当前任务，先修复那个 lint 错误

steer 命令会在不中断会话的情况下注入新的指令。

ACP vs 原生 Sub-agent

OpenClaw 有两种方式运行外部任务：

特性	ACP 会话	Sub-agent
运行时	外部编程助手	OpenClaw 内置
会话 key	`agent:xxx:acp:uuid`	`agent:xxx:subagent:uuid`
适用场景	复杂编程任务	快速委托任务
沙箱支持	暂不支持	支持
工具生态	取决于助手	OpenClaw 工具集

简单说：编程用 ACP，其他用 Sub-agent。

常见问题

会话启动失败

检查几个地方：

1. /acp doctor 查看后端健康状态
2. 确认 agentId 在 allowedAgents 列表里
3. 检查 cwd 路径是否存在

权限问题导致崩溃

如果看到 AcpRuntimeError: Permission prompt unavailable in non-interactive mode，说明权限策略和操作冲突了。

解决：设置 permissionMode=approve-all，或者把 nonInteractivePermissions 设为 deny（会静默拒绝而不是崩溃）。

会话找不到了

用 /acp sessions 列出最近会话。如果还是找不到，可能已经过期被清理，需要新建。

写在最后

ACP 解决的是一个很实际的问题：编程助手应该像聊天工具一样方便，而不是被绑在终端里。

它不是什么黑魔法，就是一层协议封装——但这一层封装，让编程助手真正融入了日常协作流程。

下次开新项目，试试在 Discord 线程里启动一个绑定的 Codex 会话。你可能会发现，这才是 AI 编程助手该有的样子。