サブエージェント

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

主な目標:

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

スラッシュコマンド

現在のセッションの sub-agent 実行を調べるには /subagents を使用します:

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/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>

生成動作

エージェントは sessions_spawn でバックグラウンドの sub-agents を開始します。sub-agent の完了は、内部の親セッションイベントとして返ります。親/依頼元エージェントは、ユーザー向けの更新が必要かどうかを判断します。

コンテキストモード

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

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

ツール: sessions_spawn

グローバル subagent レーンで deliver: false の sub-agent 実行を開始し、その後通知ステップを実行して、通知返信を依頼元チャットチャネルへ投稿します。

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

デフォルト:

• モデル: agents.defaults.subagents.model (またはエージェントごとの agents.list[].subagents.model) を設定しない限り、ネイティブ sub-agents は呼び出し元を継承します。ACP ランタイムの生成は、設定済みの subagent モデルが存在する場合は同じモデルを使用します。それ以外の場合、ACP ハーネスは独自のデフォルトを保持します。明示的な sessions_spawn.model は引き続き優先されます。
• Thinking: agents.defaults.subagents.thinking (またはエージェントごとの agents.list[].subagents.thinking) を設定しない限り、ネイティブ sub-agents は呼び出し元を継承します。ACP ランタイムの生成では、選択されたモデルに対して agents.defaults.models["provider/model"].params.thinking も適用されます。明示的な sessions_spawn.thinking は引き続き優先されます。
• 実行タイムアウト: agents.defaults.subagents.runTimeoutSeconds が設定されている場合、OpenClaw はそれを使用します。それ以外の場合は 0 (タイムアウトなし) にフォールバックします。sessions_spawn は呼び出しごとのタイムアウト上書きを受け付けません。
• タスク配信: ネイティブ sub-agents は、最初の可視 [Subagent Task] メッセージで委任されたタスクを受け取ります。sub-agent のシステムプロンプトは、タスクの隠れた重複ではなく、ランタイムルールとルーティングコンテキストを保持します。

受け入れられたネイティブ sub-agent 生成は、ツール結果に解決済みの子モデルメタデータを含みます。resolvedModel には適用されたモデル参照が含まれ、resolvedProvider には参照にプロバイダープレフィックスがある場合にそのプレフィックスが含まれます。

委任プロンプトモード

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

• suggest (デフォルト): より大きい、または遅い作業に sub-agents を使用する標準のプロンプト誘導を維持します。
• 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 を使用する。

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

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

スレッド対応チャネル

セッションバインドアダプターを持つ任意のチャネルは、永続的な スレッドバインドサブエージェントセッション（thread: true を指定した sessions_spawn）をサポートできる。 バンドル済みアダプターには現在、Discord スレッド、Matrix スレッド、 Telegram フォーラムトピック、Feishu の現在の会話バインドが含まれる。 有効化、タイムアウト、spawnSessions には、チャネルごとの threadBindings 設定キーを使用する。

クイックフロー

手動制御

設定スイッチ

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

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

許可リスト

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

検出

現在 sessions_spawn に許可されているエージェント ID を確認するには agents_list を使用する。 応答には、一覧表示された各エージェントの有効な モデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は OpenClaw、Codex app-server、およびその他の設定済みネイティブランタイムを区別できる。

allowAgents エントリは agents.list[] 内の設定済みエージェント ID を指す必要がある。 ["*"] は、任意の設定済みターゲットエージェントと要求元を意味する。エージェント設定が 削除されてもその ID が allowAgents に残っている場合、sessions_spawn はその ID を拒否し、 agents_list はそれを省略する。古い 許可リストエントリをクリーンアップするには openclaw doctor --fix を実行するか、デフォルトを継承しながらターゲットを スポーン可能なままにする必要がある場合は、最小限の agents.list[] エントリを追加する。

自動アーカイブ

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

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

デフォルトでは、サブエージェントは自分自身のサブエージェントをスポーンできない （maxSpawnDepth: 1）。1 レベルの ネストを有効にするには maxSpawnDepth: 2 を設定する — オーケストレーターパターン: main → オーケストレーターサブエージェント → ワーカーサブサブエージェント。

