Subagent Spawning

Type: OpenClaw tool for creating parallel worker agents

Definition

The subagents tool is the mechanism for creating independent worker agents that run in parallel with the main session. It supports four operations: spawn creates a labeled sub-agent with a task description, list shows all running sub-agents, steer sends additional instructions to a running agent, and kill stops one. Sub-agents run in their own isolated sessions with their own context windows, enabling concurrent work that a single sequential agent cannot achieve.

How It Works

Spawn creates a new sub-agent session labeled agent:main:subagent:{id}. You provide a task description — the more specific and bounded, the better. Vague instructions cause agents to go off-script; precise scope boundaries keep them focused. The spawned agent runs independently, doing its work and returning results when complete.

List shows all currently running sub-agents — their session labels, current state, and what they're working on. Use this to monitor progress and check if any agents are stuck.

Steer sends additional instructions to a running sub-agent without killing and respawning it. This is useful for course-correction mid-task: if a research agent finds unexpected information and needs direction, you steer it rather than restart.

Kill stops a sub-agent. Use this for runaway agents, ones that have gone off-script, or when priorities have changed and the work is no longer needed.

The power of spawning is parallel execution. Three research agents simultaneously investigating three competitors complete in 5 minutes instead of 15 sequentially. Each runs in its own isolated context window, so there's no interference between them. The main agent (Router) spawns them, monitors via list, steers if needed, and kills if necessary — but doesn't do any of the research work itself.

Sub-agents can exhaust their context on long tasks, causing repetitive responses, forgotten instructions, or incoherent outputs. The fix is breaking tasks into smaller chunks rather than asking for "everything about X" in one shot.

Key Properties

  • Four operations — spawn (create), list (monitor), steer (redirect), kill (stop)
  • Session labeling — sub-agents labeled agent:main:subagent:{id} for identification
  • Parallel execution — multiple sub-agents run concurrently, not sequentially
  • Isolated context windows — each sub-agent has its own memory; no cross-contamination
  • Steer without restart — steer sends additional instructions to a running agent mid-task
  • Task chunking — long tasks should be broken into smaller pieces to avoid context exhaustion
  • kelly-router — the Router uses subagent spawning for parallel task execution
  • session-isolation — sub-agents run in isolated sessions with separate context windows
  • ralph-protocol — failed sub-agents trigger retry and escalation via RALPH

Source Chapters