子代理程式

子代理程式是從現有代理程式執行中產生的背景代理程式執行。 每個子代理程式都在自己的工作階段（agent:<agentId>:subagent:<uuid>）中執行， 完成後會將結果公告回請求者的聊天頻道。 每次子代理程式執行都會追蹤為一項背景任務。

目標：

• 將研究、長時間任務及緩慢的工具工作平行化，而不阻塞主要執行。
• 預設讓子代理程式保持隔離（工作階段分離、選用的沙箱化）。
• 讓工具介面不易遭誤用：子代理程式預設不會取得工作階段或訊息工具。
• 支援可設定的巢狀深度，以用於協調器模式。

斜線命令

/subagents 會檢查目前工作階段的子代理程式執行：

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info 會顯示執行中繼資料（狀態、時間戳記、工作階段 ID、 文字記錄路徑、清理）。/subagents log 會列印某次執行最近的聊天輪次； 加入 tools 權杖即可包含工具呼叫／結果訊息（預設省略）。 在代理程式輪次中，使用 sessions_history 可取得有界且經安全篩選的回顧檢視， 也可以檢查磁碟上的文字記錄路徑，以查看未處理的完整文字記錄。

在 Control UI 中，近期有子執行的父工作階段會顯示可展開的 側邊欄資料列。巢狀資料列會顯示子代理程式的狀態和執行時間，選取其中一個 即可開啟該子代理程式的聊天，同時保留父層階層。

討論串綁定控制項

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

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

產生行為

代理程式使用 sessions_spawn 工具啟動背景子代理程式。 完成結果會以內部父工作階段事件傳回；父代理程式／請求者 代理程式會決定是否需要向使用者顯示更新。

上下文模式

除非呼叫者明確要求分支目前的文字記錄，否則原生子代理程式啟動時會彼此隔離。

請謹慎使用 fork。它適用於上下文敏感的委派， 不能取代清楚撰寫的任務提示。

工具：sessions_spawn

在全域 subagent 執行通道上使用 deliver: false 啟動子代理程式執行， 接著執行公告步驟，並將公告回覆發佈至請求者 聊天頻道。

可用性取決於呼叫者的有效工具政策。內建的 coding 和 messaging 設定檔包含 sessions_spawn、 sessions_yield 和 subagents；minimal 則不包含。full 允許所有 工具。對於採用自訂且較受限設定檔、但仍應能委派工作的代理程式， 請使用 tools.alsoAllow 加入這些工具，或使用上述任一設定檔。 頻道／群組、提供者、沙箱及個別代理程式的允許／拒絕政策， 仍可能在設定檔階段後移除該工具。請在同一工作階段中使用 /tools 確認有效工具清單。

預設值：

• **模型：**除非設定 agents.defaults.subagents.model（或個別代理程式的 agents.entries.*.subagents.model），否則原生子代理程式會繼承呼叫者。設定子代理程式模型時，ACP 執行階段產生也會使用相同的已設定模型；否則 ACP 控制框架會保留自己的預設值。明確指定的 sessions_spawn.model 仍具有優先權。
• **思考：**除非設定 agents.defaults.subagents.thinking（或個別代理程式的 agents.entries.*.subagents.thinking），否則原生子代理程式會繼承呼叫者。ACP 執行階段產生也會為所選模型套用 agents.defaults.models["provider/model"].params.thinking。明確指定的 sessions_spawn.thinking 仍具有優先權。
• **執行逾時：**設定時，OpenClaw 會使用 agents.defaults.subagents.runTimeoutSeconds；否則會退回至 0（不逾時）。sessions_spawn 不接受個別呼叫的逾時覆寫。
• **程序存續期：**分離的 OpenClaw 子代理程式有自己的執行生命週期。在外部命令列介面後端內建立的背景任務則不同：它與父命令列介面共用子程序，且若該父程序到達 agents.defaults.timeoutSeconds，它就會停止。
• **任務傳遞：**原生子代理程式會在第一則可見的 [Subagent Task] 訊息中收到委派的任務。子代理程式系統提示包含執行階段規則和路由上下文，不會包含隱藏的重複任務內容。

已接受的原生子代理程式產生，其工具結果會包含已解析的子模型中繼資料： resolvedModel 包含已套用的模型參照，而當參照具有提供者前置詞時， resolvedProvider 會包含該前置詞。

委派提示模式

agents.defaults.subagents.delegationMode 僅控制提示指引；它不會變更工具政策或強制委派。

• suggest（預設）：保留標準提示提醒，以便針對較大型或較緩慢的工作使用子代理程式。
• prefer：指示主要代理程式保持快速回應，並透過 sessions_spawn 委派任何比直接回覆更複雜的工作。

