什么是子智能体

本文聚焦：子智能体概念 + sessions_spawn 工具使用

前置知识：第一个 Agent 下一篇：Agent 间通信

知识点 1：子智能体概念

什么是子智能体

子智能体（Sub-agent）是 OpenClaw 中一种后台运行的代理会话，它从现有的主代理会话中派生出来，拥有独立的会话标识（agent:<agentId>:subagent:<uuid>），并在任务完成后自动将结果汇报回发起请求的聊天通道。

简单来说，子智能体就是主智能体的"分身"——它们可以并行处理耗时任务，而主智能体无需等待，可以继续响应用户或执行其他工作。

子智能体 vs 主会话

特性	主会话（Main Session）	子智能体（Sub-agent）
会话ID	agent:main:<uuid>	agent:<agentId>:subagent:<uuid>
运行方式	前台交互	后台异步
工具权限	完整工具集	受限工具集（默认无 session 工具）
生命周期	用户主动控制	任务完成自动结束
结果交付	直接回复	完成后自动汇报到请求通道
嵌套深度	深度 0	深度 1（可配置）

核心使用场景

子智能体最适合以下场景：

1. 并行化耗时任务 当需要同时处理多个独立任务时，例如：

• 同时分析多个文件
• 并行搜索多个数据源
• 批量处理图片或文档

2. 隔离敏感操作 子智能体默认运行在隔离环境中，适合：

• 执行可能出错的操作（不影响主会话）
• 测试不确定的代码
• 处理第三方不可信内容

3. 长时间运行的后台任务

• 大型代码库分析
• 复杂的数据处理流程
• 需要持续监控的任务

4. 多模型协作 主会话使用高质量模型（如 Claude 3.5 Sonnet），子智能体使用成本更低的模型（如 GPT-4o-mini）处理简单子任务，优化成本。

嵌套深度限制

OpenClaw 对子智能体的嵌套有严格限制：

• 深度 0：主会话，拥有完整工具权限
• 深度 1：子智能体，可以拥有 session 工具（如果配置允许）
• 深度 2：孙智能体，禁止使用 sessions_spawn（防止无限递归）

每个代理会话最多可同时拥有 maxChildrenPerAgent（默认 5 个）活跃子智能体，防止单点过度扩散。

生命周期管理

以下命令可在聊天通道中使用（如 Telegram、Discord）管理子智能体：

# 停止主会话会级联停止所有子智能体
/stop

# 停止特定子智能体（及其子级）
/subagents kill <id|#>

# 查看子智能体列表
/subagents list

# 查看子智能体日志
/subagents log <id|#> [limit] [tools]

# 向子智能体发送消息
/subagents send <id|#> <message>

# 引导子智能体调整方向
/subagents steer <id|#> <message>

知识点 2：sessions_spawn 详解

工具概述

sessions_spawn 是 OpenClaw 提供的原生工具，用于程序化地创建子智能体。与命令行 /subagents spawn 不同，工具调用更适合在 Agent 内部逻辑中动态决策何时派生子任务。

前置条件：

• OpenClaw 版本 >= 0.15.0（支持子智能体功能）
• 当前 Agent 配置中包含 sessions_spawn 工具权限
• 未达到 maxChildrenPerAgent 限制（默认 5 个）

注意：本文代码示例使用伪代码语法展示参数结构。实际调用时，请通过 OpenClaw 的工具调用机制使用（如 Agent 内部调用 sessions_spawn 工具）。

完整参数列表

interface SessionsSpawnParams {
  // 必需参数
  task: string;                    // 分配给子智能体的任务描述
  
  // 可选参数
  label?: string;                  // 子智能体标签（用于识别）
  agentId?: string;                // 指定代理ID（默认继承调用者）
  model?: string;                  // 覆盖模型（如 "openai/gpt-4o"）
  thinking?: "off" | "on" | "stream";  // 覆盖思考模式
  runTimeoutSeconds?: number;      // 运行超时（秒），0=无限制
  thread?: boolean;                // 是否绑定到线程（需通道支持）
  mode?: "run" | "session";        // "run"=一次性，"session"=持久会话
  runtime?: "native" | "acp";      // "native"=原生，"acp"=外部工具
  
  // ACP 特有参数（当 runtime="acp" 时）
  acpAgentId?: string;             // ACP 代理ID（如 "codex", "claude-code"）
  cwd?: string;                    // 工作目录
  env?: Record<string, string>;    // 环境变量
}

参数详解

1. task（必需）

任务描述是子智能体接收的核心指令。建议：

