# [๐Ÿš€่ง‚็œ‹ๆˆ‘็š„ๅ“”ๅ“ฉๅ“”ๅ“ฉ่ง†้ข‘](https://space.bilibili.com/3493277319825652)

English | ็ฎ€ไฝ“ไธญๆ–‡ | ็น้ซ”ไธญๆ–‡ | ๆ—ฅๆœฌ่ชž | ํ•œ๊ตญ์–ด | Franรงais | Espaรฑol | Deutsch | Italiano | ะ ัƒััะบะธะน | Portuguรชs (Brasil)

๐ŸฆžClawTeam-OpenClaw

Multi-agent swarm coordination for CLI coding agents โ€” OpenClaw as default

Upstream Quick Start License

Python Agents Transport Version

> **Fork of [HKUDS/ClawTeam](https://github.com/HKUDS/ClawTeam)** with deep OpenClaw integration: default `openclaw` agent, per-agent session isolation, exec approval auto-config, and production-hardened spawn backends. All upstream fixes are synced. You set the goal. The agent swarm handles the rest โ€” spawning workers, splitting tasks, coordinating, and merging results. Works with [OpenClaw](https://openclaw.ai) (default), [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent. ## Platform Support - Linux and macOS keep the original `tmux`-first workflow. - Windows 10/11 is supported with an automatic fallback to the `subprocess` backend. - Task locking, process liveness checks, and signal registration are routed through a shared compatibility layer so unsupported Unix-only behavior degrades safely on Windows. - `board attach` still requires `tmux`, so on Windows prefer `clawteam board serve` for live monitoring. - If you want the original tmux workflow on Windows, run ClawTeam inside WSL. --- ## Why ClawTeam? Current AI agents are powerful but work in **isolation**. ClawTeam lets agents self-organize into teams โ€” splitting work, communicating, and converging on results without human micromanagement. | | ClawTeam | Other multi-agent frameworks | |---|---------|----------------------------| | **Who uses it** | The AI agents themselves | Humans writing orchestration code | | **Setup** | `pip install` + one prompt | Docker, cloud APIs, YAML configs | | **Infrastructure** | Filesystem + tmux | Redis, message queues, databases | | **Agent support** | Any CLI agent | Framework-specific only | | **Isolation** | Git worktrees (real branches) | Containers or virtual envs | --- ## How It Works
### Agents Spawn Agents The leader calls `clawteam spawn` to create workers. Each gets its own **git worktree**, **spawn backend session**, and **identity**. ```bash clawteam spawn --team my-team \ --agent-name worker1 \ --task "Implement auth module" ``` ### Agents Talk to Agents Workers check inboxes, update tasks, and report results โ€” all through CLI commands **auto-injected** into their prompt. ```bash clawteam task list my-team --owner me clawteam inbox send my-team leader \ "Auth done. All tests passing." ``` ### You Just Watch Monitor the swarm from a tiled tmux view or Web UI. The leader handles coordination. ```bash clawteam board serve --port 8080 # Or, on Linux/macOS/WSL with tmux: clawteam board attach my-team ```
--- ## Quick Start ### Option 1: Let the Agent Drive (Recommended) Install ClawTeam, then prompt your agent: ``` "Build a web app. Use clawteam to split the work across multiple agents." ``` The agent auto-creates a team, spawns workers, assigns tasks, and coordinates โ€” all via `clawteam` CLI. ### Option 2: Drive It Manually ```bash # Create a team clawteam team spawn-team my-team -d "Build the auth module" -n leader # Spawn workers โ€” each gets a git worktree plus its own backend session clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2 flow" clawteam spawn --team my-team --agent-name bob --task "Write unit tests for auth" # Watch them work clawteam board serve --port 8080 clawteam board attach my-team # Linux/macOS/WSL with tmux ``` ### Supported Agents | Agent | Spawn Command | Status | |-------|--------------|--------| | [OpenClaw](https://openclaw.ai) | `clawteam spawn --team ...` | **Default** | | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn claude --team ...` | Full support | | [Codex](https://openai.com/codex) | `clawteam spawn codex --team ...` | Full support | | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn nanobot --team ...` | Full support | | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | `clawteam spawn hermes --team ...` | Full support (tmux + subprocess) | | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | Experimental | | Custom scripts | `clawteam spawn subprocess python --team ...` | Full support | --- ## Install ### Step 1: Prerequisites ClawTeam requires **Python 3.10+** and at least one CLI coding agent (OpenClaw, Claude Code, Codex, etc.). On Linux/macOS, the full visual workflow also requires **tmux**. On Windows, `tmux` is optional because ClawTeam defaults to the `subprocess` backend. **Check what you already have:** ```bash python --version # Need 3.10+ tmux -V # Linux/macOS/WSL only openclaw --version # Or: claude --version / codex --version ``` **Install missing prerequisites:** | Tool | Windows | macOS | Ubuntu/Debian | |------|---------|-------|---------------| | Python 3.10+ | Install from [python.org](https://www.python.org/downloads/windows/) | `brew install python@3.12` | `sudo apt update && sudo apt install python3 python3-pip` | | tmux | Optional | `brew install tmux` | `sudo apt install tmux` | | OpenClaw | `pip install openclaw` | `pip install openclaw` | `pip install openclaw` | > If using Claude Code or Codex instead of OpenClaw, install those per their own docs. OpenClaw is the default but not strictly required. On Windows, after installation you can verify the backend choice with: ```powershell clawteam config get default_backend ``` ### Windows Native Setup Use this path for PowerShell or Windows Terminal: ```powershell py -3 -m pip install -e . clawteam config get default_backend # should print subprocess clawteam spawn --team demo --agent-name worker1 --task "Do work" clawteam board serve --port 8080 ``` If you want the full tmux experience, install and run ClawTeam inside WSL instead. ### Step 2: Install ClawTeam > **โš ๏ธ Do NOT run `pip install clawteam` or `npm install -g clawteam` directly:** > - `pip install clawteam` installs the upstream PyPI version, which defaults to `claude` and lacks OpenClaw adaptations. > - `npm install -g clawteam` installs an unrelated name-squatting package (by `a9logic`). If `clawteam --version` shows "Coming Soon", you have the wrong one โ€” run `npm uninstall -g clawteam`. > > **Use the three commands below โ€” the `pip install -e .` step is required. It installs from the local repo, not from PyPI.** ```bash git clone https://github.com/win4r/ClawTeam-OpenClaw.git cd ClawTeam-OpenClaw pip install -e . # โ† Required! Installs from local repo, NOT the same as pip install clawteam ``` Optional โ€” P2P transport (ZeroMQ): ```bash python -m pip install -e ".[p2p]" ``` ### Step 3: Ensure `clawteam` is on PATH Spawned agents run in fresh shells that may not have pip's bin directory in PATH. A symlink in `~/bin` ensures `clawteam` is always reachable: ```bash mkdir -p ~/bin ln -sf "$(which clawteam)" ~/bin/clawteam ``` If `which clawteam` returns nothing, find the binary manually: ```bash # Common locations: # ~/.local/bin/clawteam # /opt/homebrew/bin/clawteam # /usr/local/bin/clawteam # /Library/Frameworks/Python.framework/Versions/3.*/bin/clawteam find / -name clawteam -type f 2>/dev/null | head -5 ``` Then ensure `~/bin` is in your PATH โ€” add this to `~/.zshrc` or `~/.bashrc` if it isn't: ```bash export PATH="$HOME/bin:$PATH" ``` On native Windows, you usually do not need the `~/bin` symlink step. Instead, make sure the Python `Scripts` directory containing `clawteam.exe` is on `PATH`, or activate the virtual environment where you installed ClawTeam before spawning agents. ### Step 4: Install the OpenClaw skill (OpenClaw users only) The skill file teaches OpenClaw agents how to use ClawTeam through natural language. Skip this step if you're not using OpenClaw. ```bash mkdir -p ~/.openclaw/workspace/skills/clawteam cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md ``` ### Step 5: Configure exec approvals (OpenClaw users only) Spawned OpenClaw agents need permission to run `clawteam` commands. Without this, agents will block on interactive permission prompts. ```bash # Ensure security mode is "allowlist" (not "full") python3 -c " import json, pathlib p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json' if p.exists(): d = json.loads(p.read_text()) d.setdefault('defaults', {})['security'] = 'allowlist' p.write_text(json.dumps(d, indent=2)) print('exec-approvals.json updated: security = allowlist') else: print('exec-approvals.json not found โ€” run openclaw once first, then re-run this step') " # Add clawteam to the allowlist (use the absolute path โ€” OpenClaw 4.2+ requires it) openclaw approvals allowlist add --agent "*" "$(which clawteam)" ``` > If `openclaw approvals` fails, the OpenClaw gateway may not be running. Start it first, then retry. ### Step 5b: Install the Hermes skill (Hermes Agent users only) The skill file teaches Hermes Agent how to use ClawTeam through natural language -- including when to route to clawteam (vs `delegate_task`), correct spawn flags, and timing expectations. Skip this step if you're not using Hermes. ```bash mkdir -p ~/.hermes/skills/openclaw-imports/clawteam cp skills/hermes/SKILL.md ~/.hermes/skills/openclaw-imports/clawteam/SKILL.md ``` > Verify with `hermes skills list | grep clawteam`. The skill should show up under `openclaw-imports` (Hermes auto-routes skills from that directory). **Key things the skill teaches Hermes:** - Route multi-agent/swarm/team queries to clawteam (not `delegate_task`) - Use `--team-name` (not `--team`), `-g`/`--goal`, `--force` on `launch` - Always pass `--command hermes` on `launch` -- templates default to `openclaw` - On `spawn`, pass `hermes` as a trailing positional arg (not `--command hermes`) - Wait `sleep 60` after launch for worker boot, then poll the board every 30s - Never peek inboxes within the first 60s (they'll be empty) - Read inboxes and produce a consolidated report before `clawteam team cleanup` Spawned Hermes workers automatically inherit MCP servers configured in `~/.hermes/config.yaml`, so any knowledge brain or tool setup is available to every worker. ### Step 6: Verify ```bash clawteam --version # Should print version clawteam config health # Should show all green ``` If using OpenClaw, also verify the skill is loaded: ```bash openclaw skills list | grep clawteam ``` ### Automated installer Steps 2โ€“6 above are also available as a single script: ```bash git clone https://github.com/win4r/ClawTeam-OpenClaw.git cd ClawTeam-OpenClaw bash scripts/install-openclaw.sh ``` This script is intended for Linux, macOS, and WSL shells, not native PowerShell. ### Troubleshooting | Problem | Cause | Fix | |---------|-------|-----| | `clawteam: command not found` | pip bin dir not in PATH | Run Step 3 and ensure either `~/bin` or your Python `Scripts` directory is on PATH | | Spawned agents can't find `clawteam` | Agents run in fresh shells without pip PATH | Verify `clawteam` is on PATH in new shells; on Windows check the Python `Scripts` directory or active virtualenv | | `openclaw approvals` fails | Gateway not running | Start `openclaw gateway` first, then retry Step 5 | | `exec-approvals.json not found` | OpenClaw never ran | Run `openclaw` once to generate config, then retry Step 5 | | Agents block on permission prompts | Exec approvals security is "full" | Run Step 5 to switch to "allowlist" | | `pip install -e .` fails | Missing build deps | Run `pip install hatchling` first | | `clawteam --version` shows "Coming Soon" | Installed the npm name-squatting package (`a9logic`, unrelated to this project) | `npm uninstall -g clawteam`, then reinstall per Step 2 | --- ## Use Cases ### 1. Autonomous ML Research โ€” 8 Agents x 8 GPUs Based on [@karpathy/autoresearch](https://github.com/karpathy/autoresearch). One prompt launches 8 research agents across H100s that design 2000+ experiments autonomously. ``` Human: "Use 8 GPUs to optimize train.py. Read program.md for instructions." Leader agent: โ”œโ”€โ”€ Spawns 8 agents, each assigned a research direction (depth, width, LR, batch size...) โ”œโ”€โ”€ Each agent gets its own git worktree for isolated experiments โ”œโ”€โ”€ Every 30 min: checks results, cross-pollinates best configs to new agents โ”œโ”€โ”€ Reassigns GPUs as agents finish โ€” fresh agents start from best known config โ””โ”€โ”€ Result: val_bpb 1.044 โ†’ 0.977 (6.4% improvement) across 2430 experiments in ~30 GPU-hours ``` Full results: [novix-science/autoresearch](https://github.com/novix-science/autoresearch) ### 2. Agentic Software Engineering ``` Human: "Build a full-stack todo app with auth, database, and React frontend." Leader agent: โ”œโ”€โ”€ Creates tasks with dependency chains (API schema โ†’ auth + DB โ†’ frontend โ†’ tests) โ”œโ”€โ”€ Spawns 5 agents (architect, 2 backend, frontend, tester) in separate worktrees โ”œโ”€โ”€ Dependencies auto-resolve: architect completes โ†’ backend unblocks โ†’ tester unblocks โ”œโ”€โ”€ Agents coordinate via inbox: "Here's the OpenAPI spec", "Auth endpoints ready" โ””โ”€โ”€ Leader merges all worktrees into main when complete ``` ### 3. AI Hedge Fund โ€” Template Launch A TOML template spawns a complete 7-agent investment team with one command: ```bash clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026" ``` Seven agents total: 5 analysts (value, growth, technical, fundamentals, sentiment) work in parallel, a risk manager synthesizes all signals, and a portfolio manager makes the final decision. Templates are TOML files โ€” **create your own** for any domain. --- ## Features
### Agent Self-Organization - Leader spawns and manages workers - Auto-injected coordination prompt โ€” zero manual setup - Workers self-report status and idle state - Any CLI agent can participate ### Workspace Isolation - Each agent gets its own **git worktree** - No merge conflicts between parallel agents - Checkpoint, merge, and cleanup commands - Branch naming: `clawteam/{team}/{agent}` ### Task Tracking with Dependencies - Shared kanban: `pending` โ†’ `in_progress` โ†’ `completed` / `blocked` - `--blocked-by` chains with auto-unblock on completion - `task wait` blocks until all tasks complete ### Inter-Agent Messaging - Point-to-point inboxes (send, receive, peek) - Broadcast to all team members - File-based (default) or ZeroMQ P2P transport ### Monitoring & Dashboards - `board show` โ€” terminal kanban - `board live` โ€” auto-refreshing dashboard - `board attach` โ€” tiled tmux view of all agents (Linux/macOS/WSL) - `board serve` โ€” Web UI with real-time updates ### Team Templates - TOML files define team archetypes (roles, tasks, prompts) - One command: `clawteam launch