name: team-dispatch description: Use when a request requires multi-agent workflow orchestration (task decomposition + dependency/DAG + parallel execution), needs durable task tracking across context compaction, or needs retries/fallbacks and completion notifications. metadata: openclaw: emoji: "🚀" i18n: default: "en" supported: ["en", "zh"]

🚀 Team Dispatch v1.0.8 — Multi-Agent Workflow Orchestration

一句需求 → 自动分析 → 智能拆解 → DAG 派发 → 故障重试 → 自动交付。

⚡ 第〇步：自动安装与环境检测（必须首先执行）

真实项目代码空间（默认）

默认真实项目/仓库目录：~/work（可通过 <SKILL_DIR>/config.json 或 ~/.openclaw/configs/team-dispatch.json 的 paths.projectsRoot 修改）
约定：每个项目在 paths.projectsRoot/<project> 下创建与产出代码（而不是放在 ~/.openclaw/workspace/）
setup.sh 会自动创建该目录（若不存在）

Agent 读到本文件后，必须先执行以下检测流程，确认系统就绪后再处理用户需求。 新用户首次安装、或已有用户技能更新后，均走此流程。

SKILL_DIR 解析

<SKILL_DIR> = 本 SKILL.md 文件所在的目录。 Agent 应从自身读取本文件的路径自动推导，例如：

若从 /Users/xxx/skills/team-dispatch/SKILL.md 读取，则 SKILL_DIR=/Users/xxx/skills/team-dispatch
若从软连接 ~/.openclaw/skills/team-dispatch/SKILL.md 读取，用 readlink 解析真实路径

一键安装

直接运行安装脚本即可完成全部配置：

bash <SKILL_DIR>/scripts/setup.sh

如果遇到模型 404/quota 问题，可追加基线模型参数：

bash <SKILL_DIR>/scripts/setup.sh --baseline-models

安装脚本自动完成的 8 项配置

setup.sh 会自动检测并配置以下所有项目，已存在的不覆盖：

#	配置项	说明
1	软连接	`~/.openclaw/skills/team-dispatch → <SKILL_DIR>`
2	任务目录（使用安装用户的主工作区）	`~/.openclaw/workspace/tasks/{active,done,templates}`（不会创建额外的 main 工作区）
3	项目模板	复制 `project.json` 到 templates/
4	用户配置	生成 `~/.openclaw/configs/team-dispatch.json`（语言、通知策略、团队显示名）
5	子 Agent agentDir 模板	全新安装：`cp -R <SKILL_DIR>/assets/agents/<id> ~/.openclaw/agents/<id>`（内含 workspace 模板 + 预置文件）
6	补齐缺失文件	已有 `~/.openclaw/agents/<id>`：仅补齐 `workspace/` 下缺失文件，不覆盖用户改动；并创建 `sessions/`
7	写入 openclaw.json	在 `agents.list` 中确保存在 `main`（dispatcher/root）并配置 `main.subagents.allowAgents: ["*"]`；同时写入 7 个子 Agent 配置（含 workspace、identity、model），已存在的补齐缺失字段
8	重启 Gateway	配置写入后自动重启 Gateway 使生效

子 Agent 完整配置规范

在 openclaw.json 的 agents.list 中：必须存在 main（dispatcher/root），并在 main 上配置 subagents.allowAgents。

main agent 配置示例（安装时应确保存在/补齐）

{
  "id": "main",
  "default": true,
  "name": "main",
  "workspace": "/Users/vvusu/.openclaw/workspace",
  "agentDir": "/Users/vvusu/.openclaw/agents/main/agent",
  "model": "openai-codex/gpt-5.4",
  "identity": {
    "name": "调度台",
    "emoji": "🎯"
  },
  "subagents": {
    "allowAgents": ["*"]
  }
}

子 Agent 配置示例

{
  "id": "<agentId>",
  "name": "<中文名>",
  "workspace": "~/.openclaw/agents/<agentId>/workspace",
  "model": {
    "primary": "<见下方模型选择策略>",
    "fallbacks": ["bailian/qwen3.5-plus", "bailian/kimi-k2.5", "zai/glm-4.7"]
  },
  "tools": { "profile": "<coding|full>" },
  "skills": [],
  "identity": {
    "name": "<中文名>",
    "emoji": "<角色 emoji>",
    "theme": "<英文角色描述>"
  }
}

模型选择策略

coder → openai-codex/gpt-5.3-codex（OAuth，专为编码优化）
其他 Agent → openai-codex/gpt-5.4（OAuth，通用稳定）
fallbacks 从用户已配置的 providers 中选取，确保不会 404

工具集分配

coder, tester → "coding"
product, research, trader, writer → "full"

