サブエージェント

サブエージェントは、既存のエージェント実行から生成されるバックグラウンドのエージェント実行です。 それぞれ独自のセッション（agent:<agentId>:subagent:<uuid>）で実行され、 完了すると結果を要求元のチャットチャネルへ通知します。 各サブエージェント実行は バックグラウンドタスクとして追跡されます。

主な目標:

• メイン実行をブロックせずに「調査 / 長いタスク / 遅いツール」の作業を並列化する。
• デフォルトでサブエージェントを分離する（セッション分離 + 任意のサンドボックス化）。
• ツールサーフェスを誤用しにくく保つ: サブエージェントにはデフォルトでセッションツールが与えられません。
• オーケストレーターパターン向けに、設定可能なネスト深度をサポートする。

スラッシュコマンド

現在のセッションのサブエージェント実行を確認または制御するには、/subagents を使用します:

/subagents list/subagents kill <id|#|all>/subagents log <id|#> [limit] [tools]/subagents info <id|#>/subagents send <id|#> <message>/subagents steer <id|#> <message>/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

現在の要求元セッションのアクティブな実行を steer するには、トップレベルの /steer <message> を使用します。対象が子実行の場合は、/subagents steer <id|#> <message> を使用します。

/subagents info は実行メタデータ（ステータス、タイムスタンプ、セッション ID、トランスクリプトパス、クリーンアップ）を表示します。境界付きで安全フィルター済みの呼び出しビューには sessions_history を使用し、生の完全なトランスクリプトが必要な場合はディスク上のトランスクリプトパスを確認します。

スレッドバインディング制御

これらのコマンドは、永続的なスレッドバインディングをサポートするチャネルで動作します。下記のスレッドをサポートするチャネルを参照してください。

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

spawn の動作

/subagents spawn は、ユーザーコマンドとして（内部リレーではなく）バックグラウンドサブエージェントを開始し、実行が完了すると要求元チャットへ最後の完了更新を1件送信します。

コンテキストモード

ネイティブサブエージェントは、呼び出し元が現在のトランスクリプトの fork を明示的に要求しない限り、分離された状態で開始します。

fork は控えめに使用してください。これはコンテキスト依存の委任のためのものであり、明確なタスクプロンプトを書くことの代替ではありません。

ツール: sessions_spawn

グローバルな subagent レーンで deliver: false を指定してサブエージェント実行を開始し、その後通知ステップを実行して、要求元チャットチャネルへ通知返信を投稿します。

利用可否は、呼び出し元の有効なツールポリシーに依存します。coding および full プロファイルは、デフォルトで sessions_spawn を公開します。messaging プロファイルは公開しません。作業を委任する必要があるエージェントには、tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] を追加するか、tools.profile: "coding" を使用してください。チャネル/グループ、プロバイダー、サンドボックス、エージェントごとの許可/拒否ポリシーは、プロファイル段階の後でもツールを削除できます。同じセッションから /tools を使用して、有効なツールリストを確認してください。

デフォルト:

• モデル: agents.defaults.subagents.model（またはエージェントごとの agents.list[].subagents.model）を設定しない限り、呼び出し元を継承します。明示的な sessions_spawn.model はそれでも優先されます。
• Thinking: agents.defaults.subagents.thinking（またはエージェントごとの agents.list[].subagents.thinking）を設定しない限り、呼び出し元を継承します。明示的な sessions_spawn.thinking はそれでも優先されます。
• 実行タイムアウト: sessions_spawn.runTimeoutSeconds が省略された場合、設定されていれば OpenClaw は agents.defaults.subagents.runTimeoutSeconds を使用します。それ以外の場合は 0（タイムアウトなし）へフォールバックします。

委任プロンプトモード

agents.defaults.subagents.delegationMode はプロンプトガイダンスのみを制御します。ツールポリシーを変更したり、委任を強制したりするものではありません。

