ACP エージェント

• plugins.allow が設定されている場合、それは制限的なPluginインベントリであり、必ず acpx を含める必要があります。そうでない場合、インストール済みの ACP バックエンドは意図的にブロックされ、/acp doctor は allowlist エントリの欠落を報告します。
• Codex ACP アダプターは acpx Pluginとともにステージングされ、可能な場合はローカルで起動されます。
• Codex ACP は分離された CODEX_HOME で実行されます。OpenClaw はホストの Codex 設定から信頼済みプロジェクトエントリのみをコピーし、アクティブなワークスペースを信頼します。認証、通知、フックはホスト設定に残します。
• 他の対象ハーネスアダプターは、初回使用時に必要に応じて npx で取得される場合があります。
• そのハーネスのベンダー認証は、引き続きホスト上に存在している必要があります。
• ホストに npm またはネットワークアクセスがない場合、キャッシュを事前にウォームアップするか、別の方法でアダプターをインストールするまで、初回実行時のアダプター取得は失敗します。

ACP は実際の外部ハーネスプロセスを起動します。OpenClaw はルーティング、バックグラウンドタスク状態、配信、バインディング、ポリシーを担当します。ハーネスはプロバイダーログイン、モデルカタログ、ファイルシステム動作、ネイティブツールを担当します。

OpenClaw の問題と判断する前に、次を確認してください。

• /acp doctor が、有効で正常なバックエンドを報告している。
• allowlist が設定されている場合、対象 id が acp.allowedAgents で許可されている。
• ハーネスコマンドが Gateway ホストで起動できる。
• そのハーネスのプロバイダー認証（claude、codex、gemini、opencode、droid など）が存在している。
• 選択したモデルがそのハーネスに存在している - モデル id はハーネス間で移植可能ではありません。
• 要求された cwd が存在しアクセス可能である。または cwd を省略し、バックエンドにデフォルトを使用させる。
• 権限モードが作業に一致している。非対話型セッションではネイティブの権限プロンプトをクリックできないため、書き込み/実行の多いコーディング実行では通常、ヘッドレスで続行できる ACPX 権限プロファイルが必要です。

• 生成は ACP ランタイムセッションを作成または再開し、OpenClaw セッションストアに ACP メタデータを記録し、実行が親所有の場合はバックグラウンドタスクを作成する場合があります。
• 親所有の ACP セッションは、ランタイムセッションが永続的な場合でもバックグラウンド作業として扱われます。完了とサーフェス横断の配信は、通常のユーザー向けチャットセッションのように動作するのではなく、親タスク通知機構を通じて行われます。
• タスクメンテナンスは、終了済みまたは孤立した親所有の単発 ACP セッションを閉じます。永続 ACP セッションは、アクティブな会話バインディングが残っている間は保持されます。アクティブなバインディングのない古い永続セッションは、所有タスクが完了した後、またはそのタスクレコードがなくなった後に静かに再開できないよう閉じられます。
• バインドされたフォローアップメッセージは、バインディングが閉じられる、フォーカス解除される、リセットされる、または期限切れになるまで、ACP セッションに直接送られます。
• Gateway コマンドはローカルにとどまります。/acp ...、/status、/unfocus は、通常のプロンプトテキストとしてバインド済み ACP ハーネスに送信されることはありません。
• cancel は、バックエンドがキャンセルをサポートしている場合にアクティブなターンを中止します。バインディングやセッションメタデータは削除しません。
• close は OpenClaw の観点から ACP セッションを終了し、バインディングを削除します。ハーネスが再開をサポートしている場合、独自の上流履歴を保持することがあります。
• acpx Pluginは close 後に OpenClaw 所有のラッパーおよびアダプタープロセスツリーをクリーンアップし、Gateway 起動時に古い OpenClaw 所有の ACPX 孤立プロセスを回収します。
• アイドル状態のランタイムワーカーは acp.runtime.ttlMinutes 後にクリーンアップ対象になります。保存されたセッションメタデータは /acp sessions で引き続き利用できます。

