1. 从单 Agent 到研发团队为什么需要 Sub-Agents如果你已经用 OpenClaw 跑通过单 Agent 工作流大概率会遇到一个瓶颈一个 Agent 既要理解需求、又要写代码、还要自测和审查上下文越堆越长角色切换时容易「精神分裂」。我试过让一个 Agent 从头到尾做登录功能结果它在写代码时把需求文档里的边界条件漏了一半审查阶段又因为「自己审自己」而放水。OpenClaw 的 Sub-Agents 机制解决的正是这个问题。它允许一个主 AgentDirector通过sessions_spawn工具调用其他隔离的 Agent每个 Agent 拥有独立的 workspace、agentDir 和会话存储扮演需求分析师、开发者、审查员、测试工程师等固定角色。主 Agent 只负责拆解任务、分派、回收结果专业 Agent 只专注自己那一块。这套机制适合三类人独立开发者想一个人跑完整研发流程、小团队想把重复性编码测试自动化、以及任何需要多角色并行处理任务的场景。本文会给出可直接复制的 Agent 角色配置骨架、协作触发规则并演示一次从任务分派到结果回收的完整验证动作。整个流程里模型调用统一走 TaoToken 的 API 网关省去逐个配置各家 Key 的麻烦。2. TaoToken 前置把模型调用统一到一个入口OpenClaw 本身是 Agent 编排框架它不绑定特定模型供应商。Sub-Agents 在运行时需要调用大模型如果你有 5 个 Agent每个都去配不同的 Key 和 Base URL维护成本会很高。TaoToken 在这里的角色是统一入口一个 API Key 覆盖多家模型Base URL 固定OpenClaw 的openclaw.json里只需要写一份配置。先拿到 Key。访问控制台创建 API Key# 控制台地址创建和管理 Key https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后复制 Key形如sk-xxxx。接着确认你要用的模型名TaoToken 的模型列表和对话测试可以在模型对话页验证# 模型对话页验证模型可用性 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chatAPI 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数。OpenClaw 的模型配置里baseUrl填这个apiKey填你刚创建的 Key。如果你打算长期跑编码类 AgentCoding Plan 的额度模型更适合高频调用# Coding Plan长期编码/Agent 场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan注意Sub-Agents 默认会继承主 Agent 的模型配置但你可以为 sub-agents 单独指定更便宜的模型。在openclaw.json的agents.defaults.subagents.model里写模型名即可TaoToken 的模型名格式通常是供应商/模型比如anthropic/claude-sonnet-4-5。3. 可复制配置5 个 Agent 的角色骨架与协作规则3.1 创建 Agent 工作空间OpenClaw 用agents add命令创建隔离 Agent每个 Agent 自动获得独立的 workspace、agentDir 和 sessions# 依次创建 5 个 Agent openclaw agents add director openclaw agents add analyst openclaw agents add developer openclaw agents add reviewer openclaw agents add tester创建过程中如果提示绑定 mode可以先跳过后面在openclaw.json里统一改。执行完后~/.openclaw/agents/下会出现 5 个目录每个目录里有agent/子目录存放认证和状态。3.2 主配置文件 openclaw.json这是整个协作系统的骨架。把下面的内容保存到~/.openclaw/openclaw.json重点看agents.list、agents.defaults.subagents和bindings三段{ agents: { list: [ { id: director, name: 项目调度, default: true, workspace: ~/.openclaw/workspace-director, agentDir: ~/.openclaw/agents/director/agent }, { id: analyst, name: 需求分析师, workspace: ~/.openclaw/workspace-analyst, agentDir: ~/.openclaw/agents/analyst/agent }, { id: developer, name: 开发者, workspace: ~/.openclaw/workspace-developer, agentDir: ~/.openclaw/agents/developer/agent }, { id: reviewer, name: 代码审查员, workspace: ~/.openclaw/workspace-reviewer, agentDir: ~/.openclaw/agents/reviewer/agent }, { id: tester, name: 测试工程师, workspace: ~/.openclaw/workspace-tester, agentDir: ~/.openclaw/agents/tester/agent } ], defaults: { subagents: { maxSpawnDepth: 2, maxChildrenPerAgent: 5, maxConcurrent: 8, model: anthropic/claude-sonnet-4-5, runTimeoutSeconds: 900 } } }, bindings: [ { agentId: director, match: { channel: feishu, accountId: dev-team } } ], channels: { feishu: { enabled: true, dmPolicy: pairing, accounts: { dev-team: { appId: cli_xxx, appSecret: xxx, botName: AI 研发助手 } } } } }几个参数的含义需要说清楚。maxSpawnDepth: 2表示 Director 可以调用子 Agent子 Agent 还能再调用工具形成两层嵌套这是编排器模式的基础。maxChildrenPerAgent: 5限制单个 Agent 最多同时开 5 个子任务防止并发把额度打满。model字段让所有 sub-agents 用 Sonnet 这类性价比模型而 Director 本身可以用更强的模型成本能压下来一大截。bindings把飞书账号绑定到 Director其他 Agent 不直接和用户交互只通过 Director 调度。3.3 各 Agent 的 SOUL.md 骨架每个 Agent 的 workspace 下需要放一个SOUL.md定义它的职责边界和输出格式。Director 的最关键它决定了任务怎么拆、怎么派# Director - 项目调度 你是项目调度专家负责协调 Analyst、Developer、Reviewer、Tester 完成研发任务。 ## 核心职责 1. 接收需求理解用户的自然语言需求 2. 任务拆解将需求分解为可执行的子任务 3. 资源调度调用合适的 Agent 完成子任务 4. 进度追踪监控任务执行状态 5. 结果汇总整合所有子任务结果向用户汇报 ## 可调用的 Agent - analyst分析需求、生成 PRD、设计 API 接口 - developer根据需求文档编写代码 - reviewer审查代码质量、发现潜在问题 - tester编写测试用例、执行测试 ## 调用方式 使用 sessions_spawn 工具调用子 Agent { task: 任务描述, agentId: analyst, mode: run, runTimeoutSeconds: 600 } ## 注意事项 1. 并发控制最多同时运行 5 个子任务 2. 超时管理单个任务最多 15 分钟 3. 错误处理某个子任务失败时继续执行其他任务最后汇总错误 4. 结果验证检查子任务输出是否完整必要时重新执行其他四个 Agent 的 SOUL.md 按同样结构写核心是「单一职责 明确输出格式」。Analyst 输出 PRD 和 API 设计Developer 输出代码文件清单Reviewer 输出分级问题报告Tester 输出测试报告。每个文件控制在 50 行以内写太笼统 Agent 会跑偏写太细又限制它的判断空间。3.4 协作触发规则Sub-Agents 的调用不是自动的靠 Director 在 SOUL.md 里定义的流程触发。标准的新功能开发流程是用户提需求 → Director 调 Analyst 生成 PRD → 把 PRD 传给 Developer 写代码 → 把代码传给 Reviewer 审查 → 把代码传给 Tester 测试 → Director 汇总。Bug 修复流程则跳过 Analyst 的完整 PRD只让它定位问题然后直接进 Developer 和 Tester。这里有个容易踩的坑子 Agent 之间不能直接通信所有数据传递都要经过 Director。所以 Director 在调用下一个 Agent 时必须把上一个 Agent 的输出作为task的一部分传进去否则 Developer 拿不到 PRDReviewer 拿不到代码。4. 验证请求跑一次多 Agent 任务分派与结果回收配置写完后先启动网关再发一条测试消息验证整条链路# 启动 OpenClaw Gateway openclaw start # 查看日志确认 5 个 Agent 都加载成功 openclaw logs --follow # 检查状态 openclaw status在飞书里找到你创建的机器人发送一条需求「开发一个用户登录功能支持邮箱密码登录和 GitHub OAuth」。Director 收到后会按 SOUL.md 里的流程依次调用四个 Agent。你可以用下面的命令观察 sub-agent 的运行状态# 列出当前会话的 sub-agent 运行 openclaw subagents list # 查看某个 sub-agent 的日志 openclaw subagents log id # 停止某个 sub-agent openclaw subagents kill id一次成功的回收结果长这样Director 返回一份汇总报告包含需求分析PRD 已生成、3 个 API 接口、代码开发5 个文件、约 150 行、代码审查发现 2 个严重问题SQL 注入风险、密码明文存储、测试验证12 个用例、通过 11 个、通过率 92%以及总耗时和成本。如果 Reviewer 报了严重问题Director 会在汇总里标出来你可以决定是否让它重新调 Developer 修复。验证时重点看两个地方一是openclaw subagents list里是否同时出现了多个 running 状态的子任务说明并发生效了二是最终报告里每个 Agent 的输出格式是否符合 SOUL.md 的定义如果 Developer 没输出文件清单说明它的 SOUL.md 写得不够明确。5. 本篇常见错排查报错一sessions_spawn调用失败提示 agent not found。检查openclaw.json里agents.list的id是否和 SOUL.md 里写的agentId完全一致大小写敏感。另外确认agentDir路径存在agents add创建后目录名默认就是 agent id。报错二子 Agent 拿不到上一个 Agent 的输出。这是最常见的问题。Sub-Agents 之间没有共享内存Director 必须在sessions_spawn的task字段里把上游结果完整传进去。检查 Director 的 SOUL.md 是否明确写了「将 Analyst 的输出作为 Developer 的 task 输入」。报错三并发任务卡住或超时。先看maxConcurrent和maxChildrenPerAgent是否设得太小5 个 Agent 串行跑时maxConcurrent至少给到 5。再看runTimeoutSeconds代码生成类任务建议 900 秒需求分析 600 秒够用。如果某个子任务一直 running用openclaw subagents kill id手动终止。报错四模型调用返回 401 或 403。检查 TaoToken 的 API Key 是否填对baseUrl是否为https://taotoken.net/api不带路径后缀。如果 Key 没问题去模型对话页确认你配置的模型名在 TaoToken 上可用。接入文档里有完整的参数说明# 接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc报错五飞书机器人不回复。确认bindings里的accountId和channels.feishu.accounts下的 key 一致。首次私聊需要配对用openclaw pairing approve feishu 配对码批准。群聊里默认需要 机器人 才响应这是requireMention的默认行为。6. 把单 Agent 工作流升级为可分工的研发团队整套配置跑通后你手里就有了一个 5 人 AI 研发团队的骨架。Director 负责调度四个专业 Agent 各管一段任务在它们之间自动流转你只需要在飞书里提需求、看汇总报告。成本上sub-agents 用 Sonnet 这类模型比全程用 Opus 省下大约 80% 的 token 开销。如果你要长期跑这套系统建议把 API Key 和模型额度规划好。TaoToken 的 API Keys 管理页可以创建多个 Key 做隔离Coding Plan 适合高频编码场景# API Keys 管理 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys # Coding Plan长期编码/Agent https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan最后给一个实操建议先把 Director 和 Developer 两个 Agent 跑通确认任务分派和结果回收没问题再逐步加 Analyst、Reviewer、Tester。一次性配 5 个 Agent 容易在 SOUL.md 的职责边界上出问题逐个加、逐个调反而更快。
OpenClaw 多 Agent 协作搭建研发团队：Sub-Agents 配置骨架与协作验证
1. 从单 Agent 到研发团队为什么需要 Sub-Agents如果你已经用 OpenClaw 跑通过单 Agent 工作流大概率会遇到一个瓶颈一个 Agent 既要理解需求、又要写代码、还要自测和审查上下文越堆越长角色切换时容易「精神分裂」。我试过让一个 Agent 从头到尾做登录功能结果它在写代码时把需求文档里的边界条件漏了一半审查阶段又因为「自己审自己」而放水。OpenClaw 的 Sub-Agents 机制解决的正是这个问题。它允许一个主 AgentDirector通过sessions_spawn工具调用其他隔离的 Agent每个 Agent 拥有独立的 workspace、agentDir 和会话存储扮演需求分析师、开发者、审查员、测试工程师等固定角色。主 Agent 只负责拆解任务、分派、回收结果专业 Agent 只专注自己那一块。这套机制适合三类人独立开发者想一个人跑完整研发流程、小团队想把重复性编码测试自动化、以及任何需要多角色并行处理任务的场景。本文会给出可直接复制的 Agent 角色配置骨架、协作触发规则并演示一次从任务分派到结果回收的完整验证动作。整个流程里模型调用统一走 TaoToken 的 API 网关省去逐个配置各家 Key 的麻烦。2. TaoToken 前置把模型调用统一到一个入口OpenClaw 本身是 Agent 编排框架它不绑定特定模型供应商。Sub-Agents 在运行时需要调用大模型如果你有 5 个 Agent每个都去配不同的 Key 和 Base URL维护成本会很高。TaoToken 在这里的角色是统一入口一个 API Key 覆盖多家模型Base URL 固定OpenClaw 的openclaw.json里只需要写一份配置。先拿到 Key。访问控制台创建 API Key# 控制台地址创建和管理 Key https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后复制 Key形如sk-xxxx。接着确认你要用的模型名TaoToken 的模型列表和对话测试可以在模型对话页验证# 模型对话页验证模型可用性 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chatAPI 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数。OpenClaw 的模型配置里baseUrl填这个apiKey填你刚创建的 Key。如果你打算长期跑编码类 AgentCoding Plan 的额度模型更适合高频调用# Coding Plan长期编码/Agent 场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan注意Sub-Agents 默认会继承主 Agent 的模型配置但你可以为 sub-agents 单独指定更便宜的模型。在openclaw.json的agents.defaults.subagents.model里写模型名即可TaoToken 的模型名格式通常是供应商/模型比如anthropic/claude-sonnet-4-5。3. 可复制配置5 个 Agent 的角色骨架与协作规则3.1 创建 Agent 工作空间OpenClaw 用agents add命令创建隔离 Agent每个 Agent 自动获得独立的 workspace、agentDir 和 sessions# 依次创建 5 个 Agent openclaw agents add director openclaw agents add analyst openclaw agents add developer openclaw agents add reviewer openclaw agents add tester创建过程中如果提示绑定 mode可以先跳过后面在openclaw.json里统一改。执行完后~/.openclaw/agents/下会出现 5 个目录每个目录里有agent/子目录存放认证和状态。3.2 主配置文件 openclaw.json这是整个协作系统的骨架。把下面的内容保存到~/.openclaw/openclaw.json重点看agents.list、agents.defaults.subagents和bindings三段{ agents: { list: [ { id: director, name: 项目调度, default: true, workspace: ~/.openclaw/workspace-director, agentDir: ~/.openclaw/agents/director/agent }, { id: analyst, name: 需求分析师, workspace: ~/.openclaw/workspace-analyst, agentDir: ~/.openclaw/agents/analyst/agent }, { id: developer, name: 开发者, workspace: ~/.openclaw/workspace-developer, agentDir: ~/.openclaw/agents/developer/agent }, { id: reviewer, name: 代码审查员, workspace: ~/.openclaw/workspace-reviewer, agentDir: ~/.openclaw/agents/reviewer/agent }, { id: tester, name: 测试工程师, workspace: ~/.openclaw/workspace-tester, agentDir: ~/.openclaw/agents/tester/agent } ], defaults: { subagents: { maxSpawnDepth: 2, maxChildrenPerAgent: 5, maxConcurrent: 8, model: anthropic/claude-sonnet-4-5, runTimeoutSeconds: 900 } } }, bindings: [ { agentId: director, match: { channel: feishu, accountId: dev-team } } ], channels: { feishu: { enabled: true, dmPolicy: pairing, accounts: { dev-team: { appId: cli_xxx, appSecret: xxx, botName: AI 研发助手 } } } } }几个参数的含义需要说清楚。maxSpawnDepth: 2表示 Director 可以调用子 Agent子 Agent 还能再调用工具形成两层嵌套这是编排器模式的基础。maxChildrenPerAgent: 5限制单个 Agent 最多同时开 5 个子任务防止并发把额度打满。model字段让所有 sub-agents 用 Sonnet 这类性价比模型而 Director 本身可以用更强的模型成本能压下来一大截。bindings把飞书账号绑定到 Director其他 Agent 不直接和用户交互只通过 Director 调度。3.3 各 Agent 的 SOUL.md 骨架每个 Agent 的 workspace 下需要放一个SOUL.md定义它的职责边界和输出格式。Director 的最关键它决定了任务怎么拆、怎么派# Director - 项目调度 你是项目调度专家负责协调 Analyst、Developer、Reviewer、Tester 完成研发任务。 ## 核心职责 1. 接收需求理解用户的自然语言需求 2. 任务拆解将需求分解为可执行的子任务 3. 资源调度调用合适的 Agent 完成子任务 4. 进度追踪监控任务执行状态 5. 结果汇总整合所有子任务结果向用户汇报 ## 可调用的 Agent - analyst分析需求、生成 PRD、设计 API 接口 - developer根据需求文档编写代码 - reviewer审查代码质量、发现潜在问题 - tester编写测试用例、执行测试 ## 调用方式 使用 sessions_spawn 工具调用子 Agent { task: 任务描述, agentId: analyst, mode: run, runTimeoutSeconds: 600 } ## 注意事项 1. 并发控制最多同时运行 5 个子任务 2. 超时管理单个任务最多 15 分钟 3. 错误处理某个子任务失败时继续执行其他任务最后汇总错误 4. 结果验证检查子任务输出是否完整必要时重新执行其他四个 Agent 的 SOUL.md 按同样结构写核心是「单一职责 明确输出格式」。Analyst 输出 PRD 和 API 设计Developer 输出代码文件清单Reviewer 输出分级问题报告Tester 输出测试报告。每个文件控制在 50 行以内写太笼统 Agent 会跑偏写太细又限制它的判断空间。3.4 协作触发规则Sub-Agents 的调用不是自动的靠 Director 在 SOUL.md 里定义的流程触发。标准的新功能开发流程是用户提需求 → Director 调 Analyst 生成 PRD → 把 PRD 传给 Developer 写代码 → 把代码传给 Reviewer 审查 → 把代码传给 Tester 测试 → Director 汇总。Bug 修复流程则跳过 Analyst 的完整 PRD只让它定位问题然后直接进 Developer 和 Tester。这里有个容易踩的坑子 Agent 之间不能直接通信所有数据传递都要经过 Director。所以 Director 在调用下一个 Agent 时必须把上一个 Agent 的输出作为task的一部分传进去否则 Developer 拿不到 PRDReviewer 拿不到代码。4. 验证请求跑一次多 Agent 任务分派与结果回收配置写完后先启动网关再发一条测试消息验证整条链路# 启动 OpenClaw Gateway openclaw start # 查看日志确认 5 个 Agent 都加载成功 openclaw logs --follow # 检查状态 openclaw status在飞书里找到你创建的机器人发送一条需求「开发一个用户登录功能支持邮箱密码登录和 GitHub OAuth」。Director 收到后会按 SOUL.md 里的流程依次调用四个 Agent。你可以用下面的命令观察 sub-agent 的运行状态# 列出当前会话的 sub-agent 运行 openclaw subagents list # 查看某个 sub-agent 的日志 openclaw subagents log id # 停止某个 sub-agent openclaw subagents kill id一次成功的回收结果长这样Director 返回一份汇总报告包含需求分析PRD 已生成、3 个 API 接口、代码开发5 个文件、约 150 行、代码审查发现 2 个严重问题SQL 注入风险、密码明文存储、测试验证12 个用例、通过 11 个、通过率 92%以及总耗时和成本。如果 Reviewer 报了严重问题Director 会在汇总里标出来你可以决定是否让它重新调 Developer 修复。验证时重点看两个地方一是openclaw subagents list里是否同时出现了多个 running 状态的子任务说明并发生效了二是最终报告里每个 Agent 的输出格式是否符合 SOUL.md 的定义如果 Developer 没输出文件清单说明它的 SOUL.md 写得不够明确。5. 本篇常见错排查报错一sessions_spawn调用失败提示 agent not found。检查openclaw.json里agents.list的id是否和 SOUL.md 里写的agentId完全一致大小写敏感。另外确认agentDir路径存在agents add创建后目录名默认就是 agent id。报错二子 Agent 拿不到上一个 Agent 的输出。这是最常见的问题。Sub-Agents 之间没有共享内存Director 必须在sessions_spawn的task字段里把上游结果完整传进去。检查 Director 的 SOUL.md 是否明确写了「将 Analyst 的输出作为 Developer 的 task 输入」。报错三并发任务卡住或超时。先看maxConcurrent和maxChildrenPerAgent是否设得太小5 个 Agent 串行跑时maxConcurrent至少给到 5。再看runTimeoutSeconds代码生成类任务建议 900 秒需求分析 600 秒够用。如果某个子任务一直 running用openclaw subagents kill id手动终止。报错四模型调用返回 401 或 403。检查 TaoToken 的 API Key 是否填对baseUrl是否为https://taotoken.net/api不带路径后缀。如果 Key 没问题去模型对话页确认你配置的模型名在 TaoToken 上可用。接入文档里有完整的参数说明# 接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc报错五飞书机器人不回复。确认bindings里的accountId和channels.feishu.accounts下的 key 一致。首次私聊需要配对用openclaw pairing approve feishu 配对码批准。群聊里默认需要 机器人 才响应这是requireMention的默认行为。6. 把单 Agent 工作流升级为可分工的研发团队整套配置跑通后你手里就有了一个 5 人 AI 研发团队的骨架。Director 负责调度四个专业 Agent 各管一段任务在它们之间自动流转你只需要在飞书里提需求、看汇总报告。成本上sub-agents 用 Sonnet 这类模型比全程用 Opus 省下大约 80% 的 token 开销。如果你要长期跑这套系统建议把 API Key 和模型额度规划好。TaoToken 的 API Keys 管理页可以创建多个 Key 做隔离Coding Plan 适合高频编码场景# API Keys 管理 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys # Coding Plan长期编码/Agent https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan最后给一个实操建议先把 Director 和 Developer 两个 Agent 跑通确认任务分派和结果回收没问题再逐步加 Analyst、Reviewer、Tester。一次性配 5 个 Agent 容易在 SOUL.md 的职责边界上出问题逐个加、逐个调反而更快。
