ACPハーネスルーター

ACPハーネスルーター は何をしますか？

ユーザーの意図が「これをClaude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Grok Build/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode（ACPハーネス）で実行する」である場合、サブエージェントランタイムやPTYスクレイピングは使用しないでください。ACP対応フローを介してルーティングします。

Codexは特別です。通常のチャット/会話バインディングと制御には、デフォルトのACPパスではなく、ネイティブのCodexアプリサーバープラグイン（/codex bind、/codex threads、/codex resume）を使用する必要があります。ACPは、ユーザーが明示的にACP//acp/acpxを指定した場合、またはネイティブのCodexランタイム生成がまだ利用できないsessions_spawnを介してバックグラウンドの子セッションを生成する場合にのみ、Codexに使用します。

インテント検出

ユーザーがOpenClawに以下を依頼した場合、このスキルをトリガーします：

• Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Grok Build / Qwen / Kiro / Kimi / iFlow / Droid / Kilocodeで何かを実行する
• ACP、/acp、またはacpxを介して明示的にCodexを実行する
• 既存のハーネス作業を継続する
• 外部コーディングハーネスに指示を中継する
• 外部ハーネスの会話をスレッド状の会話として維持する

コーディングエージェントスレッドリクエストの必須事前チェック：

• ACPハーネス作業のスレッドを作成する前に、同じターンで最初にこのスキルを読んでください。
• 読んだ後は、以下の「OpenClaw ACPランタイムパス」に従ってください。ACPハーネススレッド生成にはmessage(action="thread-create")を使用しないでください。

モード選択

以下のいずれかのパスを選択します：

1. OpenClaw ACPランタイムパス（デフォルト）：sessions_spawn / ACPランタイムツールを使用します。
2. 直接acpxパス（電話ゲーム）：execを介してacpx CLIを使用し、ハーネスセッションを直接駆動します。

以下のいずれかに該当する場合は、直接acpxを使用します：

• ユーザーが直接acpx駆動を明示的に要求した場合
• ACPランタイム/プラグインパスが利用できないか、異常な場合
• タスクが「単にプロンプトをハーネスに中継する」だけで、OpenClaw ACPライフサイクル機能が必要ない場合

以下は使用しないでください：

• ハーネス制御のためのsubagentsランタイム
• ユーザーへの要件としての/acpコマンド委任
• acpxが利用可能な場合の、サポート対象ACPハーネスCLIのPTYスクレイピング

AgentIdマッピング

ユーザーがハーネスを直接指定した場合、以下のデフォルトを使用します：

• "openclaw" -> agentId: "openclaw"
• "claude" または "claude code" -> agentId: "claude"
• "codex" -> agentId: "codex"（明示的なACP/acpxリクエストまたはバックグラウンドACPランタイム生成の場合のみ）
• "copilot" または "github copilot" -> agentId: "copilot"
• "cursor" または "cursor cli" -> agentId: "cursor"
• "droid" または "factory droid" -> agentId: "droid"
• "opencode" -> agentId: "opencode"
• "gemini" または "gemini cli" -> agentId: "gemini"
• "grok build" または "grok-build" -> agentId: "grok-build"
• "iflow" -> agentId: "iflow"
• "kilocode" -> agentId: "kilocode"
• "kimi" または "kimi cli" -> agentId: "kimi"
• "kiro" または "kiro cli" -> agentId: "kiro"
• "qwen" または "qwen code" -> agentId: "qwen"

これらのデフォルトは、現在のacpx組み込みエイリアスと一致します。

grok-buildはACPXエージェントターゲットであり、xAIモデルID xai/grok-build-0.1ではありません。grok-buildをagentIdを介してルーティングします。完全修飾されたxAI参照は、OpenClawのmodelフィールドでのみ使用します。

ポリシーが選択されたIDを拒否する場合は、ポリシーエラーを明確に報告し、許可されているACPエージェントIDを尋ねてください。

OpenClaw ACPランタイムパス

必須の動作：

1. ACPハーネススレッド生成リクエストの場合、ツールを呼び出す前に、同じターンで最初にこのスキルを読んでください。
2. sessions_spawnを以下の設定で使用します：
   • runtime: "acp"
   • thread: true
   • mode: "session"（ユーザーが明示的にワンショットを希望する場合を除く）
3. ACPハーネススレッド作成には、messageとaction=thread-createを使用しないでください。sessions_spawnが唯一のスレッド作成パスです。
4. 要求された作業をtaskに配置し、ACPセッションがすぐにそれを取得できるようにします。
5. デフォルトのACPエージェントが不明でない限り、agentIdを明示的に設定します。
6. このパスが直接機能する場合、ユーザーにスラッシュコマンドやCLIの実行を依頼しないでください。

例：

ユーザー：「spawn a test codex ACP session in thread and tell it to say hi」

呼び出し：

