Subagent Orchestration

Orchestrate OpenClaw subagents effectively. Use when spawning subagents for background work, designing agent workflows, or debugging agent failures/timeouts....

Security Scan

The skill is an instruction-only guide for spawning and managing subagents; its requests and instructions are coherent with that purpose, though it explicitly advises reading/writing files and running scripts so users should be aware of the execution risk inherent to subagents.

Purpose & Capability

Name/description align with the content: the skill documents spawn patterns, sandbox constraints, and config for subagents. All referenced capabilities (sessions_spawn, toolsAllow, web tools, file operations) are appropriate for subagent orchestration.

Instruction Scope

SKILL.md tells agents to read/write files, execute shell commands and run .py scripts, and to modify user config files under ~/.openclaw. These actions are consistent with orchestration, but they do give subagents the ability to run arbitrary code and touch user files—so this is a necessary capability for the stated purpose, but high-impact.

Install Mechanism

Instruction-only skill with no install steps or downloaded code. No install-related risks were found.

Credentials

The skill requests no environment variables or credentials. It references enabling web tools (ollama_web_fetch/search) via toolsAllow, which is appropriate and does not demand unrelated secrets.

Persistence & Privilege

The skill does not request always:true and does not autonomously persist or modify other skills. It does instruct editing per-user config files (~/.openclaw/*) to set defaults; that is coherent but means it can change user agent behavior via config edits.

Assessment

This skill is a documentation/instruction package (no code or installs). It coherently instructs agents to spawn subagents, enable web tools when appropriate, and to read/write files and run .py scripts. Before using it: (1) understand that following these instructions will cause subagents to execute code and manipulate files—avoid giving file paths that contain secrets or sensitive data; (2) only enable web tools (toolsAllow) when you trust the task and sources; (3) back up or review ~/.openclaw config changes before applying them; (4) prefer running risky or untrusted tasks in isolated environments. The skill itself is not requesting credentials or installing code, but it guides behaviors that can execute arbitrary user-side code — treat that as the primary operational risk.

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 (Analysis)

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
}