OpenClaw ACP Agents:在消息平台中统一管理 Claude Code 和 Codex 等 10+ 编码智能体

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划第 54 篇，OpenClaw 最佳实战「2026」系列第 24 篇
大家好，欢迎来到 术哥无界 | ShugeX ｜运维有术。
我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

图 1：ACP 协议连接消息平台和编码智能体

你在用 AI 编码工具时,可能遇到过这些情况：

Codex 只能在 vs code 里用,想在 neovim 里调用就得换工具
在 discord 里让智能体改代码,每次都要重新解释项目背景
不同智能体各有各的协议,接入成本高得离谱

这些问题的根源是同一个：AI 编码智能体与编辑器/平台之间缺乏统一的通信标准。

Agent Client Protocol(ACP)用一套 json-rpc 2.0 协议解决了这个问题：任何支持 ACP 的智能体可以在任何支持 ACP 的编辑器或平台中使用。OpenClaw 的 acpx 插件把这套协议接到了消息平台,让你能在 discord、 telegram 里直接驱动 Codex、 Claude Code、 gemini CLI 等 10+ 编码智能体。

1. ACP 是什么

Agent Client Protocol(ACP)是一个标准化协议,用于规范代码编辑器/IDE 与编码智能体之间的通信。

如果你熟悉 language server protocol(Lsp),理解 ACP 就很简单：Lsp 标准化了语言服务器集成,ACP 标准化了智能体-编辑器通信。

核心价值：

解耦合：智能体和编辑器可以独立演进，不再相互绑定
生态互通：支持 ACP 的智能体可在任何兼容编辑器中使用；支持 ACP 的编辑器可访问整个 ACP 兼容智能体生态
创新自由：双方可独立创新，开发者可自由组合最佳工具

协议特性：

基于 JSON-RPC 2.0 规范
支持本地(stdio)和远程(http/websocket，开发中)两种通信方式
默认用户可读文本格式为 Markdown
复用 MCP(Model Context Protocol)的 JSON 表示

2. 核心架构：client-agent 模型

图 2：ACP Client-Agent 通信架构

ACP 采用客户端-智能体(client-agent)架构。 Client 通常是编辑器或平台(如 OpenClaw),Agent 是编码智能体(如 Codex、 claude code).

通信协议

Client 和 Agent 之间通过 JSON-RPC 2.0 进行双向通信。

Client 提供的方法：

