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>
This commit is contained in:
Chris
@@ -1,25 +1,28 @@
|
||||
# sessions_spawn / sessions_send 使用指南
|
||||
|
||||
> 適用版本：OpenClaw v2026.4.x
|
||||
> 更新日期：2026-04-09
|
||||
> 更新日期：2026-04-10
|
||||
> 狀態：v4.1 修正版（修正 spawn/send 工具權限行為）
|
||||
|
||||
---
|
||||
|
||||
## Agents vs Sub-agent Runs
|
||||
## 核心概念
|
||||
|
||||
### Agent vs Sub-agent Run
|
||||
|
||||
**Agent** = 有自己 workspace、設定檔、記憶的持久實體。在 `openclaw.json` 的 `agents.list` 裡定義。
|
||||
|
||||
**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，那次在隔離 session 裡的執行。Session key 格式：`agent:<agentId>:subagent:<uuid>`。
|
||||
**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，在隔離 session 裡的那次執行。Session key 格式：`agent:<agentId>:subagent:<uuid>`。
|
||||
|
||||
兩者不是不同等級，只是存在方式不同：同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回去。
|
||||
同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回 parent。
|
||||
|
||||
---
|
||||
|
||||
## sessions_spawn — 派工（非阻塞）
|
||||
## sessions_spawn — 非阻塞派工
|
||||
|
||||
**行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。
|
||||
|
||||
**使用場景：** 獨立任務，不需要即時來回溝通。
|
||||
**使用場景：** Pipeline 步驟交接、獨立任務、並行研究。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -41,23 +44,18 @@
|
||||
| `sandbox: "require"` | 強制沙箱隔離 |
|
||||
| `model` | 覆蓋模型設定 |
|
||||
|
||||
**限制：**
|
||||
- 最多 5 層深（spawn 的 spawn 的 spawn...）
|
||||
- 最多 5 個並行
|
||||
- 預設葉層 sub-agent 不具備 sessions 工具（無法再 spawn）
|
||||
|
||||
---
|
||||
|
||||
## sessions_send — 同步溝通（可等待回覆）
|
||||
## sessions_send — 同步對話（阻塞）
|
||||
|
||||
**行為：** 向另一個 session 傳訊，可設定是否等待回覆。支援最多 5 輪來回。
|
||||
**行為：** 向另一個 session 傳訊，sender 等待回覆。支援最多 5 輪來回。
|
||||
|
||||
**使用場景：** 追問細節、審查來回、交叉確認。
|
||||
**使用場景：** CEO 問秘書即時問題、depth-0 agent 之間的直接對話。
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionKey": "agent:reviewer:subagent:xxxx",
|
||||
"message": "請審查以下量化策略內容：[...]",
|
||||
"sessionKey": "agent:secretary:subagent:xxxx",
|
||||
"message": "給我今日工作摘要",
|
||||
"timeoutSeconds": 60
|
||||
}
|
||||
```
|
||||
@@ -74,14 +72,82 @@
|
||||
|
||||
---
|
||||
|
||||
## maxSpawnDepth — 子 agent 工具權限控制
|
||||
|
||||
這是控制嵌套 spawn 能力的核心參數。
|
||||
|
||||
### 設定方式
|
||||
|
||||
在 `openclaw.json` 中設定：
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"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 建議設定
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"tools": {
|
||||
"subagents": {
|
||||
"maxSpawnDepth": 2, // 策略師（depth 1）可以 spawn 研究員（depth 2）
|
||||
"maxChildrenPerAgent": 7, // 策略師最多需要 spawn 7 個研究員
|
||||
"maxConcurrent": 8,
|
||||
"allowAgents": ["*"] // 允許 spawn 任何 agent
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用情境對照
|
||||
|
||||
| 情境 | 工具 | 原因 |
|
||||
|---|---|---|
|
||||
| 蒐集資料 | spawn | 獨立任務，不需互動 |
|
||||
| 寫回測程式 | spawn | 獨立任務 |
|
||||
| 多空平行研究 | spawn（兩個） | 並行執行 |
|
||||
| 追問研究員細節 | send | 兩個 agent 直接對話 |
|
||||
| 審查員來回審查 | send | 需要 ping-pong |
|
||||
| 請秘書做摘要 | spawn 或 send | 依是否需要等待 |
|
||||
| Coordinator 討論 | send（逐一收集） | 整合多方觀點 |
|
||||
| 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 |
|
||||
|
||||
Reference in New Issue
Block a user