> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 子代理程式 子代理程式是從現有代理程式執行中產生的背景代理程式執行。 每個子代理程式都在自己的工作階段（`agent::subagent:`）中執行， 完成後會將結果**公告**回請求者的聊天頻道。 每次子代理程式執行都會追蹤為一項[背景任務](/zh-TW/automation/tasks)。 目標： * 將研究、長時間任務及緩慢的工具工作平行化，而不阻塞主要執行。 * 預設讓子代理程式保持隔離（工作階段分離、選用的沙箱化）。 * 讓工具介面不易遭誤用：子代理程式預設**不會**取得工作階段或訊息工具。 * 支援可設定的巢狀深度，以用於協調器模式。 \*\*成本注意事項：\*\*預設情況下，每個子代理程式都有自己的上下文和權杖用量。 對於繁重或重複性的任務，請為子代理程式設定較便宜的模型， 並透過 `agents.defaults.subagents.model` 或個別代理程式覆寫， 讓主要代理程式繼續使用品質較高的模型。當子代理程式 確實需要請求者目前的文字記錄時，請使用 `context: "fork"` 來產生它。綁定討論串的子代理程式工作階段預設為 `context: "fork"`，因為它們會將目前的對話分支至 後續討論串。 ## 斜線命令 `/subagents` 會檢查**目前工作階段**的子代理程式執行： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /subagents list /subagents log [limit] [tools] /subagents info ``` `/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 ID、 文字記錄路徑、清理）。`/subagents log` 會列印某次執行最近的聊天輪次； 加入 `tools` 權杖即可包含工具呼叫／結果訊息（預設省略）。 在代理程式輪次中，使用 `sessions_history` 可取得有界且經安全篩選的回顧檢視， 也可以檢查磁碟上的文字記錄路徑，以查看未處理的完整文字記錄。 在 Control UI 中，近期有子執行的父工作階段會顯示可展開的 側邊欄資料列。巢狀資料列會顯示子代理程式的狀態和執行時間，選取其中一個 即可開啟該子代理程式的聊天，同時保留父層階層。 ### 討論串綁定控制項 這些命令適用於支援持久討論串綁定的頻道。請參閱下方的 [支援討論串的頻道](#thread-supporting-channels)。 ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /focus /unfocus /agents /session idle /session max-age ``` ### 產生行為 代理程式使用 `sessions_spawn` 工具啟動背景子代理程式。 完成結果會以內部父工作階段事件傳回；父代理程式／請求者 代理程式會決定是否需要向使用者顯示更新。 * `sessions_spawn` 是非阻塞的；它會立即傳回執行 ID。 * 完成時，子代理程式會回報給父工作階段／請求者工作階段。 * 需要子代理程式結果的代理程式輪次，應在產生所需工作後呼叫 `sessions_yield`。這會結束目前輪次，並讓完成事件成為下一則模型可見訊息。 * 完成機制採用推送方式。產生後，請**勿**為了等待其完成而在迴圈中輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；僅在偵錯時按需檢查狀態。 * 子代理程式的輸出是供請求者代理程式彙整的報告／證據。它不是使用者撰寫的指示文字，也不能覆寫系統、開發者或使用者政策。 * 完成時，OpenClaw 會盡力關閉該子代理程式工作階段開啟且受到追蹤的瀏覽器分頁／程序，然後才會繼續公告清理流程。 * OpenClaw 會透過具有穩定冪等性金鑰的 `agent` 輪次，將完成結果傳回請求者工作階段。 * 如果請求者執行仍在進行中，OpenClaw 會先嘗試喚醒／引導該執行，而非啟動第二條可見回覆路徑。 * 如果無法喚醒進行中的請求者，OpenClaw 會改以相同的完成上下文移交給請求者代理程式，而不會捨棄公告。 * 即使父代理程式決定不需要向使用者顯示更新，只要成功移交給父代理程式，就會完成子代理程式結果的傳遞。 * 原生子代理程式不會取得訊息工具。它們會將純助理文字傳回父代理程式／請求者代理程式；人類可見的回覆仍由父代理程式／請求者代理程式的一般傳遞政策負責。 * 如果無法使用直接移交，傳遞會退回至佇列路由，接著以短暫的指數退避方式重試公告，最後才會放棄。 * 傳遞會保留已解析的請求者路由：可用時，綁定討論串或綁定對話的完成路由優先。如果完成來源僅提供頻道，OpenClaw 會從請求者工作階段的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）補上缺少的目標／帳號，讓直接傳遞仍可運作。 傳遞至請求者工作階段的完成移交內容是執行階段產生的 內部上下文（不是使用者撰寫的文字），其中包含： * `Result` — 子代理程式最新可見的 `assistant` 回覆文字。工具／toolResult 輸出不會提升為子代理程式結果。以失敗告終的執行不會重複使用已擷取的回覆文字。 * `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`。 * 精簡的執行階段／權杖統計資料。 * 一項審查指示，要求請求者代理程式先驗證結果，再決定原始任務是否已完成。 * 一項後續指引，要求請求者代理程式在子代理程式結果仍需採取更多動作時，繼續執行任務或記錄後續事項。 * 一項適用於無需採取更多動作路徑的最終更新指示，使用一般助理語氣撰寫，不轉送未處理的內部中繼資料。 * `--model` 和 `--thinking` 會覆寫該特定執行的預設值。 * 使用 `info`/`log` 檢查完成後的詳細資料和輸出。 * 對於持久且綁定討論串的工作階段，請搭配 `thread: true` 和 `mode: "session"` 使用 `sessions_spawn`。 * 如果請求者頻道不支援討論串綁定，請使用 `mode: "run"`，不要重試不可能成功的討論串綁定組合。 * 對於 ACP 控制框架工作階段（Claude Code、Gemini CLI、OpenCode，或明確指定的 Codex ACP/acpx），當工具宣告支援該執行階段時，請搭配 `runtime: "acp"` 使用 `sessions_spawn`。偵錯完成結果或代理程式間迴圈時，請參閱 [ACP 傳遞模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` 外掛時，除非使用者明確要求 ACP/acpx，否則 Codex 聊天／討論串控制應優先使用 `/codex ...`，而非 ACP。 * 在啟用 ACP、請求者未處於沙箱中，且已載入 `acpx` 之類的後端外掛之前，OpenClaw 會隱藏 `runtime: "acp"`。`runtime: "acp"` 需要外部 ACP 控制框架 ID，或具有 `runtime.type="acp"` 的 `agents.entries.*` 項目；對於來自 `agents_list` 的一般 OpenClaw 設定代理程式，請使用預設的子代理程式執行階段。 ## 上下文模式 除非呼叫者明確要求分支目前的文字記錄，否則原生子代理程式啟動時會彼此隔離。 | 模式 | 適用時機 | 行為 | | ---------- | ----------------------------------- | --------------------------- | | `isolated` | 全新研究、獨立實作、緩慢的工具工作，或任何可在任務文字中完整說明的工作 | 建立乾淨的子文字記錄。這是預設值，能降低權杖用量。 | | `fork` | 依賴目前對話、先前工具結果，或請求者文字記錄中已存在之細微指示的工作 | 在子代理程式啟動前，將請求者文字記錄分支至子工作階段。 | 請謹慎使用 `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`。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { subagents: { delegationMode: "prefer", maxConcurrent: 4, }, }, list: [ { id: "coordinator", subagents: { delegationMode: "prefer" }, }, ], }, } ``` ### 工具參數 子代理的任務說明。 選用的穩定控制代稱，用於在之後的狀態輸出中識別特定子項目。必須符合 `[a-z][a-z0-9_-]{0,63}`，且不得為 `last` 或 `all` 等保留目標。 選用的易讀標籤。 在 `subagents.allowAgents` 允許時，於另一個已設定的代理 ID 下衍生。 子項目執行任務時的選用工作目錄。原生子代理仍會從目標代理工作區載入啟動檔案；`cwd` 僅變更執行階段工具和命令列介面框架執行委派工作的所在位置。 `acp` 僅供外部 ACP 框架（`claude`、`droid`、`gemini`、`opencode`，或明確要求的 Codex ACP/acpx）使用，也適用於 `agents.entries.*` 項目中 `runtime.type` 為 `acp` 的情況。 僅限 ACP。當 `runtime: "acp"` 時繼續既有的 ACP 框架工作階段；原生子代理衍生會忽略此項。 僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流至父工作階段；原生子代理衍生請省略此項。 覆寫子代理模型。無效值會被略過，子代理將使用預設模型執行，且工具結果中會顯示警告。 覆寫子代理執行的思考層級。不適用於 `visible: true`。 當 `true` 時，要求將此子代理工作階段繫結至頻道討論串。 若為 `thread: true` 且省略 `mode`，預設值會變成 `session`。`mode: "session"` 需要 `thread: true`。 若要求端頻道無法使用討論串繫結，請改用 `mode: "run"`。 使用 `visible: true` 時，請省略 `mode`；可見工作階段會持續存在，且不支援 `mode: "run"`。 `"delete"` 會在公告後立即封存工作階段（仍會透過重新命名保留逐字記錄）。 除非目標子執行階段已沙箱化，否則 `require` 會拒絕衍生。 `fork` 會將要求端目前的逐字記錄分支至子工作階段。僅限原生子代理。繫結討論串的衍生預設為 `fork`；非討論串衍生預設為 `isolated`。可見分支必須以與要求端相同的代理為目標。 建立使用者可在 Control UI 中開啟的持續性儀表板工作階段。可見衍生僅支援 `runtime: "subagent"`，並一律保留所建立的工作階段。 為新的儀表板工作階段佈建受管理的 git 工作樹。需要 `visible: true`。 選用的受管理工作樹名稱。需要 `visible: true` 和 `worktree: true`。 受管理工作樹的選用 git 基底參照。需要 `visible: true` 和 `worktree: true`。 `sessions_spawn` **不**接受頻道傳遞參數（`target`、 `channel`、`to`、`threadId`、`replyTo`、`transport`）。原生子代理會將其 最新的助理回合回報給要求端；外部傳遞仍由 父代理／要求端代理負責。 支援 `visible: true`、`model`、`cwd`，以及同代理的 `context: "fork"`。沙箱化目標會將 `cwd` 限制於該代理的工作區。此路徑不支援討論串繫結、`mode`、思考覆寫、`lightContext`、`attachments` 和 `attachAs`，因為可見工作階段是透過 `sessions.create` 建立的持續性儀表板工作階段。若要求端本身是以繼承的工具允許清單或拒絕清單衍生，則會拒絕可見衍生；此限制在衍生時即固定，沒有設定可覆寫。工作階段列出與定址遵循 `tools.sessions.visibility`；預設的 `tree` 範圍涵蓋目前工作階段及其自身的衍生子樹。關於簽出命名、設定、清理及還原行為，請參閱[受管理的工作樹](/zh-TW/concepts/managed-worktrees)。 ### 任務名稱與目標指定 `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`。 ### 快速流程 `sessions_spawn` 搭配 `thread: true`（並可選擇性加入 `mode: "session"`）。 OpenClaw 會在作用中的頻道中建立討論串，或將討論串繫結至該工作階段目標。 該討論串中的回覆和後續訊息會路由至已繫結的工作階段。 使用 `/session idle` 檢查／更新閒置自動取消聚焦，並使用 `/session max-age` 控制硬性上限。 使用 `/unfocus` 手動解除連結。 ### 手動控制 | 命令 | 效果 | | ------------------ | --------------------------------------------------------------- | | `/focus ` | 將目前討論串（或建立一個討論串）繫結至子代理／工作階段目標 | | `/unfocus` | 移除目前已繫結討論串的繫結 | | `/agents` | 列出作用中執行和繫結狀態（`binding:`、`unbound` 或 `bindings unavailable`） | | `/session idle` | 檢查／更新閒置自動取消聚焦（僅限已聚焦的繫結討論串） | | `/session max-age` | 檢查／更新硬性上限（僅限已聚焦的繫結討論串） | ### 設定開關 * **全域預設值：** `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 * **頻道覆寫和衍生自動繫結鍵**因配接器而異。請參閱上方的[支援討論串的頻道](#thread-supporting-channels)。 關於目前的配接器詳細資訊，請參閱[設定參考](/zh-TW/gateway/configuration-reference)和 [斜線命令](/zh-TW/tools/slash-commands)。 ### 允許清單 可透過明確的 `agentId` 指定為目標的已設定代理 ID 清單（`["*"]` 允許任何已設定目標）。預設值：僅限要求端代理。若設定清單後仍希望要求端使用 `agentId` 衍生自身，請將要求端 ID 納入清單。 當要求端代理未設定自己的 `subagents.allowAgents` 時所使用的預設已設定目標代理允許清單。 阻擋省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。個別代理覆寫：`agents.entries.*.subagents.requireAgentId`。 閘道 `agent` 公告傳遞嘗試的個別呼叫逾時。值為正整數毫秒，並會限制在平台安全的計時器最大值。暫時性重試可能使公告的總等待時間超過單一設定逾時。 若要求端工作階段已沙箱化，`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.`（位於相同資料夾）。 * `cleanup: "delete"` 會在宣告後立即封存（仍會透過重新命名保留逐字記錄）。 * 自動封存會盡力執行；若閘道重新啟動，待處理的計時器將會遺失。 * 設定的執行逾時**不會**自動封存；它們只會停止執行。工作階段會保留到自動封存為止。 * 自動封存同樣適用於深度 1 與深度 2 的工作階段。 * 瀏覽器清理與封存清理分開進行：執行完成時，系統會盡力關閉受追蹤的瀏覽器分頁／處理程序，即使逐字記錄／工作階段紀錄仍保留亦然。 ## 巢狀子代理程式 預設情況下，子代理程式無法產生自己的子代理程式 （`maxSpawnDepth: 1`）。將 `maxSpawnDepth: 2` 設定為啟用一層 巢狀結構，也就是**協調器模式**：主要代理程式 → 協調器子代理程式 → 工作子子代理程式。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { subagents: { maxSpawnDepth: 2, // 允許子代理程式產生子代理程式（預設：1，範圍 1-5） maxChildrenPerAgent: 5, // 每個代理程式工作階段的最大作用中子項目數（預設：5，範圍 1-20） maxConcurrent: 8, // 全域並行通道上限（預設：8） runTimeoutSeconds: 900, // sessions_spawn 的預設逾時（0 = 不逾時） announceTimeoutMs: 120000, // 每次呼叫的閘道宣告逾時 }, }, }, } ``` ### 深度層級 | 深度 | 工作階段鍵格式 | 角色 | 可以產生？ | | -- | -------------------------------------------- | ------------------- | ----------------------- | | 0 | `agent::main` | 主要代理程式 | 永遠可以 | | 1 | `agent::subagent:` | 子代理程式（允許深度 2 時為協調器） | 僅當 `maxSpawnDepth >= 2` | | 2 | `agent::subagent::subagent:` | 子子代理程式（葉節點工作者） | 永遠不行 | ### 宣告鏈 結果會沿著鏈向上傳遞： 1. 深度 2 工作者完成 → 向其父項（深度 1 協調器）宣告。 2. 深度 1 協調器收到宣告、綜整結果並完成 → 向主要代理程式宣告。 3. 主要代理程式收到宣告並傳遞給使用者。 每一層只會看到其直接子項目的宣告。 \*\*操作指引：\*\*只啟動一次子項工作並等待完成 事件，請勿圍繞 `sessions_list`、 `sessions_history`、`/subagents list` 或 `exec` 睡眠命令建立輪詢迴圈。 `sessions_list` 與 `/subagents list` 會使子工作階段關係 專注於即時工作：執行中的子項目會保持附加，已結束的子項目會在最近項目視窗中 短暫保持可見，而僅存在於儲存區的過期子項目連結則會在其 有效期限視窗後遭到忽略。這可防止舊的 `spawnedBy` / `parentSessionKey` 中繼資料在重新啟動後讓幽靈子項目重新出現。 如果子項完成事件在你已傳送最終答案後才抵達，正確的後續處理是回覆完全一致的靜默權杖 `NO_REPLY` / `no_reply`。 ### 依深度套用的工具政策 * 子項在產生時會擷取請求者的有效傳送者政策。無傳送者的子項執行與經驗證的操作員恢復作業會保留該快照，即使 `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::subagent:`。 * 驗證儲存區會從該代理程式的 `agentDir` 載入。 * 主要代理程式的驗證設定檔會合併作為**備援**；發生衝突時，代理程式設定檔會覆寫主要設定檔。 此合併採累加方式，因此主要設定檔永遠可作為 備援。目前尚不支援每個代理程式完全隔離的驗證。 ## 宣告 子代理程式透過宣告步驟回報： * 宣告步驟會在子代理程式工作階段內執行（而非請求者工作階段）。 * 如果子代理程式的回覆與 `ANNOUNCE_SKIP` 完全一致，便不會發布任何內容。 * 如果最新的助理文字是完全一致的靜默權杖 `NO_REPLY` / `no_reply`，即使先前存在可見的進度，也會抑制宣告輸出。 傳遞方式取決於請求者的深度： * 頂層請求者工作階段會使用具備外部傳遞（`deliver=true`）的後續 `agent` 呼叫。 * 巢狀請求者子代理程式工作階段會收到內部後續注入（`deliver=false`），讓協調器可以在工作階段內綜整子項結果。 * 如果巢狀請求者子代理程式工作階段已不存在，OpenClaw 會在可用時改用該工作階段的請求者。 對於頂層請求者工作階段，完成模式的直接傳遞會先 解析任何已繫結的對話／討論串路由與鉤子覆寫，接著從請求者工作階段儲存的路由 補上缺少的頻道目標欄位。即使完成來源只識別出頻道， 這也能讓完成結果留在正確的聊天／主題中。 建立巢狀完成結果時，子項完成彙整的範圍會限定於目前的請求者執行， 避免先前執行的過期子項輸出洩漏至目前的宣告。當頻道配接器提供 討論串／主題路由時，宣告回覆會保留這些路由。 ### 宣告內容 宣告內容會正規化為穩定的內部事件區塊： | 欄位 | 來源 | | ------- | ------------------------------------------------------------ | | 來源 | `subagent` 或 `cron` | | 工作階段 ID | 子工作階段鍵／ID | | 類型 | 宣告類型 + 任務標籤 | | 狀態 | 從執行階段結果（`ok`、`error`、`timeout` 或 `unknown`）衍生，而**不是**從模型文字推斷 | | 結果內容 | 子項最新的可見助理文字 | | 後續處理 | 說明何時應回覆或保持靜默的指示 | 執行終止且失敗時，會回報失敗狀態，而不會重播已擷取的 回覆文字。工具／工具結果輸出不會提升為子項結果文字。 ### 統計資料行 宣告承載資料的結尾會包含統計資料行（即使已換行）： * 執行時間（例如 `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` **不會**從訊息文字中移除推理標籤、`` 鷹架或工具呼叫 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`，讓它們能管理自己的子項。 ### 透過設定覆寫 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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` 以清除已設有墓碑之工作階段中 過期的中止復原旗標。 如果產生子代理時因閘道 `PAIRING_REQUIRED` / `scope-upgrade` 而失敗，請先檢查 RPC 呼叫端，再編輯配對狀態。 當呼叫端已在閘道要求內容中執行時，內部 `sessions_spawn` 協調會在處理程序內分派，因此不會開啟回送 WebSocket，也不依賴 命令列介面的已配對裝置範圍基準。在閘道處理程序外的呼叫端仍會使用 WebSocket 後援，並以 `client.id: "gateway-client"` 搭配 `client.mode: "backend"` 透過直接回送共用權杖／密碼驗證。遠端呼叫端、明確的 `deviceIdentity`、明確的裝置權杖路徑，以及瀏覽器／節點用戶端， 仍需一般裝置核准才能升級範圍。 ## 停止 * 在要求端聊天中傳送 `/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`）。 ## 相關內容 * [工作階段工具與狀態變更](/zh-TW/concepts/session-tool) * [ACP 代理](/zh-TW/tools/acp-agents) * [代理傳送](/zh-TW/tools/agent-send) * [背景任務](/zh-TW/automation/tasks) * [多代理沙箱工具](/zh-TW/tools/multi-agent-sandbox-tools)