個別代理程式覆寫：agents.entries.*.subagents.delegationMode。

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

工具參數

支援 visible: true、model、cwd，以及同代理的 context: "fork"。沙箱化目標會將 cwd 限制於該代理的工作區。此路徑不支援討論串繫結、mode、思考覆寫、lightContext、attachments 和 attachAs，因為可見工作階段是透過 sessions.create 建立的持續性儀表板工作階段。若要求端本身是以繼承的工具允許清單或拒絕清單衍生，則會拒絕可見衍生；此限制在衍生時即固定，沒有設定可覆寫。工作階段列出與定址遵循 tools.sessions.visibility；預設的 tree 範圍涵蓋目前工作階段及其自身的衍生子樹。關於簽出命名、設定、清理及還原行為，請參閱受管理的工作樹。

任務名稱與目標指定

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

列出由要求端工作階段樹擁有的已衍生子代理執行和背景任務記錄。 任務列涵蓋原生子代理、ACP 執行、閘道命令列介面／媒體工作， 以及排程執行。其範圍限於目前要求端；子項目只能查看自己控制的子項目。

使用 subagents 進行隨選狀態查看和偵錯。使用 sessions_yield 等待完成事件。

使用 action: "cancel" 搭配 action: "list" 傳回的 taskId 以停止任務。取消操作僅限受控制的工作階段樹；葉節點子代理 無法取消由其他工作階段擁有的工作。

討論串繫結工作階段

當頻道啟用討論串繫結時，子代理可以持續繫結至 討論串，使該討論串中的後續使用者訊息繼續路由至 相同的子代理工作階段。

支援討論串的頻道

當頻道註冊對話繫結配接器時，便支援持續性的討論串繫結子代理工作階段 （sessions_spawn 搭配 thread: true）。內建且支援此功能的頻道包括：Discord、 iMessage、Matrix 和 Telegram。Discord 和 Matrix 預設會 建立子討論串；Telegram 和 iMessage 預設會繫結 目前的對話。請使用各頻道的 threadBindings 設定鍵來控制 啟用、逾時和 spawnSessions。

快速流程

手動控制

設定開關

• 全域預設值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 頻道覆寫和衍生自動繫結鍵因配接器而異。請參閱上方的支援討論串的頻道。

關於目前的配接器詳細資訊，請參閱設定參考和 斜線命令。

允許清單

若要求端工作階段已沙箱化，sessions_spawn 會拒絕 將在未沙箱化環境中執行的目標。

探索

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

allowAgents 項目必須指向 agents.entries.* 中已設定的代理程式 ID。 ["*"] 表示任何已設定的目標代理程式以及請求者。如果代理程式設定 已刪除，但其 ID 仍保留在 allowAgents 中，sessions_spawn 會拒絕該 ID， 而 agents_list 會將其省略。執行 openclaw doctor --fix 以清除過期的 允許清單項目；若目標應在繼承預設值的同時仍可被產生，則新增最小的 agents.entries.* 項目。

自動封存

• 子代理程式工作階段會在 agents.defaults.subagents.archiveAfterMinutes 後自動封存（預設為 60）。
• 封存會使用 sessions.delete，並將逐字記錄重新命名為 *.deleted.<timestamp>（位於相同資料夾）。
• cleanup: "delete" 會在宣告後立即封存（仍會透過重新命名保留逐字記錄）。
• 自動封存會盡力執行；若閘道重新啟動，待處理的計時器將會遺失。
• 設定的執行逾時不會自動封存；它們只會停止執行。工作階段會保留到自動封存為止。
• 自動封存同樣適用於深度 1 與深度 2 的工作階段。
• 瀏覽器清理與封存清理分開進行：執行完成時，系統會盡力關閉受追蹤的瀏覽器分頁／處理程序，即使逐字記錄／工作階段紀錄仍保留亦然。

巢狀子代理程式

預設情況下，子代理程式無法產生自己的子代理程式 （maxSpawnDepth: 1）。將 maxSpawnDepth: 2 設定為啟用一層 巢狀結構，也就是協調器模式：主要代理程式 → 協調器子代理程式 → 工作子子代理程式。

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // 允許子代理程式產生子代理程式（預設：1，範圍 1-5）        maxChildrenPerAgent: 5, // 每個代理程式工作階段的最大作用中子項目數（預設：5，範圍 1-20）        maxConcurrent: 8, // 全域並行通道上限（預設：8）        runTimeoutSeconds: 900, // sessions_spawn 的預設逾時（0 = 不逾時）        announceTimeoutMs: 120000, // 每次呼叫的閘道宣告逾時      },    },  },}

深度層級

宣告鏈

結果會沿著鏈向上傳遞：

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

