tene/qum/acpx-faq

acpx 常见问题解答

通过 acpx (>= 0.19.3) 无头驱动编码智能体。

语法权威

语法来自二进制文件，而非本文件。acpx --skill show acpx 是供应商参考（约 43k 字符），是命令格式的最终决定者——不要将其转储到对话记录中。按此顺序检索：

1. acpx --help / acpx <cmd> --help - 你即将组合的标志。
2. 单个主题：acpx --skill show acpx | rg -B2 -A12 '<term>'，或一个章节：acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'。
3. 编写新内容（如流程、嵌入式运行时）：一次性转储到临时文件并 grep 该文件。

本文件不重复参考手册中已有的内容。它只包含参考手册缺失的部分：退出代码、失败语义、陷阱以及每个智能体的配方。如果此处未解答语法问题，则应在参考手册中找到答案——请去获取它，永远不要猜测标志。仓库的 docs/（退出代码、会话控制、会话观看、权限、配置）涵盖了发布版参考手册中省略的一些内容。

何时使用此通道

acpx 是无头进程外执行器通道：另一个智能体、供应商或账户，从脚本或另一个智能体驱动，在普通终端、ssh 或 cron 中运行。会话内的扇出操作应保留在框架自己的子智能体工具上。

不变量

1. 全局标志位于智能体子命令之前（--cwd、--model、--approve-all、--agent、--format、--timeout、--ttl、--mcp-config）。提示形式只接受 -s、--no-wait、-f（exec 还接受 --config-option）；其他子命令有自己的标志（sessions watch --cursor、sessions export|import --cwd）。智能体后的全局标志退出 1 并显示错误 error: unknown option；智能体前的不良标志退出 2。

2. -s <name> 从不创建会话。 它解析一个会话，从 --cwd 向上查找到最近的 .git - 一个目录或文件，因此每个工作树和子模块都是自己的边界；在 git 外部仅检查确切的 --cwd。无匹配项退出 4。先在同一个目录中使用 sessions ensure --name <n> 创建。

3. status 不是转向信号。 它探测队列拥有者进程，从不探测智能体，并在回合结束后仍持续报告 running。永远不要基于它来自动化操作。

4. 权限标志不是沙箱。

   • claude：适配器从 Claude 设置的 permissions.defaultMode 开始（acceptEdits / auto 自动批准编辑而无需询问）。只有该模式升级的请求才会到达 acpx 作为权限请求 - --deny-all 会拒绝它们（退出 5），但自动批准的编辑永远不会询问。
   • codex：在其工作区写入沙箱内（根目录为 --cwd，加上临时目录）的写入不会引发请求，因此 --deny-all 仍会写入；外部写入失败并显示 Operation not permitted - 包括链接工作树的 gitdir，因此 git worktree 中的沙箱通道无法提交（index.lock: Operation not permitted）。除非 config.toml 启用了 network_access，否则网络是关闭的。--approve-all 不会更改适配器的模式；在启动时使用 INITIAL_AGENT_MODE=read-only|agent|agent-full-access，或在活动会话上使用 codex set-mode agent-full-access -s <n> 可以更改。
   • --allowed-tools / --max-turns 仅影响 claude（和 qoder）；codex 和 agy 忽略它们。--allowed-tools 预先批准且从不限制：--help 中的 "" for no tools 表示没有批准，而不是没有工具。

   真正的文件系统控制是你传递给它的 --cwd。

5. [done] end_turn 和退出 0 不是成功的证明。 内容过滤器终止、MCP 加载失败、API 错误（令牌刷新期间的 401、模型被拒的 400）或截断的回合都会以这种方式结束。读取流，或要求智能体写入一个你可以检查的结果文件。在扇出之前，每个智能体和模型进行一次廉价的 exec（如“回复 OK”）可以捕获身份验证和模型错误 - codex 和 agy 在回合开始前拒绝未通告的 --model，claude 会发出警告并转发。

6. 持久化会话仅在忙碌或热状态时持有驻留进程栈。 每次 -s 提示都会选举一个队列拥有者，持有 npm exec -> node <adapter> -> <agent>（加上智能体的 MCP 服务器），在 MCP 之前大约 550-650 MB。空闲 TTL（默认 300 秒）后，拥有者退出，会话保持可恢复状态；下一个提示会重新生成它。sessions close 结束任务 - 将其链入启动行（参见每个智能体），以便拆解从不依赖于任何人记住；--ttl 0 移除自我回收。见“拆解”。

每个智能体

