Subagent Orchestration#

Agent Types#

TypeToolsUse ForWorkerDefault (no web)File ops, script execution, git, code changesResearcherollama_web_search, ollama_web_fetchWeb research, API lookups, live dataCouncilDefault (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)#

text

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

text

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

Council (Multi-Model Deliberation)#

text

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

text

# 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 TypeMin TimeoutRecommendedSimple file ops120s180sResearch (web)300s600sCouncil/review300s600sComplex multi-step600s900s

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#

SymptomCauseFixAgent times outCan't access web toolsUse toolsAllow or pre-fetch contentAgent times outCan't run inline PythonWrite .py file, pass pathAgent times outrunTimeoutSeconds too lowSet runTimeoutSeconds: 900 in spawn callAgent times outGateway under load (10s spawn timeout)Kill zombie subagents, wait, retryAgent returns nothingMissing contextPaste data in task parameterAgent stuck in loopVague taskAdd explicit "return X" instructionGateway crashesContext overflow on spawnUse lightContext: trueSpawn fails (10s gateway timeout)Gateway CPU overloadKill 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:

json

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

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

json

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