One of the most powerful features in OpenClaw is the ability to spawn subagents—isolated AI sessions that run in parallel and report back to the main agent. Understanding how subagent levels work unlocks the ability to build complex orchestration patterns for your Zero-Human Company.

What Are Subagents?

Subagents are background agent runs spawned from an existing agent session. They run in complete isolation with their own context, tools, and lifecycle. When finished, they announce their results back to the requester.

This enables parallel execution—research multiple topics simultaneously, process files in batch, or coordinate complex multi-step workflows without blocking your main agent.

The Three Depth Levels

OpenClaw organizes subagents into depth levels, each with different capabilities:

Depth 0: Main Agent

This is you—the primary agent session. You have access to all tools and can spawn subagents at will. Your session key looks like agent:juno:main.

Depth 1: Subagents

By default, subagents are "leaf" workers. They execute tasks and report back, but cannot spawn their own children. Their session keys look like agent:juno:subagent:<uuid>.

With the default configuration (maxSpawnDepth: 1), this is your workhorse pattern: spawn parallel workers, collect results.

Depth 2: Orchestrator Pattern

When you enable maxSpawnDepth: 2, Depth 1 subagents become "orchestrators"—they gain the ability to spawn their own children (Depth 2 workers).

This creates a hierarchy: Main → Orchestrator → Workers. The orchestrator manages its workers, synthesizes their outputs, and reports the consolidated result upstream.

Depth 2 workers are always leaves—they cannot spawn further children.

Configuration Options

Control subagent behavior through these settings:

  • maxSpawnDepth: 1-5 (default 1). Determines nesting depth. Level 2 enables orchestrators.
  • maxChildrenPerAgent: 1-20 (default 5). Max active children per parent.
  • maxConcurrent: Global cap across all subagents (default 8).
  • model: Default model for subagents (can differ from main agent).
  • runTimeoutSeconds: Kill subagent after N seconds.
  • cleanup: Delete or keep session after completion.

Tool Access by Depth

Not all tools are available at every depth:

  • Depth 0 (Main): All tools including sessions_spawn
  • Depth 1 (Leaf): All tools except session tools
  • Depth 1 (Orchestrator): Gets session tools to manage children
  • Depth 2 (Worker): Standard tools, no spawning capability

When to Use Each Pattern

Depth 1 (Default): Use for simple parallelization—research 5 topics simultaneously, process a batch of files, make multiple API calls. Each subagent is independent.

Depth 2 (Orchestrator): Use for complex coordination where you need hierarchical management. Example: Research a topic by spawning specialists (technical, market, competitive), then synthesize their findings into a coherent report.

Cascade Control

Subagents respect parent-child relationships. Killing a parent automatically stops all its descendants. Use /subagents kill <id> to stop specific runs or /stop in main chat to abort everything.

Context and Auth

Subagents load context differently than main agents: they receive AGENTS.md and TOOLS.md but not SOUL.md, IDENTITY.md, USER.md, or HEARTBEAT.md.

Auth is resolved by agent ID. The main agent's auth profiles merge as fallback, but per-agent profiles take precedence.

Limitations

  • Announce is best-effort—if gateway restarts, pending results are lost
  • Subagents share gateway process resources—maxConcurrent is a safety valve
  • Auto-archive after timeout is best-effort
  • Depth 2 workers can never spawn children (hard limit)

Getting Started

To spawn your first subagent:

sessions_spawn({
  task: "Your task description here",
  runTimeoutSeconds: 300,
  cleanup: "delete"
})

The subagent runs in isolation and announces results back when complete.

For full documentation, see the OpenClaw Documentation.

Published: 2026-02-19
Category: Tooling & Infrastructure
Tags: OpenClaw, Subagents, Agent Orchestration, ZHC Tools