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 が、有効で正常なバックエンドを報告していること。
• 許可リスト acp.allowedAgents が設定されている場合、対象 ID が許可されていること。
• ハーネスコマンドを Gateway ホスト上で起動できること。
• そのハーネス用のプロバイダー認証が存在すること（claude、codex、gemini、opencode、droid など）。
• 選択したモデルがそのハーネスに存在すること。モデル ID はハーネス間で互換ではありません。
• 要求した cwd が存在しアクセス可能であること。そうでなければ cwd を省略し、バックエンドのデフォルトを使用してください。
• 権限モードが作業内容に適合していること。非対話型セッションではネイティブの権限プロンプトをクリックできないため、書き込みやコマンド実行を多用するコーディング処理では通常、ヘッドレスで処理を続行できる ACPX 権限プロファイルが必要です。

• 起動すると ACP ランタイムセッションが作成または再開され、ACP メタデータが OpenClaw セッションストアに記録されます。また、実行が親所有の場合はバックグラウンドタスクが作成されることがあります。
• 親所有の 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 が回答を確定する前に もう一度モデルを実行するよう要求できます。このリレーは 意図的に保守的な動作を維持します。Codex ネイティブツールの引数を変更したり、 Codex のスレッド記録を書き換えたりすることはありません。ACP ランタイム／セッションモデルを使用したい場合にのみ、 ACP を明示的に使用してください。組み込み Codex のサポート境界については、 Codex ハーネス v1 サポート契約に 記載されています。

• 従来の Codex モデル参照 - 従来の Codex OAuth／サブスクリプションモデル経路。doctor によって修復されます。
• 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.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 の出力は同じスレッドへ配信されます。
• フォーカス解除／クローズ／アーカイブ／アイドルタイムアウトまたは最大経過時間による有効期限切れで、バインディングが削除されます。
• /acp close、/acp cancel、/acp status、/status、/unfocus は Gateway コマンドであり、ACP ハーネスへのプロンプトではありません。

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

• acp.enabled=true
• acp.dispatch.enabled はデフォルトでオンです（false に設定すると ACP スレッドの自動ディスパッチを一時停止します。明示的な 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 の内部ランタイムコンテキストエンベロープが渡され、外部 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": "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 の会話履歴を復元します。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" とストリームリレーのパスは、それぞれ別の、より高度な統合テストで確認します。