子代理

子代理是從現有代理執行中衍生的背景代理，在獨立工作階段中運行並在完成後通告結果。

概述

子代理是從現有代理執行中衍生的背景代理。它們在自己的工作階段（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>]

討論串綁定控制

這些命令適用於支援持久討論串綁定的頻道。請參閱下方支援討論串的頻道。

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

/subagents info 顯示執行中繼資料（狀態、時間戳記、工作階段 ID、對話記錄路徑、清理）。

衍生行為

/subagents spawn 以使用者命令的方式啟動背景子代理（而非內部中繼），並在執行完成後傳送一則最終完成更新回請求者聊天。

spawn 命令為非阻塞式；立即回傳執行 ID。
完成時，子代理會將摘要/結果訊息通告回請求者聊天頻道。
對於手動衍生，傳遞具有彈性：
- OpenClaw 首先嘗試使用穩定冪等鍵的直接 agent 傳遞。
- 若直接傳遞失敗，則退回到佇列路由。
- 若佇列路由仍不可用，通告會以短指數退避重試後最終放棄。
完成訊息為系統訊息，包含：
- Result（assistant 回覆文字，若助理回覆為空則為最新的 toolResult）
- Status（completed successfully / failed / timed out）
- 精簡的執行時間/token 統計
--model 和 --thinking 可覆寫該特定執行的預設值。
使用 info/log 在完成後檢視詳細資訊和輸出。
/subagents spawn 為一次性模式（mode: "run"）。對於持久討論串綁定的工作階段，使用 sessions_spawn 搭配 thread: true 和 mode: "session"。
對於 ACP 執行環境工作階段（Codex、Claude Code、Gemini CLI），使用 sessions_spawn 搭配 runtime: "acp"，並參閱 ACP Agents。

主要目標

平行化「研究/長期任務/慢速工具」工作，不阻塞主執行。
預設將子代理隔離（工作階段分離 + 選用沙箱）。
保持工具介面不易誤用：子代理預設不會取得工作階段工具。
支援可設定的巢狀深度，適用於協調器模式。

費用注意事項

每個子代理都有自己的上下文和 token 使用量。對於繁重或重複的任務，為子代理設定較便宜的模型，主代理使用較高品質的模型。可透過 agents.defaults.subagents.model 或每個代理的覆寫進行設定。

工具

使用 sessions_spawn：

啟動子代理執行（deliver: false，全域通道：subagent）
然後執行通告步驟並將通告回覆發送到請求者聊天頻道
預設模型：繼承呼叫者，除非你設定 agents.defaults.subagents.model（或每個代理的 agents.list[].subagents.model）；明確的 sessions_spawn.model 仍然優先。
預設思考等級：繼承呼叫者，除非你設定 agents.defaults.subagents.thinking（或每個代理的 agents.list[].subagents.thinking）；明確的 sessions_spawn.thinking 仍然優先。
預設執行超時：若省略 sessions_spawn.runTimeoutSeconds，OpenClaw 使用 agents.defaults.subagents.runTimeoutSeconds（若有設定）；否則退回到 0（無超時）。

工具參數

task（必填）
label?（選用）
agentId?（選用；若允許則在另一個代理 ID 下衍生）
model?（選用；覆寫子代理模型；無效值會被跳過，子代理使用預設模型執行並在工具結果中顯示警告）
thinking?（選用；覆寫子代理執行的思考等級）
runTimeoutSeconds?（預設為 agents.defaults.subagents.runTimeoutSeconds（若有設定），否則為 0；設定後，子代理執行在 N 秒後中止）
thread?（預設 false；為 true 時，請求頻道討論串綁定此子代理工作階段）
mode?（run|session）
- 預設為 run
- 若 thread: true 且省略 mode，預設變為 session
- mode: "session" 需要 thread: true
cleanup?（delete|keep，預設 keep）

討論串綁定的工作階段

