Files

Chris e44b959c85 docs: v4.1 協作協定重構、新增工具配置指南

- 新增 spec_v4_collaboration_protocol.md：Message Envelope、Intent 類型、
  Pipeline 改由策略師主導、Lobster DSL 取代 Standing Orders、輸出 Schema 定義
- 新增 guide_tools_skills.md：每個角色的 MCP Tools + Skills 配置對照表
- 改寫 guide_sessions_tools.md：修正 maxSpawnDepth 行為，sessions_send 不授權給子 agent
- 更新 agent_roster.md：新增 MCP Tools / Skills 欄位
- 更新排程記憶文件：移除舊協作章節，指向新協作協定
- 更新 INDEX.md：v4.1 索引與變更紀錄

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-10 02:30:39 +08:00

5.0 KiB

Raw Blame History

sessions_spawn / sessions_send 使用指南

適用版本：OpenClaw v2026.4.x
更新日期：2026-04-10
狀態：v4.1 修正版（修正 spawn/send 工具權限行為）

核心概念

Agent vs Sub-agent Run

Agent = 有自己 workspace、設定檔、記憶的持久實體。在 openclaw.json 的 agents.list 裡定義。

Sub-agent run = 當一個 Agent 被 sessions_spawn 呼叫時，在隔離 session 裡的那次執行。Session key 格式：agent:<agentId>:subagent:<uuid>。

同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回 parent。

sessions_spawn — 非阻塞派工

行為： 立即返回 runId 和 childSessionKey，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。

使用場景： Pipeline 步驟交接、獨立任務、並行研究。

{
  "agentId": "finance_researcher",
  "task": "蒐集今日盤前財經資訊，輸出 Finance_Research_Brief.json",
  "thread": true,
  "runtime": "subagent"
}

關鍵參數：

參數	說明
`agentId`	目標 Agent ID
`task`	給對方的任務提示
`runtime`	`subagent`（預設）或 `acp`
`thread: true`	綁定到 Discord 執行緒
`sandbox: "require"`	強制沙箱隔離
`model`	覆蓋模型設定

sessions_send — 同步對話（阻塞）

行為： 向另一個 session 傳訊，sender 等待回覆。支援最多 5 輪來回。

使用場景： CEO 問秘書即時問題、depth-0 agent 之間的直接對話。

{
  "sessionKey": "agent:secretary:subagent:xxxx",
  "message": "給我今日工作摘要",
  "timeoutSeconds": 60
}

操作模式：

模式	設定	用途
等待回覆	`timeoutSeconds > 0`	需要立即得到回應
即發即忘	`timeoutSeconds: 0`	不需等回覆
多輪來回	自動支援，最多 5 輪	審查、追問

對方可回覆 REPLY_SKIP 提早結束來回。

maxSpawnDepth — 子 agent 工具權限控制

這是控制嵌套 spawn 能力的核心參數。

設定方式

在 openclaw.json 中設定：

{
  "tools": {
    "subagents": {
      "maxSpawnDepth": 2,           // 允許 depth-1 子 agent 再 spawn
      "maxChildrenPerAgent": 5,      // 每個 session 最多 5 個子 agent（可調至 20）
      "maxConcurrent": 8             // 全局最大併發
    }
  }
}

各深度的工具權限

深度	角色	可用的 Session 工具
Depth 0（主 agent）	完整權限	`sessions_spawn`, `sessions_send`, `subagents`, `sessions_list`, `sessions_history`
Depth 1（maxSpawnDepth=1）	葉層	❌ 無任何 session 工具
Depth 1（maxSpawnDepth≥2）	編排者	✅ `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`
Depth 2+	永遠葉層	❌ 無任何 session 工具（`sessions_spawn` 永遠被拒絕）

關鍵限制

限制	說明
`sessions_send` 不授權給任何子 agent	無論 maxSpawnDepth 設多少，被 spawn 的 agent 都不能用 `sessions_send`
通訊方向為單向往上	子 agent 只能 announce 結果回 parent，不能橫向溝通
同層不能對話	兩個 depth-2 的子 agent 之間無法直接通訊
Depth 2 永遠是葉層	即使 maxSpawnDepth > 2，depth-2 的 agent 也不能再 spawn

KingClawArmy 建議設定

{
  "tools": {
    "subagents": {
      "maxSpawnDepth": 2,           // 策略師（depth 1）可以 spawn 研究員（depth 2）
      "maxChildrenPerAgent": 7,      // 策略師最多需要 spawn 7 個研究員
      "maxConcurrent": 8,
      "allowAgents": ["*"]           // 允許 spawn 任何 agent
    }
  }
}

使用情境對照

情境	工具	原因
CEO 啟動量化 pipeline	spawn 策略師	CEO 不能阻塞
策略師派工給情報員	spawn	獨立任務（策略師是 depth-1 編排者）
策略師並行派工多方/空方	spawn（兩個）	並行執行
策略師發現報告缺漏	重新 spawn	帶上前次結果 + 修改意見
策略師提交審查	spawn 審查員	審查是獨立任務
審查退回修改	策略師重新 spawn	帶上 Review_Report.json 的 issues
CEO 問秘書今日摘要	send	CEO 是 depth-0，需要即時回覆
你在 Discord 問 CEO	Discord message	不經 session 工具

常見錯誤

錯誤	為什麼不行	正確做法
策略師 send 研究員追問	被 spawn 的 agent 沒有 `sessions_send`	重新 spawn，帶上問題
CEO 用 send 啟動 pipeline	CEO 會阻塞等整條 pipeline 跑完	用 spawn
研究員之間互相 send	同層子 agent 不能橫向通訊	各自 announce 回策略師，由策略師整合
用 Standing Orders 定義 pipeline	自然語言無強制力	用 Lobster DSL 定義 flow
Agent 用自由文字溝通	接收方要猜意圖	用 Message Envelope + intent

5.0 KiB Raw Blame History Unescape Escape