• suggest（デフォルト）: より大きい作業や遅い作業にはサブエージェントを使用するよう促す標準のプロンプトを維持します。
• prefer: メインエージェントに、応答性を保ち、直接返信より複雑なものは sessions_spawn を通じて委任するよう伝えます。

エージェントごとのオーバーライドには agents.list[].subagents.delegationMode を使用します。

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

ツールパラメーター

タスク名とターゲット指定

taskName はオーケストレーション用にモデルへ見せるハンドルであり、セッションキーではありません。 コーディネーターが後でその子を誘導または停止する必要がある場合に、review_subagents、 linux_validation、docs_update などの安定した子名として使用します。

ターゲット解決では、完全一致の taskName と曖昧でないプレフィックスを受け付けます。 照合は、番号付き /subagents ターゲットで使われるものと同じアクティブ/直近のターゲットウィンドウにスコープされるため、古い完了済みの子によって再利用されたハンドルが曖昧になることはありません。2 つのアクティブまたは直近の子が同じ taskName を共有している場合、ターゲットは曖昧です。代わりにリストインデックス、セッションキー、または実行 ID を使用してください。

予約済みターゲットの last と all は、すでに制御上の意味を持つため、有効な taskName 値ではありません。

ツール: sessions_yield

現在のモデルターンを終了し、主にサブエージェント完了イベントであるランタイムイベントが次のメッセージとして届くのを待ちます。要求元がそれらの完了を受け取るまで最終回答を生成できない場合、必要な子作業を生成した後に使用します。

sessions_yield は待機のプリミティブです。子の完了を検出するためだけに、subagents、sessions_list、sessions_history、シェルの sleep、プロセスポーリングに対するポーリングループで置き換えないでください。

セッションの有効なツールリストに含まれている場合にのみ sessions_yield を使用してください。一部の最小またはカスタムツールプロファイルでは、sessions_yield を公開せずに sessions_spawn と subagents を公開する場合があります。その場合、完了を待つためだけにポーリングループを作らないでください。

アクティブな子が存在する場合、OpenClaw は通常のターンにコンパクトなランタイム生成の Active Subagents プロンプトブロックを挿入します。これにより要求元は、ポーリングせずに現在の子セッション、実行 ID、ステータス、ラベル、タスク、taskName エイリアスを確認できます。そのブロック内のタスクおよびラベルフィールドは、命令ではなくデータとして引用されます。これは、ユーザー/モデルが提供した生成引数に由来する可能性があるためです。

ツール: subagents

要求元セッションが所有する生成済みサブエージェント実行を一覧表示、誘導、または停止します。現在の要求元にスコープされます。子は自分が制御する子だけを参照/制御できます。

オンデマンドのステータス、デバッグ、誘導、停止には subagents を使用します。 完了イベントを待つには sessions_yield を使用します。

スレッドバインド付きセッション

チャンネルでスレッドバインドが有効な場合、サブエージェントはスレッドにバインドされたままになり、そのスレッド内の後続のユーザーメッセージを同じサブエージェントセッションへルーティングし続けることができます。

スレッド対応チャンネル

Discord は現在唯一の対応チャンネルです。永続的なスレッドバインド付きサブエージェントセッション（thread: true を指定した sessions_spawn）、手動スレッド制御（/focus、/unfocus、/agents、 /session idle、/session max-age）、およびアダプターキー channels.discord.threadBindings.enabled、 channels.discord.threadBindings.idleHours、 channels.discord.threadBindings.maxAgeHours、 channels.discord.threadBindings.spawnSessions をサポートします。

クイックフロー

手動制御

構成スイッチ

• グローバルデフォルト: session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• チャンネル上書きと生成時の自動バインドキー はアダプター固有です。上記の スレッド対応チャンネル を参照してください。

現在のアダプター詳細については、構成リファレンス と スラッシュコマンド を参照してください。

許可リスト

要求元セッションがサンドボックス化されている場合、sessions_spawn はサンドボックス外で実行されるターゲットを拒否します。