fs/*：文件系统操作（读取、写入文件）
terminal/*：终端管理（创建、输出、终止）
request_permission：权限请求

Agent 提供的方法：

initialize：建立连接
session/new：创建新会话
session/prompt：发送用户消息
session/load：恢复现有会话
session/set_mode：切换操作模式

Agent 发送的通知：

session/update：会话状态更新
session/cancel：取消操作

消息流程

一个完整的 Prompt Turn（提示轮次）流程：

Client → Agent： session/prompt 发送用户消息
Agent → Client： session/update 通知（进度更新）
Agent → Client：文件操作或权限请求（如需要）
Client → Agent：权限批准或拒绝
Agent → Client： session/prompt 响应（带 stopReason）

图 3：完整的 Prompt Turn 流程

3.Openclaw acpx 插件：核心实现

OpenClaw 通过 acpx 插件提供完整的 ACP 实现. acpx 是一个 typescript 编写的插件, GitHub 仓库已有 992+ stars.

支持的智能体

智能体	适配方式	底层工具
codex	codex-acp	codex cli
claude	claude-agent-acp	claude code
gemini	原生支持	gemini cli
cursor	原生支持	cursor cli
copilot	原生支持	github copilot cli
pi	pi-acp	pi coding agent
openclaw	原生支持	openclaw acp bridge
droid	原生支持	factory droid
kimi	原生支持	kimi cli
opencode	npx 调用	opencode
qwen	原生支持	qwen code

会话管理机制

会话键格式：

ACP 会话：agent：<agentId>：acp：<uuid>
sub-agent 会话：agent：<agentId>：subagent：<uuid>

线程绑定机制：

OpenClaw 可将线程绑定到目标 ACP 会话
线程中的后续消息自动路由到绑定的 ACP 会话
ACP 输出传回同一线程
绑定在以下情况移除：取消聚焦、关闭、归档、空闲超时或最大期限过期

支持的渠道：

Discord：线程/频道
Telegram：主题（群组/超级群组中的论坛主题和 DM 主题）

权限控制

acpx 提供两种配置键控制权限处理.

permissionMode：

值	行为
approve-all	自动批准所有文件写入和 shell 命令
approve-reads	仅自动批准读取; 写入和执行需要提示
deny-all	拒绝所有权限提示

nonInteractivePermissions (非交互模式策略)：

值	行为
fail	使用 AcpRuntimeError 中止会话 (默认)
deny	静默拒绝权限并继续 (优雅降级)

Prompt 队列

每个 ACP 会话维护独立的提示队列
活跃的 acpx 进程成为队列所有者
其他调用通过本地 IPC 提交提示
Unix 系统使用 Unix Socket（~/.acpx/queues/<hash>.sock）
Windows 使用命名管道
队列所有者使用空闲 TTL（默认 300s）

4. 实战指南：从安装到使用

安装 acpx 插件

# 安装插件openclaw plugins install acpx# 启用插件openclaw config set plugins.entries.acpx.enabled true# 验证后端健康/acp doctor

核心配置

在 openclaw 配置文件中添加：

{  acp： {    enabled： true,    dispatch： { enabled： true },    backend： "acpx",    defaultAgent： "codex",    allowedAgents： ["pi", "claude", "codex", "opencode", "gemini", "kimi"],    maxConcurrentSessions： 8,    stream： {      coalesceIdleMs： 300,      maxChunkChars： 1200,    },    runtime： {      ttlMinutes： 120,    },  },}

discord 线程绑定配置

{  session： {    threadBindings： {      enabled： true,      idleHours： 24,      maxAgeHours： 0,    },  },  channels： {    discord： {      threadBindings： {        enabled： true,        spawnAcpSessions： true,      },    },  },}

5. 常用命令参考

operator 快速流程

# 1. 生成会话/acp spawn codex --mode persistent --thread auto# 2. 检查运行时状态/acp status# 3. 调整运行时选项/acp model openai/gpt-5.2/acp permissions strict/acp timeout 120# 4. 引导活跃会话/acp steer tighten logging and continue# 5. 停止工作/acp cancel  # 停止当前 turn/acp close   # 关闭会话 + 移除绑定

完整命令列表

命令	功能	示例
/acp spawn	创建 ACP 会话	/acp spawn codex --mode persistent --thread auto
/acp cancel	取消进行中的 turn	/acp cancel agent：codex：acp：
/acp steer	发送引导指令	/acp steer prioritize failing tests
/acp close	关闭会话	/acp close
/acp status	显示状态	/acp status
/acp set-mode	设置运行时模式	/acp set-mode plan
/acp set	通用配置写入	/acp set model openai/gpt-5.2
/acp cwd	设置工作目录	/acp cwd /Users/user/Projects/repo
/acp permissions	设置审批策略	/acp permissions strict
/acp timeout	设置超时	/acp timeout 120
/acp model	设置模型覆盖	/acp model anthropic/claude-opus-4-5
/acp sessions	列出最近会话	/acp sessions
/acp doctor	后端健康检查	/acp doctor

6. ACP vs sub-agent：怎么选?

图 4：ACP 会话 vs Sub-agent 运行对比

OpenClaw 提供两种运行时：ACP 和 sub-agent. 选择哪个取决于你的需求.

特性	ACP 会话	sub-agent 运行
运行时	ACP 后端插件(如 acpx)	openclaw 原生 sub-agent 运行时
会话键	agent：：acp：	agent：：subagent：
沙箱支持	在主机运行时运行, 不在沙箱内	支持 openclaw 原生沙箱
适用场景	外部编码工具运行时	openclaw 原生委托运行

选择建议：

用 ACP：需要外部工具运行时（Codex、Claude Code、Gemini CLI 等）
用 sub-agent：需要 OpenClaw 原生沙箱执行或委托运行

你在项目中用过类似的方案吗? 欢迎在评论区聊聊你的选择.

7. 实战案例

案例 1： PR 代码审查

# 在专用命名会话中审查 PRacpx --cwd ~/repos/shop --approve-all codex -s pr-842 \'review PR #842 for regressions and propose a minimal fix'# 后续继续同一 PR 审查acpx --cwd ~/repos/shop codex -s pr-842 \'now draft commit message and rollout checklist'

案例 2：并行工作流

# 创建多个命名会话acpx codex sessions new --name backendacpx codex sessions new --name docs# 并行处理不同任务acpx codex -s backend 'fix checkout timeout'acpx codex -s docs 'document payment retry behavior'

案例 3：权限策略选择

# 自动化场景： 全批准acpx --approve-all codex 'apply this patch and run tests'# 调查场景： 只读批准(默认)acpx --approve-reads codex 'inspect repo structure and suggest plan'# 安全场景： 全拒绝acpx --deny-all codex 'explain what you can do without tool access'

案例 4：从文件/标准输入提示

# 从标准输入echo'triage failing tests' | acpx codex# 从文件acpx codex --file prompt.md# 标准输入 + 追加参数acpx codex --file - 'also check lint warnings'

案例 5： JSON 自动化

# 使用 jq 过滤工具调用acpx --format json codex exec'review changed files' \  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

8. 故障排查

常见问题

症状	可能原因	解决方案
ACP runtime backend is not configured	后端插件缺失或禁用	安装并启用后端插件,运行 /acp doctor
ACP is disabled by policy	ACP 全局禁用	设置 acp.enabled=true
ACP agent "" is not allowed	智能体不在允许列表	更新 acp.allowedAgents
Unable to resolve session target	会话键错误	运行 /acp sessions,获取正确键
Thread bindings are unavailable	适配器不支持问题	使用 --thread off 或换渠道
Sandboxed sessions cannot spawn ACP	沙箱化会话限制	使用 runtime="subagent" 或从非沙箱化会话运行
ACP 会话早期失败	权限被阻止	设置 permissionMode=approve-all

operator 烟雾测试

部署后验证 ACP spawn 端到端工作.

验证部署的网关版本
确认部署源包含 ACP 支持
打开临时会话测试：

use the sessions_spawn tool with runtime： "acp", agentId： "codex", and mode： "run".set the task to： "reply with exactly LIVE-acp-spawn-ok".report： accepted=<yes/no>; childSessionKey=<value>; error=<text>.

验证智能体报告 accepted=yes 和真实 childSessionKey

总结

OpenClaw ACP Agents 通过 acpx 插件把 ACP 协议接到了消息平台, 让你能在 Discord、Telegram 中直接驱动 10+ 编码智能体.

核心特性：

10+ 编码智能体： Codex、Claude Code、Gemini CLI、Cursor CLI、Copilot 等
跨平台会话保持：线程绑定让会话上下文在 Discord/Telegram 线程间保持
灵活权限控制：三种权限模式满足不同安全需求
队列并发支持：同一会话的并发请求有序处理

适用场景：

需要外部编码工具：选择 ACP
需要沙箱隔离：选择 sub-agent
需要跨设备协作：选择 ACP（线程绑定）