Agent Swarm | OpenClaw Skill

Description

IMPORTANT: OpenRouter is required. Routes tasks to the right model and always delegates work through sessions_spawn.

Before installing

• OPENCLAW_HOME: Not required. The skill uses OPENCLAW_HOME only if set; otherwise it defaults to ~/.openclaw. This is consistent in both metadata (_meta.json: listed in optionalEnv, not in env) and behavior.
• openclaw.json read access: The skill reads the local file openclaw.json (at $OPENCLAW_HOME/openclaw.json or ~/.openclaw/openclaw.json). Only the fields tools.exec.host and tools.exec.node are used; no gateway secrets or API keys are read. Verify you are comfortable granting read access to that file before installing.

Examples

Single task

Router output: {"task":"write a poem","model":"openrouter/moonshotai/kimi-k2.5","sessionTarget":"isolated"}

Then call: sessions_spawn(task="write a poem", model="openrouter/moonshotai/kimi-k2.5", sessionTarget="isolated")

Parallel tasks

python3 workspace/skills/agent-swarm/scripts/router.py spawn --json --multi "fix bug and write poem"

This returns multiple spawn configs. Start one sub-agent per config.

Commands

Manual/CLI use only. The examples below pass the task as a single argument; for programmatic use with untrusted user input, always invoke the router via subprocess.run(..., [..., user_message], ...) with a list of arguments (see Security). Do not build a shell command string from user input.

python scripts/router.py default
python scripts/router.py classify "fix lint errors"
python scripts/router.py spawn --json "write a poem"
python scripts/router.py spawn --json --multi "fix bug and write poem"
python scripts/router.py models

What this skill does

Agent Swarm is a traffic cop for AI models. It picks the best model for each task, then starts a sub-agent to do the work.

IMPORTANT: OpenRouter is required

Required Platform Configuration:

• 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 IDs must use openrouter/... prefix
• If OpenRouter is not configured in OpenClaw, delegation will fail

Why this helps

• Faster replies (cheap orchestrator, smart sub-agent routing)
• Better quality (code tasks go to code models, writing tasks go to writing models)
• Lower cost (you do not run every task on the most expensive model)

Core rule (non-negotiable)

For user tasks, the orchestrator must delegate. It must NOT answer the task itself.

Use this flow every time:

• Run router. From orchestrator code, use subprocess with a list of arguments (never shell interpolation with user input):

import subprocess
   result = subprocess.run(
       ["python3", "/path/to/workspace/skills/agent-swarm/scripts/router.py", "spawn", "--json", user_message],
       capture_output=True,
       text=True
   )
   data = json.loads(result.stdout) if result.returncode == 0 else {}

• If needs_config_patch is true: stop and report that patch to the user.
• Otherwise call:

• Wait for sessions_spawn result.
• Return the sub-agent result to the user.

Config basics

Edit config.json in the skill root (parent of scripts/) to change routing.

What you can change

All task-specific tiers (change the model for each)

Simple config examples

Orchestrator only (keep defaults for tiers):

{
  "default_model": "openrouter/google/gemini-2.5-flash"
}

Change one tier (e.g. CODE to MiniMax):

"routing_rules": {
  "CODE": {
    "primary": "openrouter/minimax/minimax-m2.5",
    "fallback": ["openrouter/qwen/qwen3-coder-flash"]
  }
}

Change multiple tiers (primaries only):

"routing_rules": {
  "CREATIVE": { "primary": "openrouter/moonshotai/kimi-k2.5", "fallback": [] },
  "CODE":     { "primary": "openrouter/z-ai/glm-4.7-flash", "fallback": ["openrouter/minimax/minimax-m2.5"] },
  "RESEARCH": { "primary": "openrouter/x-ai/grok-4.1-fast", "fallback": [] }
}

Security

Input Validation

The router validates and sanitizes all inputs to prevent injection attacks:

• Task strings: Validated for length (max 10KB), null bytes; rejects prompt-injection patterns (script tags, javascript: protocol, event-handler attributes). Invalid tasks raise ValueError with a clear message.
• 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: When calling router.py from orchestrator code, always use subprocess with a list of arguments, never shell string interpolation:

# ✅ 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.

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')

Prompt Injection Mitigation

The router rejects task strings that contain prompt-injection patterns (e.g.