跳轉到主要內容

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.

子代理是在既有代理執行中產生的背景代理執行。 它們在自己的工作階段（agent:<agentId>:subagent:<uuid>）中執行， 完成後會將結果公告回請求者的聊天 頻道。每個子代理執行都會作為 背景任務追蹤。 主要目標：
  • 平行化「研究／長時間任務／慢速工具」工作，不阻塞主要執行。
  • 預設隔離子代理（工作階段分離 + 選用沙盒）。
  • 讓工具介面難以誤用：子代理預設不會取得工作階段工具。
  • 支援可設定的巢狀深度，以適用於協調器模式。
成本注意事項： 每個子代理預設都有自己的上下文和 token 用量。 對於繁重或重複的任務，請為子代理設定較便宜的模型， 並讓主要代理使用品質較高的模型。可透過 agents.defaults.subagents.model 或每個代理的覆寫設定來配置。當子代理 確實需要請求者目前的逐字稿時，代理可以在那次產生時要求 context: "fork"。繫結執行緒的子代理工作階段預設為 context: "fork"，因為它們會把目前對話分支到 後續執行緒。

​
斜線指令

使用 /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>]
使用頂層 /steer <message> 來導引目前請求者工作階段的作用中執行。當目標是子執行時，請使用 /subagents steer <id|#> <message>。 /subagents info 會顯示執行中繼資料（狀態、時間戳記、工作階段 ID、 逐字稿路徑、清理）。使用 sessions_history 取得有界限且經過 安全篩選的回想檢視；需要原始完整逐字稿時，請檢查磁碟上的 逐字稿路徑。

​
執行緒繫結控制

這些指令可用於支援持久執行緒繫結的頻道。 請參閱下方的支援執行緒的頻道。 
/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

​
產生行為

/subagents spawn 會以使用者指令（不是內部轉送）的形式啟動背景子代理， 並在執行完成時，將一則最終完成更新送回 請求者聊天。
  • 產生指令是非阻塞的；它會立即回傳執行 ID。
  • 完成時，子代理會向請求者聊天頻道公告摘要／結果訊息。
  • 需要子執行結果的代理回合，應在產生所需工作後呼叫 sessions_yield。這會結束目前回合，並讓完成事件作為下一則模型可見訊息抵達。
  • 完成採用推送式。一旦產生後，請不要在迴圈中輪詢 /subagents list、sessions_list 或 sessions_history 只為了等待它完成；只有在除錯或介入時才按需檢查狀態。
  • 子執行輸出是提供給請求者代理綜合整理的報告／證據。它不是使用者撰寫的指示文字，也不能覆寫系統、開發者或使用者政策。
  • 完成時，OpenClaw 會盡力關閉該子代理工作階段開啟的已追蹤瀏覽器分頁／程序，然後公告清理流程才會繼續。
  • OpenClaw 會透過具有穩定等冪鍵的 agent 回合，將完成結果交回請求者工作階段。
  • 如果請求者執行仍在作用中，OpenClaw 會先嘗試喚醒／導引該執行，而不是啟動第二條可見回覆路徑。
  • 如果請求者代理完成交接失敗，或未產生可見輸出，OpenClaw 會將傳遞視為失敗，並退回佇列路由／重試。它不會將子執行結果直接原始傳送到外部聊天。
  • 如果無法使用直接交接，則會退回佇列路由。
  • 如果佇列路由仍不可用，公告會以短暫的指數退避重試，之後才最終放棄。
  • 完成傳遞會保留已解析的請求者路由：可用時，繫結執行緒或繫結對話的完成路由會優先；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（lastChannel / lastTo / lastAccountId）補齊缺少的目標／帳號，使直接傳遞仍可運作。
對請求者工作階段的完成交接是執行階段產生的 內部上下文（不是使用者撰寫的文字），並包含：
  • Result — 最新可見的 assistant 回覆文字，否則為已清理的最新 tool/toolResult 文字。Terminal 執行失敗時不會重用已擷取的回覆文字。
  • Status — completed successfully / failed / timed out / unknown。
  • 精簡的 runtime/token 統計資料。
  • 一則交付指示，要求請求者 agent 以一般助理語氣重寫（不要轉發原始內部中繼資料）。
  • --model 和 --thinking 會覆寫該次特定執行的預設值。
  • 使用 info/log 在完成後檢查詳細資訊與輸出。
  • /subagents spawn 是一次性模式（mode: "run"）。若要使用繫結至持續執行緒的工作階段，請使用 sessions_spawn 搭配 thread: true 和 mode: "session"。
  • 對於 ACP harness 工作階段（Claude Code、Gemini CLI、OpenCode，或明確的 Codex ACP/acpx），當工具宣告該 runtime 時，請使用 sessions_spawn 搭配 runtime: "acp"。偵錯 completion 或 agent 對 agent 迴圈時，請參閱 ACP 交付模型。啟用 codex plugin 時，除非使用者明確要求 ACP/acpx，否則 Codex chat/thread 控制應優先使用 /codex ...，而不是 ACP。
  • OpenClaw 會隱藏 runtime: "acp"，直到 ACP 已啟用、請求者未被 sandbox，且已載入如 acpx 之類的後端 plugin。runtime: "acp" 預期使用外部 ACP harness id，或具有 runtime.type="acp" 的 agents.list[] 項目；對於來自 agents_list 的一般 OpenClaw config agents，請使用預設的 sub-agent runtime。

