Sub-Agents：讓背景任務不再卡住你的對話

你在開發 Agent 時，一定遇過這種狀況：當你叫 Agent 去爬一個超大的網站，或者分析好幾份長篇文件時，整個對話就卡在那裡等它跑完。這種等待非常磨人，而且在任務結束前，你完全沒辦法跟 Agent 進行其他溝通。

這就是為什麼你需要 Sub-agents。它們就像是 Agent 的小助手，能幫你處理那些耗時的背景任務，而不會擋住主線對話。當 Sub-agent 完成工作後，它會自動把結果回報到對話中。

需要準備的東西

一個運作中的 Agent 環境
支援 sessions_spawn tool 的權限

快速開始

要使用 Sub-agents，最簡單的方式就是直接用自然語言命令你的 Agent：

「Spawn a sub-agent to research the latest Node.js release notes」

Agent 會在後台呼叫 sessions_spawn。當 Sub-agent 查完資料後，它會把發現的內容發布回你的對話視窗。

你也可以在指令中指定更詳細的參數：

「Spawn a sub-agent to analyze the server logs from today. Use gpt-5.2 and set a 5-minute timeout.」

運作原理

Main agent 啟動任務：Main agent 呼叫 sessions_spawn 並帶入任務描述。這個動作是 non-blocking 的，Main agent 會立刻收到 { status: "accepted", runId, childSessionKey }。
Sub-agent 在背景執行：系統會建立一個獨立的 Session (agent:<agentId>:subagent:<uuid>)，並在專用的 subagent queue lane 跑任務。
宣布結果：Sub-agent 完成工作後，會將結果傳回給請求者的對話，並由 Main agent 發布一個自然語言的總結。
自動歸檔：Sub-agent 的 Session 會在 60 分鐘後自動歸檔（時間可自行設定），對話紀錄會被完整保留。

[!TIP] 每個 Sub-agent 都有自己的 context 和 token 用量。建議幫 Sub-agent 設定比較便宜的 Model 來節省成本。

Configuration

Sub-agents 預設就能直接使用，不一定要設定。預設值如下：

Model：跟隨目標 Agent 的設定（除非有設定 subagents.model）
Thinking：跟隨目標 Agent 的設定（除非有設定 subagents.thinking）
最大並行數：8
自動歸檔：60 分鐘後

設定預設 Model

如果你想幫 Sub-agents 省點錢，可以設定一個較便宜的 Model：

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

設定預設 Thinking 等級

{
  agents: {
    defaults: {
      subagents: {
        thinking: "low",
      },
    },
  },
}

針對特定 Agent 覆寫設定

在多 Agent 架構中，你可以幫不同的 Agent 設定專屬的 Sub-agent 偏好：

{
  agents: {
    list: [
      {
        id: "researcher",
        subagents: {
          model: "anthropic/claude-sonnet-4",
        },
      },
      {
        id: "assistant",
        subagents: {
          model: "minimax/MiniMax-M2.1",
        },
      },
    ],
  },
}

Concurrency（並行控制）

你可以控制同時有多少個 Sub-agents 在跑：

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4, // 預設為 8
      },
    },
  },
}

Sub-agents 使用專用的 subagent queue lane，這跟 Main agent 的 queue 是分開的，所以 Sub-agent 的執行不會卡住主線的回覆。

Auto-Archive（自動歸檔）

你可以調整 Sub-agent Session 自動歸檔的時間：

{
  agents: {
    defaults: {
      subagents: {
        archiveAfterMinutes: 120, // 預設為 60
      },
    },
  },
}

[!NOTE] 歸檔只是將 transcript 重新命名為 *.deleted.<timestamp>（在同一個資料夾內），對話紀錄並不會被刪除。另外，自動歸檔是 best-effort 機制，如果 Gateway 重啟，尚未執行的歸檔計時器會消失。

疑難排解

