acpx - Headless ACP CLI

ACP (Agent Client Protocol) 的无头 CLI 客户端，专为 agent-to-agent 通信设计，避免 PTY 抓取问题。

安装

npm i -g acpx

核心能力

能力	说明
持久会话	多轮对话，按 repo/cwd 自动恢复
一次性执行	exec 模式，单次执行不保存状态
并行会话	-s/--session 命名会话，同仓库多对话
队列管理	多个 prompt 自动排队，--no-wait 异步提交
权限控制	--approve-all/--approve-reads/--deny-all
结构化输出	text/json/quiet 三种格式
优雅取消	cancel 命令或 Ctrl+C 发送 ACP session/cancel

内置 Agent 注册表

名称	命令
pi	npx pi-acp
qwen	qwen --acp
codex	npx @zed-industries/codex-acp
claude	npx -y @zed-industries/claude-agent-acp
gemini	gemini --acp
cursor	cursor-agent acp
copilot	copilot --acp --stdio
openclaw	openclaw acp
droid	droid exec --output-format acp
kimi	kimi acp
opencode	npx -y opencode-ai acp
kiro	kiro-cli acp
kilocode	npx -y @kilocode/cli acp

默认 agent 是 codex。

命令模型

# 基本用法
acpx <agent> '<prompt>'              # 持久会话模式
acpx <agent> exec '<prompt>'         # 一次性执行
acpx <agent> -s <name> '<prompt>'    # 命名会话

# 会话管理
acpx <agent> sessions                # 列出会话
acpx <agent> sessions new            # 新建会话
acpx <agent> sessions show [name]    # 显示会话详情
acpx <agent> sessions history [name] # 查看历史
acpx <agent> sessions close [name]   # 关闭会话

# 控制
acpx <agent> cancel                  # 取消当前任务
acpx <agent> set-mode <mode>         # 设置模式
acpx <agent> set <key> <value>       # 设置选项
acpx <agent> status                  # 查看状态

全局选项

选项	说明
--agent <cmd>	原始 ACP agent 命令（逃逸口）
--cwd <dir>	工作目录（影响会话作用域）
--approve-all	自动批准所有权限请求
--approve-reads	批准读取，写入需确认（默认）
--deny-all	拒绝所有权限请求
--format <fmt>	输出格式：text/json/quiet
--timeout <s>	最大等待时间
--ttl <s>	队列所有者空闲 TTL（默认 300s）
--verbose	详细日志

输出格式

text（默认）

人类可读的流式输出，带更新和工具状态。

json

NDJSON 事件流，适合自动化：

acpx --format json qwen 'review code' | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

quiet

仅输出最终结果，适合脚本：

result=$(acpx --format quiet qwen exec 'summarize repo')

实用工作流

持久仓库助手

# 第一次：分析问题
acpx qwen 'inspect failing tests and propose a fix plan'

# 后续：继续同一会话
acpx qwen 'apply the smallest safe fix and run tests'

并行命名流

acpx qwen -s backend 'fix API pagination bug'
acpx qwen -s docs 'draft changelog entry for release'

队列异步提交

# 启动任务
acpx qwen 'run full test suite and investigate failures'

# 不等待，排队执行
acpx qwen --no-wait 'after tests, summarize root causes'

一次性脚本步骤

summary=$(acpx --format quiet exec 'summarize repo purpose in 3 lines')
echo "Summary: $summary"

机器可读输出用于编排

acpx --format json qwen 'review current branch changes' > events.ndjson

使用自定义 adapter

acpx --agent './bin/custom-acp-server --profile ci' 'run validation checks'

指定工作目录

acpx --cwd ~/repos/myproject --approve-all qwen -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'

会话行为

会话作用域由以下决定：

• agentCommand（agent 命令）
• 绝对 cwd（工作目录）
• 可选的 session name

持久化：

• 会话记录存储在 ~/.acpx/sessions/*.json
• -s/--session 在同一仓库创建并行命名对话
• 关闭的会话保留 closed: true 和 closedAt 时间戳
• 自动恢复跳过已关闭的会话

队列机制

每个持久会话有独立队列：

• 当前运行的 acpx 进程成为队列所有者
• 其他调用通过本地 IPC 提交 prompt
• Unix 使用 ~/.acpx/queues/<hash>.sock
• Windows 使用命名管道
• 所有者空闲 TTL 后自动关闭（默认 300s）

配置文件

配置合并顺序（后优先）：

1. 全局：~/.acpx/config.json
2. 项目：<cwd>/.acpxrc.json

支持配置：

• defaultAgent：默认 agent
• defaultPermissions：权限模式
• ttl：空闲 TTL
• timeout：超时
• format：输出格式
• agents：agent 名称映射
• auth：认证凭据

acpx config show   # 查看配置
acpx config init   # 初始化全局配置模板

错误处理

• NO_SESSION：无持久会话，需先 sessions new
• 权限被拒绝：所有权限请求被拒绝时退出
• 超时：超过 --timeout 时退出
• Ctrl+C：发送 ACP session/cancel，等待后强制终止