ACP エージェント

• plugins.allow が設定されている場合、それは制限付き Plugin インベントリであり、acpx を必ず含める必要があります。含まれていない場合、インストール済み ACP バックエンドは意図的にブロックされます（/acp doctor は許可リストにエントリがないことを報告します）。
• Codex ACP アダプターは acpx Plugin に同梱され、可能な場合はローカルで起動します。
• Codex ACP は分離された CODEX_HOME で実行されます。OpenClaw は、信頼済みプロジェクトの信頼エントリと、安全なモデル／プロバイダーのルーティング設定（model、model_provider、model_reasoning_effort、sandbox_mode、および安全な model_providers.<name> フィールド）をホストの Codex 設定からコピーします。認証、通知、フックはホスト設定にのみ保持されます。
• その他の対象ハーネスアダプターは、初回使用時に npx を使用してオンデマンドで取得される場合があります。
• そのハーネスのベンダー認証は、ホスト上にあらかじめ存在している必要があります。
• ホストで npm またはネットワークにアクセスできない場合、キャッシュを事前にウォームアップするか、別の方法でアダプターをインストールするまで、初回実行時のアダプター取得は失敗します。

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

OpenClaw に原因があると判断する前に、次を確認してください。

• /acp doctor が、有効で正常なバックエンドを報告すること。
• その許可リストが設定されている場合、対象 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 sessions で引き続き利用できます。

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

• 「この Discord チャンネルを Codex にバインドしてください。」
• 「このチャットを Codex スレッド <id> に接続してください。」
• 「Codex スレッドを表示してから、これをバインドしてください。」

ネイティブ Codex の会話バインディングが、チャット制御のデフォルト経路です。 OpenClaw の動的ツールは引き続き OpenClaw を通じて実行されますが、シェルや apply-patch などの Codex ネイティブツールは Codex 内で実行されます。Codex ネイティブのツールイベントに対して、OpenClaw はターンごとのネイティブフック リレーを挿入します。これにより、Plugin フックは before_tool_call をブロックし、 after_tool_call を監視し、Codex の PermissionRequest イベントを OpenClaw の 承認経由でルーティングできます。Codex の Stop フックは OpenClaw の before_agent_finalize に中継され、そこで Plugin は Codex が回答を 確定する前に、モデルをもう一度実行するよう要求できます。このリレーは意図的に 保守的な動作を維持します。Codex ネイティブツールの引数を変更したり、Codex スレッドレコードを書き換えたりすることはありません。ACP ランタイム／セッション モデルを使用したい場合にのみ、明示的な ACP を使用してください。組み込み Codex のサポート境界については、 Codex ハーネス v1 サポート契約 を参照してください。

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

• --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 の出力は同じスレッドへ返されます。
• フォーカス解除、クローズ、アーカイブ、アイドルタイムアウト、または最大存続期間の満了により、バインディングが削除されます。
• /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／Telegram：session.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 の内部ランタイムコンテキストエンベロープを受け取り、外部 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" を報告します。

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

{  "task": "中断したところから続けてください - 残っているテスト失敗を修正してください",  "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 の会話履歴を復元します。thread と mode は新しく作成する OpenClaw セッションにも通常どおり適用されるため、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" とストリームリレーパスは、 より高度な別個の統合パスです。