當頻道啟用討論串綁定時，子代理可以保持綁定到討論串，使該討論串中的後續使用者訊息持續路由到同一個子代理工作階段。

支援討論串的頻道

Discord（目前唯一支援的頻道）：支援持久討論串綁定的子代理工作階段（sessions_spawn 搭配 thread: true）、手動討論串控制（/focus、/unfocus、/agents、/session idle、/session max-age），以及適配器鍵 channels.discord.threadBindings.enabled、channels.discord.threadBindings.idleHours、channels.discord.threadBindings.maxAgeHours、channels.discord.threadBindings.spawnSubagentSessions。

快速流程

使用 sessions_spawn 搭配 thread: true（選用 mode: "session"）進行衍生。
OpenClaw 在活動頻道中建立或綁定討論串到該工作階段目標。
該討論串中的回覆和後續訊息路由到綁定的工作階段。
使用 /session idle 檢查/更新閒置自動取消聚焦，使用 /session max-age 控制硬性上限。
使用 /unfocus 手動解除綁定。

手動控制

/focus <target> 將目前討論串（或建立新討論串）綁定到子代理/工作階段目標。
/unfocus 移除目前已綁定討論串的綁定。
/agents 列出活動執行和綁定狀態（thread:<id> 或 unbound）。
/session idle 和 /session max-age 僅適用於已聚焦的綁定討論串。

設定開關

全域預設：session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours
頻道覆寫和衍生自動綁定鍵為適配器專屬。請參閱上方支援討論串的頻道。

參閱設定參考和斜線命令了解目前的適配器詳細資訊。

允許清單

agents.list[].subagents.allowAgents：可透過 agentId 指定的代理 ID 清單（["*"] 允許任意）。預設：僅限請求者代理。

探索

使用 agents_list 查看目前 sessions_spawn 允許哪些代理 ID。

自動歸檔

子代理工作階段在 agents.defaults.subagents.archiveAfterMinutes（預設：60）後自動歸檔。
歸檔使用 sessions.delete 並將對話記錄重新命名為 *.deleted.<timestamp>（同一資料夾）。
cleanup: "delete" 在通告後立即歸檔（仍透過重新命名保留對話記錄）。
自動歸檔為盡力而為；閘道重啟時等待中的計時器會遺失。
runTimeoutSeconds 不會自動歸檔；它僅停止執行。工作階段保留到自動歸檔。
自動歸檔同樣適用於 depth-1 和 depth-2 工作階段。

巢狀子代理

預設情況下，子代理無法衍生自己的子代理（maxSpawnDepth: 1）。你可以透過設定 maxSpawnDepth: 2 啟用一層巢狀，允許協調器模式：主代理 -> 協調器子代理 -> 工作子子代理。

如何啟用

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // 允許子代理衍生子項（預設：1）
        maxChildrenPerAgent: 5, // 每個代理工作階段最大活動子項數（預設：5）
        maxConcurrent: 8, // 全域並行通道上限（預設：8）
        runTimeoutSeconds: 900, // 省略時 sessions_spawn 的預設超時（0 = 無超時）
      },
    },
  },
}

深度層級

深度	工作階段鍵格式	角色	可否衍生？
0	`agent:<id>:main`	主代理	永遠可以
1	`agent:<id>:subagent:<uuid>`	子代理（depth 2 允許時為協調器）	僅在 `maxSpawnDepth >= 2` 時
2	`agent:<id>:subagent:<uuid>:subagent:<uuid>`	子子代理（葉節點工作者）	永遠不行

通告鏈

結果沿鏈向上流動：

Depth-2 工作者完成 -> 通告其父層（depth-1 協調器）
Depth-1 協調器收到通告、綜合結果、完成 -> 通告主代理
主代理收到通告並傳遞給使用者

每一層僅看到來自其直接子項的通告。

依深度的工具政策