​
情境模式

原生 sub-agents 預設會以隔離方式啟動，除非呼叫者明確要求 fork 目前的 transcript。
模式使用時機行為
isolated全新研究、獨立實作、耗時的工具工作，或任何可在任務文字中簡述的事項建立乾淨的子 transcript。這是預設值，並可降低 token 使用量。
fork依賴目前對話、先前工具結果，或請求者 transcript 中已有細微指示的工作在子工作階段啟動前，將請求者 transcript 分支到子工作階段。
請謹慎使用 fork。它是用於對情境敏感的委派，而不是取代 撰寫清楚的任務 prompt。

​
工具：sessions_spawn

在全域 subagent lane 上以 deliver: false 啟動 sub-agent 執行， 接著執行 announce 步驟，並將 announce 回覆發布到請求者的 chat 頻道。 可用性取決於呼叫者的有效工具政策。coding 和 full profiles 預設會公開 sessions_spawn。messaging profile 不會；若 agent 應委派工作，請加入 tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]，或使用 tools.profile: "coding"。 頻道/群組、provider、sandbox，以及各 agent 的 allow/deny 政策， 仍可在 profile 階段後移除該工具。請在同一個 工作階段中使用 /tools 確認有效工具清單。 預設值：
  • Model： 繼承呼叫者，除非你設定 agents.defaults.subagents.model（或各 agent 的 agents.list[].subagents.model）；明確的 sessions_spawn.model 仍會優先。
  • Thinking： 繼承呼叫者，除非你設定 agents.defaults.subagents.thinking（或各 agent 的 agents.list[].subagents.thinking）；明確的 sessions_spawn.thinking 仍會優先。
  • 執行逾時： 如果省略 sessions_spawn.runTimeoutSeconds，OpenClaw 會在已設定時使用 agents.defaults.subagents.runTimeoutSeconds；否則退回到 0（無逾時）。

​
委派 prompt 模式

agents.defaults.subagents.delegationMode 只控制 prompt 指引；它不會變更工具政策或強制委派。
  • suggest（預設）：保留標準 prompt 提示，建議針對較大或較慢的工作使用 sub-agents。
  • prefer：告知主要 agent 保持回應性，並透過 sessions_spawn 委派任何比直接回覆更複雜的事項。
各 agent 覆寫使用 agents.list[].subagents.delegationMode。 
{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}

​
工具參數

​
task
string
必填
子代理程式的任務描述。
​
taskName
string
可選的穩定控制代號，供稍後以 subagents 指定目標。必須符合 [a-z][a-z0-9_]{0,63}，且不可是 last 或 all 等保留目標。當協調器可能需要在產生多個子項後導向、終止或識別特定子項時，建議使用。
​
label
string
可選的人類可讀標籤。
​
agentId
string
在 subagents.allowAgents 允許時，於另一個代理程式 ID 底下產生。
​
runtime
"subagent" | "acp"
預設值:"subagent"
acp 僅適用於外部 ACP 執行框架（claude、droid、gemini、opencode，或明確要求的 Codex ACP/acpx），以及 runtime.type 為 acp 的 agents.list[] 項目。
​
resumeSessionId
string
僅限 ACP。當 runtime: "acp" 時恢復既有的 ACP 執行框架工作階段；對原生子代理程式產生會被忽略。
​
streamTo
"parent"
僅限 ACP。當 runtime: "acp" 時，將 ACP 執行輸出串流至父工作階段；原生子代理程式產生時請省略。
​
model
string
覆寫子代理程式模型。無效值會被略過，子代理程式會使用預設模型執行，並在工具結果中顯示警告。
​
thinking
string
覆寫子代理程式執行的思考層級。
​
runTimeoutSeconds
number
設定時預設為 agents.defaults.subagents.runTimeoutSeconds，否則為 0。設定後，子代理程式執行會在 N 秒後中止。
​
thread
boolean
預設值:"false"
當為 true 時，要求此子代理程式工作階段使用頻道討論串繫結。
​
mode
"run" | "session"
預設值:"run"
如果 thread: true 且省略 mode，預設會變成 session。mode: "session" 需要 thread: true。
​
cleanup
"delete" | "keep"
預設值:"keep"
"delete" 會在公告後立即封存（仍會透過重新命名保留文字記錄）。
​
sandbox
"inherit" | "require"
預設值:"inherit"
require 會拒絕產生，除非目標子執行階段已沙箱化。
​
context
"isolated" | "fork"
預設值:"isolated"
fork 會將請求者目前的文字記錄分支到子工作階段。僅限原生子代理程式。討論串繫結的產生預設為 fork；非討論串產生預設為 isolated。
sessions_spawn 不接受頻道遞送參數（target、 channel、to、threadId、replyTo、transport）。若要遞送，請從產生的執行使用 message/sessions_send。

