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/（終了コード、セッション制御、セッション監視、権限、設定）は、出荷されたリファレンスが省略している一部をカバーしています。

このレーンを使用するタイミング

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 はディレクトリ またはファイルであり、各ワークツリーとサブモジュールが独自の境界となります。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（「Reply OK」）を1回実行すると、認証エラーとモデルエラーをキャッチできます。codexとagyは、ターンが開始される前にアドバタイズされていない --model を拒否し、claudeは警告を出力して転送します。

6. 永続セッションは、ビジー状態またはウォーム状態の間のみ、常駐プロセススタックを保持します。 すべての -s プロンプトは、npm exec -> node <adapter> -> <agent>（さらにエージェントのMCPサーバー）を保持するキュー所有者を選出します。MCP前でおおよそ550-650MBです。アイドルTTL（デフォルト300秒）が経過すると、所有者は終了し、セッションは再開可能な状態を維持します。次のプロンプトでセッションが再生成されます。sessions close はタスクを終了します。起動ラインにチェーンして組み込めば（「エージェントごと」を参照）、ティアダウンが誰かの記憶に依存することはなくなります。--ttl 0 は自己回収を削除します。「ティアダウン」を参照してください。

エージェントごと

ワンショットディスパッチ：sessions ensure && prompt && sessions close、1つのチェーンされた呼び出し。 タスクごとに1つの名前付きセッション、1つのプロンプト、結果ファイルが読み取られたら閉じます。&& チェーンによりティアダウンが機械的になります。開いたレコードを回収するものはなく、孤立はチェーンされていないクローズから発生します。一方、ゼロ以外で失敗したターン（タイムアウト3、権限5）はクローズをスキップし、セッションを回復のために開いたままにします（「実行中のセッションとの対話」を参照）。外部からキャンセルされたターンも終了コード0で終了するため、結果ファイルが成功チェックとなります（不変条件5）。フォローアップが予想されるからといってセッションを保持しないでください。ブロッカーの状態は会話の外部に存在します（クレデンシャルはマシンレベルであり、部分的な結果は結果ファイルに属します）。そのブリーフとそのファイルを新しいセッションに渡して回答します。リワーク（セッションの出力の修正、レビュー、またはポリッシュ）も新しいセッションで行います。エージェントが自身のコンテキストを再読しても、新鮮な視点で見つかるものは見逃します。閉じるための起動ラインを持つセッションに対して --no-wait を使用しないでください。所有者のシャットダウンは、保留中のプロンプトを静かにドロップし、アクティブなターンをキャンセルします（0.19.4で確認済み）。閉じる前のブロッキングプロンプトは安全です。記録に残す価値のないステートレスな回答（事前チェックの「Reply OK」）には exec を使用します。セッションはエージェントコマンド + cwd + 名前でキーが設定されます。各並列実行プログラムに独自の名前を付け、ファイルを書き込む場合には独自のディレクトリ（理想的には1つのワークツリー）を与えます。

アダプターは、アダプターバイナリ（claude-agent-acp、codex-acp）がPATH上にない限り、npm exec を介して実行されます。その場合、そのコピーがパッケージのフォールバックよりも優先され、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）を再読み取りします。ランチャーでシークレットを設定解除しても、それが除外されるわけではありません。そして、シェルが出力するものはすべて、~/.codex/sessions 以下のロールアウトファイルに含まれます。

agy / Antigravity

組み込みの acpx antigravity（0.17.1+）は agy_acp_server.par を PATHから 実行します。Antigravityが ~/.local/lib/antigravity-acp/ にインストールするコピーはPATH上にありません。そのまま acpx antigravity を実行すると、Failed to spawn agent command: agy_acp_server.par で終了コード1で終了します。そのディレクトリを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 "Carry out $D/brief.md. Write your report to $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セッションがアドバタイズするIDのみを使用してください。意図的に間違った --model を指定すると、Available models: が表示され、ターンは開始されません（サーバー1.4.5：gemini-4-argon、gemini-3.8-flash。IDに effort が含まれる gemini-3.7-flash-{low,medium,high} IDはなくなりました）。agy models は別のリストです。Flashはルーブリック駆動のバルク作業に適しており、はるかに高速ですが、レビュー/バグハンティング作業では実際の発見を見逃します。そこではより強力なモデルを使用してください。

• agyはプロンプトなしで兄弟ファイルを読み取ります。同じディレクトリを共有するエージェントは、お互いの出力を複製します。エージェントごとに1つのディレクトリを使用し、アグリーメント番号を信頼する前に再実行のチェックサムを確認してください。

• 認証：<GEMINI_HOME>/antigravity-acp/settings.json に auth.type が必要です（1回限り）：

  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 をgrepします。

• 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 'Carry out ./brief.md. Write your report to ./report.md.' && \
  acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# 失敗したターンはクローズをスキップします - 再度 -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 にフォールバックします）。 ...（翻訳のため切り詰められました）