OpenClaw Sub-Agents: How to Run Parallel AI Tasks at Scale
Sub-agents let your main AI spawn multiple specialized workers that run in parallel. Research 10 competitors while writing code. Deploy and monitor simultaneously. Here's exactly how it works.
What Are Sub-Agents?
When you message OpenClaw, you're talking to the main agent. That agent can think, use tools, browse the web, write files — but it does everything sequentially. One thing at a time.
Sub-agents break that limitation. Your main agent can spawn child agents that run in their own isolated contexts, with their own tool access, their own instructions, and their own model choice. They run concurrently — not waiting for each other.
Think of it like hiring a team: you're the project manager, sub-agents are specialists you delegate to.
The Core Benefit
Tasks that would take 30 minutes sequentially can complete in 5 minutes in parallel. Research, writing, code review, and deployment can all happen simultaneously through sub-agents.
The sessions_spawn Tool
The primary way to create sub-agents is through the sessions_spawn tool. Here's what a sub-agent spawn looks like under the hood:
{
"tool": "sessions_spawn",
"params": {
"task": "Research the top 5 competitors of Linear.app and write a 500-word comparison",
"model": "anthropic/claude-haiku-4",
"mode": "run",
"streamTo": "parent",
"context": {
"focusArea": "pricing and features",
"outputFormat": "markdown table"
}
}
}taskThe complete instruction set for the sub-agent. Be specific. It won't ask clarifying questions.
modelWhich AI model to use. You can use a cheaper model for sub-agents.
modeEither run (fire-and-forget) or session (persistent, interactive).
streamToWhere to send output. parent sends results back to the spawning agent.
contextAdditional context injected into the sub-agent's system prompt.
Run Mode vs Session Mode
This is probably the most important distinction to understand:
| Feature | Run Mode | Session Mode |
|---|---|---|
| Lifespan | Completes task and dies | Stays alive indefinitely |
| Memory | No memory between runs | Maintains context across messages |
| Cost | Pay only for the task | Ongoing heartbeat costs |
| Best For | One-off parallel tasks | Long-running monitors, watchers |
| Interaction | No back-and-forth | Can receive follow-up instructions |
Run Mode Example
"Spawn 3 run-mode sub-agents to simultaneously: 1. Fetch and summarize today's HackerNews top 10 2. Check our GitHub repo for any new PRs opened today 3. Look up the current ETH price and 7-day trend Merge results and give me a morning briefing."
Session Mode Example
{
"mode": "session",
"task": "Monitor our deployment pipeline. Every 5 minutes, check if any GitHub Actions jobs are failing. If you find failures, immediately notify the parent agent.",
"model": "google/gemini-flash-lite",
"heartbeatIntervalMs": 300000
}Session Mode Cost Warning
Session-mode sub-agents keep consuming tokens as long as they're alive. Always use the cheapest model (Gemini Flash Lite or Haiku) for session-mode workers.
Streaming Results to Parent
With streamTo: "parent", sub-agents can push intermediate results back in real time — useful for long research tasks where you want partial results as they arrive.
{
"streamTo": "parent",
"streamIntervalMs": 5000,
"streamOnComplete": true
}Monitoring Sub-Agents
# Ask your main agent: "List all active sub-agents and their current status" # Or check the gateway UI at: http://localhost:18789/sessions
Gateway Restart = Fresh Slate
If sub-agents go rogue or you're seeing unexpected behavior, openclaw gateway restart kills all sessions and starts clean.
Real Use Cases
1Parallel Competitive Research
25-30 min → 3-4 min"Research these 10 SaaS tools in parallel — spawn a sub-agent for each one. For each: pricing, key features, target audience, Trustpilot rating. Tools: Linear, Notion, Asana, Monday, ClickUp, Basecamp, Jira, Trello, Height, Todoist. Compile results into a comparison table when all agents complete."
2Multi-Source Morning Briefing
All sources in ~45 secondsSpawn simultaneously: - Agent 1: Fetch crypto prices (BTC, ETH, SOL) + 24h changes - Agent 2: Pull top 5 HackerNews stories - Agent 3: Check inbox for flagged/VIP emails - Agent 4: Review calendar for today's events - Agent 5: Check GitHub notifications Main agent: Synthesize into 200-word briefing, send to Telegram
3Code Review at Scale
8 files reviewed in parallel"PR #247 has 8 changed files. Spawn 8 sub-agents, assign one file each. Each agent should: check for bugs, security issues, performance problems. After all complete: synthesize into a single PR review comment."
Cost Implications
The Golden Rule of Sub-Agent Costs
Match the model to the task complexity. Use Haiku or Gemini Flash for simple research and data fetching. Reserve Sonnet for reasoning-heavy tasks. Never use Opus in sub-agents unless absolutely required.
Rough cost for a 10-agent parallel research task:
| Model | Cost per run |
|---|---|
| Claude Opus | ~$2.50 – $4.00 |
| Claude Sonnet | ~$0.30 – $0.60 |
| Claude Haiku | ~$0.03 – $0.08 |
| Gemini Flash Lite | ~$0.005 – $0.02 |
Best Practices
Write Clear, Complete Task Instructions
Sub-agents don't ask clarifying questions. If your task description is ambiguous, the sub-agent will make assumptions. Front-load all context. Bad: "Research competitors". Good: "Research Linear.app's top 5 competitors. For each: list pricing tiers, key features vs Linear, notable reviews. Output as a markdown table."
Limit Concurrent Agents
Don't spawn 50 agents simultaneously. Besides cost, you'll hit API rate limits. A good rule of thumb: max 5-10 concurrent agents. For large batches, process in waves.
Always Set a Timeout
Sub-agents can hang if they hit an error or infinite loop. Set reasonable timeouts: { "timeoutMs": 120000, "onTimeout": "report_partial_results" }
Use the Right Model for Each Role
Orchestrator (main): Sonnet. Research workers: Haiku or Gemini Flash. Code workers: Sonnet. Long-running monitors: Gemini Flash Lite.
Keep Costs Under Control
Now that you understand sub-agents, learn how to run them without bleeding your API budget.
Cost Optimization Guide