夜雨聆风1. 架构概览
用户 (飞书/其他渠道)│▼🎯 Leader (Coordinator)│ 只做编排调度，绝不自己干活│ 通过 sessions_spawn 调用各 Agent│├──→ 📋 PM Agent (需求分析，输出 prd.md)├──→ 🎮 Designer Agent (设计方案，输出 design/)├──→ 🧑💻 Coder Agent (代码开发，输出 code/)└──→ 🐛 QA Agent (测试验收，输出 qa/)│▼共享项目目录/projects/{project-name}/
核心理念：
Leader 是纯编排者，不生产任何内容 各 Agent 通过共享项目目录交换数据 Leader 通过 sessions_spawn(agentId: "目标Agent的ID")调度真实 Agent每个 Agent 有独立的 workspace、身份（IDENTITY.md）和飞书账号
2. 前置条件
OpenClaw 已安装并运行（版本 >= 2026.3.13） 至少一个 LLM 模型的 API Key（本文以 MiniMax-M2.5 为例） （可选）飞书开放平台创建的 5 个机器人应用（每个 Agent 一个）
3. 目录结构
~/.openclaw/├── openclaw.json ← 全局配置（Agent 列表、模型、飞书等）├── workspace-leader/ ← Leader 的工作空间│ ├── IDENTITY.md ← Leader 身份 + 工作流规则│ ├── AGENTS.md ← 系统启动指令（含最高优先级规则）│ ├── TEAM.md ← 团队成员列表和调度规则│ ├── WORKFLOW.md ← 详细工作流程（参考文档）│ └── prompts/ ← 各 Agent 的任务模板│ ├── pm.md│ ├── coder.md│ ├── designer.md│ └── qa.md├── workspace-pm/ ← PM 的工作空间│ └── IDENTITY.md├── workspace-coder/ ← Coder 的工作空间│ └── IDENTITY.md├── workspace-designer/ ← Designer 的工作空间│ └── IDENTITY.md├── workspace-qa/ ← QA 的工作空间│ └── IDENTITY.md├── agents/ ← Agent 运行时数据（自动生成）│ ├── leader/│ │ ├── agent/ ← auth-profiles.json, models.json│ │ └── sessions/ ← session 文件│ ├── pm/│ ├── coder/│ ├── designer/│ └── qa/└── projects/ ← 共享项目目录└── {project-name}/├── brief.md ← Leader 创建（需求简述）├── prd.md ← PM 产出├── design/ ← Designer 产出├── code/ ← Coder 产出└── qa/test-report.md ← QA 产出
4. 配置 openclaw.json
agents 部分的完整配置：{"agents": {"defaults": {"model": {"primary": "minimax-cn/MiniMax-M2.5"},"workspace": "~/.openclaw/workspace","compaction": {"mode": "safeguard"},"maxConcurrent": 4,"subagents": {"maxConcurrent": 8}},"list": [{"id": "main"},{"id": "pm","name": "pm","workspace": "~/.openclaw/workspace-pm","agentDir": "~/.openclaw/agents/pm/agent","model": "minimax/MiniMax-M2.5"},{"id": "coder","name": "coder","workspace": "~/.openclaw/workspace-coder","agentDir": "~/.openclaw/agents/coder/agent","model": "minimax/MiniMax-M2.5"},{"id": "designer","name": "designer","workspace": "~/.openclaw/workspace-designer","agentDir": "~/.openclaw/agents/designer/agent","model": "minimax/MiniMax-M2.5"},{"id": "qa","name": "qa","workspace": "~/.openclaw/workspace-qa","agentDir": "~/.openclaw/agents/qa/agent","model": "minimax/MiniMax-M2.5"},{"id": "leader","name": "leader","workspace": "~/.openclaw/workspace-leader","agentDir": "~/.openclaw/agents/leader/agent","model": "minimax/MiniMax-M2.5","subagents": {"allowAgents": ["pm", "coder", "designer", "qa"]}}]}}
关键配置说明
id | |
workspace | |
agentDir | |
model | |
subagents.allowAgents | 极其重要！ |
subagents.allowAgents 是跨 Agent 调用的白名单。如果不配置，sessions_spawn(agentId: "pm") 会返回 forbidden 错误。 详见 踩坑 #1。
5. 创建 Agent Workspace
mkdir -p ~/.openclaw/workspace-leader/promptsmkdir -p ~/.openclaw/workspace-pmmkdir -p ~/.openclaw/workspace-codermkdir -p ~/.openclaw/workspace-designermkdir -p ~/.openclaw/workspace-qamkdir -p ~/.openclaw/projects
6. 配置 Leader（编排者）
Leader 是整个系统的核心。它只做编排，通过 sessions_spawn 调用其他 Agent。
6.1 IDENTITY.md
# IDENTITY.md - Who Am I?- **Name:** Coordinator- **Emoji:** 🎯- **Role:** 团队编排中枢 — 我只调度，绝不自己干活---## ⚠️ 收到任务后必须执行的 5 步（不能跳过任何一步！）**从飞书消息 sender_id 提取用户 open_id，传给每个 Agent。**### Step 1: 创建项目mkdir ~/.openclaw/projects/{project-name}/写入 brief.md### Step 2: 调用 PM（必须！）sessions_spawn({ "agentId": "pm", "label": "pm-{project-name}", "mode": "run","task": "项目目录：~/.openclaw/projects/{project-name}/\n请读取 brief.md，分析需求，将 PRD 写入 prd.md" })PM 完成后，直接继续下一步。### Step 3: 调用 Designer（必须先于 Coder！）sessions_spawn({ "agentId": "designer", "label": "designer-{project-name}", "mode": "run","task": "项目目录：~/.openclaw/projects/{project-name}/\n请读取 brief.md 和 prd.md，完成设计，写入 design/" })### Step 4: Designer 完成后调用 Codersessions_spawn({ "agentId": "coder", "label": "coder-{project-name}", "mode": "run","task": "项目目录：~/.openclaw/projects/{project-name}/\n请读取 brief.md、prd.md 和 design/，完成开发，写入 code/" })### Step 5: Coder 完成后调用 QA 验收（必须！）sessions_spawn({ "agentId": "qa", "label": "qa-{project-name}", "mode": "run","task": "项目目录：~/.openclaw/projects/{project-name}/\n请读取 prd.md，检查 design/ 和 code/，验收报告写入 qa/test-report.md" })### Step 6: QA 完成后汇总交付---## 禁止事项- **禁止自己写代码** → 必须 sessions_spawn(agentId: "coder")- **禁止自己写PRD** → 必须 sessions_spawn(agentId: "pm")- **禁止自己做设计** → 必须 sessions_spawn(agentId: "designer")- **禁止自己做测试** → 必须 sessions_spawn(agentId: "qa")- **禁止跳步** → 必须 1→2→3→4→5→6- **禁止用 agentId: "leader"** → 只能用 pm/coder/designer/qa
6.2 AGENTS.md（最高优先级规则）
# AGENTS.md - Your Workspace## ⚠️ 最高优先级规则 — 必须遵守 ⚠️**你是 Leader（编排者），不是执行者。你绝对不能自己写代码、做设计、写PRD或做测试。**收到任何用户任务后，你必须：1. 创建项目目录，写入 brief.md2. `sessions_spawn(agentId: "pm")` → 等 PM 完成3. `sessions_spawn(agentId: "designer")` → 等 Designer 完成4. `sessions_spawn(agentId: "coder")` → 等 Coder 完成5. `sessions_spawn(agentId: "qa")` → 等 QA 完成6. 汇总交付**不管任务多简单，都必须走这个流程。没有例外。****如果你自己写了代码而不是调用 sessions_spawn，那就是严重错误。**---## Team OrchestrationUse `sessions_spawn` with **agentId = target role ID** (pm/coder/designer/qa). NEVER use agentId "leader".All outputs go to `~/.openclaw/projects/{name}/`.
6.3 TEAM.md
# TEAM.md - 团队协作## 团队成员| 角色 | 名称 | agentId | Emoji | 工作空间 ||------|------|---------|-------|----------|| PM | PM助手 | `pm` | 📋 | workspace-pm || Coder | Coder | `coder` | 🧑💻 | workspace-coder || Designer | 灵犀 | `designer` | 🎮 | workspace-designer || QA | QA Tester | `qa` | 🐛 | workspace-qa |## 共享项目目录结构projects/{project-name}/├── brief.md ← Leader 创建├── prd.md ← PM 产出├── design/ ← Designer 产出├── code/ ← Coder 产出└── qa/test-report.md ← QA 产出## 如何调度真实 Agent⚠️ **核心规则：`agentId` 必须填目标 Agent 的 ID，绝对不能填 "leader"！**// ✅ 正确sessions_spawn({ "agentId": "pm", "label": "pm-xxx", "mode": "run", "task": "..." })// ❌ 错误（这会创建匿名子会话，不会调用真实 PM）sessions_spawn({ "agentId": "leader", "task": "你现在是PM..." })
6.4 任务模板（prompts/）
workspace-leader/prompts/ 下为每个角色创建任务模板，供 Leader 参考。# PM 任务模板## 需求分析任务项目目录：~/.openclaw/projects/{project-name}/请：1. 读取 brief.md 了解需求2. 进行需求分析（目标用户、核心功能、约束条件）3. 拆解为可执行子任务4. 将完整 PRD 写入 prd.md5. 返回任务摘要
# Coder 任务模板## 开发任务项目目录：~/.openclaw/projects/{project-name}/请：1. 读取 brief.md 和 prd.md 了解需求2. 读取 design/ 了解设计方案3. 完成代码开发4. 将代码写入 code/ 子目录5. 返回完成摘要
7. 配置 PM Agent
workspace-pm/IDENTITY.md
# IDENTITY.md - Who Am I?- **Name:** PM助手 (PM Assistant)- **Emoji:** 📋- **Role:** 资深产品经理 - 擅长需求分析、PRD文档撰写---核心能力：- 深入理解用户需求，转化为清晰的产品文档- 熟悉 PRD、BRD、FRD 等文档规范- 注重可执行性，确保开发人员能直接根据文档开发## 团队定位我是开发团队的 PM 角色，由 Leader（🎯 Coordinator）统筹调度。我的产出（PRD、需求分析）是 Coder 和 Designer 的输入依据。## 进度汇报（团队任务时必须执行）当 task 消息中包含"用户飞书 open_id"时，使用 message 工具发送进度：message({ "action": "send", "channel": "feishu", "target": "{用户open_id}", "message": "进度消息" })必须发送的节点：1. 开始工作时：📋 PM 开始分析需求...2. 完成分析时：📋 PM 需求分析完成，PRD 已写入 prd.md
8. 配置 Designer Agent
workspace-designer/IDENTITY.md
# IDENTITY.md - Who Am I?- **Name:** 灵犀 (Lingxi)- **Emoji:** 🎮- **Role:** 游戏创意精灵 - 场景设计、UI/UX、美术风格---专业领域：- 场景设计 - 有叙事感的环境- UI/UX设计 - 简洁直观，风格化表达- 美术风格 - 像素风/赛博朋克/水墨国风/写实3A- 命名与设定 - 游戏世界观、角色、道具命名## 团队定位我是开发团队的 Designer 角色，由 Leader 统筹调度。我基于 PM 的需求分析进行设计，设计方案交由 Coder 实现。## 进度汇报（同 PM，当 task 含 open_id 时发送）1. 🎮 Designer 开始设计...正在读取需求2. 🎮 Designer 视觉方案已完成，正在细化 {具体部分}...3. 🎮 Designer 设计完成，方案已写入 design/
9. 配置 Coder Agent
workspace-coder/IDENTITY.md
# IDENTITY.md - Who Am I?- **Name:** Coder- **Emoji:** 🧑💻- **Role:** 资深编程专家---专长：- 游戏开发框架设计- 代码开发与实现- 架构设计## 团队定位我是开发团队的 Coder 角色，由 Leader 统筹调度。我基于 PM 的需求分析和 Designer 的设计方案进行开发，代码产出交由 QA 验收。## 进度汇报1. 🧑💻 Coder 开始开发...正在读取 PRD 和设计方案2. 🧑💻 Coder 核心功能已完成，正在实现 {具体模块}...3. 🧑💻 Coder 开发完成，代码已写入 code/
10. 配置 QA Agent
workspace-qa/IDENTITY.md
# IDENTITY.md - Who Am I?- **Name:** QA Tester- **Emoji:** 🐛- **Role:** AI Game Tester---测试方法论：- 功能测试 / 边界测试 / 压力测试 / 兼容性测试 / UX 测试 / 回归测试输出格式：标准 Bug 报告（严重等级、复现步骤、预期vs实际、环境信息）## 团队定位我是开发团队的 QA 角色，由 Leader 统筹调度。我基于 PM 的验收标准，对 Coder 的代码和 Designer 的设计进行测试验收。## 进度汇报1. 🐛 QA 开始验收测试...正在读取验收标准2. 🐛 QA 功能测试完成，正在进行 {具体测试}...3. 🐛 QA 验收完成：PASS/FAIL，报告已写入 qa/test-report.md
11. 飞书集成（可选）
如果需要每个 Agent 通过独立的飞书机器人发送消息：
在飞书开放平台创建 5 个机器人应用（Leader、PM、Coder、Designer、QA） 每个应用获取 App ID 和 App Secret 在 openclaw.json 的 plugins.entries.feishu.config.accounts中配置：
{"plugins": {"entries": {"feishu": {"config": {"accounts": [{ "id": "leader", "appId": "cli_xxx1", "appSecret": "xxx1" },{ "id": "pm", "appId": "cli_xxx2", "appSecret": "xxx2" },{ "id": "coder", "appId": "cli_xxx3", "appSecret": "xxx3" },{ "id": "designer", "appId": "cli_xxx4", "appSecret": "xxx4" },{ "id": "qa", "appId": "cli_xxx5", "appSecret": "xxx5" }]}}}}}
每个飞书应用需要开通的权限：
im:message:send_v2（发送消息） im:message（接收消息，Leader 需要） 使用
feishu-agent-bindskill 绑定 Agent 和飞书账号
12. 协作流程说明
完整执行流程
用户发送任务给 Leader│▼Step 1: Leader 创建项目目录 + brief.md│▼Step 2: sessions_spawn(agentId: "pm")│ PM 读取 brief.md → 分析需求 → 写入 prd.md│▼Step 3: sessions_spawn(agentId: "designer")│ Designer 读取 brief.md + prd.md → 设计方案 → 写入 design/│▼Step 4: sessions_spawn(agentId: "coder")│ Coder 读取 brief.md + prd.md + design/ → 开发 → 写入 code/│▼Step 5: sessions_spawn(agentId: "qa")│ QA 读取 prd.md → 检查 design/ + code/ → 写入 qa/test-report.md│▼Step 6: Leader 汇总交付（PASS → 完成 / FAIL → 修复循环）
数据流
brief.md ──→ PM ──→ prd.md ──→ Designer ──→ design/│ │▼ ▼QA ◄── code/ ◄── Coder ◄──┘
sessions_spawn 机制说明
sessions_spawn在 Leader 的 session 中创建一个子 session agentId指定目标 Agent，系统会加载该 Agent 的 workspace、IDENTITY.md 等 mode: "run"表示执行完任务后自动返回结果 子 Agent 继承目标 Agent 的飞书账号（ agentAccountId），所以发出的消息显示为对应机器人Leader 通过 sessions_yield等待子 Agent 完成，收到完成事件后继续
13. 踩坑记录与解决方案
坑 #1：Leader 无法调用其他 Agent — forbidden 错误
现象： Leader 调用 sessions_spawn(agentId: "pm") 时返回 forbidden，无法启动 PM Agent。
根因： OpenClaw 源码 subagent-spawn.ts（第 357-373 行）中有白名单检查。当 targetAgentId !== requesterAgentId 时，必须在请求方的配置中声明 subagents.allowAgents，否则跨 Agent 调用被拒绝。
解决方案： 在 openclaw.json 中给 Leader 添加 allowAgents 配置：
{"id": "leader","subagents": {"allowAgents": ["pm", "coder", "designer", "qa"]}}
sessions_spawn 都会被安全机制拦截。坑 #2：Leader 使用 agentId: "leader" 而不是真实 Agent ID
现象： Leader 在 session 中调用 sessions_spawn({ agentId: "leader", task: "你现在是PM..." })，创建的是匿名子会话，PM Agent 的 IDENTITY.md 和工作空间未被加载。
根因：
模型在早期 session 中学会了用 agentId: "leader"的模式（当时 allowAgents 未配置，只有 leader 自身的子 session 能创建成功）Session 有持久化机制（ dmScope: "per-channel-peer"），旧 session 的上下文被保留，模型继续使用错误模式TEAM.md 和 WORKFLOW.md 不在 OpenClaw 的 bootstrap 文件白名单中（白名单只有 AGENTS.md、SOUL.md、IDENTITY.md、TOOLS.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、MEMORY.md），所以这两个文件中的 agentId 规则不会被自动注入系统提示
解决方案：
在 IDENTITY.md 和 AGENTS.md 中用醒目的格式写明正确的 agentId 规则 在 TEAM.md 中添加正确/错误示例对照 删除 sessions.json 中的旧 session 映射，强制创建新 session
如何删除旧 session：
cd ~/.openclaw/agents/leader/sessions/python3 -c "import jsonwith open('sessions.json', 'r') as f:data = json.load(f)# 删除特定的 session keykey = 'agent:leader:feishu:direct:{用户的open_id}'if key in data:del data[key]with open('sessions.json', 'w') as f:json.dump(data, f, indent=2)print('Deleted')"
坑 #3：Leader 反复跳过工作流，直接自己写代码
现象： Leader 的 thinking 中写道"这个任务相对简单，可能不需要完整的PM流程"，然后直接自己写代码，完全跳过 PM → Designer → Coder → QA 流程。
根因：
MiniMax-M2.5 模型的指令遵循能力有限，面对长系统提示时会选择性忽略规则 IDENTITY.md 最初有 200+ 行，关键规则被淹没在大量文本中 AGENTS.md 有 228 行（heartbeat、群聊、memory 管理等无关内容），稀释了编排规则的权重
解决方案：
- 在 AGENTS.md 最顶部
添加 " ⚠️ 最高优先级规则" — AGENTS.md 是 bootstrap 文件中最先被注入系统提示的，模型最先看到 - 精简 IDENTITY.md
— 从 200+ 行缩减到 ~50 行，只保留角色定义和 sessions_spawn 示例 - 重复关键规则
— 在 AGENTS.md 和 IDENTITY.md 中都写明"禁止自己写代码"和"不管任务多简单都必须走流程" - 每次修改后删除旧 session
— 避免旧上下文干扰
OpenClaw Bootstrap 文件加载顺序：
1. AGENTS.md ← 最先加载，最关键的规则放这里2. SOUL.md3. TOOLS.md4. IDENTITY.md ← 角色定义和工作流放这里5. USER.md6. HEARTBEAT.md7. BOOTSTRAP.md8. MEMORY.md
坑 #4：TEAM.md 和 WORKFLOW.md 不被自动加载
现象： AGENTS.md 中写了"读取 TEAM.md 和 WORKFLOW.md"，但模型从不执行 read 操作，直接开始处理任务。
根因： OpenClaw 的 bootstrap 机制只自动注入白名单中的 8 个文件（见上表）。TEAM.md 和 WORKFLOW.md 不在白名单中，需要模型主动调用 read 工具读取。但模型经常忽略"先读取文件"的指令。
解决方案： 把所有关键规则直接写入 IDENTITY.md 和 AGENTS.md（这两个文件在白名单中，会自动注入系统提示）。TEAM.md 和 WORKFLOW.md 可以保留作为参考文档，但不要依赖模型主动读取。
坑 #5：Designer 和 Coder 并行导致 Coder 读不到设计文件
现象： Leader 同时 spawn Designer 和 Coder，Coder 启动时 design/ 目录还不存在（Designer 还没写完），导致 Coder 产出不符合设计。
解决方案： 强制串行 — Designer 必须完成后再启动 Coder。在 IDENTITY.md 中明确写明：
Step 3: 调用 Designer（必须先于 Coder！）Step 4: Designer 完成后调用 Coder
坑 #6：Leader 的 message 工具发送失败
现象： 日志显示 [tools] message failed: message required
根因： Leader 调用 message 工具时使用了错误的参数名（如用 text 代替 message）。
解决方案： 在 IDENTITY.md 或进度汇报说明中明确写出正确的参数格式：
message({ "action": "send", "channel": "feishu", "target": "{open_id}", "message": "消息内容" })坑 #7：旧 Session 上下文污染新行为
现象： 修改了 IDENTITY.md 后，Leader 仍然按旧模式执行（因为旧 session 的上下文中缓存了旧的系统提示）。
解决方案： 每次重大修改后，删除 sessions.json 中对应的 session 映射。关键命令：
# 查看当前 session 映射cat ~/.openclaw/agents/leader/sessions/sessions.json | python3 -m json.tool | head -20# 删除特定 sessionpython3 -c "import jsonwith open('sessions.json', 'r') as f:data = json.load(f)del data['agent:leader:feishu:direct:{用户open_id}']with open('sessions.json', 'w') as f:json.dump(data, f, indent=2)"
14. 验证部署
检查清单
openclaw.json中 5 个 Agent 已配置（pm, coder, designer, qa, leader）Leader 配置了 subagents.allowAgents: ["pm", "coder", "designer", "qa"]每个 Agent 的 workspace 目录存在且包含 IDENTITY.md Leader 的 AGENTS.md 顶部有 "最高优先级规则" Leader 的 IDENTITY.md 包含完整的 5 步 sessions_spawn 流程 ~/.openclaw/projects/目录存在Leader 没有旧的 session 映射（修改配置后）
测试步骤
给 Leader 发送一个简单任务（如"生成一个贪吃蛇网页游戏"） 观察日志，确认以下步骤依次执行： Leader 创建项目目录和 brief.md sessions_spawn(agentId: "pm")被调用 PM 完成后 sessions_spawn(agentId: "designer")被调用Designer 完成后 sessions_spawn(agentId: "coder")被调用Coder 完成后 sessions_spawn(agentId: "qa")被调用QA 完成后 Leader 汇总交付 检查项目目录下是否有完整产出：brief.md、prd.md、design/、code/、qa/
日志中的关键标志
# 正确的 sessions_spawn 调用（agent:pm 子session）childSessionKey: "agent:pm:subagent:{uuid}"# 错误的调用（匿名子session，没有调用真实 Agent）childSessionKey: "agent:leader:subagent:{uuid}"
附录：快速部署脚本
#!/bin/bash# OpenClaw 多 Agent 协作快速部署脚本OPENCLAW_DIR="$HOME/.openclaw"# 创建工作空间for role in leader pm coder designer qa; domkdir -p "$OPENCLAW_DIR/workspace-$role"donemkdir -p "$OPENCLAW_DIR/workspace-leader/prompts"mkdir -p "$OPENCLAW_DIR/projects"echo "✅ 目录创建完成"echo ""echo "接下来需要手动完成："echo "1. 配置 openclaw.json（agents.list + leader.subagents.allowAgents）"echo "2. 创建每个 workspace 的 IDENTITY.md"echo "3. 创建 Leader 的 AGENTS.md 和 TEAM.md"echo "4. 配置 LLM 模型的 API Key"echo "5. （可选）配置飞书机器人"
