サブエージェント

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

目的:

• メイン実行をブロックせずに、調査、長時間のタスク、処理の遅いツール作業を並列化する。
• サブエージェントをデフォルトで分離する（セッションの分離、任意のサンドボックス化）。
• ツールの利用範囲を誤用しにくく保つ。サブエージェントには、デフォルトでセッションツールやメッセージツールを付与しない。
• オーケストレーターパターン向けに、設定可能なネストの深さをサポートする。

スラッシュコマンド

/subagents は、現在のセッションのサブエージェント実行を確認します。

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

/subagents info は実行メタデータ（状態、タイムスタンプ、セッション ID、 トランスクリプトのパス、クリーンアップ）を表示します。/subagents log は実行の 最近のチャットターンを出力します。ツール呼び出しと結果のメッセージも含めるには tools トークンを追加します（デフォルトでは省略されます）。エージェントターン内から、 範囲が制限され安全性フィルターが適用された履歴を参照するには sessions_history を使用します。 未加工の完全なトランスクリプトを確認するには、ディスク上のトランスクリプトのパスを参照します。

スレッド紐づけの制御

これらのコマンドは、永続的なスレッド紐づけをサポートするチャンネルで使用できます。 以下のスレッド対応チャンネルを参照してください。

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

生成時の動作

エージェントは sessions_spawn ツールを使用して、バックグラウンドのサブエージェントを開始します。 完了結果は親セッション内部のイベントとして返され、ユーザー向けの更新が必要かどうかは、 親エージェントまたは依頼元エージェントが判断します。

コンテキストモード

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

fork は必要な場合に限って使用してください。コンテキスト依存の委任に使用するものであり、 明確なタスクプロンプトを記述する代わりにはなりません。

ツール: sessions_spawn

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

利用可否は、呼び出し元に適用される実効ツールポリシーによって決まります。組み込みの coding プロファイルには sessions_spawn が含まれますが、messaging と minimal には 含まれません。full ではすべてのツールが許可されます。制限の厳しいプロファイルを使用しながら 作業を委任する必要があるエージェントには、tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] を追加するか、tools.profile: "coding" を使用します。 チャンネルやグループ、プロバイダー、サンドボックス、エージェントごとの許可・拒否ポリシーによって、 プロファイルの適用後にツールが除外される場合もあります。同じセッションから /tools を使用して、 実効ツール一覧を確認してください。

デフォルト:

• モデル: agents.defaults.subagents.model（またはエージェントごとの agents.list[].subagents.model）を設定しない限り、ネイティブサブエージェントは呼び出し元のモデルを継承します。ACP ランタイムでの生成では、設定済みのサブエージェントモデルがある場合は同じモデルを使用し、それ以外の場合は ACP ハーネス独自のデフォルトを維持します。明示的な sessions_spawn.model が常に優先されます。
• 思考: agents.defaults.subagents.thinking（またはエージェントごとの agents.list[].subagents.thinking）を設定しない限り、ネイティブサブエージェントは呼び出し元の設定を継承します。ACP ランタイムでの生成では、選択したモデルに対して agents.defaults.models["provider/model"].params.thinking も適用されます。明示的な sessions_spawn.thinking が常に優先されます。
• 実行タイムアウト: agents.defaults.subagents.runTimeoutSeconds が設定されている場合、OpenClaw はその値を使用します。それ以外の場合は 0（タイムアウトなし）へフォールバックします。sessions_spawn は呼び出しごとのタイムアウトのオーバーライドを受け付けません。
• タスク配信: ネイティブサブエージェントは、最初に表示される [Subagent Task] メッセージで委任されたタスクを受け取ります。サブエージェントのシステムプロンプトにはランタイムルールとルーティングコンテキストが含まれますが、タスクの非表示の複製は含まれません。

受理されたネイティブサブエージェントの生成では、ツール結果に解決済みの子モデルのメタデータが含まれます。 resolvedModel には適用されたモデル参照が含まれ、参照にプロバイダーが含まれる場合、 resolvedProvider にはそのプロバイダーのプレフィックスが含まれます。

委任プロンプトモード

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 を使用します。

スレッドにバインドされたセッション

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

スレッドをサポートするチャンネル

会話バインドアダプターを登録しているチャンネルでは、永続的なスレッドバインド型サブエージェントセッション （thread: true を指定した sessions_spawn）がサポートされます。この機能を備えた同梱チャンネルは、 Discord、iMessage、Matrix、Telegram です。Discord と Matrix はデフォルトで 子スレッドを作成し、Telegram と iMessage はデフォルトで現在の会話をバインドします。有効化、 タイムアウト、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 はその ID を省略します。古い許可リストエントリを削除するには openclaw doctor --fix を実行するか、デフォルトを継承しながらターゲットを 引き続き生成可能にする必要がある場合は、最小限の agents.list[] エントリを追加してください。