問題：Sub-agent 任務沒有在預期時間歸檔
- 解決方案：檢查 Gateway 是否在任務期間重啟過。自動歸檔計時器在重啟後不會恢復。
問題：找不到歸檔後的對話紀錄
- 解決方案：歸檔並不是刪除，請在原資料夾尋找帶有 .deleted 字樣的檔案。

想要更進階的設定？試試 AI Setup Assistant。

下一步

設定預設 Model

你有沒有遇過這種情況：手頭上的任務越來越複雜，單一 Agent 已經快處理不來了？當你發現自己需要把大任務拆分成小任務，並交給專門的「助手」去處理時，手動管理這些過程簡直是噩夢。這就是 sessions_spawn 出場的時候，它能讓你的 Agent 具備自動建立子 Agent 的能力。

需要準備的東西

具備呼叫 sessions_spawn 工具的權限
基本的 Agent 配置權限（如果你需要設定跨 Agent 生成）

快速開始

sessions_spawn 是 Agent 用來建立子 Agent 的核心工具。你可以透過調整參數來精確控制子 Agent 的行為。

參數說明

參數	類型	預設值	說明
`task`	string	(必填)	子 Agent 應該執行的任務內容
`label`	string	—	用於識別的短標籤
`agentId`	string	(呼叫者的 ID)	在不同的 `agentId` 下生成（必須獲得授權）
`model`	string	(選填)	覆蓋此子 Agent 的模型設定
`thinking`	string	(選填)	覆蓋思考層級 (`off`, `low`, `medium`, `high` 等)
`runTimeoutSeconds`	number	`0` (無限制)	在 N 秒後強制中止子 Agent
`cleanup`	`"delete"` \| `"keep"`	`"keep"`	`"delete"` 會在任務完成通知後立即封存

模型解析順序

當子 Agent 啟動時，系統會按照以下順序決定使用的模型（先匹配到的優先）：

sessions_spawn 呼叫中直接指定的 model 參數
特定 Agent 的配置：agents.list[].subagents.model
全域預設配置：agents.defaults.subagents.model
目標 Agent 建立新 Session 時的一般模型解析邏輯

Thinking 層級解析順序

對於思考層級的設定，邏輯也是類似的：

sessions_spawn 呼叫中直接指定的 thinking 參數
特定 Agent 的配置：agents.list[].subagents.thinking
全域預設配置：agents.defaults.subagents.thinking
如果以上都沒有設定，則不會套用任何特定的子 Agent 思考層級覆蓋

跨 Agent 生成 (Cross-Agent Spawning)

預設情況下，子 Agent 只能在自己的 agentId 下生成。如果你想授權一個 Agent（例如 orchestrator）去建立其他類型的 Agent，你需要修改配置：

{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // 或使用 ["*"] 允許生成任何 Agent
        },
      },
    ],
  },
}

你可以搭配使用 agents_list 工具，來即時查看目前有哪些 agentId 是被允許用於 sessions_spawn 的。

疑難排解

無效的模型數值

如果你在呼叫時填寫了無效的模型名稱，系統會靜默跳過該數值。這時子 Agent 會自動退回到下一個有效的預設模型來執行，但你會在工具執行結果中看到一條警告訊息。

如果你在設定過程中遇到任何問題，可以直接詢問 AI Setup Assistant。

下一步

開發多代理系統最頭痛的就是「黑盒」問題。你啟動了一個 Sub-Agent 去執行任務，但它現在進行到哪了？是卡住了還是在努力運算？如果發現方向偏了，能不能中途叫停？

這種失去掌控的感覺很討厭。這就是為什麼你需要一套強大的指令集，讓你隨時都能掌握每個子任務的狀態，甚至直接介入干預。

需要準備的東西

一個正在運行的 Agent 實例
支援 Slash Commands 的通訊平台（如 Slack, Telegram 等）
至少一個已啟動的子代理任務

快速開始

想要快速上手？只需記住 /subagents list。它可以讓你看到當前 Session 下所有的子任務。