一次性派发：sessions ensure && prompt && sessions close，一次链式调用。 每个任务一个命名会话、一个提示，读取结果文件后关闭。&& 链使拆解成为机械操作 - 不会有未关闭的记录，而孤儿记录来自未链式关闭的调用 - 而非零失败（超时 3、权限 5）的回合会自行跳过关闭，保持会话打开以供恢复（见“与活动会话通信”）。外部取消的回合仍会退出 0，因此结果文件（而不是退出代码）是成功检查点（不变量 5）。不要为预期的后续操作保留会话：阻塞因素的状态存在于对话之外（凭据是机器级别的，局部结果属于结果文件） - 使用带有简报和该文件的全新会话来回答它。返工 - 对会话输出的修正、审查或润色 - 也使用全新会话：智能体重读自己的上下文会错过新视角捕捉到的问题。永远不要 --no-wait 进入其启动行带有关闭的会话：拥有者关闭会静默丢弃挂起的提示并取消活动回合（经验证 0.19.4）；关闭前的阻塞提示是安全的。对于无需保留记录的无状态答案（如预检“回复 OK”），使用 exec。会话以智能体命令 + cwd + 名称为键；为每个并行执行器提供自己的名称，并在写入文件时提供自己的目录（理想情况下是一个工作树）。

适配器通过 npm exec 运行，除非适配器二进制文件（claude-agent-acp、codex-acp）在 PATH 上 - 该副本优先于包回退，升级 acpx 永远不会更新它。每个作业的新 HOME 会重新下载它们（每个数百 MB）；共享一个 npm_config_cache。在 macOS 上，新 HOME 也会隐藏登录钥匙串：claude 适配器会失败 RUNTIME: Unable to validate model: Could not resolve authentication method - 请保留 HOME。npx 缓存也会重用过时的构建 - 在 ~/.acpx/config.json（agents.<name>.argv）中固定确切的适配器版本。固定会冻结哪些模型 ID 可用，更改它会重新键会话（见“会话”）。

执行器继承用户的全局指令文件（claude 的 ~/.claude/CLAUDE.md、codex 的全局 AGENTS.md）。像“编辑前先询问”这样的规则会结束于一个没有完成任何工作的询问上 - 在每个简报的开头写上“立即行动；不要停下来询问或以问题结束”。在那里读到“使用进程外执行器”的执行器可能会启动一个嵌套的 acpx 通道进入同一个检出目录 - 添加“你是执行器；不要委托”。在重新启动前删除或重命名旧的结果文件（轮询器会读取旧文件），并为并行通道提供自己的临时路径和端口 - 单独的工作树不能隔离 /tmp。

它们还继承了启动器的环境，codex 的 zsh 会为每个命令重新读取 $ZDOTDIR/.zshenv（默认 ~/.zshenv） - 在启动器中取消设置秘密并不能阻止其进入，并且 shell 打印的任何内容都会落在 ~/.codex/sessions 下的推出文件中。

agy / Antigravity

内置的 acpx antigravity (0.17.1+) 从 PATH 运行 agy_acp_server.par，而 Antigravity 安装在 ~/.local/lib/antigravity-acp/ 下的副本不在 PATH 上 - 裸 acpx antigravity 退出 1 并显示 Failed to spawn agent command: agy_acp_server.par。在该目录前添加 PATH 前缀，设置 agents.antigravity.argv，或使用 --agent <path>。内置的 gemini 智能体是公共 Gemini CLI - 一个不同的产品。.par 来自 Antigravity 安装或官方 ACP 注册表存档；将其与其同一版本的 localharness_external 助手放在一起（缺少助手只会记录 Localharness not found. 并继续），或将 ANTIGRAVITY_HARNESS_PATH 指向它。acpx 和 agy update 都不会刷新 .par：将其 --version 的 Build label: 与 ACP 注册表 进行比较，并一起交换两个文件（安装的助手是只读的 - 在复制新文件之前 rm -f 它）。

D=/abs/real/dir                              # 必须存在：根目录通过 realpath 解析
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
     exec "执行 $D/brief.md。将你的报告写入 $D/report.md。"

• --approve-all 是强制性的。 没有它，每次写入都会被拒绝：退出 5（或挂起直到退出 3），同时仍然打印 [done] end_turn 并且没有报告。

• 固定选项问题会使提示失败并退出 5，即使在 --approve-all 下也是如此（最后一行 Antigravity requested a user answer...） - 对于 --agent 启动也是如此。acpx 会让任何智能体的固定选项问题以此方式失败（PERMISSION_PROMPT_UNAVAILABLE）；agy 是它咬人的地方。编写永远不需要用户选择的简报。

