use-acpx

acpx

重要：必须在后台执行

必须对所有 acpx bash 命令使用 run_in_background: true。在前台运行 acpx 会阻塞 Claude Code，导致会话无法使用。

执行任何 acpx 命令时：

{
  "command": "acpx codex 'your prompt here'",
  "run_in_background": true
}

如果未在后台运行，Claude Code 将无限期阻塞，等待 Agent 完成。

acpx 是什么

acpx 是一个无头、可编写脚本的命令行客户端，用于 Agent Client Protocol（ACP）。它专为通过命令行进行 Agent 到 Agent 通信而构建，无需抓取 PTY。

警告：切勿将与 Claude 相关的 ACP Agent 与 acpx 搭配使用。使用 Claude 调用 Claude 会形成递归循环，并导致不可预测的行为。请使用 codex、openclaw、gemini 等替代 Agent。

核心功能：

• 为每个代码仓库／cwd 提供持久的多轮会话
• 单次执行模式（exec）
• 命名并行会话（-s/--session，仅限 prompt 动词）
• 支持队列的提示词提交，可选择启用即发即忘模式（--no-wait）
• 用于取消进行中轮次的协作式取消命令（cancel）
• 中断时通过 ACP session/cancel 优雅取消
• 会话控制方法（set-mode、set <key> <value>）
• 检测到子进程意外退出后重新连接／恢复 Agent
• 通过 stdin 或 --file 输入提示词
• 支持全局与项目合并的配置文件，以及 config show|init
• 检查会话元数据／历史记录（sessions show、sessions history）
• 通过 status 检查本地 Agent 进程
• 稳定的 ACP 客户端文件系统和终端请求方法
• 通过环境变量／配置凭据进行稳定的 ACP authenticate 握手
• 结构化流式输出（text、json、quiet）
• 内置 Agent 注册表，并提供原始 --agent 选项

安装

npm i -g acpx

如需正常复用会话，建议全局安装，而非使用 npx。

命令模型

prompt 是默认动词。命令遵循以下形式：

acpx [global_options] [<agent>] [verb] [prompt_options] [prompt_text...]

动词：prompt（默认）、exec、cancel、set-mode、set、status、sessions、config。如果省略提示词文本且 stdin 已通过管道传入，acpx 会从 stdin 读取。完整语法请参阅 ./references/cli.md。

内置 Agent 注册表

重要：请勿使用与 Claude 相关的 ACP Agent（例如 claude、@zed-industries/claude-agent-acp）。这会造成 Agent 调用 Agent 的递归情形，可能导致无限循环或意外行为。

友好的 Agent 名称会映射到相应命令：

• pi -> npx pi-acp
• openclaw -> openclaw acp
• codex -> npx @zed-industries/codex-acp
• gemini -> gemini --acp
• cursor -> cursor-agent acp
• copilot -> copilot --acp --stdio
• 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
• qwen -> qwen --acp

规则：

• 顶层 prompt、exec 和 sessions 的默认 Agent 为 codex。
• 未知的位置 Agent 标记会被视为原始 Agent 命令。
• --agent <command> 用于显式设置原始 ACP 适配器命令。
• 不要在同一命令中同时使用位置 Agent 和 --agent。

命令

Prompt（默认，持久会话）

acpx codex 'fix flaky tests'             # implicit prompt
acpx codex prompt 'fix flaky tests'      # explicit
acpx prompt 'fix flaky tests'            # defaults to codex

自动恢复作用域 (agentCommand, cwd, name?) 的已保存会话。如果不存在会话，则以代码 4 退出——请先运行 sessions new。支持队列：如果已有提示词正在执行，则将请求提交给当前运行队列的所有者。中断时，会先发送 ACP session/cancel，再强制终止进程。

Prompt 选项：-s/--session <name>、--no-wait、-f/--file <path>。

Exec（单次执行）

acpx codex exec 'summarize this repo'

在临时会话中运行单条提示词；不会复用或持久化会话状态。

注意：-s/--session 仅是 prompt 动词的选项，不适用于 exec。如需在不同工作目录中执行并行的单次任务模式，请参阅下文的 Cross-repo / worktree 部分。

取消 / 模式 / 设置

acpx codex cancel
acpx codex set-mode auto
acpx codex set approval_policy conservative

cancel 通过 IPC 发送协作式 session/cancel。set-mode 调用 ACP session/set_mode（模式 ID 由适配器定义）。set 调用 ACP session/set_config_option。两者在队列所有者处于活动状态时，都会通过队列所有者 IPC 路由。

