OpenClaw ACP 协议详解:让 AI 智能体之间真正“对话”

前言

你有没有想过，在 Telegram 上发一条消息，后台自动触发 Codex 帮你写代码、改 bug，完成后把结果发回来？

这不是幻想。OpenClaw 用 ACP（Agent Client Protocol）把这条链路打通了：Telegram → OpenClaw → ACP → acpx → Codex。

一、ACP 是什么？

核心定位

ACP（Agent Client Protocol，智能体客户端协议）是一套专门用于 AI 智能体之间结构化通信的协议。

在没有 ACP 之前，想让一个程序控制 Codex 或 Claude Code 这类编程智能体，基本只能靠 PTY 抓屏——像人盯着终端一样逐字符捕获输出，极其脆弱，UI 一变就全崩。

ACP 用标准化的结构化消息协议替代了这种"偷窥屏幕"的方式。

OpenClaw 里的 ACP 有两个方向

理解 ACP 的关键是：它在 OpenClaw 里同时承担两个相反方向的通信：

方向一：出向（主路径）— OpenClaw → 编码智能体

OpenClaw Gateway 内置了 @openclaw/acpx 扩展，作为 ACP 客户端，通过 ACP 协议向外驱动 Codex、Claude Code 等编码智能体执行任务。这是 Telegram 消息到 Codex 的完整链路所走的路径。

方向二：入向（辅助路径）— IDE → OpenClaw

openclaw acp 命令让 OpenClaw 作为 ACP 服务器，供 Zed 等 IDE 接入，将编辑器的请求转发到 Gateway 会话。

数据流向总览

二、怎么用？

主路径：Telegram + ACP Binding + Codex

这是 OpenClaw ACP 最核心的使用方式。在 OpenClaw 配置文件中，用 ACP Binding 将一个 Telegram 对话绑定到一个 Codex 会话：

{  "acp": {    "bindings": [      {        "channel": "telegram",        "accountId": "work",        "conversationId": "-1001234567890:topic:42",        "agentId": "codex",        "mode": "persistent"      }    ]  }}

配置好后，每条发送到该 Telegram 会话的消息都会自动经过 ACP Binding 路由，交给 @openclaw/acpx 扩展，驱动 Codex 执行，并将结果回传到 Telegram。

会话 key 的格式：Binding 会自动生成形如 agent:codex:acp:binding:telegram:work:<hash> 的会话标识，OpenClaw 以此做跨重启的持久化路由。

mode 参数：

• • persistent — 会话持久存在，消息之间保留上下文，适合持续协作
• • oneshot — 每条消息独立处理，无上下文保留

acpx：ACP 协议的 CLI 客户端

acpx 是独立的 ACP 客户端工具，可以在 OpenClaw 之外单独使用，也是 @openclaw/acpx 扩展的底层实现。

安装：

npm install -g acpx@latest# 或不安装直接使用npx acpx@latest codex "修复测试"

常用命令：

# 向 Codex 发任务acpx codex "重构 utils.ts，提取公共函数"# 向 Claude Code 发任务acpx claude "写单元测试覆盖 auth 模块"# 命名会话（多任务并行）acpx -s backend codex "优化数据库查询"acpx -s frontend codex "修复响应式布局 bug"# 输出结构化 JSON（方便脚本处理）acpx --json codex "列出所有 TODO 注释"

acpx 内置了主流编程智能体的适配器：OpenClaw、Claude Code、Codex、Gemini、Cursor、GitHub Copilot 等，也支持 --agent 指定自定义 ACP 服务器。

辅助路径：IDE 接入（openclaw acp）

如果你想让 Zed 等 IDE 直接与 OpenClaw Gateway 通信，可以用 openclaw acp 命令把 OpenClaw 暴露为 ACP 服务器：

# 基础启动openclaw acp# 指定 Gateway 地址和认证openclaw acp --url wss://gateway-host:18789 --token <your-token># 连接到指定会话openclaw acp --session agent:main:main

Zed 集成示例，在 ~/.config/zed/settings.json 中添加：

{  "assistant": {    "default_model": {      "provider": "custom",      "command": "openclaw acp",      "args": ["--url", "wss://your-gateway:18789", "--token", "your-token"]    }  }}

三、ACP 解决了什么问题？

最核心的问题：PTY 抓屏太脆弱

没有 ACP 之前，所有"让程序控制编码 AI"的方案都依赖 PTY（伪终端）抓屏。

问题是：

• • 工具 UI 改一个字，解析逻辑就全废
• • 无法判断任务"正在执行"还是"已完成"
• • 连接中断后状态全丢，无法恢复
• • 只有纯文本流，无法传递结构化数据

ACP 用协议层彻底解决了这个问题：消息有类型（newSession、prompt、cancel）、有状态、有结构，不再依赖文本解析。

可靠性：断线恢复 + 提示词队列

ACP 设计了完整的容错机制：

• • 崩溃自动重连：Codex 进程挂掉后，acpx 自动检测并恢复会话
• • 提示词队列：任务执行中发来的新消息不会丢失，按序排队执行
• • 协作式取消：取消任务时不销毁会话状态，随时可以继续

这对 Telegram 机器人场景尤为重要——用户随时可能发消息，任何消息都不能丢。

并发：命名会话

传统终端一次只能跑一个任务。ACP 的命名会话让多条工作线并行存在，每个会话有独立上下文：

acpx -s backend codex "..."   # 后端任务acpx -s frontend codex "..."  # 前端任务，同时跑

互操作性：统一协议，多工具适配

编程 AI 工具各自为战一直是行业痛点。ACP 提供了统一接口，acpx 已为主流工具实现了适配器。就像 HTTP 统一了 Web 通信，ACP 在尝试成为 AI 智能体通信的基础设施。

总结

OpenClaw ACP 的价值不在于单个命令，而在于它把"聊天 → 编码智能体"这条链路做成了有协议保障的可靠通道。你在 Telegram 发一条消息，背后是一套完整的队列、路由、会话管理机制在保证它被可靠地送到 Codex 并带回结果。

参考资料：

• • OpenClaw ACP 官方文档：https://docs.openclaw.ai/zh-CN/cli/acp
• • acpx GitHub 仓库：https://github.com/openclaw/acpx