# 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 |