edc1036435
- 刪除 v2/v3 所有舊規格文件 - 將 v4 規格文件移至 spec/ 目錄 - 新增 guides/ 目錄，包含： - guide_openclaw_config.md：openclaw.json 設定、Discord 接入、Gateway 管理 - guide_workspace_files.md：8 個 Workspace 設定檔正確用途 - guide_sessions_tools.md：sessions_spawn/send 參數與 Agents vs Sub-agent run 說明 - 更新 spec_v4_rollout_and_risks.md：加入 Phase 0/1 實際進度 - 新增 INDEX.md 文件索引 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
88 lines
2.6 KiB
Markdown
88 lines
2.6 KiB
Markdown
# sessions_spawn / sessions_send 使用指南
|
||
|
||
> 適用版本：OpenClaw v2026.4.x
|
||
> 更新日期：2026-04-09
|
||
|
||
---
|
||
|
||
## Agents vs Sub-agent Runs
|
||
|
||
**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 結果回去。
|
||
|
||
---
|
||
|
||
## sessions_spawn — 派工（非阻塞）
|
||
|
||
**行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。
|
||
|
||
**使用場景：** 獨立任務，不需要即時來回溝通。
|
||
|
||
```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` | 覆蓋模型設定 |
|
||
|
||
**限制：**
|
||
- 最多 5 層深（spawn 的 spawn 的 spawn...）
|
||
- 最多 5 個並行
|
||
- 預設葉層 sub-agent 不具備 sessions 工具（無法再 spawn）
|
||
|
||
---
|
||
|
||
## sessions_send — 同步溝通（可等待回覆）
|
||
|
||
**行為：** 向另一個 session 傳訊，可設定是否等待回覆。支援最多 5 輪來回。
|
||
|
||
**使用場景：** 追問細節、審查來回、交叉確認。
|
||
|
||
```json
|
||
{
|
||
"sessionKey": "agent:reviewer:subagent:xxxx",
|
||
"message": "請審查以下量化策略內容：[...]",
|
||
"timeoutSeconds": 60
|
||
}
|
||
```
|
||
|
||
**操作模式：**
|
||
|
||
| 模式 | 設定 | 用途 |
|
||
|---|---|---|
|
||
| 等待回覆 | `timeoutSeconds > 0` | 需要立即得到回應 |
|
||
| 即發即忘 | `timeoutSeconds: 0` | 不需等回覆 |
|
||
| 多輪來回 | 自動支援，最多 5 輪 | 審查、追問 |
|
||
|
||
對方可回覆 `REPLY_SKIP` 提早結束來回。
|
||
|
||
---
|
||
|
||
## 使用情境對照
|
||
|
||
| 情境 | 工具 | 原因 |
|
||
|---|---|---|
|
||
| 蒐集資料 | spawn | 獨立任務，不需互動 |
|
||
| 寫回測程式 | spawn | 獨立任務 |
|
||
| 多空平行研究 | spawn（兩個） | 並行執行 |
|
||
| 追問研究員細節 | send | 兩個 agent 直接對話 |
|
||
| 審查員來回審查 | send | 需要 ping-pong |
|
||
| 請秘書做摘要 | spawn 或 send | 依是否需要等待 |
|
||
| Coordinator 討論 | send（逐一收集） | 整合多方觀點 |
|