サブエージェント

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

スラッシュコマンド

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

​

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

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

​

spawn の動作

​

コンテキストモード

​

ツール: sessions_spawn

• モデル: 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（タイムアウトなし）へフォールバックします。

​

委任プロンプトモード

• 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 が再起動すると、保留中のタイマーは失われます。
• runTimeoutSeconds は自動アーカイブを行いません。実行を停止するだけです。セッションは自動アーカイブまで残ります。
• 自動アーカイブは深さ 1 と深さ 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 では常に拒否されます。さらに子をスポーンすることはできません。

​

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

​

カスケード停止

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

​

認証

• サブエージェントのセッションキーは 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 を推奨する理由

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

​

ツールポリシー

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

設定による上書き

{
  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: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

​

並行実行

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

​

生存性と復旧

​

停止

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