有効な場合にネイティブ Codex Pluginへルーティングすべき自然言語トリガー:

• 「この Discord チャンネルを Codex にバインドする。」
• 「このチャットを Codex スレッド <id> に添付する。」
• 「Codex スレッドを表示してから、これをバインドする。」

ネイティブ Codex 会話バインディングがデフォルトのチャット制御パスです。 OpenClaw の動的ツールは引き続き OpenClaw 経由で実行されますが、 shell/apply-patch などの Codex ネイティブツールは Codex 内で実行されます。 Codex ネイティブツールイベントについては、OpenClaw がターンごとのネイティブ フックリレーを注入し、Plugin フックが before_tool_call をブロックし、 after_tool_call を監視し、Codex PermissionRequest イベントを OpenClaw の承認経由でルーティングできるようにします。Codex Stop フックは OpenClaw before_agent_finalize にリレーされ、そこで Plugin は Codex が回答を 確定する前に、モデルパスをもう1回要求できます。このリレーは 意図的に保守的なままです。Codex ネイティブツールの 引数を変更したり、Codex スレッド記録を書き換えたりしません。ACP ランタイム/セッションモデルが 必要な場合にのみ、明示的な ACP を使用してください。埋め込み Codex サポート境界は Codex harness v1 サポート契約に記載されています。

