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

原文信息

作者: 运维有术
发布时间:
原文链接: https://mp.weixin.qq.com/s/gWSPzutwBtGGMUJIZ-6vCg

🚩 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+ 编码智能体。

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 表示
核心架构：client-agent 模型
ACP 架构图
图 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）
Prompt Turn 流程图
图 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：：acp：
sub-agent 会话：
agent：：subagent：
线程绑定机制：
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/.sock
）
Windows 使用命名管道
队列所有者使用空闲 TTL（默认 300s）
实战指南：从安装到使用
安装 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,
},
},
},
}
常用命令参考
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
ACP vs sub-agent：怎么选?
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 原生沙箱执行或委托运行
你在项目中用过类似的方案吗? 欢迎在评论区聊聊你的选择.
实战案例
案例 1： PR 代码审查

在专用命名会话中审查 PR

acpx –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 backend
acpx 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’
故障排查
常见问题
症状
可能原因
解决方案
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=; error=.
验证智能体报告 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（线程绑定）
相关资源
ACP 官方文档
： https://agentclientprotocol.com/
OpenClaw ACP 文档
： https://docs.openclaw.ai/tools/acp-agents
acpx GitHub
： https://github.com/openclaw/acpx
好啦，以上就是今天的全部分享！
如果觉得有收获，欢迎点赞、收藏、转发！我们下期见！👋
加入飞书群，共同交流，共同进步！
飞书群二维码