subagent-orchestration

name	subagent-orchestration
description	Orchestrate OpenClaw subagents effectively. Use when spawning subagents for background work, designing agent workflows, or debugging agent failures/timeouts. Covers delegation patterns, sandbox constraints, tool access, timeout strategy, and agent specialization. Triggers on: spawn, delegate, subagent, agent timeout, agent failure, orchestration, multi-agent.

Subagent Orchestration

Agent Types

Type	Tools	Use For
Worker	Default (no web)	File ops, script execution, git, code changes
Researcher	ollama_web_search, ollama_web_fetch	Web research, API lookups, live data
Council	Default (no web)	Analysis, review, decision-making with passed context

Sandbox Constraints

Default subagents (Worker/Council) cannot:

• Use ollama_web_fetch or ollama_web_search
• Run python3 -c "..." inline commands
• Access the main session's conversation history

They can:

• Read/write files
• Run scripts from .py files (python3 /path/to/script.py)
• Execute simple shell commands
• Use exec, read, write, edit tools

Spawning Patterns

Researcher (Web-Enabled)

sessions_spawn(
  toolsAllow: ["ollama_web_fetch", "ollama_web_search"],
  runtime: "subagent",
  mode: "run",
  lightContext: true,
  runTimeoutSeconds: 600,
  task: "Research X. Return: findings, sources, key metrics."
)

Worker (File/Code Ops)

sessions_spawn(
  runtime: "subagent",
  mode: "run",
  lightContext: true,
  runTimeoutSeconds: 300,
  task: "Run python3 /path/to/script.py. Report output."
)

Council (Multi-Model Deliberation)

# Spawn 3 parallel subagents with different models and perspectives
# See skills/council-of-llms/SKILL.md for full details
sessions_spawn(model: "ollama/kimi-k2.6:cloud", label: "Council-Strategos", ...)
sessions_spawn(model: "ollama/deepseek-v4-pro:cloud", label: "Council-Analyticos", ...)
sessions_spawn(model: "ollama/gemma4:31b-cloud", label: "Council-Creativos", ...)
# Then synthesize all 3 outputs into a unified verdict

Single-Model Council (Legacy — Avoid)

# WARNING: Single-model councils cause context overflow and produce shallow analysis
# Use multi-model pattern above instead
sessions_spawn(
  runtime: "subagent",
  mode: "run",
  lightContext: true,
  runTimeoutSeconds: 900,
  task: "Review this data and decide: [data pasted inline]. Return: verdict, conditions, risks."
)

Timeout Strategy

Task Type	Min Timeout	Recommended
Simple file ops	120s	180s
Research (web)	300s	600s
Council/review	300s	600s
Complex multi-step	600s	900s

Never rush agents. Quality > speed. If an agent takes >60s, give the user a brief status update.

Delegation Rules

1. Never run long scripts yourself. Write the script, hand the file path to a subagent.
2. Pre-fetch web content yourself for Worker/Council agents — they can't browse.
3. Use Researcher agents when you need web data that subagents can't access.
4. Write .py files first — don't pass inline Python to subagents.
5. Paste context inline — Council agents don't have your conversation history.

Common Failure Modes

Symptom	Cause	Fix
Agent times out	Can't access web tools	Use toolsAllow or pre-fetch content
Agent times out	Can't run inline Python	Write .py file, pass path
Agent times out	runTimeoutSeconds too low	Set runTimeoutSeconds: 900 in spawn call
Agent times out	Gateway under load (10s spawn timeout)	Kill zombie subagents, wait, retry
Agent returns nothing	Missing context	Paste data in task parameter
Agent stuck in loop	Vague task	Add explicit "return X" instruction
Gateway crashes	Context overflow on spawn	Use lightContext: true
Spawn fails (10s gateway timeout)	Gateway CPU overload	Kill stale subagents first, then retry

Anti-Patterns

• ❌ Doing research yourself when a Researcher agent could handle it
• ❌ Running python3 -c inline in task descriptions
• ❌ Setting 120s timeouts on research tasks
• ❌ Re-spawning an agent that's still running (>60s = be patient)
• ❌ Not passing context because "the agent should know"

Config (openclaw.json)

Set subagent defaults in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "subagents": {
        "runTimeoutSeconds": 900,
        "maxConcurrent": 5
      }
    }
  }
}

Also set in ~/.openclaw/council-config.json:

{
  "default_timeout": 900,
  "max_tokens": 8192
}