子 Agent Workspace 结构

每个子 Agent 拥有独立的 agentDir + workspace + sessions（符合 OpenClaw 多 Agent 目录规范），互不干扰。

全新安装（您指定的逻辑）

cp -R <SKILL_DIR>/assets/agents/<id> ~/.openclaw/agents/<id>

模板目录结构为：

<SKILL_DIR>/assets/agents/<id>/
└── workspace/
        ├── AGENTS.md
        ├── SOUL.md
        ├── IDENTITY.md
        ├── USER.md
        ├── TOOLS.md
        ├── HEARTBEAT.md
        ├── BOOTSTRAP.md
        └── .openclaw/workspace-state.json

安装后运行时会在以下位置写入会话与状态：

~/.openclaw/agents/<id>/sessions/

已有安装（升级/补齐）

若 ~/.openclaw/agents/<id> 已存在：只补齐 workspace/ 下缺失文件，不覆盖用户已修改的文件
sessions/ 若缺失会自动创建（本技能脚本也会 mkdir -p）

注：子 Agent 通过 sessions_spawn 启动时只注入 AGENTS.md + TOOLS.md，但完整的 workspace 文件在 Agent 作为独立 agent（而非 subagent）运行时会全部加载。

团队成员一览

agentId	中文名	Emoji	workspace	工具集	角色定位
`coder`	闪电	⚡️	workspace-coder	coding	编码开发专家
`product`	诺娃	🧭	workspace-product	full	产品规划专家
`tester`	亚特拉斯	🔍	workspace-tester	coding	测试验证专家
`research`	露娜	🔭	workspace-research	full	调研搜索专家
`trader`	泰坦	📈	workspace-trader	full	投资分析专家
`writer`	萊拉	✒️	workspace-writer	full	内容写作专家
`shield`	盾卫	🛡️	workspace-shield	full	安全审计专家

检测通过后的输出

安装脚本或 Agent 检测全部通过后，向用户确认：

✅ Team Dispatch 环境就绪！
- 软连接：✅
- 任务目录：✅
- 项目模板：✅
- 用户配置：✅（语言：zh/en）
- 子 Agent Workspace：✅（7 个独立工作目录 + AGENTS.md）
- 子 Agent 配置：✅（workspace + identity + model 完整）
- Gateway：✅（已重启生效）

系统已准备好接收任务，请告诉我您想要完成什么？

常见安装问题与自动修复

问题	原因	修复方式
子 Agent 没有独立 workspace	旧版技能未配置	重新运行 setup.sh，自动创建并补齐
子 Agent 没有角色指令	缺少 AGENTS.md	setup.sh 从 assets/agents/ 复制模板
子 Agent 不知道自己是谁	缺少 identity 配置	setup.sh 自动写入 identity 字段
用户配置不完整	手动创建了简化版	用 <SKILL_DIR>/config.json 覆盖
模型 404 / quota 错误	模型不可用	运行 `setup.sh --baseline-models`

🌍 国际化（i18n）

默认英文，通过 ~/.openclaw/configs/team-dispatch.json 中 "language": "zh" 切换中文。

📊 任务分级

收到需求后，先判断复杂度：

级别	判断标准	处理方式
S	单 Agent 可完成	直接 `sessions_spawn`，不建文件
M	2-3 个 Agent，线性依赖	自动建 DAG + 追踪
L	4+ Agent，有并行分支	自动建 DAG + 追踪 + 进度汇报
XL	跨多领域，需多轮迭代	DAG + 分阶段交付 + 用户确认点

🔀 拆解模板

根据需求类型自动选择：

开发类

product(PRD) → coder(编码) → tester(测试) → shield(安全审计)
                             → writer(文档)

安全敏感类（带部署）

product(PRD) → coder(编码) → tester(测试) → shield(安全审计) → writer(文档)

研究类

research(调研) → product(分析框架) → writer(成文)

全栈类

research(调研) → product(PRD) → coder(编码) → tester(测试) → shield(安全审计) → writer(文档)

分析类

research(数据收集) → trader(分析) → writer(报告)
                   → product(策略建议)

内容类

research(素材收集) → writer(初稿) → product(审核优化)

⚠️ 重要限制：sessions_spawn 可能不允许指定 agentId

在某些运行环境/工具策略下，sessions_spawn 可能会拒绝 agentId 参数（错误类似：agentId is not allowed for sessions_spawn (allowed: none)）。

此时 Team Dispatch 必须自动降级为“单 Agent 多角色模拟”模式：

仍然按 DAG 拆解任务
派发时不传 agentId（让 subagent 继承当前 agent 身份）
在 task prompt 顶部注入角色指令（例如“你现在扮演 coder/product/tester…”）来模拟团队分工
结果收集、依赖解锁、重试逻辑保持不变

