←→ 换页 空格 下一页
OpenClaw 使用手册

Subagent 分身
完全指南

临时分身、并行处理、任务委托——让 AI 助手多线程工作

适用版本：OpenClaw v2026.1+ | 更新日期：2026-03-16

OpenClaw Docs
概念

什么是 Subagent？

Subagent（子代理）是 OpenClaw 的临时分身机制。主代理可以创建子代理来并行执行任务，完成后自动汇报结果。

主代理

Main Agent

你的主要对话窗口，拥有完整记忆和工具权限

子代理

Subagent

临时创建，继承工作空间，完成后自动归档

01 / 10
对比

独立 Agent vs Subagent

独立 Agent

长期分身

• 完全独立的人格和工作空间
• 有自己的记忆、技能、认证
• 通过不同渠道绑定
• 用 CLI 创建配置

Subagent

临时分身

• 临时创建，用完即走
• 继承父代理的工作空间
• 自动管理生命周期
• 用 sessions_spawn 创建

💡 选择建议

  • 需要长期独立人格 → 创建独立 Agent
  • 临时并行处理任务 → 使用 Subagent
  • 不同渠道不同身份 → 独立 Agent + bindings
  • 单次委托任务 → Subagent 最简单
02 / 10
参数详解

sessions_spawn 参数

参数 类型 说明
task string ✅ 必填：分身要执行的任务描述
label string 可选：用于日志/UI 的标签
agentId string 可选：指定其他 agent（需 allowlist）
model string 可选：覆盖分身使用的模型
thinking string 可选：覆盖思考级别
mode run/session 默认 run，thread=true 时默认 session
thread boolean 是否绑定到线程（Discord 等）
runTimeoutSeconds number 超时秒数，0=不限制
03 / 10
基础用法

创建你的第一个分身

在对话中直接请求创建分身，主代理会调用 sessions_spawn 工具： 

// 用户说：
帮我创建一个分身，总结一下今天的工作

// 主代理调用：
sessions_spawn({
  "task": "总结今天的工作",
  "label": "daily-summary",
  "mode": "run"
})

// 返回：
{
  "status": "accepted",
  "childSessionKey": "agent:main:subagent:xxx",
  "runId": "uuid"
}

⚡ 自动汇报

  • 分身完成后自动汇报结果到当前对话
  • 无需轮询或手动检查状态
  • 结果包含执行统计（时间、token 等）
04 / 10
使用场景

分身的典型应用

并行处理

多个分身同时工作

创建多个分身，分别搜索、写代码、整理文档

代码审查

分身审查代码

主代理继续对话，分身在后台审查代码质量

长任务委托

耗时任务后台运行

数据分析、文件处理等耗时任务交给分身

章节分工

文章分章节写作

每个分身写一个章节，最后合并

05 / 10
高级配置

工具限制与沙箱

可以在配置文件中限制分身的工具权限： 

// ~/.openclaw/openclaw.json
{
  "tools": {
    "subagents": {
      "tools": {
        "allow": ["read", "write", "exec"],
        "deny": ["browser", "gateway"]
      }
    }
  }
}

🔒 安全特性

  • 分身默认不能调用 sessions_spawn（禁止套娃）
  • 沙箱隔离可选（继承父代理或独立容器）
  • 超时保护，防止无限运行
  • 完成后自动归档（默认 60 分钟）
06 / 10
会话工具

管理分身的四个工具

工具 功能
sessions_list 列出所有会话（包括分身）
sessions_history 获取指定会话的历史记录
sessions_send 向其他会话发送消息
sessions_spawn 创建新的子代理

📊 可见性控制

  • self - 仅当前会话
  • tree - 当前会话 + 创建的分身（默认）
  • agent - 同一 agent 的所有会话
  • all - 所有会话（需额外权限）
07 / 10
最佳实践

高效使用分身的技巧

✅ 推荐做法

  • 任务描述清晰具体，分身才能高效执行
  • 设置合理的 runTimeoutSeconds，避免无限等待
  • 使用 label 标记分身用途，方便调试
  • 复杂任务拆分成多个小任务并行处理
  • 分身完成后检查结果，必要时追加指令

❌ 避免的做法

  • 不要在分身任务中再次创建分身（会失败）
  • 不要期望分身访问父代理的对话上下文
  • 不要让分身执行需要交互确认的操作
  • 不要忽略超时设置，长任务可能卡住
08 / 10
总结

Subagent 核心要点

创建

一句话创建

帮我创建分身去...

执行

并行处理

多任务同时进行

汇报

自动通知

完成即汇报结果

归档

自动清理

60分钟后自动归档

分身让 AI 助手从单线程变成多线程！
善用分身，事半功倍 🚀

09 / 10