claw-multi-agent

claw-multi-agent 🐝

用一支 AI 团队取代一个 AI。将串行变为并行，将数小时缩短为数分钟。

---

它能做什么？

场景	示例	提速效果
并行研究	同时搜索 5 个框架，每个框架各写一份报告	~65% ⚡
多模型比较	同时向 Claude、Gemini、Kimi 提出同一个问题	~50% ⚡
代码流水线	规划 → 编码 → 审核，按顺序自动交接	质量 ↑
批量处理	并行翻译 / 分析 / 总结多份文档	线性扩展

---

⚡ 30 秒快速上手

只需说类似这样的话：

• “并行研究 LangChain、CrewAI 和 AutoGen”
• “让多个 Agent 搜索这些主题，并撰写一份综合报告”
• “比较 Claude 和 Gemini 如何回答这个问题”
• “用多 Agent 模式做这项研究”

---

🎭 交互方式 — 如何与用户对话

这是推荐的模式。每次多 Agent 运行都必须遵循此交互模式。

步骤 0 — 首先宣布激活技能

⚠️ 铁律：收到任务后，你的第一条回复必须是激活公告 — 在读取任何文件、开展调查或生成 Agent 之前。

重要原因：读取文件、研究背景和生成 Agent 都需要时间。如果先做这些，用户就会长时间看不到回应。更糟的是，这期间可能会发生上下文压缩，导致激活公告永远无法发出。

正确顺序：接收任务 → 立即发送公告 → 然后读取文件 / 生成 Agent / 等待

触发此技能时，首先要说的内容 — 在任何规划或生成 Agent 之前：

🐝 **claw-multi-agent 已唤醒**
多智能体并行模式启动，我来组建 Agent 小队处理这个任务。

这会告知用户技能已激活，并说明接下来会发生什么。

生成 Agent 之前 — 宣布计划

发送激活公告后，立即在调用 sessions_spawn 之前呈现计划：

🚀 [N]个方向同时开搞，全面覆盖你的问题。

📋 任务规划：
🔍 研究员A（GLM）— [一句话任务描述]
🔍 研究员B（GLM）— [一句话任务描述]
📊 分析师（Kimi）— 先等前[N]个结果，单独召唤（note when sequential）

模式：🎯 指挥官模式（联网搜索）
预计耗时：~[X]s（[N] Agent 并行[，分析师串行跟进]）
正在派出 Agent 小队...

角色表情符号参考：

角色	表情符号	示例
研究员	🔍	🔍 研究员A（GLM）— 研究 XX
分析师	📊	📊 分析师（Kimi）— 深入比较
写作者	✍️	✍️ 写作者（Gemini）— 起草报告
程序员	💻	💻 程序员（Kimi）— 实现逻辑
审核员	🔎	🔎 审核员（GLM）— 质量检查
规划师	📋	📋 规划师（Sonnet）— 拆解任务

关键规则：

• ✅ 始终列出每个 Agent 的：表情符号 + 角色 + 模型名称 + 一句话任务说明
• ✅ 说明模式（指挥官/流水线/混合）和预计耗时
• ✅ 公告结尾使用：正在派出 Agent 小队...
• ✅ 按顺序执行的 Agent 标注为：“先等前 N 个结果，单独召唤”
• ❌ 绝不要不做公告就静默调用 sessions_spawn

等待期间 — 简短说明

生成 Agent 后，说一句话：

⏳ 子 Agent 已全部出发，等结果回来...

收到结果后 — 结构化输出（而非原始内容堆砌）

绝不要直接粘贴子 Agent 的原始输出。 始终根据内容逻辑消化并重组 — 而不是按 Agent 的顺序排列。

推荐的输出顺序：

1. 执行统计卡 ← 先让用户知道跑了什么
2. 核心结论（3-5条最重要发现）← 最有价值的放最前面
3. 分主题展开细节（按内容逻辑组织，不按子Agent顺序）← 读起来是一篇完整文章
4. 下一步行动建议 ← 落地结尾