輸入 /subagents list 查看所有任務編號。
找到你想操作的索引（例如 1）。
使用 /subagents info 1 查看該任務的詳細狀態。

掌控 Sub-Agents (`/subagents`)

你可以使用 /subagents 指令來檢查並控制當前 Session 的子代理執行狀況：

指令	描述
`/subagents list`	列出所有子代理執行紀錄（包含進行中與已完成）
`/subagents stop <id\|#\|all>`	停止正在執行的子代理
`/subagents log <id\|#> [limit] [tools]`	查看子代理的執行紀錄 (transcript)
`/subagents info <id\|#>`	顯示詳細的執行元數據 (metadata)
`/subagents send <id\|#> <message>`	向正在執行的子代理發送訊息

你可以透過列表索引（如 1, 2）、Run ID 前綴、完整的 Session Key 或是 last 來指定對象。

實戰範例

列出並停止子代理 當你發現某個任務跑太久或不需要了：

/subagents list

回傳結果範例：

🧭 Subagents (current session)
Active: 1 · Done: 2
1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:...
2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:...
3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:...

停止編號 3 的任務：

/subagents stop 3

系統會確認：

⚙️ Stop requested for deploy staging.

檢查子代理詳情 想了解特定任務的細節：

/subagents info 1

回傳結果範例：

ℹ️ Subagent info
Status: ✅
Label: research logs
Task: Research the latest server error logs and summarize findings
Run: a1b2c3d4-...
Session: agent:main:subagent:...
Runtime: 2m31s
Cleanup: keep
Outcome: ok

查看執行日誌 如果你想看子代理最後 10 則訊息：

/subagents log 1 10

如果想連同 Tool Calls 一起看，加上 tools：

/subagents log 1 10 tools

發送後續指令 你可以直接對正在執行的子代理補一句話：

/subagents send 3 "Also check the staging environment"

這會將訊息發送到該子代理的 Session 中，並等待最多 30 秒的回覆。

結果回傳機制 (Announce)

當 Sub-Agent 完成任務後，會進入 Announce 步驟：

系統會擷取子代理的最終回覆，並向主代理的 Session 發送包含結果、狀態與統計數據的摘要訊息。
主代理會在你的聊天視窗貼出一段自然語言摘要。

這套機制會盡可能保留原始的 Thread/Topic 路由（例如 Slack threads, Telegram topics 或 Matrix threads）。

統計數據 (Announce Stats)

每則通知都會包含一行統計資訊：

執行時長 (Runtime duration)
Token 使用量 (input/output/total)
預估成本（若有透過 models.providers.*.models[].cost 設定價格）
Session Key、Session ID 以及 Transcript 路徑

執行狀態 (Announce Status)

通知訊息中的狀態是根據執行結果判定，而非模型輸出內容：

successful completion (ok) — 任務正常完成。
error — 任務失敗（錯誤細節會在備註中）。
timeout — 任務超過 runTimeoutSeconds。
unknown — 無法判斷狀態。

[!TIP] 如果不需要面向使用者的通知，主代理的摘要步驟可以回傳 NO_REPLY，這樣就不會發布任何內容。這與 ANNOUNCE_SKIP 不同，後者用於代理間的通訊流程 (sessions_send)。

疑難排解

任務無故中斷：檢查 info 指令中的 Outcome，如果是 timeout，請調整 runTimeoutSeconds。
找不到錯誤原因：使用 /subagents log <id> 20 tools 查看最後的工具調用，通常能發現 API 報錯或邏輯死循環。
狀態顯示 error：在通知訊息的 notes 部分查找具體的錯誤堆疊或描述。
訊息未發送：確認子代理是否仍在 🔄 (Active) 狀態，只有運行中的代理能接收 /subagents send。

下一步

需要更多協助？請詢問 AI Setup Assistant

