🤖 OpenClaw Sub-Agent 配置教程

什么是 Sub-Agent？

OpenClaw 的 Sub-Agent（子Agent）机制允许你从一个主Agent中派生出多个独立的子Agent来并行处理任务。每个子Agent拥有独立的会话上下文，可以使用不同的模型，完成后将结果返回给主Agent。

核心概念

概念	说明
Parent Agent	发起子任务的主Agent
Sub-Agent	被派生的独立Agent实例
runtime="subagent"	指定子Agent运行时类型
context="fork"	子Agent继承父Agent的完整上下文
context="isolated"	子Agent使用干净的独立上下文
mode="run"	一次性后台执行模式

基础用法：派生单个子Agent

最简单的子Agent派生方式，使用 sessions_spawn 工具：

// 派生一个子Agent来执行搜索任务
sessions_spawn({
  task: "搜索最新的 AI Agent 框架对比文章，总结前5个框架的优缺点",
  taskName: "ai-framework-search",
  runtime: "subagent",
  mode: "run"
})

参数详解

• task — 子Agent要执行的任务描述（必需）
• taskName — 任务别名，用于后续定位（建议使用小写字母+下划线）
• runtime — 固定为 "subagent"
• mode — "run" 表示一次性执行
• label — 显示标签，用于 sessions_list 中识别

高级用法：上下文继承与隔离

context="fork" — 继承父上下文

当子Agent需要了解父Agent的完整对话历史时使用：

// 子Agent继承父Agent的完整上下文
sessions_spawn({
  task: "基于刚才讨论的内容，生成一份总结报告",
  taskName: "summary-report",
  runtime: "subagent",
  context: "fork",  // 关键：继承父上下文
  mode: "run"
})

context="isolated" — 干净的独立上下文

当子Agent需要独立工作，不受父上下文干扰时使用：

// 子Agent使用干净的独立上下文
sessions_spawn({
  task: "分析这个Python文件的代码质量",
  taskName: "code-review",
  runtime: "subagent",
  context: "isolated",  // 关键：独立上下文
  mode: "run",
  attachments: [{
    name: "main.py",
    content: pythonCode,
    encoding: "utf8"
  }]
})

并行派生多个子Agent

OpenClaw 支持同时派生多个子Agent并行工作，大幅提升效率：

// 并行派生3个子Agent
// 子Agent 1: 搜索新闻
sessions_spawn({
  task: "搜索今天最新的AI新闻",
  taskName: "news-search",
  mode: "run"
})

// 子Agent 2: 分析竞品
sessions_spawn({
  task: "分析竞品网站的最新动态",
  taskName: "competitor-analysis",
  mode: "run"
})

// 子Agent 3: 生成报告
sessions_spawn({
  task: "生成今日营销数据报告",
  taskName: "marketing-report",
  mode: "run"
})

// 等待所有子Agent完成
sessions_yield({ message: "等待3个子任务完成..." })

为子Agent指定模型

你可以为不同子Agent指定不同的模型，实现成本和能力的最优分配：

// 简单任务用轻量模型
sessions_spawn({
  task: "整理文件列表",
  taskName: "file-organize",
  model: "claude-haiku-4.5",  // 轻量模型，成本低
  mode: "run"
})

// 复杂推理用强力模型
sessions_spawn({
  task: "分析代码架构并提出重构建议",
  taskName: "architecture-review",
  model: "claude-sonnet-4",  // 强力模型，推理能力强
  mode: "run"
})

等待子Agent完成

使用 sessions_yield 等待子Agent完成：

// 派生子Agent后，结束当前turn并等待
sessions_yield({
  message: "子Agent已派生，等待完成..."
})

// 子Agent完成后，结果会作为下一条消息返回
// 主Agent可以继续处理结果

子Agent状态监控

使用 subagents 工具查看子Agent状态：

// 查看活跃和最近的子Agent
subagents({ action: "list" })

// 查看最近1小时内的子Agent
subagents({ action: "list", recentMinutes: 60 })

最佳实践

1. 任务描述要具体

// ❌ 模糊的任务描述
task: "帮我处理一些事情"

// ✅ 具体的任务描述
task: "搜索2026年6月最新的AI Agent框架，对比LangChain、CrewAI、AutoGen三个框架的优缺点，输出Markdown表格"

2. 合理使用上下文模式

• 需要父上下文：总结讨论、基于对话生成内容 → context: "fork"
• 独立任务：搜索、分析文件、代码审查 → context: "isolated"
• 默认：不指定时为 isolated（推荐）

3. 控制并发数量

4. 使用 taskName 追踪

为每个子Agent指定有意义的 taskName，方便后续通过 sessions_list 定位和管理。

常见问题

Q: 子Agent可以访问文件系统吗？

可以。子Agent继承父Agent的工具权限，包括文件读写、执行命令等。

Q: 子Agent的执行超时怎么设置？

sessions_spawn({
  task: "...",
  mode: "run",
  runTimeoutSeconds: 300  // 5分钟超时
})

Q: 子Agent可以再派生子Agent吗？

可以，但不建议超过2层嵌套。过深的嵌套会增加调试难度和成本。

实战案例：自动化内容生产流水线

// 主Agent协调的内容生产流水线
// 1. 派生搜索Agent
sessions_spawn({
  task: "搜索最新的AI行业新闻，返回5条重要新闻的标题和摘要",
  taskName: "news-search",
  mode: "run"
})

// 2. 派生分析Agent
sessions_spawn({
  task: "分析这些新闻的技术趋势和市场影响",
  taskName: "trend-analysis",
  context: "fork",
  mode: "run"
})

// 3. 派生写作Agent
sessions_spawn({
  task: "基于搜索结果和分析，生成一篇800字的AI日报文章",
  taskName: "article-writing",
  context: "fork",
  mode: "run"
})

// 等待所有任务完成
sessions_yield({ message: "内容生产流水线已启动，等待完成..." })