统计卡格式：

## 📊 执行统计
| Agent | 模型 | 耗时 | 状态 |
|-------|------|------|------|
| 🔍 研究员A | GLM | 58s | ✅ |
| 🔍 研究员B | GLM | 62s | ✅ |
| 📊 分析师  | Kimi | 45s | ✅ |
串行需要约 165s → 并行实际 62s，节省 **62%** ⚡

❌ 错误 — 按 Agent 排序：

子Agent1的结果...
子Agent2的结果...
子Agent3的结果...  ← 读者要自己拼图，体验差

✅ 正确 — 按内容逻辑排序：

## 核心结论
1. 最重要发现A（来自多个Agent综合）
2. 最重要发现B
...

## 详细分析：[主题1]
...（整合所有相关Agent的内容）

## 详细分析：[主题2]
...

## 下一步建议
...

主 Agent 用自己的措辞重写所有内容。 子 Agent 的输出是原始素材，而不是最终答案。

结果之后——交付报告（按渠道处理）

始终先保存到文件，再根据当前渠道交付。

# Step 1: Always save to file first
write("/workspace/projects/{topic-slug}/report.md", content)

然后按渠道选择交付方式：

渠道	交付方式
feishu + 已安装 feishu-all-operations 技能	创建 Feishu 文档 → 发送链接（体验最佳）
feishu + 未安装 Feishu 技能	message(filePath=..., filename="report.md") — 作为附件发送
Discord / Telegram / Slack	message(message=...) — Markdown 会正常渲染
其他 / 未知	保存文件 + 告知用户文件路径

这很重要： Feishu 聊天不会渲染 Markdown。发送原始 Markdown 文本会显示 ##、|---| 等符号。在 Feishu 上务必使用附件或文档链接。

# Feishu (no Feishu doc skill): send as attachment
message(action="send", filePath="/workspace/projects/{topic-slug}/report.md", filename="report.md")

# Discord/Telegram: send markdown directly
message(action="send", message=report_content)

最后用一行结束：

需要调整某个方向，或推送到飞书文档吗？

规则：

• ✅ 始终先保存 .md 文件——无论使用哪个渠道
• ✅ 发送前检查当前渠道
• ❌ 在 Feishu 上绝不粘贴超过 300 个词的 Markdown 文本——它不会渲染
• ❌ 绝不能只说“报告已保存至 /path/xxx”——用户无法打开服务器路径
• ❌ 绝不要问“要不要我帮你整理成文档？”——直接去做

顺序执行与并行执行——分析师必须等待研究员

重要： 同一轮中启动的 Agent 会并行运行，彼此之间没有共享上下文。

❌ Wrong: spawn researcher-A + researcher-B + analyst all at once
          → analyst has no data, returns empty

✅ Right: 
  Round 1: spawn researcher-A + researcher-B (parallel, independent)
  Wait for both to return...
  Round 2: main agent consolidates research results
           → then either: main agent writes analysis itself
           → or: spawn analyst with research results injected as context

最佳实践：任何依赖其他 Agent 输出的 Agent，都应在收集到依赖项后，于之后的轮次启动。

---

🤖 模型选择指南——不同角色该用哪个模型

始终为每个 Agent 选择合适的模型，并在公告中明确说明模型。

模型列表

模型	别名	特点	适合角色
glm	GLM	便宜、速度快、中文好	搜索、简单调研、状态检查
kimi	Kimi	长上下文（128k）、代码能力强	深度分析、代码、长文整合
gemini	Gemini	创意能力强、多模态	写作、文案、图像理解
sonnet	Claude Sonnet	均衡、工具调用稳定	复杂推理、规划、审核
opus	Claude Opus	推理能力最强	极复杂分析、架构设计

角色 → 模型映射（默认）

