# OpenClaw Sub-Agents Sub-agents are background agent instances spawned from a main [[OpenClaw]] agent. They run in isolated sessions identified as `agent:<id>:subagent:<uuid>`, execute non-blocking, and announce results back to the requester's channel when done. The point is parallelism and delegation: the main agent stays responsive while heavy or long-running work runs in the background. ## Spawning Two surfaces: - **Tool**: `sessions_spawn` (the agent's own programmatic interface) - **Slash command**: `/subagents spawn <agentId> <task>` Key parameters: - `task` ; the instruction - `label` ; human-readable name in listings - `model` / `thinking` overrides ; cheaper or deeper than the parent - `timeout` ; auto-kill after the given duration - `thread` binding (Discord) ; reply destination - `sandbox.mode` ; sandbox vs host execution ## Orchestrator Pattern With `maxSpawnDepth: 2` the system supports a two-tier hierarchy: - **Depth-0**: the main agent (talks to the user) - **Depth-1 orchestrator**: spawned by main, receives session-management tools, decomposes work, spawns its own children - **Depth-2 leaf workers**: do the actual focused work, no further spawning Result flow propagates up: depth-2 → depth-1 → main → user. The orchestrator can iterate, retry failed children, and synthesize before reporting back. ## Concurrency & Limits - `maxConcurrent`: default **8** simultaneous sub-agents per gateway - `maxChildrenPerAgent`: default **5** direct children per parent - Max nesting depth: **5** (rarely useful past 2) - Auto-archive after **60 minutes** idle (configurable) ## Cost Optimization Configure cheaper models for sub-agents via `agents.defaults.subagents.model`. A common pattern: Opus for the user-facing main agent (judgment, prioritization), Haiku/Sonnet for fan-out workers (extraction, classification, transformation). ## Operations ```bash /subagents list # all running children /subagents log <uuid> # tail output /subagents info <uuid> # config, state /subagents send <uuid> <msg> # message a running child /subagents steer <uuid> # guide without replacing context /subagents kill <uuid> # terminate ``` ## Tool Denylists A sub-agent can be configured with a tool denylist so it inherits only a safe subset of capabilities ; a research worker doesn't need exec, a script-running worker doesn't need browser, etc. Combined with sandboxed sessions, this is how OpenClaw bounds blast radius for delegated work. ## References - Sub-Agents: https://docs.openclaw.ai/tools/subagents ## Related - [[OpenClaw]] - [[OpenClaw Gateway]] - [[OpenClaw Multi-Agent Routing]] - [[OpenClaw ACP Agents]] - [[AI Subagents]]