Agent Swarm

# Agent Swarm | OpenClaw Skill > IMPORTANT: OPENROUTER IS REQUIRED > > Agent Swarm only supports `openrouter/...` models and requires a configured OpenRouter API key in OpenClaw. > Without OpenRouter, subagent delegation and `sessions_spawn` routing will fail. **LLM routing and subagent delegation.** Routes each task to the right model, spawns subagents, and reduces API costs by using cheaper models for simple tasks. **Parallel tasks:** one message can spawn multiple subagents at once (e.g. "fix the bug and write a poem" → code + creative in parallel). **v1.7.8 — Current stable release.** COMPLEX tier, absolute paths for TUI delegation. Prompt-injection rejection (v1.7.6+), OPENCLAW_HOME fully optional. **Source:** [github.com/RuneweaverStudios/agent-swarm](https://github.com/RuneweaverStudios/agent-swarm). Agent Swarm | OpenClaw Skill routes your OpenClaw tasks to the best LLM for the job and delegates work to subagents. You save API costs (orchestrator stays on a cheap model; only the task runs on the matched model) and get better results—GLM 4.7 for code, Kimi k2.5 for creative, Grok Fast for research. **Security improvements in v1.7.0+:** - Removed gateway auth token/password exposure from router output - Gateway management functionality has been removed - use the separate [gateway-guard](https://clawhub.ai/skills/gateway-guard) skill if gateway auth management is needed - FACEPALM troubleshooting integration has been removed - use the separate [FACEPALM](https://github.com/RuneweaverStudios/FACEPALM) skill if troubleshooting is needed - **v1.7.3+**: Added comprehensive input validation, config patch validation, and security documentation - **v1.7.4+**: Clarified "saves tokens" means cost savings (not token storage), removed hard-coded paths, documented file access scope - **v1.7.5+**: Declared required environment variables and credentials in metadata, enhanced requirements documentation - **v1.7.6+**: Added prompt-injection rejection logic that actively blocks known injection patterns - **v1.7.8**: OPENCLAW_HOME made fully optional (defaults to ~/.openclaw), version bump ## Why Agent Swarm With a single model, OpenClaw can feel slow: you're forced to choose between quality and cost, and every prompt pays the same price. Agent Swarm removes that tradeoff. The orchestrator stays on a fast, cheap model; only the task at hand runs on the best model for the job. No wasted prompts—efficient routing, not one-size-fits-all. With OpenRouter, replies come back faster and the conversation feels more lively and natural. ## Requirements (critical) **Platform Configuration Required:** - **OpenRouter API key**: Must be configured in OpenClaw platform settings (not provided by this skill) - **OPENCLAW_HOME** (optional): Environment variable pointing to OpenClaw workspace root. If not set, defaults to `~/.openclaw` - **openclaw.json access**: The router reads `tools.exec.host` and `tools.exec.node` from `openclaw.json` (located at `$OPENCLAW_HOME/openclaw.json` or `~/.openclaw/openclaw.json`). Only these two fields are accessed; no gateway secrets or API keys are read. **Model Requirements:** - **OpenRouter is mandatory** — All model delegation uses OpenRouter (`openrouter/...` prefix). Configure OpenClaw with an OpenRouter API key so one auth profile covers every model. - If OpenRouter is not configured in OpenClaw, delegation will fail ## Security ### Input Validation The router validates and sanitizes all inputs to prevent injection attacks: - **Task strings**: Validated for length (max 10KB), null bytes, and suspicious patterns - **Config patches**: Only allows modifications to `tools.exec.host` and `tools.exec.node` (whitelist approach) - **Labels**: Validated for length and null bytes ### Safe Execution (Critical for Orchestrators) **When calling `router.py` from orchestrator code, always use `subprocess` with a list of arguments, never shell string interpolation:** ```python # ✅ SAFE: Use subprocess with list arguments import subprocess result = subprocess.run( ["python3", "/path/to/router.py", "spawn", "--json", user_message], capture_output=True, text=True ) # ❌ UNSAFE: Shell string interpolation (vulnerable to injection) import os os.system(f'python3 router.py spawn --json "{user_message}"') # DON'T DO THIS ``` The router uses Python's `argparse`, which safely handles arguments when passed as a list. Shell string interpolation is vulnerable to command injection if the user message contains shell metacharacters (`;`, `|`, `&`, `$()`, etc.). ### Config Patch Safety The `recommended_config_patch` only modifies safe fields: - `tools.exec.host` (must be 'sandbox' or 'node') - `tools.exec.node` (only when host is 'node') All config patches are validated before being returned. The orchestrator should validate patches again before applying them to `openclaw.json`. ### Prompt Injection Rejection (v1.7.6+) The router actively rejects task strings that contain known prompt-injection patterns: - System/instruction override attempts (`ignore previous instructions`, `you are now`, etc.) - Role impersonation (`[SYSTEM]`, `<|im_start|>system`, `### Instruction:`, etc.) - Delimiter injection and safety bypass language If a prompt-injection pattern is detected, the router raises a `ValueError` and refuses to route the task. This is a defense-in-depth measure alongside: 1. The orchestrator (validating task strings) 2. The sub-agent LLM (resisting prompt injection) 3. The OpenClaw platform (sanitizing `sessions_spawn` inputs) ### File Access Scope The router reads `openclaw.json` **only** to inspect `tools.exec.host` and `tools.exec.node` configuration. This is necessary to determine the execution environment for spawned sub-agents. **Important:** - The router **does not** read gateway secrets, API keys, or any other sensitive configuration - Only `tools.exec.host` and `tools.exec.node` are accessed - No data is written to `openclaw.json` except via validated config patches (whitelisted to `tools.exec.*` only) - The router does not persist, upload, or transmit any tokens or credentials - The phrase "saves tokens" in documentation refers to **API cost savings** (using cheaper models for simple tasks), not token storage or collection ## Default behavior **Session default / orchestrator:** Gemini 2.5 Flash (`openrouter/google/gemini-2.5-flash`) — fast, cheap, reliable at tool-calling. The router delegates tasks to tier-specific sub-agents (Kimi for creative, GLM 4.7 for code, etc.) via `sessions_spawn`. Simple tasks (check, status, list) down-route to Gemini 2.5 Flash. --- ## Orchestrator flow (task delegation) The **main agent (Gemini 2.5 Flash)** does not do user tasks itself. For every user **task** (code, research, write, build, etc.): 1. Run Agent Swarm router: `python scripts/router.py spawn --json "<user message>"` and parse the JSON. 2. Call **sessions_spawn** with the `task` and `model` from the router output (use the exact `model` value). 3. Forward the sub-agent's result to the user. **Example:** ``` router: {"task":"write a poem","model":"openrouter/moonshotai/kimi-k2.5","sessionTarget":"isolated"} → sessions_spawn(task="write a poem", model="openrouter/moonshotai/kimi-k2.5", sessionTarget="isolated") → Forward Kimi k2.5's poem to user. Say "Using: Kimi k2.5". ``` **Exception:** Meta-questions ("what model are you?") you answer yourself. ### Parallel tasks For one message with multiple tasks, use **`spawn --json --multi "<message>"`**. The router splits on *and*, *then*, *;*, and *also*, classifies each part, and returns `{"parallel": true, "spawns": [{task, model, sessionTarget}, ...], "count": N}`. The orchestrator can then call `sessions_spawn` for each entry and run them in parallel; use subagent-tracker to see progress. **Example:** `spawn --json --multi "fix the login bug and write a short poem"` → two spawns (e.g. GLM 4.7 for code, Kimi for poem). --- ## Quick start ```bash npm install -g clawhub