ACP エージェント

• plugins.allow が設定されている場合、それは制限付きのプラグインインベントリであり、必ず acpx を含める必要があります。含まれていない場合、インストール済みの ACP バックエンドは意図的にブロックされ、/acp doctor は allowlist エントリがないことを報告します。
• Codex ACP アダプターは acpx プラグインとともにステージングされ、可能な場合はローカルで起動されます。
• 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 プラグインは close 後に OpenClaw 所有のラッパーおよびアダプタープロセスツリーをクリーンアップし、Gateway 起動時に古い OpenClaw 所有 ACPX 孤児プロセスを刈り取ります。
• アイドル状態のランタイムワーカーは acp.runtime.ttlMinutes 後にクリーンアップ対象になります。保存済みセッションメタデータは /acp sessions で引き続き利用できます。

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

• 「この 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 ハーネス v1 サポート契約に記載されています。

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

ACP ランタイムにルーティングする必要があるトリガー:

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

OpenClaw は runtime: "acp" を選択し、ハーネス agentId を解決し、 サポートされている場合は現在の会話またはスレッドにバインドし、 close/expiry までフォローアップをそのセッションにルーティングします。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[].runtime.type="acp" で明示的に構成されていない限り、agents_list から通常の OpenClaw config エージェント id を渡さないでください。 それ以外の場合は、デフォルトのサブエージェントランタイムを使用してください。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 出力は同じスレッドに返送されます。
• Unfocus/close/archive/idle-timeout または max-age expiry によってバインディングが削除されます。
• /acp close、/acp cancel、/acp status、/status、/unfocus は Gateway コマンドであり、ACP ハーネスへのプロンプトではありません。

スレッドバインド ACP に必要な feature flags:

• 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 チャンネルは同じバインディングインターフェイスを通じてサポートを追加できます。

対話型セッションは、可視チャット surface で会話を続けることを目的としています:

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

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

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

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

別のエージェント実行によって spawn された一回限りの ACP セッションは、sub-agent と同様のバックグラウンド子です:

• 親は sessions_spawn({ runtime: "acp", mode: "run" }) で作業を依頼します。
• 子は自身の ACP ハーネスセッション内で実行されます。
• 子ターンはネイティブ sub-agent spawn と同じバックグラウンド lane で実行されるため、遅い ACP ハーネスが無関係なメインセッション作業をブロックすることはありません。
• 完了は task-completion announce パス経由で報告されます。OpenClaw は内部完了メタデータを外部ハーネスへ送信する前にプレーンな ACP プロンプトへ変換するため、ハーネスは OpenClaw 専用のランタイムコンテキストマーカーを見ません。
• ユーザー向けの返信が有用な場合、親は子の結果を通常の assistant voice で書き直します。

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

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

• ターゲットセッションの返信を待ちます。
• 必要に応じて、要求元とターゲットに制限された回数のフォローアップターンを交換させます。
• ターゲットに announce メッセージを生成するよう依頼します。
• その announce を可視チャネルまたはスレッドへ配信します。

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

OpenClaw は、リクエスト元が自身の親所有のワンショット ACP 子の 親である場合にのみ、A2A フォローアップをスキップします。その場合、 タスク完了の上で 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>"}

一般的なユースケース:

• ノート PC の Codex セッションをスマートフォンへ引き継ぐ - 中断したところから続けるようエージェントに指示します。
• CLI で対話的に開始したコーディングセッションを、エージェント経由でヘッドレスに継続します。
• gateway の再起動やアイドルタイムアウトで中断された作業を再開します。

注意:

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

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" とストリームリレーパスは、 より高度な別個の統合パスです。