​
任務名稱與目標指定

taskName 是面向模型的編排控制代號，不是工作階段鍵。 當協調器可能需要稍後導向或終止該子項時，可將它用於穩定的子項名稱，例如 review_subagents、 linux_validation 或 docs_update。 目標解析接受完全相符的 taskName，以及不含歧義的前置字串。 比對範圍會限制在與編號 /subagents 目標相同的作用中/近期目標視窗，因此過期的已完成子項不會讓重複使用的控制代號變得有歧義。如果兩個作用中或近期子項共用相同的 taskName，該目標就有歧義；請改用清單索引、工作階段鍵或執行 ID。 保留目標 last 和 all 不是有效的 taskName 值，因為它們已有控制意義。

​
工具：sessions_yield

結束目前模型回合並等待執行階段事件，主要是子代理程式完成事件，以作為下一則訊息送達。當產生必要的子項工作後，且請求者在這些完成事件送達前無法產生最終答案時使用。 sessions_yield 是等待原語。不要為了偵測子項完成，而以輪詢 subagents、sessions_list、sessions_history、shell sleep 或程序輪詢的迴圈取代它。 只有在工作階段的有效工具清單包含它時，才使用 sessions_yield。某些最小或自訂工具設定檔可能會公開 sessions_spawn 和 subagents，但不公開 sessions_yield；在這種情況下，不要為了等待完成而自創輪詢迴圈。 當存在作用中子項時，OpenClaw 會將精簡的執行階段產生 Active Subagents 提示區塊注入一般回合，讓請求者無需輪詢即可看到目前的子工作階段、執行 ID、狀態、標籤、任務與 taskName 別名。該區塊中的任務與標籤欄位會以資料形式加上引號，而非指令，因為它們可能源自使用者/模型提供的產生引數。

​
工具：subagents

列出、導向或終止由請求者工作階段擁有的已產生子代理程式執行。 它的範圍限制在目前請求者；子項只能看見/控制自己所控制的子項。 使用 subagents 進行隨選狀態查詢、偵錯、導向或終止。 使用 sessions_yield 等待完成事件。

​
討論串繫結工作階段

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

​
支援討論串的頻道

Discord 目前是唯一支援的頻道。它支援持久的討論串繫結 subagent 工作階段（使用 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.spawnSessions。

​
快速流程

1

Spawn

使用帶有 thread: true 的 sessions_spawn（並可選擇加上 mode: "session"）。
2

Bind

OpenClaw 會建立討論串，或將討論串繫結到作用中頻道中的該工作階段目標。
3

Route follow-ups

該討論串中的回覆與後續訊息會路由到繫結的工作階段。
4

Inspect timeouts

使用 /session idle 檢查/更新非活動自動取消聚焦，並使用 /session max-age 控制硬性上限。
5

Detach

使用 /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
string[]
可透過明確 agentId 指定為目標的代理程式 ID 清單（["*"] 允許任何項目）。預設：僅限請求者代理程式。如果你設定了清單，且仍希望請求者能以 agentId 產生自身，請將請求者 ID 包含在清單中。
​
agents.defaults.subagents.allowAgents
string[]
當請求者代理程式未設定自己的 subagents.allowAgents 時使用的預設目標代理程式允許清單。
​
agents.defaults.subagents.requireAgentId
boolean
預設值:"false"
封鎖省略 agentId 的 sessions_spawn 呼叫（強制明確選擇設定檔）。每個代理程式覆寫：agents.list[].subagents.requireAgentId。
如果請求者工作階段已沙箱化，sessions_spawn 會拒絕會以非沙箱方式執行的目標。

