sessions_spawn Deep Dive

+15 Mana ✨
OpenClaw Sub-Agents Guide(DOCUMENTATION)OpenClaw sessions_spawn Reference(DOCUMENTATION)

Introduction

The sessions_spawn tool is the foundation of multi-agent coordination in OpenClaw. It lets a parent agent create child agent sessions that run tasks concurrently. Unlike sequential tool calls, spawned sessions execute in parallel and return results asynchronously. This lesson covers every parameter of sessions_spawn and how the spawning lifecycle works.

Key Concepts

  • sessions_spawn: The tool that creates a new child agent session from a parent session
  • task: The instruction text that the child agent will execute
  • label: A human-readable identifier for the spawned session, used for tracking
  • agentId: Optionally route the task to a specific agent instead of the default
  • model / thinking: Override the model and thinking budget for the child session
  • runTimeoutSeconds: Maximum execution time before the child session is forcefully terminated
  • announce step: The parent agent's notification to the user that a sub-agent has been spawned

Real World Context

A lead developer asks their OpenClaw agent to review a large pull request that touches the frontend, backend, and database layers. Instead of reviewing everything sequentially, the parent agent spawns three child sessions: one for frontend code review, one for backend logic review, and one for database migration review. All three run in parallel, and the parent synthesizes their results into a unified review.

Deep Dive

Basic Spawn

The simplest form of sessions_spawn creates a child session with a task:

json
{
  "tool": "sessions_spawn",
  "params": {
    "task": "Review the frontend components in src/components/ for accessibility issues",
    "label": "frontend-a11y-review"
  }
}

This creates a new child session that executes the accessibility review task. The label helps identify this specific session in logs and status displays. The child session runs independently and non-blocking, meaning the parent agent can continue working or spawn additional sessions.

Full Parameter Set

A spawn with all parameters specified:

json
{
  "tool": "sessions_spawn",
  "params": {
    "task": "Analyze the database migration in db/migrations/20260220_add_indexes.sql for performance impact",
    "label": "db-migration-review",
    "agentId": "database-specialist",
    "model": "anthropic:claude-sonnet-4-20250514",
    "thinking": {
      "budget": 12000
    },
    "runTimeoutSeconds": 300
  }
}

This spawn routes the task to a specific database-specialist agent with Claude Sonnet, a 12000-token thinking budget, and a 5-minute timeout. If the child session does not complete within 300 seconds, it is terminated.

Non-Blocking Returns

When sessions_spawn is called, it returns immediately with a session reference:

json
{
  "sessionId": "sub-abc123",
  "label": "db-migration-review",
  "status": "running"
}

The parent agent does not wait for the child to finish. It receives the session ID and can check the status later or continue spawning more sessions. Results are collected when the parent needs them.

The Announce Step

When a sub-agent is spawned, the parent agent notifies the user:

json
{
  "announce": {
    "message": "Spawning database specialist to review migration performance",
    "label": "db-migration-review",
    "sessionId": "sub-abc123"
  }
}

This announce step keeps the user informed about what is happening behind the scenes. It appears in the conversation as a status update, not a full message.

Common Pitfalls

  • Not setting runTimeoutSeconds: Without a timeout, a misbehaving child session can run indefinitely, consuming tokens and blocking the parent from collecting results.
  • Spawning too many sessions simultaneously: Each spawn consumes resources. Spawning 20 sessions at once can exhaust rate limits and cause cascading failures.
  • Forgetting that child sessions have limited tool access: Child sessions may not have access to all the tools the parent has. Verify tool availability before spawning.

Best Practices

  • Always set a runTimeoutSeconds appropriate to the task complexity to prevent runaway sessions.
  • Use descriptive labels that clearly identify what each child session is doing for easier tracking.
  • Start with 2-3 parallel sessions and scale up after validating that your rate limits can handle the load.

Tip: Combine sub-agents with OpenClaw hooks to trigger sub-agent spawning automatically when specific events occur.

Summary

  • sessions_spawn creates child agent sessions that execute tasks concurrently and non-blocking
  • Parameters include task, label, agentId, model, thinking budget, and runTimeoutSeconds
  • The tool returns immediately with a session reference; results are collected later
  • The announce step notifies the user when a sub-agent is spawned
  • Always set timeouts and use descriptive labels for effective orchestration
✓ Completed