當你在開發複雜的 Agent 系統時，最怕的就是 sub-agent 跑去亂動不該動的東西。你可能只想讓它幫你改個程式碼，結果它卻跑去管理你的 WhatsApp Session，或是試圖刪除系統 Gateway。管理這些「子代理」的權限邊界，一直是讓開發者頭痛的問題。

這篇文章會告訴你如何透過 Tool Policy 來鎖定 sub-agent 的行為，讓它們乖乖待在該待的地方。

需要準備的東西

在開始調整權限之前，請確保你已經具備以下條件：

一個已經設定好的主 Agent (Main Agent)
需要被呼叫的 Sub-agent
對設定檔（通常是 json5 格式）的基本瞭解

Quick Start: 5 分鐘限制工具權限

預設情況下，sub-agent 會繼承大部分工具，但你可以透過設定檔來進一步限縮。

如果你想禁止 sub-agent 使用特定的工具（例如瀏覽器或爬蟲）：

{
  tools: {
    subagents: {
      tools: {
        // deny 永遠優先於 allow
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

如果你希望 sub-agent 只能使用少數幾個核心工具，可以這樣寫：

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // 就算設定了 allow，預設的禁止清單依然有效
      },
    },
  },
}

深入瞭解 Tool Policy

預設情況下，sub-agent 會拿到除了「預設禁止清單」以外的所有工具。這些工具之所以被禁止，是因為它們對於背景任務來說不安全或不必要。

預設禁止工具清單

禁止工具	原因
`sessions_list`	Session 管理 — 由主 Agent 負責統籌
`sessions_history`	Session 管理 — 由主 Agent 負責統籌
`sessions_send`	Session 管理 — 由主 Agent 負責統籌
`sessions_spawn`	禁止巢狀展開（sub-agent 不能再產生 sub-agent）
`gateway`	系統管理 — 從 sub-agent 呼叫太過危險
`agents_list`	系統管理權限
`whatsapp_login`	互動式設定 — 這不是背景任務該做的
`session_status`	狀態/排程 — 由主 Agent 協調
`cron`	狀態/排程 — 由主 Agent 協調
`memory_search`	應改在 spawn prompt 中傳遞相關資訊
`memory_get`	應改在 spawn prompt 中傳遞相關資訊

注意： 你的自定義 deny 項目會被「加進」這個預設清單中。如果你設定了 allow，則只有該清單中的工具可用（但預設禁止清單依然會覆蓋在上面）。

Authentication (身份驗證) 邏輯

Sub-agent 的驗證是根據 agent id 來決定的，而不是看 session 類型：

載入路徑：驗證資訊會從目標 agent 的 agentDir 載入。
備援機制：主 Agent 的 auth profiles 會被合併進來作為 fallback（如果發生衝突，以 agent 本身的 profile 為準）。
疊加特性：這種合併是累加的，主 profile 永遠可以作為備援使用。

小提醒： 目前尚不支援完全隔離的 sub-agent 身份驗證。

Context 與 System Prompt 的差異

為了讓 sub-agent 更專注於任務，它們接收到的 System Prompt 比主 Agent 簡潔得多：

包含內容： Tooling, Workspace, Runtime 區塊，以及 AGENTS.md 和 TOOLS.md。
不包含內容： SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md。

此外，sub-agent 還會收到一個「任務導向」的 System Prompt，明確指示它專注於分配到的任務並完成它，不要試圖扮演主 Agent 的角色。

疑難排解

為什麼我設定了 allow，某些工具還是不能用？

請檢查該工具是否在「預設禁止清單」中。deny 的優先級永遠高於 allow。

我可以讓 sub-agent 擁有完全獨立的驗證環境嗎？

目前系統不支援完全隔離的驗證。Sub-agent 會優先使用自己的設定，但主 Agent 的 profile 始終會作為 fallback 存在。

有任何設定上的疑問嗎？可以直接詢問 AI Setup Assistant。

下一步