• openai-codex/* - doctor により修復される従来の Codex OAuth/サブスクリプションモデルルート。
• openai/* - OpenAI エージェントターン用のネイティブ Codex app-server 埋め込みランタイム。
• /codex ... - ネイティブ Codex 会話制御。
• /acp ... または runtime: "acp" - 明示的な ACP/acpx 制御。

ACP ランタイムにルーティングすべきトリガー:

• 「これをワンショットの Claude Code ACP セッションとして実行し、結果を要約してください。」
• 「このタスクにはスレッド内で Gemini CLI を使用し、その後のフォローアップを同じスレッドに保持してください。」
• 「バックグラウンドスレッドで ACP 経由で Codex を実行してください。」

OpenClaw は runtime: "acp" を選択し、ハーネス agentId を解決し、 サポートされている場合は現在の会話またはスレッドにバインドし、 クローズ/期限切れまでフォローアップをそのセッションにルーティングします。Codex は ACP/acpx が明示されている場合、または要求された操作でネイティブ Codex Plugin が利用できない場合にのみ、このパスに従います。

sessions_spawn では、runtime: "acp" は ACP が有効で、リクエスターがサンドボックス化されておらず、ACP ランタイム バックエンドが読み込まれている場合にのみ公開されます。acp.dispatch.enabled=false は自動 ACP スレッドディスパッチを一時停止しますが、明示的な sessions_spawn({ runtime: "acp" }) 呼び出しを隠したりブロックしたりしません。対象は codex、 claude、droid、gemini、opencode などの ACP ハーネス ID です。通常の OpenClaw 設定エージェント ID を agents_list から渡さないでください。ただし、そのエントリーが agents.list[].runtime.type="acp" で明示的に設定されている場合は除きます。 それ以外の場合は、デフォルトのサブエージェントランタイムを使用してください。OpenClaw エージェントが runtime.type="acp" で設定されている場合、OpenClaw は runtime.acp.agent を基盤となるハーネス ID として使用します。

• --bind here と --thread ... は相互排他的です。
• --bind here は現在の会話バインディングを公開しているチャンネルでのみ機能します。それ以外の場合、OpenClaw は明確な未サポートメッセージを返します。バインディングは Gateway 再起動後も維持されます。
• Discord では、spawnSessions は --thread auto|here の子スレッド作成を制御します - --bind here ではありません。
• --cwd なしで別の ACP エージェントにスポーンする場合、OpenClaw はデフォルトで ターゲットエージェントの ワークスペースを継承します。存在しない継承パス（ENOENT/ENOTDIR）はバックエンドのデフォルトにフォールバックします。その他のアクセスエラー（例: EACCES）はスポーンエラーとして表面化します。
• Gateway 管理コマンドはバインド済み会話内でローカル処理のままです - 通常のフォローアップテキストがバインド済み ACP セッションにルーティングされる場合でも、/acp ... コマンドは OpenClaw によって処理されます。/status と /unfocus も、そのサーフェスでコマンド処理が有効な場合は常にローカル処理のままです。

チャンネルアダプターでスレッドバインディングが有効な場合:

• OpenClaw はスレッドをターゲット ACP セッションにバインドします。
• そのスレッド内のフォローアップメッセージはバインド済み ACP セッションにルーティングされます。
• ACP 出力は同じスレッドに返されます。
• フォーカス解除/クローズ/アーカイブ/アイドルタイムアウト、または max-age の期限切れによりバインディングが削除されます。
• /acp close、/acp cancel、/acp status、/status、/unfocus は Gateway コマンドであり、ACP ハーネスへのプロンプトではありません。

スレッドバインド ACP に必要な機能フラグ:

• acp.enabled=true
• acp.dispatch.enabled はデフォルトでオンです（自動 ACP スレッドディスパッチを一時停止するには false を設定します。明示的な sessions_spawn({ runtime: "acp" }) 呼び出しは引き続き機能します）。
• チャンネルアダプターのスレッドセッションスポーンが有効（デフォルト: true）:
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

スレッドバインディングのサポートはアダプター固有です。アクティブなチャンネル アダプターがスレッドバインディングをサポートしていない場合、OpenClaw は明確な 未サポート/利用不可メッセージを返します。

• セッション/スレッドバインディング機能を公開する任意のチャンネルアダプター。
• 現在の組み込みサポート: Discord スレッド/チャンネル、Telegram トピック（グループ/スーパーグループ内のフォーラムトピックと DM トピック）。
• Plugin チャンネルは同じバインディングインターフェイスを通じてサポートを追加できます。

対話型セッションは、表示されているチャットサーフェスで会話を続けることを意図しています。

• /acp spawn ... --bind here は現在の会話を ACP セッションにバインドします。
• /acp spawn ... --thread ... はチャンネルのスレッド/トピックを ACP セッションにバインドします。
• 永続的に構成された bindings[].type="acp" は、一致する会話を同じ ACP セッションにルーティングします。

バインドされた会話内のフォローアップメッセージは ACP セッションへ直接ルーティングされ、 ACP の出力は同じチャンネル/スレッド/トピックへ戻されます。

OpenClaw がハーネスへ送信する内容:

• 通常のバインド済みフォローアップはプロンプトテキストとして送信され、ハーネス/バックエンドがサポートする場合にのみ添付ファイルも送信されます。
• /acp 管理コマンドとローカル Gateway コマンドは、ACP ディスパッチ前にインターセプトされます。
• ランタイム生成の完了イベントは対象ごとに具体化されます。OpenClaw エージェントは OpenClaw の内部 runtime-context エンベロープを受け取り、外部 ACP ハーネスは子の結果と指示を含むプレーンなプロンプトを受け取ります。生の <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> エンベロープを外部ハーネスへ送信したり、ACP ユーザートランスクリプトテキストとして永続化したりしてはいけません。
• ACP トランスクリプトエントリは、ユーザーに見えるトリガーテキストまたはプレーンな完了プロンプトを使用します。内部イベントメタデータは可能な場合は OpenClaw 内で構造化されたまま保持され、ユーザー作成のチャットコンテンツとして扱われません。

別のエージェント実行によってスポーンされたワンショット ACP セッションは、 サブエージェントに似たバックグラウンドの子です。

• 親は sessions_spawn({ runtime: "acp", mode: "run" }) で作業を要求します。
• 子は自身の ACP ハーネスセッション内で実行されます。
• 子ターンはネイティブのサブエージェントスポーンと同じバックグラウンドレーンで実行されるため、遅い ACP ハーネスが無関係なメインセッション作業をブロックしません。
• 完了はタスク完了通知パスを通じて報告されます。OpenClaw は外部ハーネスへ送信する前に内部完了メタデータをプレーンな ACP プロンプトへ変換するため、ハーネスは OpenClaw 専用のランタイムコンテキストマーカーを見ません。
• ユーザー向けの返信が有用な場合、親は子の結果を通常のアシスタント音声で書き直します。

このパスを、親と子の間のピアツーピアチャットとして扱わないでください。 子には、親へ戻る完了チャンネルがすでにあります。

sessions_send はスポーン後に別のセッションを対象にできます。通常のピアセッションでは、 OpenClaw はメッセージを注入した後、エージェント間（A2A）フォローアップパスを使用します。

• 対象セッションの返信を待ちます。
• 必要に応じて、リクエスターと対象に制限された回数のフォローアップターンを交換させます。
• 対象に通知メッセージを生成するよう依頼します。
• その通知を表示中のチャンネルまたはスレッドへ配信します。

この A2A パスは、送信者に表示可能なフォローアップが必要なピア送信向けのフォールバックです。 たとえば広い tools.sessions.visibility 設定のもとで、無関係なセッションが ACP 対象を見てメッセージ送信できる場合にも有効なままです。

OpenClaw が A2A フォローアップをスキップするのは、リクエスターが自分自身の、 親が所有するワンショット ACP 子の親である場合だけです。この場合、タスク完了の上に A2A を実行すると、子の結果で親を起こし、親の返信を子へ送り返し、 親/子のエコーループを作成する可能性があります。完了パスがすでに結果を担当しているため、 sessions_send の結果は、その所有子ケースで delivery.status="skipped" を報告します。

新しく開始する代わりに以前の ACP セッションを続行するには、resumeSessionId を使用します。 エージェントは session/load によって会話履歴を再生するため、 以前の完全なコンテキストを引き継ぎます。

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

一般的なユースケース:

• Codex セッションをラップトップからスマートフォンへ引き渡す - エージェントに中断したところから続けるよう伝えます。
• CLI で対話的に開始したコーディングセッションを、今度はエージェント経由でヘッドレスに続行する。
• Gateway の再起動またはアイドルタイムアウトによって中断された作業を再開する。

注:

• resumeSessionId は runtime: "acp" の場合にのみ適用されます。デフォルトのサブエージェントランタイムは、この ACP 専用フィールドを無視します。
• streamTo は runtime: "acp" の場合にのみ適用されます。デフォルトのサブエージェントランタイムは、この ACP 専用フィールドを無視します。
• resumeSessionId はホストローカルな ACP/ハーネス再開 ID であり、OpenClaw チャンネルセッションキーではありません。OpenClaw はディスパッチ前に ACP スポーンポリシーと対象エージェントポリシーを引き続きチェックしますが、その上流 ID の読み込みに関する認可は ACP バックエンドまたはハーネスが所有します。
• resumeSessionId は上流 ACP 会話履歴を復元します。作成する新しい OpenClaw セッションには thread と mode が通常どおり適用されるため、mode: "session" には引き続き thread: true が必要です。
• 対象エージェントは session/load をサポートしている必要があります（Codex と Claude Code はサポートしています）。
• セッション ID が見つからない場合、スポーンは明確なエラーで失敗します。新しいセッションへの暗黙のフォールバックはありません。

Gateway のデプロイ後は、単体テストを信頼するだけでなく、 ライブのエンドツーエンドチェックを実行します:

1. ターゲットホスト上のデプロイ済み Gateway バージョンとコミットを検証します。
2. ライブエージェントへの一時 ACPX ブリッジセッションを開きます。
3. そのエージェントに、runtime: "acp"、agentId: "codex"、mode: "run"、タスク Reply with exactly LIVE-ACP-SPAWN-OK で sessions_spawn を呼び出すよう依頼します。
4. accepted=yes、実際の childSessionKey、バリデーターエラーがないことを検証します。
5. 一時ブリッジセッションをクリーンアップします。

ゲートは mode: "run" のままにし、streamTo: "parent" はスキップします - スレッドにバインドされた mode: "session" とストリームリレーのパスは、別個の より充実した統合パスです。