世界上有一种技术叫 Sub-Agents，它就像一个指挥官同时派出多个小兵去干活，每个小兵有自己的任务，完成后回来汇报。在 OpenClaw 里，子代理就是在现有代理运行中后台启动的独立代理，运行在自己的会话里（agent:<agentId>:subagent:<uuid>），完成后会宣布结果回到请求者的聊天频道。
🤔 什么是 Sub-Agents？
子代理是从现有代理运行中后台启动的代理。它们运行在独立的会话中，完成后会将结果公告回请求者的聊天频道。
核心目标：
- 并行化「研究 / 耗时任务 / 慢工具」工作
- 默认保持子代理隔离（会话分离 + 可选沙盒）
- 保持工具表面难以滥用：子代理默认不获得会话工具
- 支持可配置的嵌套深度
⚡ 使用方式
斜杠命令
/subagents list # 查看当前会话的子代理
/subagents kill <id|#|all> # 停止子代理
/subagents log <id|#> [limit] # 查看日志
/subagents info <id|#> # 查看详情
/subagents send <id|#> <message> # 发送消息
/subagents steer <id|#> <message> # 引导
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]工具调用
使用 sessions_spawn 工具：
{
"task": "帮我搜索最近关于 OpenAI 的新闻",
"label": "research",
"agentId": "main", // 可选，目标代理ID
"model": "claude-sonnet-4", // 可选，覆盖模型
"thinking": "high", // 可选，覆盖思考级别
"runTimeoutSeconds": 300, // 可选，运行超时
"thread": false, // 默认 false
"mode": "run", // run|session
"cleanup": "keep", // delete|keep
"sandbox": "inherit" // inherit|require
}🧵 线程绑定会话
当频道启用线程绑定时，子代理可以绑定到线程，这样该线程中的后续用户消息会持续路由到同一个子代理会话。
当前支持的线程频道：Discord（唯一支持）
其他频道暂不支持线程绑定功能。
其他频道暂不支持线程绑定功能。
使用方式
// 使用 thread: true 启用线程绑定
sessions_spawn({
task: "深入分析这个代码库",
thread: true,
mode: "session" // 持久会话
})手动控制
/focus <target> # 绑定当前线程到子代理/会话
/unfocus # 解除绑定
/agents # 列出活跃运行和绑定状态
/session idle # 查看/更新空闲自动解除
/session max-age # 控制硬性超时🔄 嵌套子代理
默认情况下，子代理不能生成自己的子代理（maxSpawnDepth: 1）。可以启用一层嵌套（maxSpawnDepth: 2），实现编排者模式：主代理 → 编排者子代理 → 工作子代理。
启用嵌套
{
"agents": {
"defaults": {
"subagents": {
"maxSpawnDepth": 2, // 允许子代理生成子代理
"maxChildrenPerAgent": 5, // 每个代理最大活跃子代理数
"maxConcurrent": 8, // 全局并发上限
"runTimeoutSeconds": 900 // 默认超时
}
}
}
}深度层级
| 深度 | 会话键 | 角色 | 能生成子代理？ |
|---|---|---|---|
| 0 | agent:<id>:main | 主代理 | 始终可以 |
| 1 | agent:<id>:subagent:<uuid> | 子代理（深度2时为编排者） | 仅当 maxSpawnDepth ≥ 2 |
| 2 | agent:<id>:subagent:<uuid>:subagent:<uuid> | 子子代理（叶子工作节点） | 永远不能 |
📢 公告机制
子代理完成后通过公告步骤报告结果：
- 如果子代理回复恰好是
ANNOUNCE_SKIP，则不发布任何内容 - 否则根据请求者深度交付：顶级请求者使用外部交付，嵌套请求者使用内部注入
公告内容包含：
- Status（成功/错误/超时/未知）
- Result（助手回复文本或最新 toolResult）
- 运行时/Token 统计
- 会话键/ID 和转录路径
🛠️ 工具策略
默认情况下，子代理获得除会话工具外的所有工具：
- 默认拒绝：
sessions_list,sessions_history,sessions_send,sessions_spawn - 当
maxSpawnDepth ≥ 2时，深度1编排者额外获得sessions_spawn,subagents,sessions_list,sessions_history
{
"tools": {
"subagents": {
"tools": {
"deny": ["gateway", "cron"],
"allow": ["read", "exec", "process"]
}
}
}
}⏱️ 超时与限制
- 默认超时：使用
agents.defaults.subagents.runTimeoutSeconds（0=无超时） - 最大嵌套深度：5（maxSpawnDepth 范围：1-5）
- 每会话最大活跃子代理：5（maxChildrenPerAgent 范围：1-20）
- 全局并发：8（maxConcurrent）