サブエージェント

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

​

スラッシュコマンド

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

​

スレッドバインドの制御

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

​

生成時の動作

​

コンテキストモード

​

ツール: sessions_spawn

• モデル: agents.defaults.subagents.model（またはエージェントごとの agents.entries.*.subagents.model）を設定しない限り、ネイティブサブエージェントは呼び出し元のモデルを継承します。ACP ランタイムによる生成では、サブエージェントモデルが設定されている場合は同じモデルを使用し、それ以外の場合は ACP ハーネス独自のデフォルトを維持します。明示的な sessions_spawn.model がある場合は、それが引き続き優先されます。
• 思考: agents.defaults.subagents.thinking（またはエージェントごとの agents.entries.*.subagents.thinking）を設定しない限り、ネイティブサブエージェントは呼び出し元の設定を継承します。ACP ランタイムによる生成でも、選択したモデルに agents.defaults.models["provider/model"].params.thinking を適用します。明示的な sessions_spawn.thinking がある場合は、それが引き続き優先されます。
• 実行タイムアウト: agents.defaults.subagents.runTimeoutSeconds が設定されている場合、OpenClaw はそれを使用します。それ以外の場合は 0（タイムアウトなし）へフォールバックします。sessions_spawn は、呼び出しごとのタイムアウトの上書きを受け付けません。
• プロセスの存続期間: 切り離された OpenClaw サブエージェントには、独自の実行ライフサイクルがあります。外部 CLI バックエンド内で作成されたバックグラウンドタスクは異なり、親 CLI サブプロセスを共有し、その親が agents.defaults.timeoutSeconds に達すると停止します。
• タスクの配信: ネイティブサブエージェントは、委任されたタスクを最初の可視 [Subagent Task] メッセージで受け取ります。サブエージェントのシステムプロンプトには、実行時ルールとルーティングコンテキストが含まれ、タスクの非表示の複製は含まれません。

​

委任プロンプトモード

• suggest（デフォルト）: 規模が大きい、または時間のかかる処理にはサブエージェントを使用するよう促す、標準のプロンプトを維持します。
• prefer: メインエージェントに応答性を維持させ、直接返信よりも複雑な処理は sessions_spawn を通じて委任するよう指示します。

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

​

ツールパラメーター

​

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

​

ツール：sessions_yield

​

ツール：subagents

​

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

​

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

​

クイックフロー

​

手動制御

​

設定スイッチ

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

​

許可リスト

​

検出

​

自動アーカイブ

• サブエージェントセッションは、agents.defaults.subagents.archiveAfterMinutes 後（デフォルトは 60）に自動的にアーカイブされます。
• アーカイブでは sessions.delete を使用し、トランスクリプトの名前を *.deleted.<timestamp> に変更します（同じフォルダー内）。
• cleanup: "delete" は通知直後にアーカイブします（名前変更によってトランスクリプトは引き続き保持されます）。
• 自動アーカイブはベストエフォートです。Gateway が再起動すると、保留中のタイマーは失われます。
• 構成された実行タイムアウトは自動アーカイブを行いません。実行を停止するだけです。セッションは自動アーカイブされるまで残ります。
• 自動アーカイブは、深さ 1 と深さ 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. メインエージェントが通知を受信し、ユーザーに配信します。

​

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

• 子はスポーン時に、リクエスターに適用される送信者ポリシーを取得します。送信者のない子の実行と、認証済みオペレーターによる再開では、後から toolsBySender が変更されてもそのスナップショットが維持されます。現在のグローバル、エージェント、プロバイダー、サンドボックス、およびサブエージェントの制限は引き続き適用されます。代わりに、子を対象とする新しい外部チャネルのターンでは、現在の送信者ポリシーが再解決されます。
• ロールと制御スコープは、スポーン時にセッションメタデータへ書き込まれます。これにより、フラット化または復元されたセッションキーが誤ってオーケストレーター権限を再取得することを防ぎます。
• 深さ 1（maxSpawnDepth >= 2 の場合のオーケストレーター）: 子をスポーンして状態を確認できるよう、sessions_spawn、subagents、sessions_list、sessions_history が付与されます。その他のセッションツールとシステムツールは引き続き拒否されます。
• 深さ 1（maxSpawnDepth == 1 の場合の末端）: セッションツールはありません（現在のデフォルト動作）。
• 深さ 2（末端ワーカー）: セッションツールはありません。深さ 2 では sessions_spawn が常に拒否されます。それ以上の子はスポーンできません。

​

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

​

カスケード停止

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

​

認証

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

​

通知

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

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

​

通知コンテキスト

​

統計行

• ランタイム（例: runtime 5m12s）。
• トークン使用量（入力/出力/合計）。
• モデルの料金が構成されている場合の推定コスト（models.providers.*.models[].cost）。
• sessionKey、sessionId、およびトランスクリプトのパス。これにより、メインエージェントは sessions_history を介して履歴を取得するか、ディスク上のファイルを確認できます。

​

sessions_history を推奨する理由

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

​

ツールポリシー

​

構成によるオーバーライド

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

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

​

同時実行

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

​

稼働状況と復旧

​

停止

• リクエスト元のチャットで /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 エージェント
• エージェント送信
• バックグラウンドタスク
• マルチエージェントサンドボックスツール