e44b959c85
- 新增 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>
154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
# 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 步驟交接、獨立任務、並行研究。
|
||
|
||
```json
|
||
{
|
||
"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 之間的直接對話。
|
||
|
||
```json
|
||
{
|
||
"sessionKey": "agent:secretary:subagent:xxxx",
|
||
"message": "給我今日工作摘要",
|
||
"timeoutSeconds": 60
|
||
}
|
||
```
|
||
|
||
**操作模式：**
|
||
|
||
| 模式 | 設定 | 用途 |
|
||
|---|---|---|
|
||
| 等待回覆 | `timeoutSeconds > 0` | 需要立即得到回應 |
|
||
| 即發即忘 | `timeoutSeconds: 0` | 不需等回覆 |
|
||
| 多輪來回 | 自動支援，最多 5 輪 | 審查、追問 |
|
||
|
||
對方可回覆 `REPLY_SKIP` 提早結束來回。
|
||
|
||
---
|
||
|
||
## 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
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用情境對照
|
||
|
||
| 情境 | 工具 | 原因 |
|
||
|---|---|---|
|
||
| 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 |
|