• 仅使用 ACP 会话通告的 ID - 故意错误的 --model 会打印 Available models: 而不启动回合（服务器 1.4.5：gemini-4-argon、gemini-3.8-flash；努力 ID 中的 gemini-3.7-flash-{low,medium,high} ID 已消失）。agy models 是一个不同的列表。Flash 适合基于规则的大量工作，并且快得多，但在审查 / 错误搜寻工作中会错过真正的发现；在那里使用更强的模型。

• agy 会在未提示的情况下读取同级文件 - 共享目录的智能体会相互复制输出。每个智能体一个目录，并在相信一致数字之前对任何重新运行进行校验和。

• 认证：需要在 <GEMINI_HOME>/antigravity-acp/settings.json 中设置 auth.type（一次性）：

  mkdir -p ~/.gemini/antigravity-acp
  echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json
  

  没有它：立即显示 [error] RUNTIME: Authentication required（退出 1）。有了它但从未登录：session/new 会阻塞等待浏览器登录，直到 --timeout（退出 3） - 交互式登录一次。服务器的凭据与 agy CLI 的凭据分开：macOS 钥匙串（服务 gemini，账户 antigravity-acp），或在非 macOS 上或在设置了 AGY_ACP_FORCE_FILE_STORAGE=1 时为 <GEMINI_HOME>/antigravity-acp/acp_token.json。GEMINI_HOME 单独不能隔离 macOS 凭据。授权问题是服务器端的 - 不要通过切换到 gemini-api-key 或 GCP 项目（单独计费，不是修复）来“修复”它。

• 永远不要将位置智能体与 --agent 一起传递 - 退出 2。

• 验证提示：要求裸回复并读取整个日志。 agy 将答案路由到大脑工件文件中，因此 tail 无法区分“没有工具”和“在别处回答”。添加“不要创建任何文件”。

• agy 将 MCP 失败隐藏在看起来成功的回合中 - 退出 0、[done] end_turn，并且整个回复是 The MCP server '<name>' failed to initialize: ...。搜索 failed to initialize。

• 优先使用 exec。 在检查点中途的服务器死亡已被报告会永久破坏保存的对话（could not find doneCh for checkpoint）；唯一报告过的恢复方法是删除 ~/.gemini/antigravity-acp/conversations/<id>.db。

Linux / NixOS

内置智能体会自行添加所需的 --uid=。NixOS 还需要 CA 包，因此将 --agent（或 agents.antigravity.argv）指向一个包装脚本（~/.local/bin/agy-acp-server）：

#!/usr/bin/env bash
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
exec ~/.local/lib/antigravity-acp/agy_acp_server.par --uid= "$@"

没有 SSL_CERT_FILE，.par 嵌入的 OpenSSL 没有有效的 CA 路径；其本地代理报告 502 Bad Gateway: Failed to connect to backend API，并且回合仍以 [done] end_turn 和 退出 0 结束（不变量 5）。真正的 CERTIFICATE_VERIFY_FAILED 仅在 --alsologtostderr 下出现。

codex

D=/abs/dir
acpx --cwd "$D" codex sessions ensure --name work            # 幂等；-s 不能创建
acpx --cwd "$D" codex set model gpt-6-astra -s work
acpx --cwd "$D" codex set reasoning_effort high -s work
{ acpx --cwd "$D" --approve-all --timeout 5400 --suppress-reads \
     codex -s work '执行 ./brief.md。将你的报告写入 ./report.md。' && \
  acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# 失败的回合会跳过 close - 重新提示 -s work 以恢复，然后自行关闭

一次性：--model <id> exec --config-option reasoning_effort=low 内联设置模型和努力程度。

• codex 适配器（@agentclientprotocol/codex-acp）浮动在 ^1.1.5 上 - 行为可能在没有 acpx 升级的情况下更改，但破坏性的 2.x 超出范围。过时的适配器会拒绝较新的模型 ID：在 session/set_config_option 处显示 [error] RUNTIME: Invalid params（退出 1），或仍以 [done] end_turn、退出 0 结束的 400 model is not supported。固定一个当前版本：{"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}。精确固定仍然会浮动其内部的 codex 二进制文件（2.5.0 依赖于 @openai/codex ^0.165.0）。当账户缺少模型时，当前适配器也会出现相同症状：通告的列表因账户而异 - 在通道自己的登录下进行预检。
• OpenAI 的内容过滤器会杀死良性回合，这些回合会干净地结束（[done] end_turn，退出 0）。文件名、注释或提示中的词语如 race / sweep / exploit / attack 会触发它。在相信完成之前读取对话记录尾部；通过重新提示相同的 -s <name> 恢复（上下文会保留，除非重新连接失败 - acpx 然后静默回退到 session/new）并带有相关的工件文件。在简报中，用“攻击向量 (attack vector)”等代替。