1. 项目定位与用途
acpx 是 OpenClaw 团队开发的 Agent Client Protocol (ACP) 命令行客户端，定位为 AI 代理与编排系统间的结构化通信桥梁。它通过标准化的 ACP 协议替代不稳定的 PTY 会话抓取方式，使开发者能够以可靠、可预测的方式与各类 AI 编程代理交互。项目提供统一的命令界面，支持会话持久化、提示队列、工作流执行等企业级功能，旨在构建稳健的 AI 辅助开发工作流，适用于从个人编码助手到大规模自动化系统的多种场景。
项目档案命令行工具
acpx 完整使用指南：基于 Agent Client Protocol 与 AI 编程代理通信的命令行客户端工具
acpx 是一个无头 CLI 客户端，通过 Agent Client Protocol (ACP) 实现与 AI 编程代理的结构化通信，替代脆弱的 PTY 会话抓取。本文介绍其核心功能：持久化会话、提示队列、工作流执行、多代理支持等。包含安装步骤、基本用法、会话管理、工作流编写以及架构原理，适用于需要可靠 AI 代理集成的开发场景。
AI 总结
acpx 是一个无头命令行客户端，通过 Agent Client Protocol (ACP) 实现与 AI 编程代理的结构化通信，替代脆弱的 PTY 会话抓取方式，提供持久化会话、提示队列和工作流执行能力。
中文项目介绍
acpx 是一个专为 AI 代理与编排系统设计的无头命令行客户端，基于 Agent Client Protocol (ACP) 实现结构化双向通信。它解决了传统 PTY 会话抓取方式脆弱、不稳定且难以维护的问题，为 AI 代理交互提供可靠的协议层。
项目支持持久化多轮对话会话，会话数据默认存储在 ~/.acpx/sessions，支持跨调用自动恢复和软关闭机制。通过命名会话功能，用户可以在同一代码库中并行运行多个工作流。提示队列系统确保请求按序执行，并支持协作取消和优雅中断处理。
acpx 提供统一接口适配多种 ACP 兼容代理，包括 Codex、Claude Code、OpenClaw 等，内置代理注册表并支持自定义服务器。工作流引擎允许通过 TypeScript 模块定义复杂任务流，支持工作区隔离和检查点机制。权限模块提供细粒度的文件系统访问控制，会话运行时通过 JSON-RPC over stdio 与代理进程通信。适用场景涵盖 AI 辅助编程、自动化代码审查、多步骤任务编排以及需要可靠代理通信的开发工具链集成。
详细信息与使用说明
2. 核心问题与解决方案
传统 AI 代理集成依赖 PTY 会话抓取，这种方式脆弱且难以维护：输出格式变化会导致解析失败，会话状态无法持久化，并发控制缺失。acpx 通过引入 Agent Client Protocol (ACP) 解决这些问题：定义结构化的 JSON-RPC 消息格式，明确方法契约和错误语义；实现会话持久化机制，将对话历史存储在 ~/.acpx/sessions；采用队列所有权模型确保同一会话的请求串行化；提供协作取消和优雅降级策略。这些设计显著提升了代理通信的可靠性和可观测性。
3. 适用场景
acpx 适用于需要与 AI 编程代理进行结构化交互的多种场景：个人开发者使用 Codex 或 Claude 进行代码生成与修复；团队构建自动化代码审查流水线，集成到 CI/CD 流程；复杂多步骤任务编排，如 PR triage、分支管理等工作流；研究机构进行 AI 代理能力评估与基准测试。其命名会话功能支持并行工作流，工作区隔离特性确保多任务间环境干净分离。项目特别适合需要高可靠性、可重现会话状态的生产环境，以及需要统一接口适配多种代理的异构系统。
4. 安装方式
根据 package.json 配置，acpx 通过 npm 包管理器分发。用户可执行全局安装命令：npm install -g acpx。安装后，acpx 命令将直接可用。项目依赖 Node.js 运行环境，从构建配置推断推荐使用 Node.js 22 或更高版本，并以 ESM 模块格式发布。开发模式下可使用 pnpm dev 启动，但生产使用建议安装稳定版本。仓库中未明确给出系统级依赖（如 Python 或构建工具），仅需标准 Node.js 环境即可运行。
5. 使用方式
acpx 提供丰富的命令行接口。基本用法为 acpx <agent> "<prompt>"，例如 acpx codex "find the flaky test"。会话管理支持 sessions new/create/show/close 等子命令，可通过 -s 参数指定命名会话。提示输入支持 --file 从文件读取或通过 stdin 管道传递。工作流执行使用 acpx flow run <file.ts> 运行 TypeScript 模块。配置管理通过 acpx config init/show 进行。控制命令包括 set-mode、set <key> <value> 调整会话参数，cancel 协作取消任务。项目还提供 exec 子命令用于一次性无状态执行。
6. 实现特点与架构
acpx 采用分层架构：CLI 层负责命令解析与输出格式化；ACP 客户端层通过 stdio 以 JSON-RPC 方式与代理进程通信，避免 PTY 解析；会话运行时管理生命周期、队列所有权和权限控制；工作流引擎作为轻量编排层执行 TypeScript 流定义。会话数据持久化到 ~/.acpx/sessions，使用临时文件+原子重命名保证写入安全。项目包含完整的 conformance 测试套件，基于 spec/v1 验证协议合规性。权限模块支持 approve-all、approve-reads、deny-all 等策略，并提供交互式回退。架构设计强调边界清晰，工作流层不侵入 ACP 核心协议。
思维导图
acpx
核心模块
CLI 入口
ACP 客户端
会话运行时
工作流引擎
会话管理
持久化存储
命名会话
队列控制
软关闭/恢复
协议与通信
Agent Client Protocol
JSON-RPC over stdio
权限策略
工作流系统
TypeScript 流定义
动作节点
工作区隔离
测试与验证
Conformance 套件
代理适配器测试
文档与示例
架构文档
代理集成指南
示例工作流
常见问题
什么是 Agent Client Protocol (ACP)，acpx 为何使用它？
Agent Client Protocol (ACP) 是定义 AI 代理与客户端间结构化通信的协议，使用 JSON-RPC over stdio 替代 PTY 会话抓取。acpx 采用 ACP 是因为 PTY 方式脆弱且难以维护，而 ACP 提供稳定的方法契约、类型化消息和明确的错误处理，使代理通信更可靠、可观测且易于集成。
acpx 支持哪些 AI 代理？
acpx 内置对多种 ACP 兼容代理的支持，包括 Codex、Claude Code、OpenClaw、Cursor、Copilot 等，通过 agents 目录下的配置文件管理。此外，--agent 参数允许连接自定义 ACP 服务器，提供扩展性。具体支持列表可参考 agents/README.md。
如何安装 acpx 并开始使用？
确保已安装 Node.js 22+ 环境，执行 npm install -g acpx 进行全局安装。安装后运行 acpx <agent> "<prompt>" 即可，例如 acpx codex "find the flaky test"。首次使用建议运行 acpx config init 初始化配置，详细命令参考 acpx --help 或 docs/CLI.md。
会话数据存储在哪里？如何清理？
会话数据默认存储在 ~/.acpx/sessions 目录，每个会话包含历史记录、配置和元数据。使用 acpx sessions show 查看列表，acpx sessions close <id> 可软关闭会话（保留历史）。硬删除需手动移除对应文件。索引文件确保会话快速查找，且写入过程使用临时文件+原子重命名保证安全。
工作流 (flow) 如何编写和执行？
工作流是 TypeScript 模块，定义节点图与动作。使用 acpx flow run <file.ts> 执行。节点通过 acp 对象调用 ACP 方法，支持 workspace 指定工作目录。示例参考 examples/flows/ 目录。工作流作为 ACP 运行时之上的轻量编排层，保持边界清晰，不侵入核心协议，支持检查点与隔离执行。