Dwsy 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）
配置文件
配置合并顺序（后优先）：
- 全局：
~/.acpx/config.json - 项目：
<cwd>/.acpxrc.json
支持配置：
defaultAgent：默认 agentdefaultPermissions：权限模式ttl：空闲 TTLtimeout：超时format：输出格式agents：agent 名称映射auth：认证凭据
acpx config show # 查看配置
acpx config init # 初始化全局配置模板
错误处理
NO_SESSION：无持久会话，需先sessions new- 权限被拒绝：所有权限请求被拒绝时退出
- 超时：超过
--timeout时退出 - Ctrl+C：发送 ACP
session/cancel，等待后强制终止