ACPX 项目总结 - OpenClaw 与 Claude 的互通协作

📋 目录

项目概述

ACPX (Agent Client Protocol X) 是一个用于 Agent Client Protocol (ACP) 的无头 CLI 客户端，让 AI 助手和编排器能够通过结构化协议与编码代理通信，而不是通过 PTY（伪终端）会话抓取。

核心目标

为 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 协议架构

协议层结构

┌─────────────────────────────────────────┐
│         ACPX (协议转换器)           │
├─────────────────────────────────────────┤
│  • 会话管理                        │
│  • 提示队列                        │
│  • 消息路由                        │
│  • 格式转换                        │
└─────────────────────────────────────────┘
         ▼                 ▼
┌─────────────┐    ┌─────────────┐
│  OpenClaw  │    │ Claude Code │
│  ACP Server │    │ ACP Client │
└─────────────┘    └─────────────┘

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 代理能够相互对话：

┌─────────────┐      ACPX      ┌─────────────┐
│  OpenClaw  │ ◄──────────────► │ Claude Code │
│  (主代理)   │   (协议转换)    │  (编码代理)   │
└─────────────┘                  └─────────────┘

协议优势：

  • ✅ 结构化消息（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"
    }
  }
}

工作原理：

  1. OpenClaw 启动 ACP 桥接服务

  2. 监听 WebSocket 连接（ws://127.0.0.1:18789）

  3. 接受来自 Claude Code 的 ACP 请求

  4. 通过 gateway token 认证

  5. 执行请求并返回结构化响应

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'

流程：

  1. OpenClaw 通过 ACPX 发送任务

  2. ACPX 连接到 Codex/Claude Code ACP 服务器

  3. 代理执行任务

  4. 返回结构化结果（工具调用、diffs）

  5. OpenClaw 处理结果

场景 2：Claude Code 调用 OpenClaw

# Claude Code 请求 OpenClaw 的状态
acpx openclaw exec 'summarize active session state'

流程：

  1. Claude Code 通过 ACPX 发送请求

  2. ACPX 连接到 OpenClaw ACP 桥接

  3. OpenClaw 执行查询

  4. 返回会话状态数据

  5. 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'

流程：

  1. OpenClaw 通过 ACPX 发送任务

  2. Claude Code 接收并执行审查

  3. 返回结构化的工具调用和 diffs

  4. 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 抓取 避免终端模拟的复杂性

安装与使用

安装

# 全局安装（推荐）
npm install -g acpx@latest

# 或者不安装直接运行
npx acpx@latest

安装 ACPX 技能

# 安装 ACPX 技能以便获得完整参考
npx acpx@latest --skill install 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'

# 设置 TTL
acpx openclaw --ttl 30 'keep queue owner alive for quick follow-ups'

# 设置超时
acpx openclaw --timeout 90 'investigate intermittent test timeout'

配置管理

# 显示当前配置
acpx config show

# 初始化全局配置
acpx config init

# 查看配置文件
cat ~/.acpx/config.json
cat .acpxrc.json

总结

ACPX 的角色

ACPX 是 OpenClaw 和 Claude Code 之间的协议转换桥梁，通过 ACP 实现了：

  1. 统一通信：一个命令接口管理多个代理

  2. 结构化消息：类型化的 ACP 消息替代 PTY 抓取

  3. 会话管理：持久化、命名、并行工作流

  4. 智能队列：自动排队，优雅取消

  5. 双向协作：OpenClaw ↔ Claude Code 互相调用

如何实现互通协作

OpenClaw 端：

  1. 启动 ACP 桥接服务

  2. 监听 WebSocket 连接

  3. 接受来自 Claude 的请求

  4. 执行并返回结构化响应

Claude Code 端：

  1. 通过 ACPX 调用 OpenClaw

  2. 发送结构化请求

  3. 接收并处理响应

ACPX 中间层：

  1. 协议转换

  2. 会话管理

  3. 消息路由

  4. 格式转换

核心价值

  • 开发一次，多处可用：开发者只需维护一个 ACP 接口

  • 跨代理兼容：支持 Codex、Claude、Gemini、OpenClaw、Pi 等多个代理

  • 结构化通信：避免 PTY 抓取的复杂性

  • 并行工作流：命名会话支持同时处理多个任务

  • 状态持久化：会话状态保存到磁盘，崩溃后自动恢复

一句话总结：ACPX 通过 ACP 协议实现了 OpenClaw 和 Claude Code 之间的标准化、结构化、双向通信，让两者能够无缝协作、共享会话、委派任务，并支持并行工作流。