​
探索

使用 agents_list 查看目前允許 sessions_spawn 使用哪些代理程式 ID。 回應會包含每個列出代理程式的有效模型與嵌入式執行階段中繼資料，讓呼叫端能區分 PI、Codex 應用程式伺服器及其他已設定的原生執行階段。

​
自動封存

  • 子代理程式工作階段會在 agents.defaults.subagents.archiveAfterMinutes 後自動封存（預設 60）。
  • 封存會使用 sessions.delete，並將文字記錄重新命名為 *.deleted.<timestamp>（同一資料夾）。
  • cleanup: "delete" 會在公告後立即封存（仍會透過重新命名保留文字記錄）。
  • 自動封存是盡力而為；如果 gateway 重新啟動，待處理計時器會遺失。
  • runTimeoutSeconds 不會自動封存；它只會停止執行。工作階段會保留到自動封存為止。
  • 自動封存同樣適用於深度 1 與深度 2 的工作階段。
  • 瀏覽器清理與封存清理是分開的：追蹤到的瀏覽器分頁/程序會在執行結束時盡力關閉，即使文字記錄/工作階段記錄被保留也一樣。

​
巢狀子代理程式

預設情況下，子代理程式無法產生自己的子代理程式 （maxSpawnDepth: 1）。設定 maxSpawnDepth: 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)
      },
    },
  },
}

​
深度層級

深度工作階段鍵形狀角色可以產生？
0agent:<id>:main主代理程式一律可以
1agent:<id>:subagent:<uuid>子代理程式（允許深度 2 時為編排器）僅當 maxSpawnDepth >= 2
2agent:<id>:subagent:<uuid>:subagent:<uuid>子子代理程式（葉節點工作者）絕不

​
公告鏈

結果會沿鏈向上流動：
  1. 深度 2 工作者完成 → 向其父項（深度 1 編排器）公告。
  2. 深度 1 編排器收到公告，彙整結果，完成 → 向主項公告。
  3. 主代理程式收到公告並遞送給使用者。
每個層級只會看到來自其直接子項的公告。
操作指引： 啟動一次子項工作並等待完成事件，而不是圍繞 sessions_list、 sessions_history、/subagents list 或 exec sleep 命令建立輪詢迴圈。 sessions_list 和 /subagents list 會讓子工作階段關係聚焦於即時工作 — 即時子項會保持附加，已結束子項會在短暫的近期視窗中保持可見，而過期的僅儲存子項連結會在其新鮮度視窗後被忽略。這可防止舊的 spawnedBy / parentSessionKey 中繼資料在重新啟動後重新喚起幽靈子項。如果子項完成事件在你已經送出最終答案後才抵達，正確的後續回應是精確的靜默權杖 NO_REPLY / no_reply。

​
依深度區分的工具政策

  • 角色與控制範圍會在生成時寫入工作階段中繼資料。這可避免扁平化或還原後的工作階段金鑰意外重新取得協調器權限。
  • 深度 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，就不會發布任何內容。
  • 如果最新的助理文字是精確的靜默權杖 NO_REPLY / no_reply，即使先前有可見進度，也會抑制宣告輸出。
傳遞取決於請求者深度：
  • 頂層請求者工作階段會使用帶有外部傳遞的後續 agent 呼叫（deliver=true）。
  • 巢狀請求者子代理工作階段會收到內部後續注入（deliver=false），讓協調器可以在工作階段中合成子項結果。
  • 如果巢狀請求者子代理工作階段已不存在，OpenClaw 會在可用時退回到該工作階段的請求者。
對於頂層請求者工作階段，完成模式的直接傳遞會先解析任何繫結的對話/討論串路由與鉤子覆寫，然後從請求者工作階段儲存的路由填補缺漏的頻道目標欄位。這會確保完成回到正確的聊天/主題，即使完成來源只識別頻道。 建立巢狀完成結果時，子項完成彙總會限制在目前請求者執行範圍內，防止過去執行的陳舊子項輸出洩漏到目前宣告中。頻道配接器可用時，宣告回覆會保留討論串/主題路由。

​
宣告內容

宣告內容會正規化為穩定的內部事件區塊：
欄位來源
來源subagent 或 cron
工作階段 id子工作階段金鑰/id
類型宣告類型 + 任務標籤
狀態從執行階段結果衍生（success、error、timeout 或 unknown）— 不是 從模型文字推斷
結果內容最新可見的助理文字，否則為已清理的最新工具/toolResult 文字
後續描述何時回覆與何時保持靜默的指示
終端失敗執行會回報失敗狀態，而不重播擷取到的回覆文字。逾時時，如果子項只完成工具呼叫，宣告可以將該歷史壓縮成簡短的部分進度摘要，而不是重播原始工具輸出。