角色	默认模型	原因
🔍 研究员 / Researcher	GLM	轻量级搜索，够用且便宜
📊 分析师 / Analyst	Kimi	长上下文，能处理大量资料
✍️ 写作者 / Writer	Gemini	创意写作效果最佳
💻 程序员 / Coder	Kimi	长上下文代码理解
🔎 审核员 / Reviewer	GLM	简单判断，无需重型模型
📋 规划师 / Planner	Sonnet	结构化规划能力强
🧐 批评者 / Critic	Sonnet	逻辑严谨，善于挑战假设

何时覆盖默认设置

• 任务很简单 → 降级为 GLM（节省成本）
• 需要最高质量 → 升级为 Opus
• 用户明确指定模型 → 按用户要求执行
• 多模型对比场景 → 每个 Agent 使用不同模型，并在公告中说明

始终公布模型

在启动前公告中，每个 Agent 条目都必须包含模型：

✅ 这样：🔍 研究员A（GLM）— 调研 LangChain
❌ 这样：🔍 研究员A — 调研 LangChain

---

步骤 0：始终先规划（Agent 数量动态确定）

不要硬编码要启动多少个 Agent。 合适的数量取决于任务复杂度。始终从规划步骤开始：

1. Analyze the task → identify subtopics / dimensions
2. Decide: how many agents? which roles? which mode?
3. Spawn accordingly (could be 2, could be 10)
4. Consolidate results

规划输出示例：

Task: "Research the top AI agent frameworks"
→ Plan: 5 researchers (one per framework) + 1 analyst for comparison
→ Mode: Orchestrator (needs web search)
→ Spawn: 5 parallel sub-agents

Agent 数量应与任务相匹配，而不是套用模板。

---

三种模式——根据意图自动路由

无需说明要使用哪种模式。 只需描述任务。该技能会读取以下两个信号：

1. 是否需要网页搜索 / 实时信息？ → 使用 sessions_spawn（带工具）
2. 是否需要多个草稿版本进行比较？ → 并行启动写作者

User says anything
        ↓
  Wants multiple versions / drafts / angles?
        YES ──→ Also needs web search?
        │              YES → 🔀 Hybrid Mode   (search first, then N drafts)
        │              NO  → 🔄 Pipeline Mode (N drafts in parallel, pure text)
        │
        NO  ──→ Needs web search / file ops?
                       YES → 🎯 Orchestrator Mode (sessions_spawn, parallel)
                       NO  → 🔄 Pipeline Mode     (pure text, faster)

该技能会识别的触发信号：

信号	示例	触发模式
多草稿意图	“几个版本”、“多个角度”、“让我挑”、“各自写”、“不同风格”	Pipeline 或 Hybrid
搜索意图	“搜索”、“最新”、“调研”、“联网”、“search”、“latest”	Orchestrator 或 Hybrid
两者都有	“搜索后给我几版报告”、“研究后写多个草稿”	Hybrid
两者皆无	“翻译”、“分析”、“写作”、纯文本任务	Pipeline

你也可以直接向路由器查询：

python scripts/router.py mode "搜索竞品资料，帮我写3个版本的分析"
# → 🔀 HYBRID
python scripts/router.py mode "调研LangChain并写一份报告"
# → 🎯 ORCHESTRATOR
python scripts/router.py mode "用三个角度分析这个方案"
# → 🔄 PIPELINE

🎯 编排模式（使用工具，实现真正的并行）

通过 sessions_spawn 启动子 Agent。每个 Agent 都拥有完整的 OpenClaw 工具：网页搜索、文件读写、代码执行。

⚡ 并行机制： 在同一轮工具调用中多次调用 sessions_spawn——OpenClaw 会同时执行它们。所有子 Agent 都会同时运行；等它们完成后，主 Agent 会收集所有结果。

Same round → parallel execution:

sessions_spawn(task="Search LangChain...") ──┐
sessions_spawn(task="Search CrewAI...")    ──┤→ all run simultaneously
sessions_spawn(task="Search AutoGen...")   ──┘
sessions_spawn(task="Search LangGraph...") ─┘

↓  (all finish, main agent receives all 4 results)