{
  "task": "Say hi.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

スレッド生成リカバリポリシー

ユーザーがコーディングハーネスをスレッドで開始するように要求した場合、それをACPランタイムリクエストとして扱い、エンドツーエンドで満たそうとします。

ACPバックエンドが利用できない場合の必須の動作：

1. すぐにユーザーに代替パスを選択するように求めないでください。
2. まず、自動ローカル修復を試みます：
   • プラグインローカルに固定されたacpxがACPXプラグインパッケージにインストールされていることを確認します
   • ${ACPX_CMD} --versionを検証します
3. 再インストール/修復後、ゲートウェイを再起動し、その再起動をユーザーに代わって実行することを明示的に提案します。
4. 修復後、ACPスレッド生成を1回再試行します。
5. 修復+再試行が失敗した場合のみ、具体的なエラーを報告し、フォールバックオプションを提案します。

フォールバックを提案する場合、ACPを最初に維持します：

• オプション1：正確な失敗ステップを表示した後、ACP生成を再試行する
• オプション2：直接acpx電話ゲームフロー

これらのリクエストに対して、デフォルトでサブエージェントランタイムを使用しないでください。

ACPXインストールとバージョンポリシー（直接acpxパス）

このリポジトリでは、直接acpx呼び出しは、@openclaw/acpx拡張パッケージと同じ固定ポリシーに従う必要があります。

1. グローバルPATHではなく、プラグインローカルバイナリを優先します：
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. 拡張機能の依存関係から固定バージョンを解決します：
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. バイナリがないか、バージョンが一致しない場合は、プラグインローカルに固定されたバージョンをインストールします：
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>
4. 使用前に確認します：
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. インストール/修復でACPXアーティファクトが変更された場合は、ゲートウェイを再起動し、再起動を実行することを提案します。
6. ユーザーが明示的にグローバルインストールを要求しない限り、npm install -g acpxを実行しないでください。

設定して再利用します：

ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

直接acpxパス（「電話ゲーム」）

このパスを使用して、/acpやサブエージェントランタイムなしでハーネスセッションを駆動します。

ルール

1. ${ACPX_CMD}を呼び出すexecコマンドを使用します。
2. 会話ごとに安定したセッション名を再利用し、後続のプロンプトが同じハーネスコンテキストに留まるようにします。
3. クリーンなアシスタントテキストをユーザーに中継するために--format quietを優先します。
4. ユーザーがワンショット動作を希望する場合にのみ、exec（ワンショット）を使用します。
5. タスクのスコープがリポジトリコンテキストに依存する場合は、作業ディレクトリを明示的に指定します（--cwd）。

セッション命名

安定した名前を使用します。例：

• oc-<harness>-<conversationId>

ここで、conversationIdは利用可能な場合はスレッドID、それ以外の場合はチャンネル/会話IDです。

コマンドテンプレート

永続セッション（存在しない場合は作成し、その後プロンプト）：

${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"

ワンショット：

${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"

進行中のターンをキャンセル：

${ACPX_CMD} codex cancel -s oc-codex-<conversationId>

セッションを閉じる：

${ACPX_CMD} codex sessions close oc-codex-<conversationId>

acpxのハーネスエイリアス

• claude
• codex
• copilot
• cursor
• droid
• gemini
• grok-build
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

acpxの組み込みアダプターコマンド

デフォルトは次のとおりです：

• openclaw -> openclaw acp
• claude -> bundled @agentclientprotocol/[email protected]
• codex -> bundled @agentclientprotocol/[email protected] through OpenClaw's isolated CODEX_HOME wrapper
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• grok-build -> grok agent stdio
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

~/.acpx/config.jsonがagentsをオーバーライドする場合、それらのオーバーライドがデフォルトを置き換えます。 ローカルのCursorインストールがまだACPをagent acpとして公開している場合は、cursorエージェントのオーバーライドとして明示的に設定します。

障害処理

• acpx: command not found：
  • スレッド生成ACPリクエストの場合、すぐにACPXプラグインパッケージにプラグインローカルの固定されたacpxをインストールします
  • インストール後にゲートウェイを再起動し、自動的に再起動を実行することを提案します
  • その後、1回再試行します
  • ポリシーで明示的に要求されない限り、最初にインストール許可を求めないでください
  • 明示的に要求されない限り、グローバルacpxをインストールしないでください
• アダプターコマンドが見つからない（例：claude-agent-acpが見つからない）：
  • スレッド生成ACPリクエストの場合、最初に壊れた~/.acpx/config.jsonエージェントオーバーライドを削除して組み込みデフォルトを復元します
  • その後、フォールバックを提案する前に1回再試行します
  • ユーザーがバイナリベースのオーバーライドを希望する場合は、設定されたアダプターバイナリを正確にインストールします
• NO_SESSION：${ACPX_CMD} <agent> sessions new --name <sessionName>を実行してからプロンプトを再試行します。
• キューがビジー：完了を待つ（デフォルト）か、非同期動作が明示的に望まれる場合は--no-waitを使用します。

出力中継

ユーザーに中継する場合は、acpxコマンド結果から最終的なアシスタントテキスト出力を返します。ユーザーが詳細なログを要求しない限り、生のローカルツールノイズを中継しないでください。