寫程式最怕的就是跑出去的任務停不下來，特別是當你開始讓 Agent 處理複雜的自動化流程，如果沒控制好，資源跟 Token 很快就會被燒光。你可能遇過那種「停不掉的背景任務」，看著後台不斷跑 Request 卻不知道該從哪裡把它關掉。

管理 Sub-Agents 的生命週期非常重要，這不僅是為了節省成本，更是為了確保你的 Gateway 運作穩定。

需要準備的東西

已配置 Sub-Agents 功能的 Gateway 環境
具備存取對話介面或修改設定檔的權限

快速開始

你可以透過以下幾種方式來中止正在執行的 Sub-Agents：

方法	效果
在對話中使用 `/stop`	中止主會話（Main Session）以及所有由它產生的活躍 Sub-Agent
使用 `/subagents stop <id>`	停止特定的 Sub-Agent，不會影響到主會話
設定 `runTimeoutSeconds`	在指定時間後自動中止 Sub-Agent 的執行
使用 `maxConcurrent`	限制同時執行的數量，防止資源耗盡

[!NOTE] runTimeoutSeconds 並不會自動封存（Archive）會話。會話會一直保留到正常的封存計時器（Archive Timer）觸發為止。

完整配置範例

如果你想在全域或特定 Agent 層級控制 Sub-Agents 的行為，可以參考下方的 json5 設定：

完整的 Sub-agent 設定範例

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops 可以在 "main" 底下產生 sub-agents
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // sub-agents 禁止使用瀏覽器工具
      },
    },
  },
}

Troubleshooting & Limitations

在使用 Sub-Agents 時，有幾個關於穩定性與限制的細節你需要注意：

Gateway 重啟風險：通知機制是 Best-effort 的。如果 Gateway 重啟，所有待處理的通知任務都會遺失。
不支援巢狀產生：Sub-Agents 無法再產生屬於它們自己的 Sub-Agents，這能避免無限迴圈。
資源共享機制：所有的 Sub-Agents 都共用同一個 Gateway Process。請務必使用 maxConcurrent 作為安全閥，避免單一任務吃光所有資源。
自動封存並非絕對：自動封存計時器同樣是 Best-effort。如果 Gateway 在計時器觸發前重啟，該次封存任務就會失效。

如果你在設定過程中遇到困難，可以點擊 AI Setup Assistant 獲取即時協助。

下一步

Session Tools — 深入瞭解 sessions_spawn 與其他會話工具
Multi-Agent Sandbox and Tools — 學習如何針對不同 Agent 設定工具權限
Configuration — 完整的 agents.defaults.subagents 參數參考
Queue — 瞭解 subagent lane 的運作排隊機制

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

Sub-Agents：讓背景任務不再卡住你的對話

需要準備的東西

快速開始

運作原理

Configuration

設定預設 Model

設定預設 Thinking 等級

針對特定 Agent 覆寫設定

Concurrency（並行控制）

Auto-Archive（自動歸檔）

疑難排解

下一步

需要準備的東西

快速開始

參數說明

模型解析順序

Thinking 層級解析順序

跨 Agent 生成 (Cross-Agent Spawning)

疑難排解

無效的模型數值

下一步

需要準備的東西

快速開始

掌控 Sub-Agents (/subagents)

實戰範例

結果回傳機制 (Announce)

統計數據 (Announce Stats)

執行狀態 (Announce Status)

疑難排解

下一步

需要準備的東西

Quick Start: 5 分鐘限制工具權限

深入瞭解 Tool Policy

預設禁止工具清單

Authentication (身份驗證) 邏輯

Context 與 System Prompt 的差異

疑難排解

為什麼我設定了 allow，某些工具還是不能用？

我可以讓 sub-agent 擁有完全獨立的驗證環境嗎？

下一步

需要準備的東西

快速開始

完整配置範例

完整的 Sub-agent 設定範例

Troubleshooting & Limitations

下一步

還是卡住了？

掌控 Sub-Agents (`/subagents`)