会话

acpx sessions list
acpx sessions new [--name <name>]
acpx sessions close [name]
acpx sessions show [name]
acpx sessions history [name] [--limit <count>]
acpx status

acpx codex sessions new --name backend
acpx codex sessions close backend
acpx codex sessions show backend
acpx codex sessions history backend --limit 20
acpx codex status

主要行为：sessions 和 sessions list 等效。new 会为当前作用域创建一个新会话；如果该作用域中已有打开的会话，则会将其软关闭。show [name] 会打印元数据；history [name] 会打印轮次预览（默认 20 条）。

完整的子命令列表（包括 ensure）、所有标志、全局选项、配置键、会话作用域规则、队列内部机制、输出格式详情、权限模式和退出代码，请参阅 ./references/cli.md。

全局选项（摘要）

• --agent <command>：原始 ACP 命令（应急选项）
• --cwd <dir>：会话作用域的工作目录
• --approve-all / --approve-reads（默认）/ --deny-all：权限模式（互斥）
• --format <fmt>：text（默认）、json、quiet
• --timeout <seconds> / --ttl <seconds>：时间控制（TTL 默认值为 300s）
• --verbose：将 ACP/调试日志输出到 stderr

参考摘要

配置文件：按顺序合并 — ~/.acpx/config.json（全局）、<cwd>/.acpxrc.json（项目）。关键设置：defaultAgent、defaultPermissions、ttl、timeout、format、agents 映射、auth 映射。运行 acpx config show 查看配置；运行 acpx config init 创建全局模板。

会话行为：会话按 agentCommand + 绝对路径 cwd + 可选的 name 划分作用域。记录位于 ~/.acpx/sessions/*.json。提示词模式会沿目录向上查找到 git 根目录，自动恢复会话；若未找到会话，则以退出代码 4 退出（运行 sessions new）。失效的 PID 会重新生成。使用 -s/--session <name> 开启并行对话。

提示词排队：某个会话的首个 acpx 进程会成为队列所有者；其他进程通过本地 IPC 提交任务。默认行为：等待任务完成。--no-wait：入队后立即返回。Ctrl+C 会先发送 ACP session/cancel，再强制终止进程。空闲达到 TTL 后，所有者会关闭（默认 300s）。

输出格式：--format text（默认）输出人类可读的流；--format json 输出供自动化使用的 NDJSON；--format quiet 仅输出最终文本；--json-strict 禁止输出非 JSON 的 stderr 内容。

权限模式：选择一种 — --approve-all、--approve-reads（默认）、--deny-all。如果所有请求都被拒绝或取消，且没有任何请求获批，acpx 会以权限拒绝状态退出。

所有选项、子命令、退出代码和 IPC 内部机制的完整详情，请参阅 ./references/cli.md。

实用工作流

持久化的仓库助手（多轮对话）：

acpx codex 'inspect failing tests and propose a fix plan'
acpx codex 'apply the smallest safe fix and run tests'

并行命名会话 + 排队的后续任务：

acpx codex -s backend 'fix API pagination bug'
acpx codex -s docs 'draft changelog entry for release'
acpx codex --no-wait 'after tests, summarize root causes and next steps'

单次调用和自动化：

acpx --format quiet exec 'summarize repo purpose in 3 lines'
acpx --format json codex 'review current branch changes' > events.ndjson
acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'

跨仓库 / 工作树委派（当前仓库保持不变）：

# Same shell stays on the orchestration repo; the agent works elsewhere
acpx --cwd /home/dev/code/projectB codex exec 'audit failing CI in projectB'

# Parallel one-shots on isolated worktrees — no --session needed,
# each acpx process is naturally isolated by its --cwd
acpx --cwd /tmp/codex-worktrees/feat-A codex exec 'task A' &
acpx --cwd /tmp/codex-worktrees/feat-B codex exec 'task B' &
wait
# Note: when calling from Claude Code Bash tool, use run_in_background: true
# per-call instead — the &+wait pattern blocks the tool until both complete.

--cwd 会覆盖 Agent 所看到的工作目录，但技能、MCP 服务和配置仍从用户主目录加载（codex 使用 ~/.codex/）。将目标路径添加到 ~/.codex/config.toml 中的 [projects."<path>"]（Codex 侧的 TOML 配置），以避免首次使用时出现信任提示。

更多示例（包括 stdin/文件提示词、会话管理和 JSON 自动化管道），请参阅 ./references/cli.md。