検出

現在 sessions_spawn に許可されているエージェント ID を確認するには agents_list を使用します。レスポンスには、リストされた各エージェントの有効なモデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は PI、Codex アプリサーバー、その他の設定済みネイティブランタイムを区別できます。

自動アーカイブ

• サブエージェントセッションは agents.defaults.subagents.archiveAfterMinutes（デフォルト 60）後に自動的にアーカイブされます。
• アーカイブは sessions.delete を使用し、トランスクリプトを *.deleted.<timestamp>（同じフォルダー）にリネームします。
• cleanup: "delete" はアナウンス直後にアーカイブします（リネームによりトランスクリプトは引き続き保持されます）。
• 自動アーカイブはベストエフォートです。Gateway が再起動すると、保留中のタイマーは失われます。
• runTimeoutSeconds は自動アーカイブを行いません。実行を停止するだけです。セッションは自動アーカイブまで残ります。
• 自動アーカイブは深さ 1 と深さ 2 のセッションに等しく適用されます。
• ブラウザーのクリーンアップはアーカイブのクリーンアップとは別です。追跡されているブラウザータブ/プロセスは、トランスクリプト/セッションレコードが保持される場合でも、実行終了時にベストエフォートで閉じられます。

ネストされたサブエージェント

デフォルトでは、サブエージェントは独自のサブエージェントを生成できません （maxSpawnDepth: 1）。1 レベルのネスト、つまり オーケストレーターパターン を有効にするには、maxSpawnDepth: 2 を設定します: メイン → オーケストレーター サブエージェント → ワーカー サブサブエージェント。

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

深さレベル

アナウンスチェーン

結果はチェーンをさかのぼって戻ります。

1. 深さ 2 のワーカーが終了 → 親（深さ 1 のオーケストレーター）へアナウンスします。
2. 深さ 1 のオーケストレーターがアナウンスを受け取り、結果を合成して終了 → メインへアナウンスします。
3. メインエージェントがアナウンスを受け取り、ユーザーへ配信します。

各レベルは、直接の子からのアナウンスのみを確認します。

深さごとのツールポリシー

• ロールと制御スコープはスポーン時にセッションメタデータへ書き込まれます。これにより、フラットな、または復元されたセッションキーが誤ってオーケストレーター権限を取り戻すことを防ぎます。
• 深さ 1（maxSpawnDepth >= 2 の場合のオーケストレーター）: 子を管理できるように、sessions_spawn、subagents、sessions_list、sessions_history を取得します。その他のセッション/システムツールは引き続き拒否されます。
• 深さ 1（maxSpawnDepth == 1 の場合のリーフ）: セッションツールなし（現在のデフォルト動作）。
• 深さ 2（リーフワーカー）: セッションツールなし。sessions_spawn は深さ 2 では常に拒否されます。さらに子をスポーンすることはできません。

エージェントごとのスポーン制限

各エージェントセッション（どの深さでも）は、同時に最大 maxChildrenPerAgent （デフォルト 5）個までのアクティブな子を持てます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。

カスケード停止

深さ 1 のオーケストレーターを停止すると、その深さ 2 の子もすべて自動的に停止します。

• メインチャットの /stop は、すべての深さ 1 エージェントを停止し、その深さ 2 の子へカスケードします。
• /subagents kill <id> は、特定のサブエージェントを停止し、その子へカスケードします。
• /subagents kill all は、リクエスターのすべてのサブエージェントを停止し、カスケードします。

認証

サブエージェントの認証は、セッション種別ではなく エージェント ID によって解決されます。

• サブエージェントのセッションキーは agent:<agentId>:subagent:<uuid> です。
• 認証ストアはそのエージェントの agentDir から読み込まれます。
• メインエージェントの認証プロファイルは フォールバック としてマージされます。競合時はエージェントプロファイルがメインプロファイルを上書きします。