Depth 1（協調器，當 maxSpawnDepth >= 2）：取得 sessions_spawn、subagents、sessions_list、sessions_history，以便管理其子項。其他工作階段/系統工具仍被拒絕。
Depth 1（葉節點，當 maxSpawnDepth == 1）：無工作階段工具（目前預設行為）。
Depth 2（葉節點工作者）：無工作階段工具 — sessions_spawn 在 depth 2 永遠被拒絕。無法衍生更多子項。

每個代理的衍生限制

每個代理工作階段（任何深度）最多可有 maxChildrenPerAgent（預設：5）個活動子項。這可防止單一協調器的失控扇出。

層疊停止

停止 depth-1 協調器會自動停止其所有 depth-2 子項：

在主聊天中使用 /stop 會停止所有 depth-1 代理並層疊到它們的 depth-2 子項。
/subagents kill <id> 停止特定子代理並層疊到其子項。
/subagents kill all 停止請求者的所有子代理並層疊。

驗證

子代理驗證依代理 ID 解析，而非工作階段類型：

子代理工作階段鍵為 agent:<agentId>:subagent:<uuid>。
驗證儲存從該代理的 agentDir 載入。
主代理的驗證配置檔作為備援合併；代理配置檔在衝突時覆寫主配置檔。

注意：合併為累加性，因此主配置檔永遠可作為備援。目前尚不支援每個代理完全隔離的驗證。

通告

子代理透過通告步驟回報：

通告步驟在子代理工作階段（而非請求者工作階段）中執行。
若子代理回覆正好為 ANNOUNCE_SKIP，則不會發布任何內容。
否則，通告回覆透過後續 agent 呼叫（deliver=true）發送到請求者聊天頻道。
通告回覆在頻道適配器可用時保留討論串/主題路由。
通告訊息正規化為穩定模板：
- Status: 從執行結果衍生（success、error、timeout 或 unknown）。
- Result: 來自通告步驟的摘要內容（缺失時為 (not available)）。
- Notes: 錯誤詳細資訊和其他有用的上下文。
Status 不從模型輸出推斷；它來自執行時結果訊號。

通告負載

通告負載在結尾包含統計行（即使被包裝）：

執行時間（例如 runtime 5m12s）
Token 使用量（輸入/輸出/總計）
在設定模型定價時的估計費用（models.providers.*.models[].cost）
sessionKey、sessionId 和對話記錄路徑（讓主代理可透過 sessions_history 取得歷史記錄或在磁碟上檢查檔案）

工具政策（子代理工具）

預設情況下，子代理取得除工作階段工具和系統工具外的所有工具：

sessions_list
sessions_history
sessions_send
sessions_spawn

當 maxSpawnDepth >= 2 時，depth-1 協調器子代理額外取得 sessions_spawn、subagents、sessions_list 和 sessions_history，以便管理其子項。

透過設定覆寫

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // 拒絕優先
        deny: ["gateway", "cron"],
        // 若設定 allow，則變為僅允許模式（拒絕仍然優先）
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

並行

子代理使用專用的程序內佇列通道：

通道名稱：subagent
並行數：agents.defaults.subagents.maxConcurrent（預設 8）

停止

在請求者聊天中傳送 /stop 會中止請求者工作階段並停止從中衍生的任何活動子代理，並層疊到巢狀子項。
/subagents kill <id> 停止特定子代理並層疊到其子項。

限制

子代理通告為盡力而為。若閘道重啟，等待中的「通告回覆」工作會遺失。
子代理仍共享相同的閘道程序資源；將 maxConcurrent 視為安全閥。
sessions_spawn 永遠為非阻塞式：立即回傳 { status: "accepted", runId, childSessionKey }。
子代理上下文僅注入 AGENTS.md + TOOLS.md（不含 SOUL.md、IDENTITY.md、USER.md、HEARTBEAT.md 或 BOOTSTRAP.md）。
最大巢狀深度為 5（maxSpawnDepth 範圍：1-5）。大多數使用情境建議 Depth 2。
maxChildrenPerAgent 限制每個工作階段的活動子項（預設：5，範圍：1-20）。

子代理

概述