子代理

子代理是從現有代理執行中衍生的背景代理執行。它們在獨立的工作階段（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 以使用者指令（而非內部轉發）啟動背景子代理，執行完成後傳送一則最終完成更新回請求者聊天。

  • 衍生指令是非阻塞的；立即回傳執行 id。
  • 完成時，子代理向請求者聊天頻道公告摘要/結果訊息。
  • 手動衍生的傳遞具有容錯機制：
    • OpenClaw 先嘗試以穩定冪等鍵值直接 agent 傳遞。
    • 直接傳遞失敗時，後備至佇列路由。
    • 佇列路由仍不可用時，以短指數退避重試後放棄。
  • 傳遞給請求者工作階段的完成交接是執行時產生的內部上下文（非使用者撰寫的文字），包含：
    • Result（assistant 回覆文字，如果助理回覆為空則使用最新的 toolResult）
    • Status（completed successfully / failed / timed out / unknown）
    • 精簡的執行時/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 代理。

主要目標：

  • 將「研究/長時間任務/慢速工具」工作並行化，不阻塞主執行。
  • 預設隔離子代理（工作階段分離 + 選用沙箱化）。
  • 讓工具介面難以被誤用：子代理預設不會取得工作階段工具。
  • 支援可設定的巢狀深度，實現協調器模式。

成本提示：每個子代理有獨立的上下文與 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）
  • sandbox?（inherit|require，預設 inherit；require 在目標子執行環境未沙箱化時拒絕衍生）
  • sessions_spawn 不接受頻道傳遞參數（target、channel、to、threadId、replyTo、transport）。如需傳遞，從衍生的執行中使用 message/sessions_send。

執行緒綁定工作階段

啟用頻道的執行緒綁定時，子代理可以保持綁定到某個執行緒，讓該執行緒中的後續使用者訊息繼續路由到同一個子代理工作階段。

支援執行緒的頻道

  • 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。

快速流程：

  1. 使用 sessions_spawn 搭配 thread: true（可選 mode: "session"）衍生。
  2. OpenClaw 在活躍頻道中建立或綁定一個執行緒到該工作階段目標。
  3. 該執行緒中的回覆和後續訊息路由到綁定的工作階段。
  4. 使用 /session idle 檢視/更新閒置自動解除聚焦，/session max-age 控制硬性上限。
  5. 使用 /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 清單（["*"] 允許任意）。預設：僅限請求者代理。
  • 沙箱繼承防護：如果請求者工作階段在沙箱中，sessions_spawn 會拒絕將要在未沙箱化環境中執行的目標。

探索：

  • 使用 agents_list 查看 sessions_spawn 目前允許的代理 id。

自動封存：

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

巢狀子代理

預設情況下，子代理無法衍生自己的子代理（maxSpawnDepth: 1）。將 maxSpawnDepth 設為 2 可啟用一層巢狀，實現協調器模式：主代理 → 協調器子代理 → 工作者子子代理。

啟用方式

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

深度層級

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

公告鏈

結果沿鏈向上傳遞：

  1. 深度 2 工作者完成 → 公告給其父項（深度 1 協調器）
  2. 深度 1 協調器收到公告、整合結果、完成 → 公告給主代理
  3. 主代理收到公告並傳遞給使用者

每一層只看到來自直接子項的公告。

各深度的工具策略

  • 角色和控制範圍在衍生時寫入工作階段中繼資料。這防止扁平化或還原的工作階段鍵值意外重獲協調器權限。
  • 深度 1（協調器，當 maxSpawnDepth >= 2 時）：取得 sessions_spawn、subagents、sessions_list、sessions_history 以管理其子項。其他工作階段/系統工具仍被禁止。
  • 深度 1（葉節點，當 maxSpawnDepth == 1 時）：無工作階段工具（目前的預設行為）。
  • 深度 2（葉節點工作者）：無工作階段工具 — sessions_spawn 在深度 2 永遠被禁止。無法衍生更多子項。

每代理衍生上限

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

級聯停止

停止深度 1 的協調器會自動停止其所有深度 2 子項：

  • 在主聊天中 /stop 停止所有深度 1 代理並級聯到其深度 2 子項。
  • /subagents kill <id> 停止特定子代理並級聯到其子項。
  • /subagents kill all 停止請求者的所有子代理並級聯。

認證

子代理認證按代理 id 解析，不按工作階段類型：

  • 子代理工作階段鍵值為 agent:<agentId>:subagent:<uuid>。
  • 認證儲存從該代理的 agentDir 載入。
  • 主代理的認證設定檔作為後備合併；代理設定檔在衝突時覆寫主設定檔。

注意：合併是加法式的，主設定檔始終可作為後備使用。目前尚不支援每個代理完全隔離的認證。

公告

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

  • 公告步驟在子代理工作階段（非請求者工作階段）內執行。
  • 如果子代理回覆 ANNOUNCE_SKIP，則不會發布任何內容。
  • 否則傳遞取決於請求者深度：
    • 頂層請求者工作階段使用後續 agent 呼叫進行外部傳遞（deliver=true）
    • 巢狀請求者子代理工作階段收到內部後續注入（deliver=false），讓協調器在工作階段內整合子項結果
    • 如果巢狀請求者子代理工作階段已不存在，OpenClaw 會在可用時後備至該工作階段的請求者
  • 建構巢狀完成結果時，子項完成聚合限定於當前請求者執行，防止舊版先前執行的子項輸出洩漏到當前公告。
  • 公告回覆在頻道轉接器可用時保留執行緒/主題路由。
  • 公告上下文正規化為穩定的內部事件區塊：
    • 來源（subagent 或 cron）
    • 子工作階段鍵值/id
    • 公告類型 + 任務標籤
    • 從執行時結果衍生的狀態行（success、error、timeout 或 unknown）
    • 公告步驟的結果內容（缺少時為 (no output)）
    • 描述何時回覆與何時保持沉默的後續指示
  • Status 不從模型輸出推斷；而是來自執行時結果信號。

公告酬載末尾包含統計行（即使被包裝）：

  • 執行時間（例如 runtime 5m12s）
  • Token 用量（輸入/輸出/總計）
  • 設定模型定價（models.providers.*.models[].cost）時的預估成本
  • sessionKey、sessionId 和對話紀錄路徑（讓主代理可透過 sessions_history 取得歷史或在磁碟上檢視檔案）
  • 內部中繼資料僅用於協調；面向使用者的回覆應以正常助理語氣改寫。

工具策略（子代理工具）

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

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

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

透過設定覆寫：

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny 優先
        deny: ["gateway", "cron"],
        // 如果設定 allow，變為僅允許模式（deny 仍然優先）
        // 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）。大多數使用情境建議深度 2。
  • maxChildrenPerAgent 限制每個工作階段的活躍子項數（預設：5，範圍：1–20）。
arrow_back
上一頁
Agent Send
下一頁
ACP Agents
arrow_forward