​
統計行

宣告承載會在結尾包含統計行（即使被包裝）：
  • 執行時間（例如 runtime 5m12s）。
  • 權杖用量（輸入/輸出/總計）。
  • 設定模型價格時的預估成本（models.providers.*.models[].cost）。
  • sessionKey、sessionId 與逐字稿路徑，讓主代理可以透過 sessions_history 擷取歷史，或檢查磁碟上的檔案。
內部中繼資料僅供協調使用；面向使用者的回覆應改寫為一般助理語氣。

​
為什麼偏好 sessions_history

sessions_history 是更安全的協調路徑：
  • 助理回憶會先正規化：移除 thinking 標籤；移除 <relevant-memories> / <relevant_memories> 鷹架；移除純文字工具呼叫 XML 承載區塊（<tool_call>、<function_call>、<tool_calls>、<function_calls>），包含從未乾淨關閉的截斷承載；移除降級的工具呼叫/結果鷹架與歷史內容標記；移除洩漏的模型控制權杖（<|assistant|>、其他 ASCII <|...|>、全形 <｜...｜>）；移除格式錯誤的 MiniMax 工具呼叫 XML。
  • 憑證/類權杖文字會被修訂。
  • 長區塊可以被截斷。
  • 非常大的歷史可以捨棄較舊的列，或以 [sessions_history omitted: message too large] 取代過大的列。
  • 需要完整逐位元組逐字稿時，原始磁碟逐字稿檢查是後援方式。

​
工具政策

子代理會先使用與父代理或目標代理相同的設定檔與工具政策管線。之後，OpenClaw 會套用子代理限制層。 在沒有具限制性的 tools.profile 時，子代理會取得除工作階段工具和系統工具以外的所有工具：
  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn
sessions_history 在這裡也仍然是有界、已清理的回憶檢視，而不是原始逐字稿傾印。 當 maxSpawnDepth >= 2 時，深度 1 協調器子代理還會取得 sessions_spawn、subagents、sessions_list 與 sessions_history，因此可以管理其子項。

​
透過設定覆寫

{
  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.subagents.tools.allow 是最終的僅允許篩選器。它可以縮小已解析的工具集，但不能加回被 tools.profile 移除的工具。例如，tools.profile: "coding" 包含 web_search/web_fetch，但不包含 browser 工具。若要讓 coding-profile 子代理使用瀏覽器自動化，請在設定檔階段加入 browser： 
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}
當只有一個代理應取得瀏覽器自動化時，請使用每個代理的 agents.list[].tools.alsoAllow: ["browser"]。

​
並行

子代理使用專用的程序內佇列通道：
  • 通道名稱： subagent
  • 並行度： agents.defaults.subagents.maxConcurrent（預設 8）

​
存活性與復原

OpenClaw 不會將缺少 endedAt 視為子代理仍然存活的永久證據。超過陳舊執行視窗的未結束執行，在 /subagents list、狀態摘要、後代完成閘控與每個工作階段並行檢查中，不再計為作用中/擱置中。 Gateway 重新啟動後，陳舊的未結束還原執行會被修剪，除非其子工作階段標記為 abortedLastRun: true。這些重新啟動中止的子工作階段仍可透過子代理孤兒復原流程復原，該流程會在清除中止標記前傳送合成的恢復訊息。 自動重新啟動復原會依每個子工作階段設有界限。如果同一個子代理子項在快速重新卡住視窗內反覆被接受進行孤兒復原，OpenClaw 會在該工作階段上保留復原墓碑，並在之後重新啟動時停止自動恢復它。執行 openclaw tasks maintenance --apply 來協調任務記錄，或執行 openclaw doctor --fix 來清除已設墓碑工作階段上的陳舊中止復原旗標。
如果子代理生成因 Gateway PAIRING_REQUIRED / scope-upgrade 而失敗，請先檢查 RPC 呼叫者，再編輯配對狀態。 內部 sessions_spawn 協調應使用 client.id: "gateway-client" 搭配 client.mode: "backend"，透過直接 local loopback 共享權杖/密碼驗證連線；該路徑不依賴 CLI 的已配對裝置範圍基準。遠端呼叫者、明確的 deviceIdentity、明確的裝置權杖路徑，以及瀏覽器/node 用戶端，仍需要正常的裝置核准才能升級範圍。

​
停止

  • 在請求者聊天中傳送 /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）。

​
相關