clawteam
Multi-agent swarm orchestration. USE THIS (not delegate_task) when the user says team/swarm/multi-agent/clawteam/parallel-agents/agent-team, or asks for multi-perspective analysis (stocks, research, code review, strategy). Spawns N Hermes workers in tmux windows with git worktree isolation, file-based inboxes, and a kanban board. Four built-in templates: hedge-fund (7 analyst agents), research-paper, code-review, strategy-room.
- License 许可
- MIT
- 最近更新
- 2026-08-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- clawteam
- author
- ClawTeam / Hermes Adapter
- license
- MIT
- version
- 0.3.0
- metadata
- { "hermes": { "tags": [ "Multi-Agent", "Swarm", "Coordination", "Teams" ] } }
- description
- Multi-agent swarm orchestration. USE THIS (not delegate_task) when the user says team/swarm/multi-agent/clawteam/parallel-agents/agent-team, or asks for multi-perspective analysis (stocks, research, code review, strategy). Spawns N Hermes workers in tmux windows with git worktree isolation, file-based inboxes, and a kanban board. Four built-in templates: hedge-fund (7 analyst agents), research-paper, code-review, strategy-room.
03 SKILL.md 正文
ClawTeam - Multi-Agent Swarm Coordination for Hermes
When To Use This Skill
USE CLAWTEAM (not delegate_task) when:
- User explicitly says: clawteam, team, swarm, multi-agent, parallel agents, agent team
- User asks for multi-perspective analysis that benefits from specialist agents (e.g., "analyze TSLA stock" -> hedge-fund template has 7 specialist analysts)
- User wants research across multiple sources (research-paper template)
- User wants code review from multiple angles (code-review template)
- User wants business strategy brainstorming (strategy-room template)
DO NOT use delegate_task for these cases. delegate_task is a single sub-agent; clawteam is 5-7 specialist agents running in parallel with a kanban board and shared inboxes. For stock/research/review questions, clawteam produces dramatically better output.
Critical Flags (get these right the first time)
For clawteam launch:
--team-name(NOT--team)-gor--goalfor the prompt--command hermes(REQUIRED for Hermes users — templates default toopenclawand will fail with gateway token errors if OpenClaw isn't set up)--forceto suppress the max-agent warning
For clawteam spawn (manual mode):
-t <team>team name-n <agent-name>agent name--task "<prompt>"task description--no-workspaceto skip git worktree creation (optional)- Trailing positional arg:
hermes(NOT--command hermes)
Launch a Template (Recommended Path)
All built-in templates default to command = ["openclaw"]. Hermes users MUST pass --command hermes:
# Stock analysis (7 specialist analysts: portfolio-manager, buffett, growth, technical, fundamentals, sentiment, risk-manager)
clawteam launch hedge-fund --team-name tesla --goal "Analyze TSLA" --command hermes --force
# Research paper summary
clawteam launch research-paper --team-name papers --goal "Survey arxiv 2024.X" --command hermes --force
# Code review (multiple perspectives)
clawteam launch code-review --team-name review1 --goal "Review PR #42" --command hermes --force
# Business strategy
clawteam launch strategy-room --team-name strat --goal "Q2 planning" --command hermes --force
CRITICAL: Timing Expectations (DO NOT cleanup early)
Spawned Hermes workers need substantial time to produce output:
- Boot: 20-40 seconds per worker (loading 62 tools + 113 skills + MCP servers)
- Research/analysis: 1-5 minutes depending on task complexity
- Hedge-fund template (7 analysts running in parallel): typically 2-5 minutes total
After launching a team, WAIT before checking results. NEVER check inboxes within the first 60 seconds — they will be empty and you will incorrectly conclude the team failed.
Correct polling pattern for a hedge-fund team:
# Launch
clawteam launch hedge-fund --team-name <name> --goal "<prompt>" --command hermes --force
# Wait for boot (mandatory, do not skip)
sleep 60
# Poll the board every 30 seconds until tasks move to COMPLETED.
# Maximum total wait: ~5 minutes. Use tmux capture to see worker progress.
for i in 1 2 3 4 5 6 7 8; do
sleep 30
echo "=== tick $i ($(( i * 30 + 60 ))s elapsed) ==="
clawteam board show <name>
# Check if any non-leader task is COMPLETED (then continue monitoring)
# Break the loop only when most/all tasks show COMPLETED
done
# Only read inboxes after tasks show COMPLETED on the board
for agent in portfolio-manager buffett-analyst growth-analyst technical-analyst fundamentals-analyst sentiment-analyst risk-manager; do
echo "=== $agent ==="
clawteam inbox peek <name> --agent $agent
done
# Clean up ONLY after you've read the reports
clawteam team cleanup <name> --force
If inboxes are still empty after 5 minutes, something is wrong (token auth, model provider, or worker crashed). Inspect instead of giving up:
clawteam team status <name> # Check liveness of each agent
tmux list-windows -t clawteam-<name> 2>/dev/null # Confirm tmux panes exist
tmux capture-pane -t clawteam-<name>:0 -p 2>&1 | tail -30 # Inspect worker 0's output
Manual Inbox/Cleanup Commands (reference)
clawteam board show <team> # Kanban view
clawteam board live <team> # Auto-refreshing board
clawteam inbox peek <team> --agent <name> # Peek one agent's inbox
clawteam team status <team> # Agent liveness + health
clawteam team cleanup <team> --force # Delete team (only after reading reports)
Manual Team Setup (For Custom Teams)
When no template fits:
# 1. Create team
clawteam team spawn-team my-team -d "Goal description" -n leader
# 2. Spawn Hermes workers (hermes is a positional arg at the end, NOT --command hermes)
clawteam spawn -t my-team -n researcher --task "Research X" --no-workspace hermes
clawteam spawn -t my-team -n writer --task "Write report based on researcher's findings" --no-workspace hermes
# 3. Monitor
clawteam board show my-team
How The Hermes Adapter Builds Commands
When ClawTeam spawns a Hermes worker, the adapter builds:
hermes chat --yolo --source tool -q "<task prompt>"
Notes on each flag:
chatsubcommand inserted only if user passed barehermes--yolowhenskip_permissions=True(default for clawteam)--source toolis intended to tag the session so clawteam spawns don't clutterhermes sessions list. Known limitation on Hermes ≤ 0.8.0: the flag is accepted but not propagated to the SQLite store — sessions still record assource=cli. ClawTeam passes the flag correctly; the fix belongs upstream (run_agent.py:1057and:6600short-circuit onself.platform="cli"before readingHERMES_SESSION_SOURCE). See Known upstream issues below for the one-line patch.-q "<prompt>"passes the task as a one-shot query- No
--continue— Hermes auto-generates a fresh session ID per spawn -m <model>added if--modelwas passed to clawteam
Known upstream issues
--source tool ignored by Hermes ≤ 0.8.0
Hermes's cmd_chat correctly sets HERMES_SESSION_SOURCE from the flag, but the agent constructor's session-create call reads self.platform first:
# hermes-agent/run_agent.py:1057 and :6600 (pre-fix)
source=self.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
cli.py hardcodes platform="cli", which is truthy, so the env var never wins. One-line fix (swap the precedence):
source=os.environ.get("HERMES_SESSION_SOURCE") or self.platform or "cli",
Verify post-fix with: hermes chat --yolo --source tool -q "ping" && hermes sessions list --source tool. Until this lands upstream, ClawTeam-spawned Hermes workers appear interleaved with your interactive sessions — annoying, not broken.
MCP Inheritance
Spawned Hermes workers inherit any MCP servers configured in ~/.hermes/config.yaml. If you have a knowledge base, memory store, or other MCP tool wired into Hermes, every worker gets that capability automatically.
Include MCP-related instructions in task prompts if you want workers to use them:
clawteam spawn -t research -n analyst --task "Research topic X. Use available MCP tools to check prior work and store findings." --no-workspace hermes
Command Reference
Team Management
| Command | Description |
|---|---|
clawteam team spawn-team <name> -d "<desc>" -n <leader> |
Create team |
clawteam team discover |
List all teams |
clawteam team status <team> |
Show team status |
clawteam team cleanup <team> --force |
Delete team |
Launching Templates
| Command | Description |
|---|---|
clawteam launch <template> --team-name <name> --goal "<prompt>" --command hermes --force |
One-command team launch |
clawteam template list |
List available templates |
Spawning Agents Manually
| Command | Description |
|---|---|
clawteam spawn -t <team> -n <name> --task "<prompt>" hermes |
Spawn Hermes worker |
clawteam spawn -t <team> -n <name> --task "<prompt>" --skip-permissions hermes |
Spawn with --yolo |
clawteam spawn -t <team> -n <name> --task "<prompt>" -m claude-sonnet-4 hermes |
Spawn with specific model |
Task Management
| Command | Description |
|---|---|
clawteam task create <team> "<desc>" -o <owner> |
Create task |
clawteam task create <team> "<desc>" -o <owner> --blocked-by <id> |
Create with dependency |
clawteam task update <team> <id> --status completed |
Complete task |
clawteam task list <team> |
List all tasks |
Messaging
| Command | Description |
|---|---|
clawteam msg send <team> --from <name> --to <name> "<msg>" |
Direct message |
clawteam msg broadcast <team> --from <name> "<msg>" |
Broadcast to all |
clawteam inbox peek <team> --agent <name> |
Peek at inbox |
clawteam inbox receive <team> |
Drain your own inbox |
Monitoring
| Command | Description |
|---|---|
clawteam board show <team> |
Kanban board |
clawteam board attach <team> |
Tmux tiled view (requires terminal) |
clawteam board live <team> |
Auto-refreshing board |
clawteam board serve --port 8080 |
Web dashboard |
Known Failure Modes
-
risk-manager crash: The risk-manager agent is prone to crashing mid-execution (
"Agent 'risk-manager' exited unexpectedly. Reset N task(s) to pending"). This can leave the team's final synthesis incomplete. If this happens, read tmux scrollback for the portfolio-manager (leader) window first — it may have the final recommendation before the crash. -
Inbox empty despite COMPLETED tasks: Hermes workers write to tmux scrollback, not to the inbox system. The kanban board reflects task state but not content. Always capture tmux panes to read actual output.
-
Workers do not persist findings: Agent outputs live in tmux scrollback and are lost when the session is cleaned up. Capture the panes before running
team cleanup, or instruct agents (via the task prompt) to write to any MCP-backed persistence store configured in~/.hermes/config.yaml.
CRITICAL: Inbox Peek Is Unreliable — Use Tmux Capture
clawteam inbox peek often returns EMPTY even when tasks show COMPLETED on the board. The actual agent outputs live in tmux scrollback, not in the inbox system.
Always use tmux pane capture to read agent reports:
# List all tmux windows for the team
tmux list-windows -t clawteam-<team-name> 2>/dev/null
# Capture each window's scrollback (each window = one agent)
for win in $(tmux list-windows -t clawteam-<team-name> -F '#{window_index}' 2>/dev/null); do
echo -e "\n\n=== Window $win ==="
tmux capture-pane -t clawteam-<team-name>:$win -p 2>&1 | tail -100
done
Also: If you have an MCP-backed persistence store (knowledge base, memory system) wired into ~/.hermes/config.yaml, include instructions in the goal so agents write findings there. This gives you a persistent fallback when tmux sessions are lost. Exact tool names depend on which MCP server you use.
Anti-Patterns (Do Not Do)
- Don't use
delegate_taskwhen the user asks for multi-agent/swarm/team analysis. Use clawteam. - Don't pass
--team(the flag is--team-name). - Don't pass
--command hermestospawn(it's a positional arg at the end). That flag only works onlaunch. - Don't forget
--command hermesonlaunch— templates default to openclaw. - Don't assume templates will use Hermes by default. They don't. Always pass
--command hermes. - Don't clean up the team before reading final reports — BUT
inbox peekalone is unreliable; always ALSO capture tmux panes. - Don't rely on
clawteam inbox peekalone — tasks can be COMPLETED on the board while inbox messages are empty. Tmux scrollback capture is the source of truth.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
skill-creator-cc
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
prd-writing-guide
Write complete, unambiguous PRDs that development teams can implement without guesswork. Includes requirement discovery framework, structured documentation methodology, completeness checklists, and common pitfall avoidance. Use when: writing new PRDs, reviewing PRD drafts, validating requirement completeness, preparing for engineering handoff. Triggers: 'write PRD', '写PRD', '产品需求文档', '需求文档', '需求规格', '需求评审', '完善需求', 'create requirements doc', 'product requirements', 'feature spec', 'requirements document'. Anti-triggers: 'technical design doc', 'architecture design', 'implementation plan', 'API design', '架构设计', '技术方案', '实现方案', '接口设计'.