自動アーカイブ

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

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

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

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // サブエージェントによる子の生成を許可（デフォルト：1、範囲：1～5）        maxChildrenPerAgent: 5, // エージェントセッションごとのアクティブな子の最大数（デフォルト：5、範囲：1～20）        maxConcurrent: 8, // グローバル同時実行レーンの上限（デフォルト：8）        runTimeoutSeconds: 900, // sessions_spawn のデフォルトタイムアウト（0 = タイムアウトなし）        announceTimeoutMs: 120000, // 呼び出しごとの Gateway 通知タイムアウト      },    },  },}

深度レベル

通知チェーン

結果はチェーンを上へ遡って返されます。

1. 深さ 2 のワーカーが完了 → 親（深さ 1 の統括役）へ通知します。
2. 深さ 1 の統括役が通知を受け取り、結果を統合して完了 → メインへ通知します。
3. メインエージェントが通知を受け取り、ユーザーへ届けます。

各階層には、直接の子からの通知のみが表示されます。

深さ別のツールポリシー

• 役割と制御範囲は、起動時にセッションメタデータへ書き込まれます。これにより、フラット化または復元されたセッションキーが誤って統括権限を取り戻すのを防ぎます。
• 深さ 1（maxSpawnDepth >= 2 の場合の統括役）： 子を起動して状態を確認できるよう、sessions_spawn、subagents、sessions_list、sessions_history が付与されます。その他のセッション／システムツールは引き続き拒否されます。
• 深さ 1（maxSpawnDepth == 1 の場合の末端）： セッションツールはありません（現在のデフォルト動作）。
• 深さ 2（末端ワーカー）： セッションツールはありません。深さ 2 では sessions_spawn が常に拒否されます。それ以上の子は起動できません。

エージェント単位の起動上限

各エージェントセッション（深さを問わず）は、同時に最大 maxChildrenPerAgent （デフォルト 5）個のアクティブな子を持てます。これにより、単一の統括役から 無制限に処理が拡散するのを防ぎます。

連鎖停止

深さ 1 の統括役を停止すると、その配下の深さ 2 の子もすべて自動的に 停止します。

• メインチャットで /stop を実行すると、深さ 1 のすべてのエージェントが停止し、その配下の深さ 2 の子にも停止が連鎖します。

認証

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

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

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

通知

サブエージェントは、通知ステップを通じて結果を返します。

• 通知ステップは、要求元のセッションではなく、サブエージェントのセッション内で実行されます。
• サブエージェントが厳密に ANNOUNCE_SKIP と応答した場合、何も投稿されません。
• 最新のアシスタントテキストが厳密なサイレントトークン NO_REPLY / no_reply の場合、それ以前に表示可能な進捗が存在していても通知出力は抑制されます。

配信方法は要求元の深さによって異なります。

• 最上位の要求元セッションでは、外部配信（deliver=true）を伴う後続の agent 呼び出しが使用されます。
• ネストされた要求元サブエージェントセッションには内部の後続注入（deliver=false）が送られ、統括役がセッション内で子の結果を統合できるようにします。
• ネストされた要求元サブエージェントセッションが存在しない場合、OpenClaw は利用可能であれば、そのセッションの要求元へフォールバックします。

最上位の要求元セッションでは、完了モードの直接配信は、まず関連付けられた 会話／スレッドのルートとフックの上書きを解決し、その後、要求元セッションに 保存されたルートから不足しているチャンネル・ターゲット項目を補完します。 これにより、完了元がチャンネルしか識別していない場合でも、完了通知が正しい チャット／トピックへ送られます。

ネストされた完了結果を構築するとき、子の完了集約は現在の要求元の実行範囲に 限定され、以前の実行で生成された古い子の出力が現在の通知へ混入するのを防ぎます。 通知応答は、チャンネルアダプターで利用可能な場合、スレッド／トピックの ルーティングを維持します。

通知コンテキスト

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

最終的に失敗した実行は、取得済みの応答テキストを再掲せず、失敗ステータスを 報告します。ツール／toolResult の出力は、子の結果テキストへ昇格されません。

統計行

通知ペイロードの末尾には、ラップされている場合でも統計行が含まれます。

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

内部メタデータは統括専用です。ユーザー向けの応答は、通常のアシスタントの 文体に書き直す必要があります。

sessions_history を推奨する理由

sessions_history は、エージェントターン内から子のトランスクリプトを 読み取るための、より安全な統括経路です。

