acpx
为 ACP 兼容编码代理提供无头、可持久化会话的统一命令行客户端。
- Star 数
- ★ 3.4k
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 57/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 开发者想让 Codex 或 Claude Code 在同一仓库里跨多次调用保留上下文，用命名会话并行推进多个工作流。
- 不适合
- 只想在聊天界面里点选操作、不熟悉命令行的用户
- 需要稳定 API、不愿承受 pre-1.0 接口变动的生产团队
- 依赖未提供 ACP 适配器的编码代理的用户
- 源码审查
- 57/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
acpx 是 Agent Client Protocol（ACP）的无头命令行客户端，由 openclaw 以 MIT 许可发布在 npm 上。它把不同 ACP 兼容的编码代理（Codex、Claude Code、Pi、OpenClaw，或通过 --agent 指定的自定义命令）统一到同一条命令形态下，提供可持久化的命名会话、无状态的 exec 单次运行，以及默认文本、--format json 的 NDJSON 事件流与 --format quiet 三种输出格式。会话状态保存在 ~/.acpx/ 下，作用域绑定当前仓库，可跨多次调用保留上下文，并支持排队、取消、导入导出与重连。它还包含权限模式、--cwd 文件系统边界、全局与项目 JSON 配置，以及通过 acpx flow run 执行的 TypeScript 多步工作流。除 CLI 外，包导出了 acpx/runtime 与 acpx/flows，可用 createSharedAcpRuntime() 让应用与 CLI 共享同一个本地会话持有者。项目目前处于 pre-1.0，CLI 与运行时接口仍在演进。
acpx 接收子命令与代理名（如 acpx codex …），拉起对应的 ACP 兼容代理进程并与之按 ACP 协议通信。它读取提示词参数或 stdin、--cwd 指定的工作目录、全局与项目 JSON 配置以及命令行参数（参数优先级最高），据此创建、命名、切换或复用 ~/.acpx/ 下的会话；当某一轮仍在运行时，后续提示会被排队。输出层把 ACP 事件转换为终端可读文本，或用 --format json 输出 NDJSON 事件（保留结构化思考、工具调用、diff 与完成状态），或用 --format quiet 只打印最终助手文本。acpx flow run 执行 TypeScript 工作流，把 ACP 轮次与确定性动作、判断、计算和检查点组合起来；acpx/runtime 与 acpx/flows 则把这些原语暴露给代码调用方。
- 开发者想让 Codex 或 Claude Code 在同一仓库里跨多次调用保留上下文，用命名会话并行推进多个工作流。
- CI 或自动化脚本需要机器可读输出，用 --format json 解析 NDJSON 事件中的工具调用与完成状态。
- 团队想对同一提示在多个 ACP 兼容代理之间做对比评估。
- 需要严格文件系统边界与权限策略（从读审批到全部拒绝或全部放行）后再让代理改代码的用户。
- 应用开发者希望在自有服务中嵌入会话与工作流能力，而不通过 shell 调用 CLI。
- 需要把代理轮次与确定性计算、条件判断、检查点串成 TypeScript 多步流程的工程团队。
如何安装或部署这个 Agent？
需要 Node.js 22.13 或更新版本，并先安装和认证你要使用的编码代理（若其适配器未自行提供认证）。通过 npm 全局安装：
npm install -g acpx@latest不想全局安装时可用 npx：
npx acpx@latest --help从源码构建需使用 pnpm：
pnpm install --frozen-lockfile
pnpm run check如何使用这个 Agent？
先在该仓库中显式创建会话，再发送提示：
acpx codex sessions new
acpx codex "find the slowest test and explain why"使用命名会话与无状态单次运行：
acpx codex sessions new --name backend
acpx codex -s backend "trace the checkout timeout"
acpx codex exec "summarize this repository"切换代理或使用自定义 ACP 服务器并指定模型选项：
acpx claude exec "review this diff"
acpx --agent '<command>' exec "hello"
acpx --model gpt-5.4 codex exec --config-option reasoning_effort=high "review this repository"为自动化输出 NDJSON、并限定工作目录：
acpx --cwd /path/to/repo --format json codex exec "list failing tests"这个 Agent 有哪些优点和局限？
- 用同一条命令形态统一 Codex、Claude Code、Pi、OpenClaw 及自定义 ACP 服务器，切换代理只改一个参数。
- 持久化命名会话让上下文跨多次调用保留，并支持并行工作流与进行中提问排队。
- --format json 输出 NDJSON ACP 事件，保留工具调用、diff 与完成状态，便于自动化消费。
- 同时提供 CLI、acpx/runtime、acpx/flows 与 createSharedAcpRuntime()，覆盖脚本与嵌入两种用法。
- 权限模式与 --cwd 文件系统边界把会话作用域和写权限显式化。
- 项目处于 pre-1.0，README 明确提示 CLI 与运行时接口仍会变化，存在升级破坏风险。
- 本身不提供模型或代理能力，必须另行安装并认证上游编码代理，否则无可用会话。
- 依赖 Node.js 22.13 及以上版本，老旧运行时环境需先升级。
- 会话状态写入 ~/.acpx/，多进程或多机器的队列与重连行为需要按文档自行管理。
- flows 能力限于 TypeScript 工作流，非 TypeScript 栈的团队需要额外适配。
这个 Agent 与同类方案有什么区别？
README 未点名任何具体竞品；它把自己定位为在终端里直接与编码代理交互这一方式的替代，即用结构化 ACP 客户端取代人工在交互式终端里操作代理。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| acpx 当前 | 57 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 3.4k | 今天 | TypeScript | Codex · Claude Code |
| MonoCode | 56 · 缺口较多 | 桌面应用免费 | ★ 3.2k | 今天 | TypeScript | Codex · Claude Code |
| Mirafold | 89 · 表现良好 | 命令行工具免费版 + 付费版 | ★ 18 | 1 个月前 | TypeScript | Codex · Claude Code |
| Atlas | 50 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 9.6k | 1 天前 | Rust | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
权限模型文档详尽：默认 approve-reads、--deny-all/--approve-all 互斥、非交互默认拒绝、fs-safe 根与符号链接/硬链接防护、--no-fs/--no-terminal 能力开关，且明确声明这不是 OS 沙箱（least_privilege 2）。交互式逐请求确认与 flow 显式授权设计存在（user_confirmation 2）。数据落盘位置在 install.md 表格中透明列出（data_flow_transparency 2）。敏感数据处理有 0600/0700 权限、auth 环境变量与配置分离、SECURITY.md 指引（sensitive_data_handling 2）。依赖安全仅见 CI 与 lockfile 引用，未见审计/SBOM/依赖漏洞策略，且内置适配器通过 npx 自动拉取未固定完整版本（dependency_security 1）。外部副作用方面文档承认取消不撤销已完成的写入与命令，无回滚机制（external_effects 1）。rollback 仅 sessions prune/export-import 与 flow 运行包，无操作级回滚（rollback 1）。来源归属有 MIT 与作者字段，但发布者身份未经验证、无签名/来源证明（source_attribution 1）。
文档与代码/测试在 agent 注册表、权限模式、退出码上相互一致（self_consistency 2）。依赖可用性依赖 Node 22.13+、pnpm 11.26、uvx、上游 CLI 与 npx 首次拉取，存在外部前置条件（dependency_availability 1）。失败信息有明确退出码 5、PERMISSION_PROMPT_UNAVAILABLE、preflight 失败提示（failure_messages 2）。
面向开发者、编排器与嵌入宿主，场景覆盖会话/一次性/flow/嵌入（audience_and_scenarios 2）。能力边界明确说明非沙箱、--no-terminal 不阻止适配器原生工具（capability_boundaries 2）。触发精度有显式 session 创建、权限策略优先级、非交互策略（trigger_precision 2）。环境适配覆盖 Windows 命名管道、argv 迁移、Node 版本矩阵（environment_fit 2）。
文档结构清晰，README 与 docs 分层（information_architecture 2）。安装说明含全局/npx/源码构建与版本要求（install_notes 2）。命名稳定性因 pre-1.0 明确警告 CLI/runtime 接口会变（naming_stability 1）。示例与 quickstart 充分（examples_and_faq 2）。已知限制在 permissions/SECURITY 中诚实披露（known_limitations 2）。MIT 许可证完整（license 2）。版本号 0.20.0 存在但 CHANGELOG 仅外链未在证据中（versioning_changelog 1）。维护责任指向 OpenClaw Team 与 SECURITY 联系方式，但发布者未经验证（maintenance_responsibility 1）。
输出格式 text/json/json-strict/quiet 与结构化事件便于自动化消费（output_usability 2）。相对裸 PTY 抓取提供结构化 ACP 会话，边际价值明确（marginal_value 2）。成本为 Node 运行时与 npx 首次拉取开销，文档已提示（cost_benefit 2）。
README 声明多可追溯到 docs 与测试文件，但部分行为（flow 权限强制）文档自述为设计目标而非已实现（claim_traceability 1）。跨源佐证有限，仅 README/docs/测试/CI 相互印证，无独立第三方（cross_source_corroboration 1）。文档明确区分设计目标与已实现状态，事实与推断分离较好（fact_inference_separation 2）。
- 发布者身份未经验证，来源归属与维护责任仅凭仓库元数据，不能据此推断可靠性或安全性。
- 内置适配器通过 npx 自动拉取且版本范围为 ^ 区间，首次运行会执行外部包，存在供应链风险，建议固定版本并审计。
- 文档明确声明 acpx 不是 OS 沙箱，--no-terminal/--no-fs 不阻止适配器原生工具或子进程，取消不撤销已完成的写入与命令。
- flow 权限强制模型在文档中自述为设计目标，可能尚未完全实现，勿假定已强制。
- pre-1.0 版本，CLI 与 runtime 接口可能在次版本间破坏性变更。