Main agent consolidates → writes full report

顺序执行 = 启动一个 Agent，等待结果，然后再启动下一个。 仅当后续任务依赖前面的结果时才使用（例如，研究完成后再撰写报告）。

如何启动——务必包含角色、模型提示和返回内容要求：

# Parallel research: spawn all 4 in the same round → they run simultaneously
sessions_spawn({
    "task": "[CONTEXT] Comparing AI agent frameworks for a tech team report.\n\n[YOUR TASK] Search LangChain: architecture, pros/cons, GitHub stars, latest version. Return 5 bullet points ≤100 words each. Do NOT write a full report.",
    "label": "🔍 researcher-langchain [model: default]"
})
sessions_spawn({
    "task": "[CONTEXT] Same report.\n\n[YOUR TASK] Search CrewAI: architecture, pros/cons, GitHub stars, latest version. Return 5 bullet points ≤100 words each.",
    "label": "🔍 researcher-crewai [model: default]"
})
sessions_spawn({
    "task": "[CONTEXT] Same report.\n\n[YOUR TASK] Search AutoGen: architecture, pros/cons, GitHub stars, latest version. Return 5 bullet points ≤100 words each.",
    "label": "🔍 researcher-autogen [model: default]"
})
sessions_spawn({
    "task": "[CONTEXT] Same report.\n\n[YOUR TASK] Search LangGraph: architecture, pros/cons, GitHub stars, latest version. Return 5 bullet points ≤100 words each.",
    "label": "🔍 researcher-langgraph [model: default]"
})
# All 4 run in parallel → when all return, main agent consolidates and writes report

混合模式：先并行，再顺序执行（最常见的模式）：

# Phase 1: parallel research (spawn all at once)
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search LangChain. 5 bullets ≤100 words.", "label": "🔍 researcher-langchain"})
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search CrewAI. 5 bullets ≤100 words.", "label": "🔍 researcher-crewai"})
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search AutoGen. 5 bullets ≤100 words.", "label": "🔍 researcher-autogen"})

# Phase 2: after all 3 return → main agent writes report (sequential, depends on research)
# (main agent does this directly, no need to spawn a writer)

关键规则：

• ✅ 同一轮 = 并行：针对相互独立的任务，同时启动多个 Agent
• ✅ 顺序执行：启动一个 Agent，等待结果，然后再启动下一个——仅用于任务之间存在依赖的情况
• ✅ 子 Agent 只返回摘要（每点不超过 100 个单词）
• ✅ 主 Agent 撰写完整报告（避免触发令牌数限制）
• ✅ 清楚标注每个 Agent：角色 + 所用模型
• ❌ 不要让子 Agent 同时搜索并撰写长篇报告

---

🔄 流水线模式（纯文本，适用于任何任务）

通过 Python CLI 运行 Agent。不支持网页搜索，但适用于任何纯文本任务：写作、分析、翻译、多模型比较、头脑风暴、代码生成。

cd ~/.openclaw/skills/claw-multi-agent

# Parallel: multiple agents tackle different angles simultaneously
python run.py --mode parallel \
  --agents "fast:🔍 researcher:summarize the pros of microservice architecture" \
           "fast:🔍 researcher:summarize the cons of microservice architecture" \
           "fast:🔍 researcher:list real-world companies using microservices and outcomes" \
           "smart:📊 analyst:compare microservices vs monolith for a 10-person startup" \
  --aggregation synthesize

# Sequential: chain agents, each builds on the previous output
python run.py --mode sequential \
  --agents "fast:📋 planner:break down how to build a REST API in Python" \
           "smart:💻 coder:implement the API based on the plan above" \
           "fast:🔎 reviewer:review the code for bugs and security issues" \
  --aggregation last

# Auto-route: router classifies task and picks tiers automatically
python run.py --auto-route --task "write a technical blog post about GRPO vs PPO"

# Dry-run: preview the plan without executing
python run.py --dry-run \
  --agents "fast:researcher:research X" "smart:writer:write report"

