OpenClaw 多 Agent 子任务分发：sessions_spawn 实战
/ ~/.openclaw/openclaw.json — sessions_spawn 完整配置},// 子 Agent 默认配置"spawn": {},"list": ["model": {},},"tools": {
·
OpenClaw 多 Agent 子任务分发：sessions_spawn 实战
🧬 一个 Agent 不够用？让父 Agent 自动拆解任务、生成子 Agent、并行执行、汇总结果。sessions_spawn 把 OpenClaw 从"单兵作战"升级为"指挥部模式"
📑 文章目录
- 为什么需要子任务分发：单 Agent 的天花板
- sessions_spawn 30 秒速懂：Agent 的 fork()
- sessions_spawn vs 多 Agent 路由：两种"多 Agent"有什么不同
- 核心机制：父子 Agent 的生命周期
- 实战一：架构规划 + 代码实现的两阶段分发
- 实战二：并行代码生成——同时写五个模块
- 社区案例：Patch——Telegram 协调 20 个并行 Agent
- 任务分解策略设计：什么任务该拆，怎么拆
- 子 Agent 权限隔离与安全配置
- 结果汇总：子 Agent 怎么把活儿交回来
- 调优与调试：Token 成本、超时、失败处理
- 完整配置 & 总结
1. 为什么需要子任务分发：单 Agent 的天花板
用 OpenClaw 干过大活的人都遇到过这个瓶颈：
💬 你：帮我重构整个项目，从 Express 迁移到 Hono，
包括路由层、中间件、数据库层、测试，全部迁移。
🤖 Agent（单兵作战模式）：
好的，让我开始...
[重构 routes/auth.ts] ← 45 分钟
[重构 routes/users.ts] ← 30 分钟
[重构 middleware/cors.ts] ← 15 分钟
[重构 middleware/auth.ts] ← 20 分钟
[重构 db/connection.ts] ← 25 分钟
[重构 tests/auth.test.ts] ← 40 分钟
...
⚠️ 到第 4 个文件时上下文已经 120K Token
⚠️ Compaction 触发，丢失了前面的迁移细节
⚠️ 测试文件的改动跟路由文件不一致
总耗时：3.5 小时
总成本：$18
质量：后半段明显退化
问题出在哪？
三大瓶颈
瓶颈一：串行执行
单 Agent 一次只能干一件事。五个互不依赖的文件重构，它必须一个接一个地做——即使这些任务完全可以并行。
瓶颈二：上下文污染
一个 Agent 在同一个 Session 中做所有事，路由重构的上下文（Hono 语法、中间件迁移方案）会和测试重构的上下文（vitest 配置、mock 策略）混在一起。上下文越来越大，质量越来越差。
瓶颈三：能力错配
架构规划需要深度思考（高 thinking budget），批量文件改写只需要快速执行（低 thinking budget）。单 Agent 只有一套模型配置，无法针对子任务动态调整。
sessions_spawn 解决的就是这三个问题：拆任务、给专人、并行跑。
2. sessions_spawn 30 秒速懂：Agent 的 fork()
类比理解
如果你写过 Unix/Linux 程序，你一定知道 fork() 系统调用——父进程创建一个子进程，子进程继承父进程的环境但独立运行。
sessions_spawn 就是 OpenClaw Agent 的 fork()：
Unix 世界：
父进程 → fork() → 子进程（独立 PID、独立内存空间）
OpenClaw 世界：
父 Agent → sessions_spawn → 子 Agent（独立 Session、独立上下文、独立 workspace）
💡 一句话定义：
sessions_spawn是 OpenClaw Agent 的一个内置工具，允许父 Agent 将复杂目标分解为子任务，并生成专门的子 Agent 来处理。每个子 Agent 运行在自己的 Session 中，有独立的上下文窗口，执行完毕后将结果返回给父 Agent。
它解决了什么
| 问题 | sessions_spawn 的解法 |
|---|---|
| 串行瓶颈 | 多个子 Agent 并行执行，互不等待 |
| 上下文污染 | 每个子 Agent 有独立的 Session 和上下文 |
| 能力错配 | 每个子 Agent 可以使用不同的模型和 thinking budget |
| 结果汇总 | 父 Agent 收集所有子 Agent 的结果，统一整合 |
3. sessions_spawn vs 多 Agent 路由：两种"多 Agent"有什么不同
OpenClaw 有两种"多 Agent"机制，新手容易混淆：
| 维度 | 多 Agent 路由（上篇文章） | sessions_spawn（本文） |
|---|---|---|
| 谁创建 Agent | 你（人类）在 openclaw.json 中预定义 | 父 Agent 在运行时动态创建 |
| 触发方式 | 不同渠道 / /agent <name> 手动切换 |
父 Agent 调用 sessions_spawn 工具自动生成 |
| 生命周期 | 常驻（Gateway 运行期间始终存在） | 临时（任务完成后子 Agent 销毁） |
| 典型用途 | 不同角色处理不同类型的任务 | 一个大任务拆成多个并行子任务 |
| Session | 独立长期 Session | 子 Session，结果回传给父 Session |
| 类比 | 公司里不同部门（研发部、行政部） | 项目经理临时组建专项攻坚小组 |
多 Agent 路由：
你 ──→ Telegram Bot A ──→ work Agent（常驻）
你 ──→ Telegram Bot B ──→ life Agent（常驻）
不同入口 → 不同固定 Agent
sessions_spawn：
你 ──→ 父 Agent（接收大任务）
│
├── spawn → 子 Agent 1（规划架构） ← 临时
├── spawn → 子 Agent 2（写路由） ← 临时
├── spawn → 子 Agent 3（写测试） ← 临时
│
└── 汇总子 Agent 结果 → 返回给你
一句话总结：路由是"静态分工"，spawn 是"动态派遣"。两者互补，不是替代。
4. 核心机制：父子 Agent 的生命周期
4.1 完整生命周期
Phase 1: 父 Agent 接收任务
┌─────────────────────────────────────────┐
│ 💬 你："重构整个项目，从 Express 到 Hono" │
│ │
│ 🤖 父 Agent（main）： │
│ 分析任务 → 决定拆分为 3 个子任务 │
└─────────────────────────────────────────┘
│
▼
Phase 2: 父 Agent 调用 sessions_spawn
┌─────────────────────────────────────────┐
│ 父 Agent 调用 sessions_spawn 三次： │
│ │
│ spawn({ │
│ prompt: "规划 Express→Hono 迁移架构", │
│ model: "opus-4", │
│ thinkingBudget: 20000 │
│ }) → 子 Agent A (架构师) │
│ │
│ spawn({ │
│ prompt: "重构路由层和中间件", │
│ model: "sonnet-4.5", │
│ thinkingBudget: 5000 │
│ }) → 子 Agent B (编码) │
│ │
│ spawn({ │
│ prompt: "重写所有测试", │
│ model: "sonnet-4.5", │
│ thinkingBudget: 3000 │
│ }) → 子 Agent C (测试) │
└─────────────────────────────────────────┘
│
▼
Phase 3: 子 Agent 并行执行
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 子 Agent A│ │ 子 Agent B│ │ 子 Agent C│
│ (架构师) │ │ (编码) │ │ (测试) │
│ Opus 4 │ │ Sonnet │ │ Sonnet │
│ │ │ │ │ │
│ 独立 │ │ 独立 │ │ 独立 │
│ Session │ │ Session │ │ Session │
│ 独立 │ │ 独立 │ │ 独立 │
│ 上下文 │ │ 上下文 │ │ 上下文 │
│ │ │ │ │ │
│ 输出： │ │ 输出： │ │ 输出： │
│ 架构方案 │ │ 重构代码 │ │ 测试代码 │
└──────┬───┘ └──────┬───┘ └──────┬───┘
│ │ │
▼ ▼ ▼
Phase 4: 结果汇总
┌─────────────────────────────────────────┐
│ 🤖 父 Agent 收集三个子 Agent 的结果： │
│ │
│ 子 A 返回：架构方案 + 文件变更计划 │
│ 子 B 返回：重构后的路由和中间件代码 │
│ 子 C 返回：重写后的测试文件 │
│ │
│ 父 Agent 整合 → 检查一致性 → 返回给你 │
└─────────────────────────────────────────┘
│
▼
Phase 5: 子 Agent 销毁
子 Session 关闭，资源释放
父 Agent 继续在原 Session 中工作
4.2 sessions_spawn 工具参数
// sessions_spawn 的调用参数
{
"tool": "sessions_spawn",
"arguments": {
// 必填：给子 Agent 的指令
"prompt": "规划 Express 到 Hono 的迁移架构方案...",
// 可选：子 Agent 使用的模型（不指定则继承父 Agent）
"model": "anthropic/claude-opus-4",
// 可选：子 Agent 的 thinking budget
"thinkingBudget": 20000,
// 可选：子 Agent 可使用的工具
"allowedTools": ["read_file", "exec", "browser"],
// 可选：子 Agent 的工作目录
"workingDirectory": "~/workspace/work/src/routes"
}
}
4.3 关键特性
| 特性 | 说明 |
|---|---|
| 独立 Session | 子 Agent 运行在全新的 Session 中，上下文是干净的 |
| 独立上下文 | 子 Agent 的上下文不会污染父 Agent |
| 模型可覆盖 | 子 Agent 可以用跟父 Agent 不同的模型 |
| 工具可限制 | 可以限制子 Agent 能使用哪些工具 |
| 结果回传 | 子 Agent 完成后，输出自动返回给父 Agent |
| 并行执行 | 多个 spawn 可以同时运行 |
5. 实战一：架构规划 + 代码实现的两阶段分发
5.1 场景描述
你想把一个 Express.js 项目迁移到 Hono。这需要两个阶段：
- 架构规划（需要深度思考，用 Opus）
- 代码实现（需要快速编写，用 Sonnet）
5.2 让父 Agent 自动分发
💬 你：帮我把这个 Express 项目迁移到 Hono。
先做架构规划，确认方案后再实施。
🤖 父 Agent (main, Sonnet 4.5)：
好的，我来分析项目结构...
[读取 package.json, src/ 目录结构]
项目包含：
- 12 个路由文件
- 5 个中间件
- 3 个数据库模型
- 28 个测试文件
我会分两个阶段来处理：
=== 阶段一：架构规划 ===
[调用 sessions_spawn]
生成子 Agent: architect (Opus 4, thinking: 20K)
指令："分析以下 Express.js 项目结构，规划到 Hono 的完整迁移方案。
重点关注：路由迁移策略、中间件兼容性、数据库层是否需要改动、
测试迁移策略。输出为结构化的迁移计划文档。"
⏳ 子 Agent (architect) 正在工作...
[子 Agent 返回] 迁移计划：
1. 路由层：Express.Router → Hono.app.route()，12 个文件
2. 中间件：cors/helmet 用 Hono 原生替代，auth 需重写
3. 数据库层：无需改动（已用 Repository 模式解耦）
4. 测试：supertest → @hono/testing，需更新所有测试
5. 风险点：Express 的 req.ip 在 Hono 中行为不同
=== 阶段二：并行实施 ===
方案看起来很好，我开始并行实施：
[调用 sessions_spawn × 3]
子 Agent B (Sonnet 4.5, thinking: 5K):
"按照以下迁移计划，重构 src/routes/ 下的所有路由文件..."
子 Agent C (Sonnet 4.5, thinking: 5K):
"按照以下迁移计划，重构 src/middleware/ 下的所有中间件..."
子 Agent D (Sonnet 4.5, thinking: 3K):
"按照以下迁移计划，更新所有测试文件从 supertest 到 @hono/testing..."
⏳ 三个子 Agent 并行执行中...
[子 Agent B 完成] 路由层重构完成，12 个文件已更新
[子 Agent C 完成] 中间件重构完成，5 个文件已更新
[子 Agent D 完成] 测试更新完成，28 个文件已更新
=== 汇总 ===
所有子任务完成。我来做最终整合检查...
[运行 npm test]
✅ 27/28 测试通过
⚠️ 1 个测试失败：tests/auth.test.ts（req.ip 行为差异）
让我修复这个问题...
[修复 auth.test.ts]
[运行 npm test]
✅ 28/28 测试全部通过
迁移完成！总结：
- 45 个文件已修改
- 使用了 4 个子 Agent（1 架构 + 3 实施）
- 总耗时：25 分钟（串行需要 3+ 小时）
5.3 配置父 Agent 的 SOUL.md 来引导分发策略
# SOUL.md — 支持 sessions_spawn 的父 Agent
## 任务分解策略
当收到一个大型任务（涉及 5+ 个文件或 3+ 个独立步骤）时：
1. **先分析**：读取项目结构，理解任务范围
2. **判断是否需要拆分**：
- 子任务之间是否独立？→ 拆分并行
- 需要不同深度的思考？→ 拆分用不同模型
- 单 Agent 上下文能否容纳？→ 超过 50K 就拆
3. **制定分发计划**：告诉用户你打算怎么拆，等确认后再执行
4. **使用 sessions_spawn**：
- 架构/设计类任务 → 高 thinking budget (15K-20K)
- 编码/实现类任务 → 中 thinking budget (3K-5K)
- 格式化/清理类任务 → 低 thinking budget (1K)
5. **汇总和验证**：所有子 Agent 完成后，整合结果并运行测试
## sessions_spawn 使用规则
- 每次 spawn 前告诉用户你在做什么
- 子 Agent 的 prompt 必须包含足够的上下文（不要假设子 Agent 知道之前的对话）
- 子 Agent 完成后，检查输出的一致性
- 如果子 Agent 失败，报告失败原因并决定是重试还是回退
6. 实战二：并行代码生成——同时写五个模块
6.1 场景
你在开发一个新功能，需要同时创建五个模块：API 路由、数据模型、业务逻辑、验证层、测试。
6.2 父 Agent 的分发策略
💬 你：创建一个"用户邀请"功能，包括：
1. POST /api/invites 路由
2. Invite 数据模型（PostgreSQL）
3. InviteService 业务逻辑
4. 输入验证（zod schema）
5. 完整的测试套件
🤖 父 Agent：
这是一个五模块并行开发任务。我来拆分：
[分析现有代码风格和项目约定]
[读取 CLAUDE.md 了解编码规范]
我会先生成一个共享的接口定义，然后让 5 个子 Agent 并行工作：
=== 预备工作（父 Agent 自己做）===
创建 src/types/invite.ts：
export interface Invite {
id: string;
email: string;
role: 'admin' | 'member' | 'viewer';
invitedBy: string;
expiresAt: Date;
status: 'pending' | 'accepted' | 'expired';
createdAt: Date;
}
=== 并行分发 ===
[spawn × 5 并行]
子 Agent 1: "创建 src/routes/invites.ts — POST /api/invites 路由
参考 src/routes/users.ts 的风格。类型定义见 src/types/invite.ts"
子 Agent 2: "创建 src/models/invite.model.ts — PostgreSQL 模型
参考 src/models/user.model.ts 的风格。Schema 定义见类型文件"
子 Agent 3: "创建 src/services/invite.service.ts — 业务逻辑
包含：createInvite, acceptInvite, expireInvite, listInvites"
子 Agent 4: "创建 src/validators/invite.validator.ts — zod schema
参考 src/validators/user.validator.ts 的风格"
子 Agent 5: "创建 tests/invite.test.ts — 完整测试
覆盖：创建邀请、接受邀请、过期处理、权限检查"
6.3 关键技巧：共享上下文注入
子 Agent 不能读取父 Agent 的上下文，所以父 Agent 必须在 spawn 的 prompt 中注入足够的上下文：
❌ 错误做法（子 Agent 收到一个没有上下文的指令）：
spawn({ prompt: "创建 invite 路由" })
→ 子 Agent："什么框架？什么风格？什么类型？"
✅ 正确做法（在 prompt 中注入完整上下文）：
spawn({
prompt: `
创建 src/routes/invites.ts — POST /api/invites 路由。
项目使用 Hono 框架 + TypeScript strict mode。
参考现有路由风格（src/routes/users.ts 的内容如下）：
${usersRouteContent}
Invite 类型定义（src/types/invite.ts）：
${inviteTypeContent}
编码规范：
- JSDoc 注释
- Result<T,E> 错误处理
- zod 验证在 middleware 层
`
})
7. 社区案例：Patch——Telegram 协调 20 个并行 Agent
7.1 Patch 是什么
社区中有一个叫"Patch"的项目，它是一个运行在 OpenClaw 上的主管 Agent（Supervisor）。Patch 通过 Telegram 接收用户的高层指令，然后将任务分解为多个子任务，通过 sessions_spawn 生成 5-20 个并行的子 Agent 来执行。
7.2 Patch 的工作方式
用户 → Telegram → Patch (主管 Agent)
│
│ 分析任务，制定计划
│
├── spawn → 子 Agent 1 (重构模块 A)
├── spawn → 子 Agent 2 (重构模块 B)
├── spawn → 子 Agent 3 (重构模块 C)
├── spawn → 子 Agent 4 (写测试)
├── spawn → 子 Agent 5 (更新文档)
├── spawn → 子 Agent 6 ...
├── ...
└── spawn → 子 Agent 20
所有子 Agent 并行执行
│
▼
Patch 收集结果
运行集成测试
生成总结报告
│
▼
通过 Telegram 返回给用户：
"✅ 20 个子任务完成。18 个成功，2 个需要人工审查。
集成测试 95% 通过，3 个 flaky test 需要关注。"
7.3 Patch 的配置思路
# Patch 的 SOUL.md（简化版）
## 身份
你是 Patch，一个项目协调员。你的工作不是亲自写代码，
而是将大型任务分解、分发给专门的子 Agent，并确保质量。
## 工作流程
1. 收到任务后，先花 2 分钟分析范围
2. 列出所有子任务和依赖关系
3. 将无依赖的任务并行 spawn
4. 有依赖的任务等前置完成后再 spawn
5. 所有子任务完成后，运行集成测试
6. 生成报告：成功/失败/需人工审查
## 子 Agent 分配策略
- 架构决策：Opus 4, thinking 20K
- 常规编码：Sonnet 4.5, thinking 5K
- 文档/格式：Haiku 3.5, thinking 1K
- 测试编写：Sonnet 4.5, thinking 3K
## 并行限制
- 最多同时 10 个子 Agent（避免 API rate limit）
- 如果任务超过 10 个，分批执行
## 失败处理
- 子 Agent 失败：重试一次，仍失败则标记为"需人工审查"
- 集成测试失败：分析失败原因，尝试自动修复（最多 2 轮）
7.4 关键收获
Patch 的作者分享的经验：
- 并行 20 个 Agent 比串行快 8 倍：原本 4 小时的工作，30 分钟完成
- Token 成本增加约 30%：因为每个子 Agent 都需要注入上下文，有重复。但时间节省值得这个代价
- 子 Agent 质量更高：每个子 Agent 的上下文是干净的，专注于一个任务，不会被其他任务的信息干扰
- 最大挑战是结果整合：20 个子 Agent 的输出如果有冲突（比如两个人改了同一个文件），父 Agent 需要智能合并
8. 任务分解策略设计：什么任务该拆，怎么拆
8.1 决策树：该不该用 sessions_spawn
你收到的任务 →
│
├── 涉及几个独立步骤？
│ │
│ ├── 1-2 个 → 不拆，单 Agent 搞定
│ │
│ └── 3+ 个 → 继续判断 ↓
│
├── 步骤之间有依赖吗？
│ │
│ ├── 全部有依赖（A→B→C）→ 不拆，串行更安全
│ │
│ ├── 部分有依赖 → 拆成依赖组：
│ │ Phase 1: [A, B] 并行
│ │ Phase 2: [C(依赖A), D(依赖B)] 并行
│ │
│ └── 完全独立 → 全部并行 spawn
│
├── 需要不同深度的思考吗？
│ │
│ ├── 是（如：设计+实现）→ 拆，用不同模型
│ │
│ └── 否（同质任务）→ 拆只为并行加速
│
└── 单 Agent 上下文能容纳吗？
│
├── 是（< 50K Token）→ 可以不拆
│
└── 否（> 50K Token）→ 必须拆，避免 compaction 导致质量下降
8.2 分解模式
模式 A：阶段分解（串行 spawn）
Phase 1: spawn(架构师) → 输出架构方案
↓ 方案作为输入
Phase 2: spawn(编码者) → 输出代码
↓ 代码作为输入
Phase 3: spawn(测试者) → 输出测试
适用场景：后一步依赖前一步的输出。
模式 B：并行分解（并发 spawn）
spawn(模块A编码) ─┐
spawn(模块B编码) ─┤
spawn(模块C编码) ─┼── 全部完成后汇总
spawn(模块D编码) ─┤
spawn(模块E编码) ─┘
适用场景：多个独立模块的同类任务。
模式 C：混合分解（分阶段 + 并行）
Phase 1: spawn(架构师) → 输出方案
↓
Phase 2: spawn(路由) ─┐
spawn(模型) ─┼── 并行执行
spawn(测试) ─┘
↓
Phase 3: spawn(集成测试) → 验证
适用场景：大型项目，先规划再并行实施最后验证。这是最常用的模式。
8.3 prompt 工程：怎么给子 Agent 写指令
子 Agent 的 prompt 必须是"自包含的"——
它不能假设子 Agent 知道之前的对话。
一个好的子 Agent prompt 包含：
1. 【目标】你要做什么（一句话）
2. 【背景】项目用什么技术栈，当前处于什么阶段
3. 【规范】编码风格、命名约定、错误处理模式
4. 【参考】现有代码的示例（直接粘贴，不要说"参考 xxx 文件"）
5. 【输出】期望的输出格式（文件路径 + 内容）
6. 【约束】不要做什么（如"不要修改其他文件"）
9. 子 Agent 权限隔离与安全配置
9.1 为什么需要权限隔离
子 Agent 继承父 Agent 的基础权限，但你可能不想给所有子 Agent 相同的权限。例如：
- 架构师子 Agent 只需要读取文件，不需要写入
- 编码子 Agent 需要写入特定目录，但不需要执行命令
- 测试子 Agent 需要执行命令（运行测试），但不需要写入源代码
9.2 在 spawn 中限制工具
// 架构师：只读
{
"tool": "sessions_spawn",
"arguments": {
"prompt": "分析项目架构...",
"allowedTools": ["read_file", "list_directory", "browser"]
}
}
// 编码者：读写特定目录
{
"tool": "sessions_spawn",
"arguments": {
"prompt": "实现路由模块...",
"allowedTools": ["read_file", "write_file", "list_directory"],
"workingDirectory": "~/workspace/work/src/routes"
}
}
// 测试者：读写 + 执行测试
{
"tool": "sessions_spawn",
"arguments": {
"prompt": "编写并运行测试...",
"allowedTools": ["read_file", "write_file", "exec"],
"workingDirectory": "~/workspace/work/tests"
}
}
9.3 openclaw.json 中的子 Agent 默认权限
// ~/.openclaw/openclaw.json — 子 Agent 安全配置
{
"agents": {
"defaults": {
"spawn": {
// 子 Agent 默认继承的安全策略
"defaultTools": ["read_file", "write_file", "list_directory", "exec"],
// 子 Agent 永远不能使用的工具（即使父 Agent 授权）
"blockedTools": [
"browser",
"mcp.*.delete",
"mcp.*.create"
],
// 子 Agent 的文件操作限制在父 Agent 的 workspace 内
"inheritWorkspace": true,
// 子 Agent 的 elevated 策略
"elevated": {
"mode": "parent-approval"
},
// 并行限制
"maxConcurrent": 10,
// 单个子 Agent 的 Token 上限
"maxTokensPerChild": 200000,
// 子 Agent 的超时（分钟）
"timeout": 30
}
}
}
}
🚨 安全红线：
elevated.mode: "parent-approval"意味着子 Agent 要执行高权限操作时，审批请求会传递给父 Agent（而不是直接弹窗给用户）。父 Agent 根据自己的策略决定是否批准。这避免了 20 个子 Agent 同时弹 20 个审批窗口的混乱。
10. 结果汇总：子 Agent 怎么把活儿交回来
10.1 自动回传机制
子 Agent 完成任务后，它的最终输出（最后一条消息）会自动返回给父 Agent，成为父 Agent 上下文中的一条工具结果消息。
父 Agent 的上下文视角：
[User] "重构整个项目..."
[Agent] 分析后决定 spawn 3 个子 Agent
[Tool: sessions_spawn] 子 Agent A 的最终输出：
"架构方案如下：1. 路由层... 2. 中间件... 3. ..."
[Tool: sessions_spawn] 子 Agent B 的最终输出：
"路由层重构完成。修改了 12 个文件：src/routes/auth.ts..."
[Tool: sessions_spawn] 子 Agent C 的最终输出：
"测试更新完成。28 个测试文件已更新，运行结果：27/28 通过"
[Agent] 汇总所有结果...
10.2 设计好的输出格式
为了让父 Agent 高效汇总，子 Agent 的 prompt 应该规定输出格式：
在 spawn prompt 的最后加上：
"完成后，以以下格式汇报：
## 任务完成报告
- 状态：成功/部分成功/失败
- 修改的文件列表（带完整路径）
- 关键决策说明（如果有偏离预定方案的地方）
- 发现的问题或风险
- 建议的后续步骤"
10.3 处理子 Agent 失败
父 Agent 的失败处理逻辑：
子 Agent 返回 →
│
├── 状态: 成功 → 收集结果，继续
│
├── 状态: 部分成功 →
│ 分析哪些部分完成了
│ 对未完成部分：重新 spawn（加更多上下文）或手动处理
│
└── 状态: 失败 →
分析失败原因
├── 可重试错误（超时、API 限流）→ 重试一次
└── 不可重试错误（任务描述不清、权限不足）→ 报告给用户
11. 调优与调试：Token 成本、超时、失败处理
11.1 Token 成本分析
sessions_spawn 的 Token 开销模型：
总 Token = 父 Agent Token + Σ(子 Agent Token)
父 Agent Token：
正常对话 + spawn 调用的 prompt + 结果汇总
子 Agent Token：
每个子 Agent = 系统提示 + 注入的上下文 + 执行过程 + 输出
关键开销点：
⚠️ 上下文重复注入：
如果 5 个子 Agent 都需要知道项目编码规范，
每个子 Agent 的 prompt 里都要包含这段规范 → 5 倍重复
优化方式：
1. 提取共享上下文到一个文件，让子 Agent 自己读取
spawn({ prompt: "先读取 CLAUDE.md 了解规范，然后..." })
2. 精简注入的上下文，只给每个子 Agent 需要的部分
11.2 成本优化策略
| 策略 | 说明 | 预期节省 |
|---|---|---|
| 子 Agent 用便宜模型 | 批量编码用 Haiku/Sonnet，只有规划用 Opus | 30-60% |
| 精简 prompt | 只注入子 Agent 需要的上下文，不是全部 | 15-25% |
| 限制 thinking | 简单子任务设低 thinking budget | 20-40% |
| 减少子 Agent 数量 | 能 3 个做完的不拆成 10 个 | 上下文重复减少 |
| 文件引用代替内联 | "先读取 CLAUDE.md" 代替把 CLAUDE.md 内容塞进 prompt |
50%+ 上下文节省 |
11.3 调试技巧
# 查看子 Agent 的 Session 列表
openclaw sessions list --parent main
# PARENT CHILD_ID AGENT STATUS TOKENS DURATION
# main spawn-a1b2 architect completed 45K 3m 20s
# main spawn-c3d4 coder-1 completed 32K 2m 10s
# main spawn-e5f6 coder-2 failed 18K 1m 05s
# main spawn-g7h8 tester running 28K 4m 30s
# 查看失败的子 Agent 的日志
openclaw sessions log spawn-e5f6
# [ERROR] Tool 'exec' not allowed for this spawned session
# [ERROR] 子 Agent 尝试运行命令但没有 exec 权限
# 查看父子 Agent 的 Token 消耗
openclaw usage --today --by-session --parent main
11.4 常见问题排查
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| 子 Agent 什么都不做就返回了 | prompt 不够清晰 | 加入具体的步骤和期望输出格式 |
| 子 Agent 重复做父 Agent 已做的事 | 子 Agent 不知道上下文 | 在 prompt 中说明"以下工作已完成" |
| 子 Agent 修改了不该改的文件 | 缺少 workingDirectory 限制 | 设置 workingDirectory + allowedTools |
| 子 Agent 执行超时 | 任务太大 / thinking budget 太高 | 进一步拆分子任务或降低 budget |
| 父 Agent 汇总时上下文爆了 | 子 Agent 返回内容太长 | 在 prompt 中要求精简输出格式 |
| 多个子 Agent 修改了同一文件 | 任务拆分有重叠 | 明确每个子 Agent 的文件职责范围 |
| API rate limit 错误 | 并行太多 | 降低 maxConcurrent（建议 5-10） |
12. 完整配置 & 总结
完整的 openclaw.json（支持 sessions_spawn）
// ~/.openclaw/openclaw.json — sessions_spawn 完整配置
{
"agents": {
"defaults": {
"context": {
"compactionThreshold": 0.7,
"preserveRecent": 6
},
// 子 Agent 默认配置
"spawn": {
"defaultTools": ["read_file", "write_file", "list_directory", "exec"],
"blockedTools": ["browser", "mcp.*.delete"],
"inheritWorkspace": true,
"elevated": { "mode": "parent-approval" },
"maxConcurrent": 10,
"maxTokensPerChild": 200000,
"timeout": 30
}
},
"list": [
{
"name": "main",
"description": "Primary agent with spawn orchestration capability",
"model": {
"primary": "anthropic/claude-sonnet-4-5",
"thinkingBudget": { "type": "tokens", "maxTokens": 8000 }
},
"workspace": "~/workspace/work",
"soul": "~/.openclaw/agents/main/SOUL.md"
}
]
},
"tools": {
"elevated": {
"mode": "ask",
"gates": ["exec", "write", "apply_patch"]
}
}
}
推荐的 SOUL.md 模板（支持 spawn 的父 Agent）
# SOUL.md — 主管 Agent
## 任务分解策略
当收到大型任务（5+ 文件或 3+ 独立步骤）时：
1. 先分析任务范围，列出所有子任务
2. 识别依赖关系（哪些可以并行，哪些必须串行）
3. 告诉用户你的分发计划，等确认后执行
4. 使用 sessions_spawn 分发子任务
## 子 Agent 模型选择
- 架构/设计：高 thinking budget (15K-20K)
- 常规编码：中 thinking budget (3K-5K)
- 文档/测试：低 thinking budget (1K-3K)
## 子 Agent prompt 规范
每个子 Agent 的 prompt 必须包含：
- 明确的目标（一句话）
- 项目上下文（技术栈、编码规范）
- 参考代码（如果有的话，直接粘贴关键片段）
- 期望的输出格式
- 约束条件（不能做什么）
## 汇总规则
- 所有子 Agent 完成后，运行测试验证
- 如果有冲突，优先以架构师子 Agent 的方案为准
- 子 Agent 失败时：重试一次，仍失败则报告给用户
🎯 五个关键 Takeaway
- sessions_spawn 是动态派遣 —— 不同于多 Agent 路由的"静态分工"，spawn 让父 Agent 在运行时按需创建临时子 Agent 来处理子任务
- 并行是最大价值 —— 5 个独立模块可以同时开发，实测速度提升 3-8 倍，上下文零污染
- 子 Agent 的 prompt 必须自包含 —— 子 Agent 看不到父 Agent 的上下文，所有需要的信息必须注入到 spawn prompt 中
- 权限隔离不能省 —— 通过
allowedTools、workingDirectory、blockedTools限制每个子 Agent 的能力范围 - 混合分解模式最实用 —— 先 spawn 一个架构师（串行），再根据方案 spawn 多个编码者（并行），最后汇总验证
📚 参考资料
- OpenClaw 官方 sessions_spawn 文档
- OpenClaw GitHub: sessions_spawn 源码
- Patch 项目：Telegram 协调多 Agent 实践
- OpenClaw Multi-Agent 配置文档
- Anthropic: Agent 编排模式
- OpenClaw Token 优化指南
- OpenClaw 多 Agent 路由架构详解
如果觉得有帮助，欢迎 点赞 👍 收藏 ⭐ 关注 🔔，有问题评论区见！
本文为原创内容，转载请注明出处。
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
更多推荐
13
0- 0
已为社区贡献20条内容
所有评论(0)