マージは追加的なので、メインプロファイルは常にフォールバックとして利用できます。エージェントごとに完全に分離された認証はまだサポートされていません。

アナウンス

サブエージェントはアナウンスステップを通じて報告します。

• アナウンスステップは、リクエスターセッションではなくサブエージェントセッション内で実行されます。
• サブエージェントが正確に ANNOUNCE_SKIP と返信した場合、何も投稿されません。
• 最新のアシスタントテキストが完全に無言のトークン NO_REPLY / no_reply である場合、以前に可視の進捗があってもアナウンス出力は抑制されます。

配送はリクエスターの深さに依存します。

• トップレベルのリクエスターセッションは、外部配送（deliver=true）付きのフォローアップ agent 呼び出しを使用します。
• ネストされたリクエスターのサブエージェントセッションは、内部フォローアップ注入（deliver=false）を受け取り、オーケストレーターがセッション内で子の結果を合成できるようにします。
• ネストされたリクエスターのサブエージェントセッションがなくなっている場合、利用可能であれば OpenClaw はそのセッションのリクエスターへフォールバックします。

トップレベルのリクエスターセッションでは、完了モードの直接配送はまず、バインド済みの会話/スレッドルートとフック上書きを解決し、その後、リクエスターセッションに保存されたルートから欠けているチャネルターゲットフィールドを埋めます。これにより、完了元がチャネルだけを識別している場合でも、完了は正しいチャット/トピックに保持されます。

ネストされた完了の検出結果を構築する際、子の完了集約は現在のリクエスター実行にスコープされ、以前の実行の古い子出力が現在のアナウンスに漏れ込むのを防ぎます。アナウンス返信は、チャネルアダプターで利用可能な場合、スレッド/トピックのルーティングを保持します。

アナウンスコンテキスト

アナウンスコンテキストは、安定した内部イベントブロックへ正規化されます。

終端失敗実行は、キャプチャした返信テキストを再生せずに失敗ステータスを報告します。タイムアウト時に、子がツール呼び出しまでしか進めなかった場合、アナウンスは未加工のツール出力を再生する代わりに、その履歴を短い部分進捗サマリーへ畳み込めます。

統計行

アナウンスペイロードには、末尾に統計行が含まれます（折り返される場合でも）。

• 実行時間（例: runtime 5m12s）。
• トークン使用量（入力/出力/合計）。
• モデル料金が設定されている場合の推定コスト（models.providers.*.models[].cost）。
• メインエージェントが sessions_history で履歴を取得したり、ディスク上のファイルを検査したりできるようにするための sessionKey、sessionId、およびトランスクリプトパス。

内部メタデータはオーケストレーション専用です。ユーザー向けの返信は通常のアシスタントの声に書き換えるべきです。

sessions_history を推奨する理由

sessions_history は、より安全なオーケストレーション経路です。

• アシスタントのリコールは最初に正規化されます。思考タグが取り除かれ、<relevant-memories> / <relevant_memories> の足場が取り除かれ、プレーンテキストのツール呼び出し XML ペイロードブロック（<tool_call>、<function_call>、<tool_calls>、<function_calls>）が、きれいに閉じられていない切り詰められたペイロードを含めて取り除かれます。また、格下げされたツール呼び出し/結果の足場と履歴コンテキストマーカー、漏洩したモデル制御トークン（<|assistant|>、その他の ASCII <|...|>、全角 <｜...｜>）、不正な MiniMax ツール呼び出し XML も取り除かれます。
• 認証情報/トークンらしきテキストはリダクトされます。
• 長いブロックは切り詰められる場合があります。
• 非常に大きな履歴では、古い行が削除されたり、過大な行が [sessions_history omitted: message too large] に置き換えられたりする場合があります。
• 完全にバイト単位で一致するトランスクリプト全体が必要な場合、未加工のディスク上トランスクリプト検査がフォールバックです。

ツールポリシー