{  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 (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

深さレベル

通知チェーン

結果はチェーンを上流へ戻る:

1. 深さ 2 の worker が完了する → 親（深さ 1 の orchestrator）に通知する。
2. 深さ 1 の orchestrator が通知を受け取り、結果を統合して完了する → main に通知する。
3. Main agent が通知を受け取り、ユーザーに届ける。

各レベルは、直接の子からの通知だけを見る。

深さ別のツールポリシー

• ロールと制御スコープは spawn 時にセッションメタデータへ書き込まれる。これにより、フラットまたは復元されたセッションキーが誤って orchestrator 権限を取り戻すことを防ぐ。
• 深さ 1（orchestrator、maxSpawnDepth >= 2 の場合）: 子を spawn して状態を確認できるように、sessions_spawn、subagents、sessions_list、sessions_history を取得する。他の session/system ツールは拒否されたまま。
• 深さ 1（leaf、maxSpawnDepth == 1 の場合）: session ツールなし（現在のデフォルト動作）。
• 深さ 2（leaf worker）: session ツールなし。sessions_spawn は深さ 2 では常に拒否される。さらに子を spawn することはできない。

エージェントごとの spawn 制限

各エージェントセッション（どの深さでも）は、一度に最大 maxChildrenPerAgent （デフォルト 5）個のアクティブな子を持てる。これにより、単一の orchestrator からの暴走的な fan-out を防ぐ。

カスケード停止

深さ 1 の orchestrator を停止すると、その深さ 2 の子もすべて自動的に停止する。

• main チャットでの /stop はすべての深さ 1 エージェントを停止し、その深さ 2 の子へカスケードする。

認証

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

• サブエージェントのセッションキーは agent:<agentId>:subagent:<uuid>。
• auth store はそのエージェントの agentDir から読み込まれる。
• main agent の auth profiles は フォールバック としてマージされる。競合時は agent profiles が main profiles を上書きする。

マージは加算的なので、main profiles は常にフォールバックとして利用できる。 エージェントごとに完全に分離された auth はまだサポートされていない。

通知

サブエージェントは announce ステップで報告する。

• announce ステップは、requester セッションではなくサブエージェントセッション内で実行される。
• サブエージェントが正確に ANNOUNCE_SKIP と返信した場合、何も投稿されない。
• 最新の assistant テキストが正確なサイレントトークン NO_REPLY / no_reply の場合、それ以前に可視の進捗が存在していても announce 出力は抑制される。

配送は requester の深さに依存する。

• トップレベルの requester セッションは、外部配送（deliver=true）付きのフォローアップ agent 呼び出しを使用する。
• ネストされた requester subagent セッションは、orchestrator が子の結果をセッション内で統合できるように、内部フォローアップ注入（deliver=false）を受け取る。
• ネストされた requester subagent セッションがなくなっている場合、OpenClaw は利用可能ならそのセッションの requester にフォールバックする。

トップレベルの requester セッションでは、completion-mode の直接配送はまず バインド済みの会話/thread route と hook override を解決し、その後 requester セッションに保存された route から不足している channel-target フィールドを埋める。 これにより、completion の起点が channel だけを識別している場合でも、 completion は正しい chat/topic に留まる。

ネストされた completion findings を構築するとき、子の完了集約は現在の requester run に スコープされ、古い prior-run の子出力が現在の announce に漏れることを防ぐ。 Announce replies は channel adapters で利用可能な場合、thread/topic routing を保持する。

Announce context

Announce context は安定した内部イベントブロックに正規化される。

Terminal failed runs は、キャプチャされた reply text を再生せずに 失敗ステータスを報告する。Tool/toolResult output は child result text に昇格されない。

Stats line

Announce payloads には末尾に stats line が含まれる（折り返されている場合でも）。

• Runtime（例: runtime 5m12s）。
• Token usage（input/output/total）。
• model pricing が設定されている場合の推定コスト（models.providers.*.models[].cost）。
• main agent が sessions_history で履歴を取得したり、ディスク上のファイルを確認したりできるように、sessionKey、sessionId、transcript path。

内部メタデータは orchestration のためだけのものだ。ユーザー向け返信は 通常の assistant の声に書き直すべきである。

sessions_history を推奨する理由

sessions_history はより安全な orchestration パスである。

• Assistant recall は最初に正規化される。thinking tags は削除され、<relevant-memories> / <relevant_memories> scaffolding は削除され、plain-text tool-call XML payload blocks（<tool_call>、<function_call>、<tool_calls>、<function_calls>）は、正常に閉じない truncated payloads を含めて削除され、downgraded tool-call/result scaffolding と historical-context markers は削除され、漏れた model control tokens（<|assistant|>、他の ASCII <|...|>、全角 <｜...｜>）は削除され、malformed MiniMax tool-call XML は削除される。
• Credential/token-like text は redacted される。
• 長いブロックは truncate される場合がある。
• 非常に大きい histories では、古い rows が drop されたり、 oversized row が [sessions_history omitted: message too large] に置き換えられたりする場合がある。
• older transcript windows を後方にページングするには、存在する場合 nextOffset を使用する。
• 完全な byte-for-byte transcript が必要な場合は、生の on-disk transcript inspection がフォールバックになる。

ツールポリシー

サブエージェントはまず、親または target agent と同じ profile と tool-policy pipeline を使用する。 その後、OpenClaw が sub-agent restriction layer を適用する。

制限的な tools.profile がない場合、サブエージェントは message tool、session tools、system tools を除くすべてのツールを取得する。

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

ここでも sessions_history は bounded, sanitized recall view のままであり、 raw transcript dump ではない。

maxSpawnDepth >= 2 の場合、深さ 1 の orchestrator sub-agents はさらに 子を管理できるように sessions_spawn、subagents、sessions_list、 sessions_history を受け取る。

config による override

{  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 は最終的な allow-only filter である。これは すでに解決済みの tool set を狭めることはできるが、tools.profile によって 削除されたツールを 追加し直す ことはできない。たとえば、tools.profile: "coding" は web_search/web_fetch を含むが、browser tool は含まない。 coding-profile のサブエージェントに browser automation を使わせるには、 profile stage で browser を追加する。

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

1 つのエージェントだけが browser automation を取得すべき場合は、 per-agent の agents.list[].tools.alsoAllow: ["browser"] を使用する。

並行性

サブエージェントは専用の in-process queue lane を使用する。

• Lane name: subagent
• Concurrency: agents.defaults.subagents.maxConcurrent（デフォルト 8）

Liveness と recovery

OpenClaw は endedAt が存在しないことを、サブエージェントがまだ生存している 永続的な証拠として扱わない。stale-run window より古い unended runs は、 /subagents list、status summaries、descendant completion gating、 per-session concurrency checks で active/pending として数えられなくなる。

Gateway 再起動後、stale unended restored runs は、その子セッションが abortedLastRun: true とマークされていない限り prune される。これらの restart-aborted child sessions は sub-agent orphan recovery flow を通じて 回復可能なままであり、この flow は aborted marker をクリアする前に synthetic resume message を送信する。

自動 restart recovery は子セッションごとに bounded される。同じ サブエージェントの子が rapid re-wedge window 内で繰り返し orphan recovery に 受け入れられた場合、OpenClaw はそのセッションに recovery tombstone を永続化し、 後続の再起動で auto-resume しなくなる。task record を reconcile するには openclaw tasks maintenance --apply を実行し、tombstoned sessions 上の 古い aborted recovery flags をクリアするには openclaw doctor --fix を実行する。

停止

• requester chat で /stop を送信すると requester session が abort され、そこから spawn された active sub-agent runs が停止され、ネストされた子へカスケードする。

制限事項

• サブエージェントの announce は best-effort である。Gateway が再起動すると、保留中の「announce back」作業は失われる。
• サブエージェントは同じ Gateway process resources を引き続き共有する。maxConcurrent は safety valve として扱う。
• sessions_spawn は常に non-blocking である。これは { status: "accepted", runId, childSessionKey } を即座に返す。
• サブエージェント context は AGENTS.md と TOOLS.md だけを注入する（SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md、BOOTSTRAP.md は注入しない）。Codex-native subagents も同じ境界に従う。TOOLS.md は継承された Codex thread instructions に留まり、parent-only persona、identity、user files は turn-scoped collaboration instructions として注入されるため、子はそれらを複製しない。
• 最大ネスト深さは 5（maxSpawnDepth range: 1–5）。ほとんどのユースケースでは深さ 2 が推奨される。
• maxChildrenPerAgent はセッションごとの active children を制限する（デフォルト 5、range 1–20）。

関連

• ACP agents
• Agent send
• Background tasks
• Multi-agent sandbox tools