• 明确具体：说明要做什么、输出什么格式
• 包含上下文：提供必要的背景信息
• 设定边界：明确任务范围和限制

示例：

{
  "task": "分析 /home/user/project/src 目录下的所有 JavaScript 文件，找出潜在的性能问题，输出 Markdown 格式的报告，包含文件路径、问题类型和建议修复方案。"
}

2. model（可选）

覆盖默认模型配置。优先级：

sessions_spawn.model > agents.list[].subagents.model > agents.defaults.subagents.model > 调用者模型

成本优化示例：

{
  "task": "总结以下文本...",
  "model": "openai/gpt-4o-mini"  // 简单任务使用低成本模型
}

3. mode（可选）

• "run"（默认）：一次性任务，完成后自动汇报并结束
• "session"：持久会话，保持活跃直到显式关闭（需 thread: true）

4. runtime（可选）

• "native"（默认）：OpenClaw 原生子智能体
• "acp"：外部 ACP 工具（Codex、Claude Code 等）

使用示例

示例 1：基础用法（并行分析多个文件）

// 主会话中调用
const files = ["/docs/api.md", "/docs/guide.md", "/docs/faq.md"];

// 为每个文件派生一个子智能体
for (const file of files) {
  await sessions_spawn({
    task: `阅读 ${file} 并提取关键API端点列表，返回JSON格式：{endpoints: [{method, path, description}]}`,
    label: `analyze-${file.split('/').pop()}`
  });
}

示例 2：指定模型和超时

// 复杂任务使用更强的模型，简单任务使用轻量级模型
await sessions_spawn({
  task: "重构以下代码，提高可读性并添加错误处理...",
  model: "anthropic/claude-3-5-sonnet-20241022",
  runTimeoutSeconds: 300,  // 5分钟超时
  label: "refactor-critical-code"
});

示例 3：创建持久会话（Thread 绑定）

// 在 Discord/Slack 等支持线程的平台上创建持久子智能体
await sessions_spawn({
  task: "持续监控这个项目的 GitHub Issues，当有新 Bug 报告时分析并提供修复建议",
  mode: "session",
  thread: true,
  label: "github-issue-monitor"
});

验证子智能体创建

调用 sessions_spawn 后，可通过以下方式验证：

1. 查看子智能体列表：执行 /subagents list 查看新创建的子智能体
2. 检查标签：确认 label 参数正确显示
3. 等待结果：子智能体完成后会自动汇报结果到当前通道

示例输出：

active subagents:
1. analyze-api.md (gpt-4o, 2m) running - 阅读 /docs/api.md 并提取...
2. analyze-guide.md (gpt-4o, 2m) running - 阅读 /docs/guide.md 并提取...

常见陷阱

陷阱 1：在子智能体中递归调用 sessions_spawn

// ❌ 错误：深度 1 的子智能体尝试再派生子智能体
// 这将触发安全限制，调用会被拒绝
await sessions_spawn({
  task: "这个任务需要再派生子智能体..."  // 会失败！
});

陷阱 2：忘记处理超时

// ❌ 错误：没有设置超时，可能无限等待
await sessions_spawn({
  task: "分析整个互联网..."  // 永远不会完成！
});

// ✅ 正确：设置合理的超时
await sessions_spawn({
  task: "分析特定目录...",
  runTimeoutSeconds: 60
});

陷阱 3：任务描述过于模糊

// ❌ 错误：子智能体不知道具体要做什么
await sessions_spawn({
  task: "处理这些文件"  // 太模糊！
});

// ✅ 正确：明确的指令
await sessions_spawn({
  task: "读取 /docs/api.md，提取所有 HTTP API 端点，以 JSON 格式返回：{endpoints: [...]}"
});

实践建议

1. 任务粒度要适中：每个子智能体处理一个独立、明确的任务，避免过度拆分或任务过于庞大

2. 善用 label 参数：为子智能体设置描述性标签，方便后续通过 /subagents list 识别和管理

3. 成本优化策略：简单任务使用轻量级模型（如 GPT-4o-mini），复杂任务使用高质量模型

4. 超时设置：始终为可能长时间运行的任务设置 runTimeoutSeconds，防止资源浪费

5. 错误处理：子智能体可能失败，主会话应设计重试或降级逻辑

6. 避免深度嵌套：不要设计需要孙智能体的架构，OpenClaw 禁止深度 2 的 sessions_spawn

相关阅读

• 第一个 Agent
• Agent 间通信
• 任务委派模式
• Pipeline 模式