每一層只會看到其直接子項目的宣告。

依深度套用的工具政策

• 子項在產生時會擷取請求者的有效傳送者政策。無傳送者的子項執行與經驗證的操作員恢復作業會保留該快照，即使 toolsBySender 之後變更亦然；目前的全域、代理程式、供應商、沙箱與子代理程式限制仍會套用。以子項為目標的新外部頻道回合則會重新解析目前的傳送者政策。
• 角色與控制範圍會在產生時寫入工作階段中繼資料。這可避免扁平化或還原後的工作階段鍵意外重新取得協調器權限。
• **深度 1（協調器，當 maxSpawnDepth >= 2 時）：**會取得 sessions_spawn、subagents、sessions_list、sessions_history，因此能產生子項並檢查其狀態。其他工作階段／系統工具仍會遭拒。
• **深度 1（葉節點，當 maxSpawnDepth == 1 時）：**沒有工作階段工具（目前的預設行為）。
• **深度 2（葉節點工作者）：**沒有工作階段工具；sessions_spawn 在深度 2 永遠會遭拒。無法再產生子項。

每個代理程式的產生限制

每個代理程式工作階段（任何深度）同一時間最多可以有 maxChildrenPerAgent 個（預設為 5）作用中子項。這可防止單一協調器無限制地向外展開。

串聯停止

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

• 主要聊天中的 /stop 會停止所有深度 1 代理程式，並串聯停止其深度 2 子項。

驗證

子代理程式驗證是依代理程式 ID解析，而不是依工作階段類型：

• 子代理程式工作階段鍵為 agent:<agentId>:subagent:<uuid>。
• 驗證儲存區會從該代理程式的 agentDir 載入。
• 主要代理程式的驗證設定檔會合併作為備援；發生衝突時，代理程式設定檔會覆寫主要設定檔。

此合併採累加方式，因此主要設定檔永遠可作為 備援。目前尚不支援每個代理程式完全隔離的驗證。

宣告

子代理程式透過宣告步驟回報：

• 宣告步驟會在子代理程式工作階段內執行（而非請求者工作階段）。
• 如果子代理程式的回覆與 ANNOUNCE_SKIP 完全一致，便不會發布任何內容。
• 如果最新的助理文字是完全一致的靜默權杖 NO_REPLY / no_reply，即使先前存在可見的進度，也會抑制宣告輸出。

傳遞方式取決於請求者的深度：

• 頂層請求者工作階段會使用具備外部傳遞（deliver=true）的後續 agent 呼叫。
• 巢狀請求者子代理程式工作階段會收到內部後續注入（deliver=false），讓協調器可以在工作階段內綜整子項結果。
• 如果巢狀請求者子代理程式工作階段已不存在，OpenClaw 會在可用時改用該工作階段的請求者。

對於頂層請求者工作階段，完成模式的直接傳遞會先 解析任何已繫結的對話／討論串路由與鉤子覆寫，接著從請求者工作階段儲存的路由 補上缺少的頻道目標欄位。即使完成來源只識別出頻道， 這也能讓完成結果留在正確的聊天／主題中。

建立巢狀完成結果時，子項完成彙整的範圍會限定於目前的請求者執行， 避免先前執行的過期子項輸出洩漏至目前的宣告。當頻道配接器提供 討論串／主題路由時，宣告回覆會保留這些路由。

宣告內容

宣告內容會正規化為穩定的內部事件區塊：

執行終止且失敗時，會回報失敗狀態，而不會重播已擷取的 回覆文字。工具／工具結果輸出不會提升為子項結果文字。

統計資料行

宣告承載資料的結尾會包含統計資料行（即使已換行）：

• 執行時間（例如 runtime 5m12s）。
• 權杖用量（輸入／輸出／總計）。
• 已設定模型定價時的預估成本（models.providers.*.models[].cost）。
• sessionKey、sessionId 與逐字記錄路徑，讓主要代理程式可以透過 sessions_history 擷取歷程，或檢查磁碟上的檔案。

內部中繼資料僅供協調使用；面向使用者的回覆 應以一般助理語氣重寫。

為何偏好 sessions_history

sessions_history 是在代理程式回合內讀取子項 逐字記錄時較安全的協調路徑：