サブエージェントは、まず親またはターゲットエージェントと同じプロファイルおよびツールポリシーパイプラインを使用します。その後、OpenClaw がサブエージェント制限レイヤーを適用します。

制限的な tools.profile がない場合、サブエージェントはセッションツールとシステムツールを除くすべてのツールを取得します。

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

ここでも sessions_history は境界付けられ、サニタイズされたリコールビューのままです。未加工のトランスクリプトダンプではありません。

maxSpawnDepth >= 2 の場合、深さ 1 のオーケストレーターサブエージェントは、子を管理できるように追加で sessions_spawn、subagents、sessions_list、および sessions_history を受け取ります。

設定による上書き

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow は最終的な許可のみフィルターです。すでに解決済みのツールセットを狭めることはできますが、tools.profile によって削除されたツールを戻して追加することはできません。たとえば、tools.profile: "coding" には web_search/web_fetch が含まれますが、browser ツールは含まれません。coding プロファイルのサブエージェントがブラウザー自動化を使用できるようにするには、プロファイル段階で browser を追加します。

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

ブラウザー自動化を 1 つのエージェントだけに付与したい場合は、エージェントごとの agents.list[].tools.alsoAllow: ["browser"] を使用します。

並行実行

サブエージェントは専用のプロセス内キューレーンを使用します。

• レーン名: subagent
• 並行数: agents.defaults.subagents.maxConcurrent（デフォルト 8）

生存性と復旧

OpenClaw は、endedAt がないことをサブエージェントがまだ生存している恒久的な証拠として扱いません。古い実行ウィンドウよりも古い未終了実行は、/subagents list、ステータスサマリー、子孫完了ゲート、およびセッションごとの並行数チェックでアクティブ/保留としてカウントされなくなります。

Gateway 再起動後、古い未終了の復元実行は、その子セッションに abortedLastRun: true が付けられていない限りプルーニングされます。これらの再起動で中断された子セッションは、サブエージェント孤児復旧フローを通じて復旧可能なままで、そこでは中断マーカーをクリアする前に合成再開メッセージが送信されます。

自動再起動復旧は子セッションごとに境界付けられます。同じサブエージェントの子が、高速な再ウェッジウィンドウ内で孤児復旧として繰り返し受け入れられた場合、OpenClaw はそのセッションに復旧トゥームストーンを永続化し、以降の再起動で自動再開しなくなります。タスクレコードを整合させるには openclaw tasks maintenance --apply を実行し、トゥームストーン化されたセッションの古い中断復旧フラグをクリアするには openclaw doctor --fix を実行します。

停止

• リクエスターチャットで /stop を送信すると、リクエスターセッションが中断され、そこからスポーンされたアクティブなサブエージェント実行がすべて停止され、ネストされた子へカスケードします。
• /subagents kill <id> は、特定のサブエージェントを停止し、その子へカスケードします。

制限事項

• サブエージェントのアナウンスはベストエフォートです。Gateway が再起動した場合、保留中の「アナウンスバック」作業は失われます。
• サブエージェントは引き続き同じ Gateway プロセスリソースを共有します。maxConcurrent は安全弁として扱ってください。
• sessions_spawn は常に非ブロッキングです。即座に { status: "accepted", runId, childSessionKey } を返します。
• サブエージェントコンテキストは AGENTS.md、TOOLS.md、SOUL.md、IDENTITY.md、および USER.md のみを注入します（MEMORY.md、HEARTBEAT.md、BOOTSTRAP.md は含みません）。
• 最大ネスト深さは 5 です（maxSpawnDepth の範囲: 1–5）。ほとんどのユースケースでは深さ 2 が推奨されます。
• maxChildrenPerAgent はセッションごとのアクティブな子数を上限設定します（デフォルト 5、範囲 1–20）。

関連

• ACP エージェント
• エージェント送信
• バックグラウンドタスク
• マルチエージェントサンドボックスツール