如果你有权限配置并希望启用真实多 Agent 派发：

在 openclaw.json 中设置 agents.defaults.subagents.allowAgents: ["*"]（或允许列表）
重启 Gateway

⚙️ 核心调度流程

⚠️ 关键行为约定：事件驱动的自动调度循环

当你通过 sessions_spawn 派发任务后，OpenClaw 会在 subagent 完成时自动向你的会话推送一条 completion event（以 user message 形式到达）。

你必须在收到每一条 completion event 后，立刻执行完整的调度循环：

从 event 中提取 label，匹配到对应的 task

更新该 task 的 status/result/completedAt，写入 JSON

扫描所有 pending 任务，找出依赖已全部 done 的任务

立刻派发这些就绪的任务（sessions_spawn）

检查项目是否全部完成，若完成则归档并通知用户

不要等待用户指令，不要等待其他事件，不要跳过这个循环。每收到一条 completion event 就执行一次。

这是 Team Dispatch 的核心机制——事件驱动的级联派发。如果你不执行这个循环，任务就会"卡住"。

Step 1: 首次派发

扫描项目 JSON 中所有 status=pending 且依赖全部 done（或无依赖）的任务，批量派发：

for each task where status=="pending" && allDepsAreDone(task):
  task.status = "in-progress"
  task.startedAt = now()
  prompt = buildPrompt(task)
  sessions_spawn(agentId=task.agentId, task=prompt,
                 runTimeoutSeconds=task.timeoutSeconds,
                 label="{project}:{taskId}")
  task.sessionKey = response.childSessionKey
  writeJSON()

Step 2: 收到 completion event → 立刻执行调度循环

当 subagent completion event 到达时（OpenClaw 自动推送，格式为 "✅ Subagent {agentId} finished\n{result}"），你必须立刻执行以下完整流程，不需要用户指令：

# ① 识别完成的任务
task = findByLabel(event.label)   # 或从 event 内容匹配 agentId + 上下文

# ② 更新状态
task.result = summarize(event.result)
task.status = "done"
task.completedAt = now()
writeJSON()

# ③ 扫描并派发就绪的下游任务（关键！）
dispatchReady():
  for each t where t.status=="pending" && allDepsAreDone(t):
    t.status = "in-progress"
    t.startedAt = now()
    prompt = buildPrompt(t)  # 含上游结果注入
    sessions_spawn(agentId=t.agentId, task=prompt, ...)
    t.sessionKey = response.childSessionKey
    writeJSON()

# ④ 检查项目是否全部完成
checkProjectDone():
  if all tasks are done/skipped:
    project.status = "completed"
    moveToArchive()          # tasks/active → tasks/done
    finalizeAndNotify()      # 向用户发送最终交付清单

再次强调：Step 2 是一个自动触发的循环。你不需要也不应该等用户说"继续"或"下一步"。每收到一个 completion event，就执行一轮 ②→③→④。这样任务会像多米诺骨牌一样自动级联推进，直到全部完成。

Step 3: Prompt 构建 — 结果注入

下游 Agent 自动获得上游输出：

buildPrompt(task):
  prompt = task.description
  if task.dependsOn:
    prompt += "\n\n--- 上游任务结果 ---"
    for depId in task.dependsOn:
      dep = findTask(depId)
      prompt += "\n\n[{dep.id}] ({dep.agentId}): {dep.result}"
  return prompt

Step 4: 并行派发注意事项

当多个任务同时就绪时（如 t4-tests 和 t5-docs 都依赖 t3-core），应同时派发所有就绪任务，而非逐个等待：

# 错误做法 ❌：派发 t4，等 t4 完成，再派发 t5
# 正确做法 ✅：同时派发 t4 和 t5，各自独立完成后触发下游

🛡️ 故障处理

故障类型与自动恢复

类型	触发条件	自动处理
超时	超过 timeoutSeconds	超时 × 1.5 后重试
失败	Agent 返回 failed	重试（最多 retryLimit 次）
拒绝	并发上限	进入 queued，自动出队
模型错误	模型不可用(404等)	检查修正模型配置

降级策略（onFailure 字段）

策略	值	行为
阻塞	`"block"`	中止项目，通知用户（默认）
跳过	`"skip"`	标记 skipped，下游继续
降级	`"fallback"`	换备选 Agent 重试
人工	`"manual"`	暂停，等用户提供结果

📈 状态机

项目状态

active → completed    (全部 done/skipped)
active → blocked      (关键任务失败，重试耗尽)
active → cancelled    (用户取消)
blocked → active      (用户干预后恢复)

任务状态

