文章总结： ACPX是无头CLI客户端，通过ACP协议实现OpenClaw与Claude等AI代理的标准化通信，替代PTY抓取。核心功能包括持久化会话、智能队列、双向委派与崩溃恢复，支持并行工作流。文档详述技术架构与代码审计实战，提供完整安装指南，有效解决了多代理协作中的通信结构与状态同步难题。 综合评分： 89 文章分类： AI安全,安全工具,解决方案,实战经验,安全开发
让 AI 助手间的’聊天’协作：OpenClaw委派 Claude完成审计（ACPX协议）
原创
糖果LUA 糖果LUA
AI安全运营
2026年3月9日 19:09 北京
📋 目录
- 项目概述
- 核心特性
- ACP 协议架构
- OpenClaw 与 Claude 的互通协作
- 实际协作场景
- 技术架构
- 核心优势
- 安装与使用
- 总结
#
项目概述
ACPX (Agent Client Protocol X) 是一个用于 Agent Client Protocol (ACP) 的无头 CLI 客户端，让 AI 助手和编排器能够通过结构化协议与编码代理通信，而不是通过 PTY（伪终端）会话抓取。
核心目标
为 AI 代理之间的通信提供统一的命令行接口，支持多个编码代理。
已关注
关注
重播 分享 赞
关闭
观看更多
更多
退出全屏
切换到竖屏全屏退出全屏
AI安全运营已关注
分享视频
，时长00:06
0/0
00:00/00:06
切换到横屏模式
继续播放
[ ]
进度条，百分之0
播放
00:00
/
00:06
00:06
倍速
全屏
倍速播放中
0.5倍 0.75倍 1.0倍 1.5倍 2.0倍
超清 流畅
继续观看
让 AI 助手间的’聊天’协作：OpenClaw委派 Claude完成审计（ACPX协议）
观看更多
转载
,
让 AI 助手间的’聊天’协作：OpenClaw委派 Claude完成审计（ACPX协议）
AI安全运营已关注
分享点赞在看
已同步到看一看写下你的评论
视频详情
支持的编码代理
| 代理 | 命令 | 源 |
| — | — | — |
| Codex | acpx codex | codex.openai.com |
| Claude Code | acpx claude | claude.ai/code |
| Gemini | acpx gemini | github.com/google/gemini-cli |
| OpenClaw ACP | acpx openclaw | github.com/openclaw/openclaw |
| OpenCode | acpx opencode | opencode.ai |
| Pi | acpx pi | github.com/mariozechner/pi |
核心特性
1. 会话管理
- 持久化会话：跨调用保存的多轮对话，按仓库范围限定
- 命名会话：在同一仓库中运行并行工作流（
-s backend,-s frontend） - 提示队列：当一个提示正在运行时，提交新提示，它们按顺序执行
- 协作取消：通过队列 IPC 发送
session/cancel，无需拆除会话状态 - 软关闭生命周期：关闭会话而不删除磁盘上的历史记录
- 崩溃重连：检测死亡的代理进程并自动重新加载会话
2. 高级功能
- 队列所有者 TTL：保持队列所有者活跃以便快速跟进（
--ttl） - 即发即忘：
--no-wait将提示排队并立即返回 - 优雅取消：Ctrl+C 发送
session/cancel，在强制终止前回退 - 会话控制：
set-mode和set用于session/set_mode和session/set_config_option - 从文件/stdin 提示：
--file或管道 stdin 获取提示内容 - 配置文件：全局 + 项目 JSON 配置（
acpx config show|init） - 会话检查/历史：
sessions show和sessions history --limit - 本地状态检查：
status报告运行中/死亡/无会话，pid，运行时间，最后提示 - 客户端方法：稳定的
fs/*和terminal/*处理程序，带有权限控制和 cwd 沙箱 - 认证握手：通过 env/config 凭证进行稳定的认证支持
- 结构化输出：类型化的 ACP 消息（thinking、工具调用、diffs）而不是 ANSI 抓取
- 任何 ACP 代理：内置注册表 +
--agent转义舱用于自定义服务器 - 一次性模式：
exec用于无状态的即发即忘任务
ACP 协议架构
协议层结构
#
ACP 消息类型
ACPX 返回类型化的 ACP 消息，而不是原始文本：
{"eventVersion":1,"sessionId":"abc123","requestId":"req-42","seq":7,"stream":"prompt","type":"tool_call"}
消息类型：
thinking：代理的思考过程tool_call：工具调用diff：代码更改end_turn：任务完成
#
OpenClaw 与 Claude 的互通协作
核心连接机制
ACPX 是 OpenClaw 和 Claude Code 之间的桥梁，通过 Agent Client Protocol (ACP) 实现标准化通信。
1. 统一的协议层
ACPX 提供了统一的接口，让不同的 AI 代理能够相互对话：
协议优势：
- ✅ 结构化消息（thinking、工具调用、diffs）
- ✅ 避免 PTY 抓取的复杂性
- ✅ 类型安全的通信
- ✅ 跨代理兼容性
2. OpenClaw 作为 ACP 服务器
OpenClaw 可以作为 ACP 服务器，接受来自其他代理的请求：
# 启动 OpenClaw ACP 桥接
acpx openclaw exec'summarize active session state'
配置示例（在 ~/.acpx/config.json 中）：
{"agents":{"openclaw":{"command":"env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node scripts/run-node.mjs acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"}}}
工作原理：
- OpenClaw 启动 ACP 桥接服务
- 监听 WebSocket 连接（
ws://127.0.0.1:18789） - 接受来自 Claude Code 的 ACP 请求
- 通过 gateway token 认证
- 执行请求并返回结构化响应
3. Claude Code 作为 ACP 客户端
Claude Code 可以通过 ACPX 调用 OpenClaw：
# 从 Claude Code 调用 OpenClaw
acpx claude 'ask OpenClaw to summarize current state'
或者直接使用 ACPX：
# 使用 Claude Code 代理
acpx claude 'refactor auth module'
# 使用 OpenClaw 桥接
acpx openclaw exec'summarize active session state'
4. 双向协作模式
场景 1：OpenClaw 调用 Claude Code
# OpenClaw 委派编码任务给 Claude Code
acpx codex 'fix the failing tests'
流程：
- OpenClaw 通过 ACPX 发送任务
- ACPX 连接到 Codex/Claude Code ACP 服务器
- 代理执行任务
- 返回结构化结果（工具调用、diffs）
- OpenClaw 处理结果
场景 2：Claude Code 调用 OpenClaw
# Claude Code 请求 OpenClaw 的状态
acpx openclaw exec'summarize active session state'
流程：
- Claude Code 通过 ACPX 发送请求
- ACPX 连接到 OpenClaw ACP 桥接
- OpenClaw 执行查询
- 返回会话状态数据
- Claude Code 接收并处理
5. 会话共享
ACPX 支持命名会话，实现并行工作流：
# OpenClaw 中创建命名会话
acpx openclaw sessions new --name api
# 在不同的命名会话中并行工作acpx openclaw -s api 'implement cursor pagination'acpx openclaw -s docs 'rewrite API docs'
# 列出所有会话
acpx openclaw sessions list
会话特性：
- ✅ 按仓库范围限定
- ✅ 持久化到磁盘（
~/.acpx/sessions/） - ✅ 支持并行工作流
- ✅ 崩溃后自动重连
6. 提示队列
ACPX 提供智能提示队列，防止任务冲突：
# 提交多个任务，它们按顺序执行
acpx openclaw 'task 1'acpx openclaw 'task 2'acpx openclaw 'task 3'
队列功能：
- ✅ 自动排队执行
- ✅
--no-wait即发即忘 - ✅
--ttl保持队列所有者活跃 - ✅ Ctrl+C 优雅取消
#
实际协作场景
场景 1：代码审查流水线
OpenClaw 作为协调者，委派任务给 Claude Code：
# OpenClaw 调用 Claude Code 审查 PR
acpx codex -s pr-842 'Review PR #842 for regressions and propose a minimal fix'
流程：
- OpenClaw 通过 ACPX 发送任务
- Claude Code 接收并执行审查
- 返回结构化的工具调用和 diffs
- OpenClaw 处理并应用更改
场景 2：状态同步
Claude Code 查询 OpenClaw 的状态：
# Claude Code 请求 OpenClaw 会话状态
acpx openclaw exec'summarize active session state'
用途：
- 同步上下文
- 获取会话历史
- 检查运行状态
场景 3：并行开发
使用命名会话同时处理多个任务：
# OpenClaw 中并行工作
acpx openclaw -s backend 'implement API'acpx openclaw -s frontend 'update UI'acpx openclaw -s docs 'write documentation'
优势：
- ✅ 独立的会话状态
- ✅ 不会相互干扰
- ✅ 可以同时运行
场景 4：一次性任务
使用 exec 命令执行无状态任务：
# 一次性任务，不保存会话
acpx openclaw exec'what does this repo do?'
特点：
- ✅ 无状态执行
- ✅ 不保存历史
- ✅ 适合快速查询
技术架构
1. 会话生命周期
创建 → 运行 → 队列 → 完成 → 关闭 ↓ ↓ ↓ ↓ ↓sessions new prompt queue end_turn sessions close
2. 配置管理
ACPX 支持多级配置：
# 全局配置~/.acpx/config.json
# 项目配置/.acpxrc.json
# 命令行标志（优先级最高）acpx --flag value
配置示例：
{"defaultAgent":"codex","defaultPermissions":"approve-all","nonInteractivePermissions":"deny","authPolicy":"skip","ttl":300,"timeout":null,"format":"text","agents":{"openclaw":{"command":"env OPENCLAW_HIDE_BANNER=1 node scripts/run-node.mjs acp ..."}}}
3. 输出格式
ACPX 支持多种输出格式：
# 文本格式（人类可读）
acpx --format text codex 'review this PR'
# JSON 格式（自动化）
acpx --format json codex exec'review this PR'| jq ...
# JSON-Strict（仅 JSON）
acpx --format json --json-strict codex exec'review'
# Quiet（仅最终结果）
acpx --format quiet codex 'give me a 3-line summary'
核心优势
ACPX 的优势
| 特性 | 说明 |
| — | — |
| 统一接口 | 一个命令管理多个代理 |
| 结构化通信 | 类型化的 ACP 消息，避免 PTY 抓取 |
| 会话持久化 | 跨调用保存状态 |
| 并行工作流 | 命名会话支持并行任务 |
| 智能队列 | 自动排队，防止冲突 |
| 优雅取消 | Ctrl+C 发送 session/cancel |
| 崩溃恢复 | 自动重连死亡进程 |
| 配置灵活 | 全局 + 项目配置 |
| 多种输出 | text/json/json-strict/quiet |
OpenClaw + Claude 协作的优势
| 协作点 | 说明 | | — | — | | 协议统一 | 通过 ACP 实现标准化通信 | | 双向调用 | OpenClaw ↔ Claude Code 互相调用 | | 会话共享 | 命名会话支持并行工作流 | | 状态同步 | 实时查询会话状态 | | 任务委派 | OpenClaw 委派编码任务给 Claude | | 结构化输出 | 类型化的消息，易于解析 | | 无 PTY 抓取 | 避免终端模拟的复杂性 |
安装与使用
安装
# 全局安装（推荐）
npminstall-g acpx@latest
# 或者不安装直接运行
npx acpx@latest
安装 ACPX 技能
# 安装 ACPX 技能以便获得完整参考
npx acpx@latest --skillinstall acpx
读取技能参考
# 读取 ACPX 技能参考https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md
基本使用
# 创建新会话
acpx codex sessions new
# 发送提示
acpx codex 'fix the failing tests'
# 从文件读取提示
acpx codex --file prompt.md
# 从 stdin 读取提示
echo'fix flaky tests'| acpx codex
# 列出会话
acpx codex sessions list
# 显示会话状态
acpx codex status
# 取消运行中的任务
acpx codex cancel
高级使用
# 创建命名会话
acpx openclaw sessions new --name api
# 在命名会话中工作
acpx openclaw -s api 'implement cursor pagination'
# 并行工作流
acpx openclaw -s backend 'implement API'
acpx openclaw -s frontend 'update UI'
# 一次性任务
acpx openclaw exec'summarize this repo'
# 即发即忘
acpx openclaw --no-wait 'draft test migration plan'w
# 设置 TTL
acpx openclaw --ttl30'keep queue owner alive for quick follow-ups'
# 设置超时
acpx openclaw --timeout90'investigate intermittent test timeout'
配置管理
# 显示当前配置acpx config show# 初始化全局配置acpx config init# 查看配置文件cat ~/.acpx/config.jsoncat .acpxrc.json
#
总结
ACPX 的角色
ACPX 是 OpenClaw 和 Claude Code 之间的协议转换桥梁，通过 ACP 实现了：
- 统一通信：一个命令接口管理多个代理
- 结构化消息：类型化的 ACP 消息替代 PTY 抓取
- 会话管理：持久化、命名、并行工作流
- 智能队列：自动排队，优雅取消
- 双向协作：OpenClaw ↔ Claude Code 互相调用
如何实现互通协作
OpenClaw 端：
- 启动 ACP 桥接服务
- 监听 WebSocket 连接
- 接受来自 Claude 的请求
- 执行并返回结构化响应
Claude Code 端：
- 通过 ACPX 调用 OpenClaw
- 发送结构化请求
- 接收并处理响应
ACPX 中间层：
- 协议转换
- 会话管理
- 消息路由
- 格式转换
核心价值
- 开发一次，多处可用：开发者只需维护一个 ACP 接口
- 跨代理兼容：支持 Codex、Claude、Gemini、OpenClaw、Pi 等多个代理
- 结构化通信：避免 PTY 抓取的复杂性
- 并行工作流：命名会话支持同时处理多个任务
- 状态持久化：会话状态保存到磁盘，崩溃后自动恢复
一句话总结：ACPX 通过 ACP 协议实现了 OpenClaw 和 Claude Code 之间的标准化、结构化、双向通信，让两者能够无缝协作、共享会话、委派任务，并支持并行工作流。
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：AI安全运营 糖果LUA 糖果LUA《让 AI 助手间的’聊天’协作：OpenClaw委派 Claude完成审计（ACPX协议）》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论