• 汎用ログの秘匿化が無効な場合でも、認証情報／トークンに似たテキストを秘匿化します。
• 長いテキストブロック（ブロックごとに 4000 文字）を切り詰め、思考シグネチャ、推論再生ペイロード、およびインライン画像データを除外します。
• 応答に 80 KB の上限を適用します。大きすぎる行は [sessions_history omitted: message too large] に置き換えられます。
• nextOffset が存在する場合は、それを使用して古いトランスクリプトの期間へ遡ってページングします。
• sessions_history は、メッセージテキストから推論タグ、<relevant-memories> の足場、またはツール呼び出し XML を除去しません。秘匿化とサイズ制限のみを適用し、生のトランスクリプト形式に近い構造化コンテンツブロックを返します。/subagents log は構造化ブロックではなくプレーンなチャット行を表示するため、より強力な文章サニタイザーを適用します（推論タグ、メモリの足場、およびツール呼び出し XML を除去します）。
• バイト単位で完全なトランスクリプトが必要な場合は、ディスク上の生のトランスクリプトを確認する方法がフォールバックです。

ツールポリシー

サブエージェントには、まず親または対象エージェントと同じプロファイルと ツールポリシーのパイプラインが適用されます。その後、OpenClaw が サブエージェント制限レイヤーを適用します。

サブエージェントは、深さや役割にかかわらず、常に gateway、 agents_list、session_status、cron を利用できません （システムレベル／対話型のツール、またはメインエージェントが調整すべき ツールです）。末端サブエージェント（デフォルトの深さ 1 の動作、および 常に深さ 2）は、さらに subagents、sessions_list、 sessions_history、sessions_spawn を利用できません。サブエージェントには message ツールが一切付与されません。これはこの拒否リストでフィルタリング されるのではなく、起動時に無効化されます。また、サブエージェントが通知チェーン のみを通じて通信するよう、sessions_send も引き続き拒否されます。

ここでも sessions_history は制限付きでサニタイズされた参照ビューであり、 生のトランスクリプトダンプではありません。

maxSpawnDepth >= 2 の場合、深さ 1 の統括役サブエージェントには、子を 管理できるように sessions_spawn、subagents、sessions_list、 sessions_history が追加で付与されます。

設定による上書き

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // 拒否が優先される        deny: ["gateway", "cron"],        // allow を設定すると、許可リストのみになる（拒否は引き続き優先される）        // allow: ["read", "exec", "process"]      },    },  },}

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

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

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

並行処理

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

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

稼働確認と復旧

OpenClaw は、endedAt が存在しないことを、サブエージェントがまだ 稼働中である永続的な証拠とはみなしません。古い実行とみなす期間 （2 時間、または設定された実行タイムアウトに短い猶予期間を加えた時間のうち、 長い方）を超えて終了していない実行は、/subagents list、ステータス概要、 子孫の完了ゲート、およびセッション単位の並行数チェックで、 アクティブ／保留中として数えられなくなります。

Gateway の再起動後、古くなった未終了の復元済み実行は、その子セッションに abortedLastRun: true が設定されていない限り削除されます。再起動によって 中断された実行は、サブエージェントの孤立復旧フロー用に登録されたままになります。 古い実行は再開せずに終了処理され、新しい子セッションには中断マーカーが 消去される前に合成された再開メッセージが送信されます。

自動再起動復旧は、子セッションごとに制限されます。同じサブエージェントの子が、 短時間で再停止する期間内に孤立復旧の対象として繰り返し受け入れられた場合、 OpenClaw はそのセッションに復旧トゥームストーンを永続化し、以後の再起動では 自動再開を停止します。タスクレコードを整合させるには openclaw tasks maintenance --apply を実行し、トゥームストーンが設定された セッションの古い中断復旧フラグを消去するには openclaw doctor --fix を 実行します。

停止

• 要求元のチャットで /stop を送信すると、要求元セッションが中断され、そこから起動されたアクティブなサブエージェントの実行が、ネストされた子まで連鎖して停止します。

制限事項

• サブエージェントの通知はベストエフォートです。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 は注入されません）。Codex ネイティブのサブエージェントも同じ境界に従います。TOOLS.md は継承された Codex スレッドの指示に残りますが、親専用のペルソナ、アイデンティティ、ユーザーファイルは、子がそれらを複製しないよう、ターン単位のコラボレーション指示として注入されます。
• 最大ネスト深度は 5 です（maxSpawnDepth の範囲: 1～5）。ほとんどのユースケースでは深度 2 を推奨します。
• maxChildrenPerAgent はセッションごとのアクティブな子の数を制限します（デフォルト 5、範囲 1～20）。

関連項目

• セッションツールと状態変更
• ACP エージェント
• エージェント送信
• バックグラウンドタスク
• マルチエージェントサンドボックスツール