tenequm/acpx-faq

acpx FAQ

透過 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/（退出碼、session 控制、session 監看、權限、設定）涵蓋了出廠參考文件中遺漏的部分內容。

何時使用這個通道

acpx 是無頭的程序外執行器通道：由腳本或另一個代理驅動的另一個代理、供應商或帳戶，在純文字終端機、ssh 或 cron 中執行。會話內的分支（fan-out）則應使用主機（harness）自己的子代理工具。

不變量

1. 全域標誌必須在代理子指令之前（--cwd、--model、--approve-all、 --agent、--format、--timeout、--ttl、--mcp-config）。提示（prompt）指令形式只接受 -s、--no-wait、-f（而 exec 指令還接受 --config-option）；其他子指令 則有自己的標誌（sessions watch --cursor、sessions export|import --cwd）。在代理子指令之後出現的全域標誌會以退出碼 1 結束，並顯示 error: unknown option；而在代理子指令之前的錯誤標誌則會以退出碼 2 結束。

2. -s <name> 永遠不會建立 session。 它只會解析一個 session，從 --cwd 目錄向上尋找最近的 .git - 可以是目錄或檔案，因此每個工作樹（worktree）和子模組（submodule）都有自己的邊界；在 git 目錄之外，只會檢查精確的 --cwd。找不到符合的 session 會以退出碼 4 結束。請先在同一目錄中使用 sessions ensure --name <n> 建立。

3. status 不是方向燈。 它探測的是佇列擁有者（queue-owner）程序，而不是代理本身，並且在操作結束後仍會持續顯示 running。請永遠不要根據它來自動化任何流程。

4. 權限標誌不是沙箱。

   • claude：適配器從 Claude 設定的 permissions.defaultMode 開始執行（acceptEdits / auto 會自動批准編輯而不詢問）。只有該模式升級（escalates）的請求才會以權限請求的形式到達 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，或是在 live session 上執行 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）或回合被截斷，都可能以這種方式結束。請讀取串流（stream），或要求代理寫入一個您可以檢查的結果檔案。在進行分支（fan-out）之前，對每個代理和模型執行一次便宜的 exec（例如「回覆 OK」）可以捕捉到認證和模型錯誤——codex 和 agy 會在回合開始前拒絕未經宣告的 --model，而 claude 會發出警告並繼續轉發。

6. 持久化 session 只在忙碌或保持活躍（warm）時持有常駐程序堆疊。 每次 -s 提示都會選出一個佇列擁有者，它持有 npm exec -> node <adapter> -> <agent>（加上代理的 MCP 伺服器），在 MCP 之前大約佔用 550-650 MB。在閒置 TTL（預設 300 秒）過後，擁有者會退出，而 session 保持可恢復狀態；下一次提示會重新啟動它。sessions close 會結束任務——將它串連到啟動指令中（請參閱「各代理說明」），這樣清理工作就不會依賴任何人去記住；--ttl 0 則會移除自動清理機制。請參閱「清理」部分。

各代理說明

一次發送：sessions ensure && prompt && sessions close，一個鏈式呼叫。 每個任務一個具名 session，一個提示，在讀取結果檔案後關閉。&& 鏈結使得清理工作變成機械化——沒有未關閉的記錄，而孤兒 session 來自於未串連的 close——而一個非零退出（例如超時 3、權限 5）的回合會跳過自身的 close，讓 session 保持開啟以便復原（請參閱「與 live session 通訊」）。一個被外部取消的回合仍然會以退出碼 0 結束，因此結果檔案，而不是退出碼，才是成功的檢查點（不變量 5）。不要為了預期的後續工作而保留一個 session：阻擋者（blocker）的狀態存在於對話之外（憑證是機器層級的，部分結果應屬於結果檔案）——應該用一個新的 session 來回應，輸入簡短的摘要加上該檔案。重做（修正、審查或優化 session 的輸出）也應該使用新的 session：讓代理重新讀取自己的上下文，會錯過新視角才能發現的問題。絕對不要在啟動指令帶有關閉操作的 session 中使用 --no-wait：擁有者關閉時會靜默地丟棄待處理的提示，並取消當前的回合（已在 0.19.4 中驗證）；在關閉之前使用阻塞式提示是安全的。使用 exec 來取得不需要保留記錄的無狀態答案（例如用於預檢的「回覆 OK」）。Session 是根據「代理指令 + cwd + 名稱」來作為鍵值（key）的；請為每個並行執行器指定不同的名稱，並且在它要寫入檔案時，使用不同的目錄（最好是各自的工作樹）。

適配器透過 npm exec 執行，除非適配器二進位檔（claude-agent-acp、codex-acp）已在 PATH 上——這種情況下會優先使用該二進位檔，而不是套件後備方案，而且升級 acpx 也不會更新它。為每個任務使用全新的 HOME 目錄會導致重新下載它們（每個數百 MB）；請共用同一個 npm_config_cache。在 macOS 上，全新的 HOME 目錄也會隱藏登入鑰匙圈（Keychain）：Claude 適配器會失敗並顯示 RUNTIME: Unable to validate model: Could not resolve authentication method——請保留 HOME 目錄。npx 快取也可能重複使用過時的建置——請在 ~/.acpx/config.json（agents.<name>.argv）中鎖定確切的適配器版本。鎖定版本會凍結可用的模型 ID，而更改它會使 session 重新產生鍵值（請參閱「Sessions」）。

執行器會繼承使用者的全域指令檔案（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 且沒有報告。

• 固定選擇的問題即使在 --approve-all 下也會導致提示失敗並退出碼 5 （最後一行 Antigravity requested a user answer...）——對於 --agent 啟動也是如此。 acpx 會以相同方式使任何代理的固定選擇問題失敗（PERMISSION_PROMPT_UNAVAILABLE）； agy 是這個問題最常見的地方。請撰寫永遠不需要使用者選擇的簡短指令。

• 只使用 ACP session 所宣告的 ID——一個故意給錯的 --model 會印出 Available models: 而不開始回合（伺服器 1.4.5：gemini-4-argon、 gemini-3.8-flash；ID 中包含努力值的 gemini-3.7-flash-{low,medium,high} 已消失）。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 會將答案路由到大腦產物檔案（brain artifact files）中，因此 tail 無法區分「沒有使用工具」和「在其他地方回答了」。請加上「不要建立任何檔案」。

• agy 會將 MCP 失敗隱藏在一個看似成功的回合中——退出碼 0，[done] end_turn，而整個回應是 MCP 伺服器 '<名稱>' 初始化失敗：...。 請 grep 關鍵字 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：[error] RUNTIME: Invalid params 在 session/set_config_option 時（退出碼 1），或一個 400 model is not supported，但仍以 [done] end_turn 和退出碼 0 結束。請鎖定一個目前版本： {"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）並使用 ar

…

[已截斷以供翻譯]