pending → in-progress → done
       → queued       → in-progress   (并发满)
       → in-progress  → failed → pending (重试)
                               → skipped (跳过)

🔒 并发控制

并发上限由 agents.defaults.subagents.maxChildrenPerAgent/maxConcurrent 决定（默认 5，建议 10）
超出时任务进入 queued 状态，有 Agent 完成后自动出队
优先级：关键路径 > 依赖链长 > 声明顺序

🔗 依赖模式

模式	图示	场景
线性	`A → B → C`	Bug 修复、简单功能
扇出	`A → B, C, D`	一个输入多个并行处理
扇入	`B, C → D`	多个结果汇合
菱形	`A → B, C → D`	先分后合

⏸️ 用户确认点（XL 级）

关键节点暂停等用户审核：

{
  "id": "review-prd",
  "agentId": null,
  "description": "请用户确认 PRD 是否符合预期",
  "status": "pending",
  "dependsOn": ["prd"],
  "type": "checkpoint"
}

checkpoint 类型不派发 Agent，暂停并通知用户。

📁 项目文件

存储路径：<workspace>/tasks/

tasks/
├── active/          # 进行中
│   └── <project>.json
├── done/            # 已完成
│   └── <project>.json
└── templates/
    └── project.json  # 任务模板

🔧 运维工具

脚本	用途	命令
`scripts/setup.sh`	一键安装/配置	`bash <SKILL_DIR>/scripts/setup.sh`
`scripts/setup.sh --baseline-models`	切换稳定基线模型	解决 404/quota 问题
`scripts/setup-config.sh`	生成用户配置	自动跳过已存在
`scripts/doctor.sh`	环境健康检查	`bash <SKILL_DIR>/scripts/doctor.sh`
`scripts/demo-project.sh`	生成闭环自测 Demo 项目（product → coder → tester）	`bash <SKILL_DIR>/scripts/demo-project.sh`
`scripts/watch.sh`	低频巡检卡死任务（前台运行）	`INTERVAL=300 GRACE=20 bash <SKILL_DIR>/scripts/watch.sh`
`scripts/watch-install.sh`	安装 watcher（后台常驻，跨平台：macOS/Linux；Windows见ps1）	`bash <SKILL_DIR>/scripts/watch-install.sh`
`scripts/watch-uninstall.sh`	卸载 watcher（后台常驻）	`bash <SKILL_DIR>/scripts/watch-uninstall.sh`
`assets/windows/watch-install.ps1.txt`	Windows 安装 watcher（Scheduled Task）	`copy <SKILL_DIR>\\assets\\windows\\watch-install.ps1.txt watch-install.ps1; powershell -ExecutionPolicy Bypass -File .\\watch-install.ps1`
`scripts/demo-project.sh`	生成协作开发测试 Demo 项目（写入 tasks/active）	`bash <SKILL_DIR>/scripts/demo-project.sh`

✅ 闭环自测（最小协作链路）

生成一个带 3 个任务的 Demo DAG（写入 ~/.openclaw/workspace/tasks/active/）：

bash <SKILL_DIR>/scripts/demo-project.sh

然后在 main agent 对话中说：

“请用 team-dispatch 跑一下刚生成的 demo-collab-loop 项目（product → coder → tester），并在完成后归档到 tasks/done。”

预期：main 会按依赖顺序依次 sessions_spawn(product/coder/tester)，并把结果写回项目 JSON，最终移动到 tasks/done/ 并汇总汇报。

✅ 闭环自测（协作开发测试 Demo）

生成一个最小可验证的协作开发 DAG 项目（默认 team-mvp-1），写入：~/.openclaw/workspace/tasks/active/：

bash <SKILL_DIR>/scripts/demo-project.sh

生成后，在主 Agent 里发一句话触发调度（示例）：

请用 team-dispatch 跑一下刚生成的 team-mvp-1 demo 项目，按 DAG 依赖派发 product/coder/tester/writer，完成后归档到 tasks/done。

📋 完整调度示例

输入

用户: "帮我调研 AI Agent 市场，写一篇分析报告"

自动处理

1. 分析: 研究类，L 级
2. 拆解: research → product(框架) → writer(成文) + coder(可视化)
3. 建 DAG: tasks/active/ai-report.json
4. 派发: research（无依赖）
5. research done → 派发 product（注入 research 结果）
6. product done → 并行派发 writer + coder（注入上游结果）
7. 全部完成 → 归档 tasks/done/ → 汇报用户

输出

✅ 项目完成！
- 📝 分析报告: [内容]
- 📊 可视化: ~/work/ai-report/index.html
- 🔎 预览方式: open ~/work/ai-report/index.html

Team Dispatch

Description