流水线模式适用于：

• 多角度分析（每个维度启动一个 Agent）
• 多模型比较（同一任务使用不同模型）
• 代码流水线（规划 → 编码 → 审查）
• 批量写作（并行翻译／总结 N 份文档）

---

🔀 混合模式（搜索 + 多稿）

兼具两种模式的优势：子 Agent 使用工具进行网页搜索，然后由多个写作者根据研究结果并行生成草稿。

适用场景： 用户同时需要实时研究和多个版本进行比较。

Phase 1 (Orchestrator — with tools, parallel):
  sessions_spawn(search topic A) ──┐
  sessions_spawn(search topic B) ──┤ → all run simultaneously
  sessions_spawn(search topic C) ──┘
  ↓ research summaries collected

Phase 2 (Pipeline — pure text, parallel):
  openclaw agent (writer style 1) ──┐
  openclaw agent (writer style 2) ──┤ → all run simultaneously
  openclaw agent (writer style 3) ──┘
  ↓ 3 draft versions returned

Main agent: compare drafts → pick best or synthesize

CLI 用法：

# Auto: router detects hybrid intent and runs both phases
python run.py --mode hybrid --task "调研主流AI框架，给我3个不同风格的对比报告" --num-drafts 3

# Auto-mode: let router decide the mode automatically
python run.py --auto-mode --task "搜索竞品资料后写几个版本的分析"

在对话中使用（sessions_spawn 方式）：

# Phase 1: parallel research (spawn all at once)
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search LangChain. 5 bullets.", "label": "🔍 research-langchain"})
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search CrewAI. 5 bullets.", "label": "🔍 research-crewai"})
sessions_spawn({"task": "[CONTEXT] ...\n\n[TASK] Search AutoGen. 5 bullets.", "label": "🔍 research-autogen"})

# After all 3 return → Phase 2: main agent writes 3 draft versions itself
# (or spawn 3 pipeline agents with research as context)

---

智能路由器

内置任务分类器。根据关键词自动选择合适的层级：

python scripts/router.py classify "write a Python web scraper"
# → Tier: CODE  (routes to smart model)

python scripts/router.py classify "research the latest LLM papers"
# → Tier: RESEARCH  (routes to fast model)

python scripts/router.py spawn --json --multi "research X and write a report"
# → splits into 2 tasks: RESEARCH + CREATIVE

层级	模型	用途
FAST	default（轻量）	简单查询、状态、翻译、搜索
CODE	default（智能）	编程、调试、实现
RESEARCH	default（轻量）	研究、搜索、比较、调查
CREATIVE	default（智能）	写作、文章、文档
REASONING	default（最佳）	架构、逻辑、复杂分析

---

contextSharing：为子 Agent 提供背景信息

子 Agent 会以全新的会话启动——不了解你的目标。请添加 [CONTEXT] 块。

模式 1：recent（推荐——适用于 95% 的情况）

[CONTEXT] User is comparing AI agent frameworks for a team report. Audience: engineers.

[YOUR TASK] Search LangChain pros and cons. Return 5 bullet points ≤100 words each.

模式 2：summary（顺序任务——传递之前的结果）

[PRIOR FINDINGS]
- LangChain: richest ecosystem, steep curve
- CrewAI: clean role separation...

[YOUR TASK] Based on above, search AutoGen. Return 3 unique points not covered above.

模式 3：full（复杂背景——让 Agent 阅读文件）

[CONTEXT FILE] Read /workspace/research/context.md for full background.

[YOUR TASK] Search latest Test-Time Compute Scaling advances. Return 3 summaries.

在并行 Agent 之间复用上下文：

BG = "Researching RL post-training for ML engineers. Topics: GRPO/DAPO/PPO, veRL."

