ACPX - 智能体协作框架
2026-03-09 2026年03月 ACPX智能体协作框架.md

ACPX - 智能体协作框架

通过ACP协议让AI智能体之间相互协作

概述

项目地址：https://github.com/openclaw/acpx

ACPX 是一个用于 Agent Client Protocol (ACP) 的无头CLI客户端，让AI智能体和编排器可以通过结构化协议与编码智能体对话，而无需再从PTY会话中 scraping 字符。

简单来说：OpenClaw 可以指挥 ClaudeCode、Codex、Gemini、OpenCode 等各种AI智能体协同工作了！

核心能力

🤖 多智能体支持

智能体 命令 说明
Codex acpx codex OpenAI Codex CLI
Claude Code acpx claude Anthropic Claude Code
Gemini acpx gemini Google Gemini CLI
OpenClaw acpx openclaw OpenClaw ACP桥接
OpenCode acpx opencode OpenCode AI
Pi acpx pi Pi Coding Agent

核心特性

1. 持久会话

  • 多轮对话，跨调用持久化，按仓库隔离
  • 会话状态保存在 ~/.acpx/

2. 命名会话

  • 支持并行工作流（-s backend, -s frontend）
  • 同一仓库多个并行任务

3. 提示队列

  • 提交提示时已有任务在运行？自动排队顺序执行

4. 协作取消

  • cancel 发送 ACP session/cancel，不破坏会话状态

5. 软关闭

  • 关闭会话但不删除磁盘历史

6. 队列所有者TTL

  • 保持队列所有者短暂存活（--ttl）

7. 即发即忘

  • --no-wait 排队后立即返回

8. 优雅取消

  • Ctrl+C 先发送 session/cancel，再force-kill

9. 会话控制

  • set-mode 和 set 用于会话模式配置

10. 崩溃重连

  • 检测到智能体进程死亡，自动重新加载会话

11. 结构化输出

  • typed ACP 消息（thinking, tool calls, diffs），无需ANSI scraping

快速开始

安装

npm install -g acpx@latest

或免安装使用：

npx acpx@latest codex "fix the tests"

让你的智能体知道如何使用ACPX

将以下内容告诉 OpenClaw、Pi、Claude Code 等智能体：

I want you to use acpx to run coding agents over the Agent Client Protocol (ACP) instead of scraping PTY sessions. Please do the following:

1. Install acpx globally (recommended):
   npm install -g acpx@latest

2. Install the acpx skill:
   npx acpx@latest --skill install acpx

3. Read the acpx skill reference:
   https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md

From now on, when you need to delegate work to a coding agent, use acpx instead of spawning raw terminal sessions.

Examples:
   npx acpx@latest codex "fix the failing tests"
   npx acpx@latest claude "refactor the auth module"

使用示例

基本用法

# 创建新会话
acpx codex sessions new

# 发送提示（隐式）
acpx codex "find the flaky test and fix it"

# 从stdin读取提示
echo 'fix flaky tests' | acpx codex

# 从文件读取
acpx codex --file prompt.md

# 不等待，立即返回
acpx codex --no-wait 'draft test migration plan'

# 取消当前任务
acpx codex cancel

# 设置会话模式
acpx codex set-mode plan

# 查看状态
acpx codex status

命名会话（并行工作流）

# 创建命名会话
acpx codex sessions new --name api

# 在命名会话中执行
acpx codex -s api 'implement cursor pagination'

# 另一个并行会话
acpx codex sessions new --name docs
acpx codex -s docs 'rewrite API docs'

一次性任务

# 无状态一次性执行
acpx codex exec 'what does this repo do?'

# 默认智能体
acpx exec 'summarize this repo'

会话管理

# 列出所有会话
acpx codex sessions

# 查看会话历史
acpx codex sessions history --limit 10

# 关闭会话
acpx codex sessions close
acpx codex sessions close api

实用场景

PR审查

acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'Review PR #842 for regressions and propose a minimal fix'

并行工作流

# 同时处理不同任务
acpx codex -s bugfix 'isolate flaky checkout test'
acpx codex -s release 'draft release notes from recent commits'

权限控制

# 自动批准所有操作
acpx --approve-all codex 'apply the patch and run tests'

# 只允许读取
acpx --approve-reads codex 'inspect repo structure'

# 拒绝所有
acpx --deny-all codex 'explain what you can do'

# 非交互模式失败
acpx --non-interactive-permissions fail codex 'run checks'

输出格式

文本（默认）

acpx codex 'review this PR'

JSON（自动化）

acpx --format json codex exec 'review this PR'

静默（仅结果）

acpx --format quiet codex 'give me a 3-line summary'

配置文件

位置（后者优先）：
1. 全局：~/.acpx/config.json
2. 项目：<cwd>/.acpxrc.json

配置示例：

{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-all",
  "nonInteractivePermissions": "deny",
  "ttl": 300,
  "timeout": null,
  "format": "text",
  "agents": {
    "my-custom": {
      "command": "./bin/my-acp-server"
    }
  }
}

工作原理

你 → OpenClaw → acpx → ACP协议 → ClaudeCode/Codex/Gemini
                                    ↓
                              结构化通信
                                    ↓
                              返回结构化结果

为什么重要？

传统方式（PTY Scraping）

AI → 启动终端 → 模拟按键 → 读取输出 → 解析ANSI
        ↓
      脆弱、慢、不可靠

ACPX方式（结构化协议）

AI → acpx → ACP协议 → 智能体
        ↓
    结构化消息、类型安全、快速

相关链接

  • 项目主页：https://github.com/openclaw/acpx
  • ACP协议：https://agentclientprotocol.com
  • OpenClaw：https://github.com/openclaw/openclaw

整理时间：2026-03-09