ACP エージェント

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

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

OpenClaw を疑う前に、次を確認してください。

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

• Spawn は ACP ランタイムセッションを作成または再開し、ACP メタデータを OpenClaw セッションストアに記録します。また、実行が親所有の場合はバックグラウンドタスクを作成することがあります。
• 親所有の ACP セッションは、ランタイムセッションが永続的であってもバックグラウンド作業として扱われます。完了とサーフェス横断の配信は、通常のユーザー向けチャットセッションのように振る舞うのではなく、親タスク通知機構を通じて行われます。
• タスクメンテナンスは、終端状態または孤立した親所有のワンショット ACP セッションを閉じます。永続 ACP セッションは、アクティブな会話バインディングが残っている間は保持されます。アクティブなバインディングがない古い永続セッションは、所有タスクが完了した後またはそのタスクレコードがなくなった後に暗黙に再開されないよう閉じられます。
• バインドされたフォローアップメッセージは、バインディングが閉じられる、フォーカス解除される、リセットされる、または期限切れになるまで、ACP セッションに直接送られます。
• Gateway コマンドはローカルに留まります。/acp ...、/status、/unfocus が、バインドされた ACP ハーネスに通常のプロンプトテキストとして送信されることはありません。
• cancel は、バックエンドがキャンセルをサポートしている場合にアクティブなターンを中止します。バインディングやセッションメタデータは削除しません。
• close は OpenClaw の視点から ACP セッションを終了し、バインディングを削除します。ハーネスが resume をサポートしている場合、ハーネス側の上流履歴は保持されることがあります。
• 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 はターンごとのネイティブ hook relay を注入し、plugin hooks が before_tool_call をブロックし、 after_tool_call を監視し、Codex PermissionRequest イベントを OpenClaw approvals 経由でルーティングできるようにします。Codex Stop hooks は OpenClaw before_agent_finalize にリレーされ、そこで plugins は Codex が回答を確定する前に もう1回のモデルパスを要求できます。このリレーは意図的に保守的なままです。 Codex ネイティブツールの引数を変更したり、Codex のスレッドレコードを書き換えたりしません。 ACP ランタイム/セッションモデルを使いたい場合にのみ、明示的な ACP を使用してください。 埋め込み Codex サポート境界は Codex harness v1 サポート契約に記載されています。

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

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

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

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

sessions_spawn では、ACP が有効で、requester がサンドボックス化されておらず、 ACP ランタイム backend が読み込まれている場合にのみ、runtime: "acp" が通知されます。 acp.dispatch.enabled=false は自動 ACP スレッド dispatch を一時停止しますが、 明示的な sessions_spawn({ runtime: "acp" }) 呼び出しを隠したりブロックしたりしません。 これは codex、claude、droid、gemini、opencode などの ACP harness id を対象にします。 そのエントリが agents.list[].runtime.type="acp" で明示的に構成されていない限り、 agents_list から通常の OpenClaw config agent id を渡さないでください。 それ以外の場合は、既定の sub-agent ランタイムを使用します。OpenClaw agent が runtime.type="acp" で構成されている場合、OpenClaw は runtime.acp.agent を基盤となる harness id として使用します。

• --bind here と --thread ... は相互排他的です。
• --bind here は、現在の会話へのバインディングを通知するチャンネルでのみ機能します。それ以外の場合、OpenClaw は明確な未サポートメッセージを返します。バインディングは gateway 再起動後も永続します。
• Discord では、spawnSessions が --thread auto|here の子スレッド作成を制御します。--bind here は対象ではありません。
• --cwd なしで別の ACP agent に spawn した場合、OpenClaw は既定で対象 agent の workspace を継承します。継承されたパスが存在しない場合 (ENOENT/ENOTDIR) は backend 既定に fallback します。その他のアクセスエラー (例: EACCES) は spawn エラーとして表示されます。
• 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 harness へのプロンプトではありません。

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

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

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

• セッション/スレッドバインディング機能を公開する任意のチャンネルアダプター。
• 現在の組み込みサポート: 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" を報告します。

新しく開始する代わりに、前の 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 会話履歴を復元します。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" とストリームリレー経路は、別の より詳細な統合パスです。