sessions_spawn({"task": f"[CONTEXT] {BG}\n\n[TASK] Search GRPO vs PPO benchmarks. 5 bullets ≤100 words.", "label": "🔍 researcher-grpo [model: default]"})
sessions_spawn({"task": f"[CONTEXT] {BG}\n\n[TASK] Search DAPO design. 5 bullets ≤100 words.", "label": "🔍 researcher-dapo [model: default]"})
sessions_spawn({"task": f"[CONTEXT] {BG}\n\n[TASK] Search veRL architecture. 5 bullets ≤100 words.", "label": "🔍 researcher-verl [model: default]"})

---

执行摘要——务必输出

每次运行多个 Agent 后，都要打印标准卡片：

## 📊 Execution Summary

Mode: 🎯 Orchestrator Mode (sessions_spawn, with tools)

| Agent | Role | Model | Time | Status |
|-------|------|-------|------|--------|
| 🔍 researcher-langchain | Researcher | default | 22s | ✅ |
| 🔍 researcher-crewai    | Researcher | default | 19s | ✅ |
| 🔍 researcher-autogen   | Researcher | default | 24s | ✅ |
| 🔍 researcher-langgraph | Researcher | default | 21s | ✅ |
| ✍️ main (consolidate)   | Writer     | default | 38s | ✅ |

Agents spawned: 4  |  Parallel time: ~24s  |  Serial equivalent: ~86s  |  Saved: ~62s (72%)

务必包含：

• 模式（编排器／流水线 + 顺序／并行）
• 每个 Agent 的角色表情符号 + 名称 + 所用模型
• 每个 Agent 的实际耗时
• 总并行耗时与串行执行所需时间的对比

---

预设角色

角色	表情符号	最适合
researcher	🔍	网页搜索、信息收集
writer	✍️	报告、文档、文章
coder	💻	编写代码、调试、实现
analyst	📊	数据分析、比较、统计
reviewer	🔎	代码／内容审查、质量保证
planner	📋	任务规划、拆解
critic	🧐	风险分析、反方论证

---

⚠️ 注意事项

易犯错误 0：在宣布前先读取文件（最常见的错误）

在发送启动公告前调查上下文，会导致长时间沉默；上下文压缩还可能让公告彻底丢失。

• ❌ 收到任务 → 读取 operators.py → 读取 README → 宣布 → 启动
• ✅ 收到任务 → 立即宣布（可以说“正在分析任务……”）→ 读取文件 → 启动

易犯错误 1：子 Agent 的输出令牌限制

子 Agent 的输出上限约为 4096 个令牌。超出上限 → 工具参数被截断 → 文件写入会悄无声息地失败。

• ❌ “搜索并撰写一份 2000 字的报告”
• ✅ 子 Agent 返回摘要；主 Agent 撰写报告

易犯错误 2：流水线模式下，编排模式没有工具

python run.py 进程没有 web_search、exec 等工具。

• ❌ 流水线模式：“搜索 X 的最新新闻”
• ✅ 任何需要实际访问 Web 的任务 → 编排模式

易犯错误 3：并行 Agent 不能相互依赖

同一轮启动的 Agent 会同时运行。

• ❌ Agent-2：“根据 Agent-1 的结果……”
• ✅ 并行 = 相互独立；顺序 = 链式执行

易犯错误 4：不要硬编码 Agent 数量

根据任务而不是模板来匹配 Agent 数量。

• ❌ 始终恰好启动 3 个 Agent
• ✅ 先制定计划，再决定：简单任务 → 2 个 Agent，复杂任务 → 8 个以上 Agent

---

流水线模式速查

python run.py
  --mode parallel|sequential
  --agents "tier_or_model:🎭role:task description"   # repeatable, any number
  --aggregation synthesize|compare|concatenate|last
  --timeout 300
  --dry-run          # preview without executing
  --auto-route       # router picks tiers automatically
  --list-models      # show current model config

聚合方式	效果
synthesize	主 Agent 总结所有输出（默认）
compare	并排展示每个 Agent 的输出
concatenate	按顺序连接输出
last	仅显示最后一个 Agent 的输出（顺序执行）