• 即使停用一般用途的日誌遮蔽功能，也會遮蔽類似認證資訊／權杖的文字。
• 截斷過長的文字區塊（每個區塊 4000 個字元），並捨棄思考簽章、推理重播承載資料與行內影像資料。
• 強制執行 80 KB 的回應上限；過大的資料列會替換為 [sessions_history omitted: message too large]。
• 如果存在 nextOffset，請使用它向後翻閱較舊的逐字記錄視窗。
• sessions_history 不會從訊息文字中移除推理標籤、<relevant-memories> 鷹架或工具呼叫 XML；它會傳回接近原始逐字記錄格式的結構化內容區塊，只是經過遮蔽並限制大小。/subagents log 會套用更完整的散文清理器（移除推理標籤、記憶鷹架與工具呼叫 XML），因為它會呈現純文字聊天行，而非結構化區塊。
• 當你需要完整且逐位元組一致的逐字記錄時，直接檢查磁碟上的原始逐字記錄是備援方式。

工具政策

子代理程式會先使用與父代理程式或目標代理程式相同的設定檔與工具政策 流水線。之後，OpenClaw 會套用子代理程式限制 層。

無論深度或角色為何，子代理程式一律無法使用 gateway、agents_list、session_status 與 cron（系統層級／互動式工具，或 應由主要代理程式協調的工具）。葉節點子代理程式（預設的深度 1 行為，以及一律適用於深度 2 的行為）還會失去 subagents、 sessions_list、sessions_history 與 sessions_spawn。子代理程式永遠 不會取得 message 工具；它是在產生時停用，而不是由 此拒絕清單篩除；sessions_send 也會維持停用，讓子代理程式 只能透過宣告鏈通訊。

sessions_history 在此同樣是有界限且經過清理的回憶檢視， 而不是原始逐字記錄傾印。

當 maxSpawnDepth >= 2 時，深度 1 協調器子代理程式還會 收到 sessions_spawn、subagents、sessions_list 與 sessions_history，讓它們能管理自己的子項。

透過設定覆寫

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // 拒絕規則優先        deny: ["gateway", "cron"],        // 若設定 allow，便會變成僅允許清單（拒絕規則仍優先）        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow 是最終的僅允許篩選器。它可以縮小 已解析的工具集，但無法重新加入遭 tools.profile 移除的工具。例如，tools.profile: "coding" 包含 web_search/web_fetch，但不包含 browser 工具。若要讓 程式設計設定檔的子代理使用瀏覽器自動化，請在 設定檔階段加入 browser：

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

當只有一個代理應取得瀏覽器自動化功能時，請使用每個代理的 agents.entries.*.tools.alsoAllow: ["browser"]。

並行處理

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

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

存活狀態與復原

OpenClaw 不會將缺少 endedAt 視為子代理仍然存活的 永久證明。未結束且早於過期執行時間範圍的執行 （2 小時，或設定的執行逾時加上一小段寬限期， 以較長者為準），不再計入 /subagents list、 狀態摘要、後代完成閘控及每個工作階段的 並行檢查中的作用中／待處理項目。

閘道重新啟動後，過期且未結束的已還原執行將被清除，除非 其子工作階段標記為 abortedLastRun: true。因重新啟動而中止的 執行仍會登記在子代理孤兒復原流程中：過期的 執行會直接完成，不進行恢復；而較新的子工作階段會先收到 合成的恢復訊息，之後才會清除中止標記。

每個子工作階段的自動重新啟動復原次數有限。如果同一個 子代理子項目在快速再次卡住的時間範圍內反覆獲准進行孤兒復原， OpenClaw 會在該工作階段中保存復原墓碑，並停止在後續重新啟動時 自動恢復它。請執行 openclaw tasks maintenance --apply 以協調任務記錄，或執行 openclaw doctor --fix 以清除已設有墓碑之工作階段中 過期的中止復原旗標。

停止

• 在要求端聊天中傳送 /stop，會中止要求端工作階段，並停止由該工作階段產生的所有作用中子代理執行，且會連鎖停止巢狀子項目。

限制

• 子代理公告為盡力而為。如果閘道重新啟動，待處理的「回傳公告」工作將會遺失。
• 子代理仍共用相同的閘道處理程序資源；請將 maxConcurrent 視為安全閥。
• sessions_spawn 一律為非阻塞：它會立即傳回 { status: "accepted", runId, childSessionKey }。
• 子代理內容僅注入 AGENTS.md 和 TOOLS.md（不含 SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md 或 BOOTSTRAP.md）。Codex 原生子代理遵循相同邊界：TOOLS.md 會保留在繼承的 Codex 執行緒指示中，而僅限父項目的角色設定、身分與使用者檔案，則會以單一回合範圍的協作指示注入，避免子項目複製這些內容。
• 最大巢狀深度為 5（maxSpawnDepth 範圍：1-5）。大多數使用情境建議使用深度 2。
• maxChildrenPerAgent 會限制每個工作階段的作用中子項目數量（預設為 5，範圍為 1-20）。

相關內容

• 工作階段工具與狀態變更
• ACP 代理
• 代理傳送
• 背景任務
• 多代理沙箱工具