OpenClaw

OpenClaw Sub-Agents & sessions_spawn👨‍💻

Sub-agents in OpenClaw are spawned sessions that run in isolation from the parent agent. The sessions_spawn command creates a new session with its own context window, tools, and sandbox scope, allowing an orchestrator agent to delegate tasks to specialized workers without polluting its own context. This is the foundation of the orchestrator pattern: a coordinator agent breaks a complex task into pieces, spawns sub-agents to handle each piece, collects results, and synthesizes a final response. Sub-agents can run in parallel, share results through explicit handoff, and are cleaned up automatically when they complete.

Key Takeaways

  • 1sessions_spawn creates a new isolated session with a fresh context window. The sub-agent inherits the parent's model configuration by default but can override it. Isolation means the sub-agent's conversation history, tool calls, and errors do not leak into the parent's context.
  • 2The orchestrator pattern uses sessions_spawn to coordinate multiple sub-agents. The orchestrator receives a complex task, decomposes it into subtasks, spawns a sub-agent for each, waits for results, and synthesizes a final answer. This keeps the orchestrator's context clean and focused on coordination.
  • 3Session isolation is a security feature. Each spawned session has its own sandbox scope. A sub-agent cannot access the parent's files, tools, or session data unless explicitly granted. This prevents a compromised or misbehaving sub-agent from affecting the parent or sibling sessions.
  • 4Parallel execution is supported. An orchestrator can spawn multiple sub-agents simultaneously using sessions_spawn with different task payloads. Results are collected as each sub-agent completes. This is useful for tasks like reviewing multiple files, querying multiple APIs, or processing data in parallel.
  • 5The sessions list command shows all active sessions, including spawned sub-agents. Each session shows its parent ID, status (running, completed, errored), and resource usage. Use this to monitor and debug orchestrator workflows.
  • 6Sub-agents are ephemeral by default. Once a sub-agent completes its task and returns results, the session is cleaned up. For long-running sub-agents that need persistence, configure session retention in the spawn options.

Master openclaw sub-agents & sessions_spawn

Take the Introduction to OpenClaw course with hands-on lessons and challenges.

Examples

Basic sessions_spawn — delegating a task to a sub-agent

bash

The --parent-session flag links the sub-agent to its orchestrator. The --wait flag blocks until the sub-agent completes and returns its result. Without --wait, the spawn returns immediately with the session ID for later polling.

Orchestrator pattern — parallel sub-agent execution

json

The orchestrator agent has access to sessions_spawn (to create sub-agents), sessions_list (to monitor them), and sessions_result (to collect their output). The file-reviewer agent is the worker template. The orchestrator spawns one file-reviewer per changed file, all running in parallel with isolated sandboxes.

Monitoring spawned sessions

bash

The sessions list output shows the parent-child relationship between orchestrator and sub-agents. Each sub-agent has an independent status. The orchestrator can check results from completed sessions and handle errors from failed ones without its own session being affected.

Spawn options for fine-grained control

bash

Spawn options let the orchestrator control cost and security per sub-agent. Override the model to use a cheaper one for simple tasks. Set timeouts to prevent runaway sub-agents. Restrict sandbox-paths to limit file access to only what the sub-agent needs.

Collecting results from parallel sub-agents in code

bash

This script demonstrates the full orchestration loop: spawn sub-agents in parallel with --no-wait, wait for all to finish, then collect results sequentially. In practice, the orchestrator agent handles this logic internally using its tools, but the CLI equivalent helps visualize the workflow.

Common Mistakes

Mistake:

Spawning sub-agents without setting sandbox scope to 'tree', allowing sub-agents to have broader permissions than the parent

Fix:

Always set sandbox scope to 'tree' on the orchestrator agent. This propagates sandbox restrictions to all spawned sub-agents, ensuring they cannot access files or tools outside the parent's allowed scope.

Mistake:

Spawning too many sub-agents in parallel without considering API rate limits and cost

Fix:

Each sub-agent makes its own API calls. Spawning 50 sub-agents simultaneously can hit rate limits and generate unexpected costs. Use a concurrency limit (--max-concurrent) or batch sub-agents in groups of 5-10.

Mistake:

Using the parent session's context to pass large amounts of data to sub-agents instead of using file references

Fix:

Sub-agents have their own context windows. Pass file paths or references instead of raw data. A sub-agent can read the file directly using its tools, avoiding context window bloat in the parent.

Mistake:

Not handling sub-agent errors in the orchestrator, causing the entire workflow to fail silently when one sub-agent errors

Fix:

Check the status of each sub-agent after spawning. Use sessions result with error handling to detect failures. Implement retry logic or graceful degradation for non-critical sub-agent failures.

Best Practices

  • Use the orchestrator pattern for tasks that naturally decompose: multi-file code review, parallel data analysis, distributed testing. A single agent trying to handle everything at once hits context limits faster.
  • Set timeouts on all spawned sessions. A sub-agent stuck in a loop wastes resources. 60-120 seconds is reasonable for most review and analysis tasks.
  • Use cheaper models for sub-agents doing simple extraction or classification. The orchestrator needs a strong model for synthesis, but sub-agents doing focused tasks often work well with gpt-4o-mini.
  • Monitor spawned sessions with `openclaw sessions list` during development. Understand the parent-child relationships and resource usage before running orchestrator workflows in production.
  • Clean up completed sessions. While ephemeral sessions auto-cleanup, persistent sessions accumulate. Run `openclaw sessions prune --older-than 7d` periodically.
  • Start with sequential sub-agent execution (--wait) for debugging, then switch to parallel execution (--no-wait) once the workflow is stable.

Summary

Sub-agents in OpenClaw are spawned via sessions_spawn to run isolated tasks under an orchestrator. The orchestrator pattern decomposes complex tasks, spawns specialized sub-agents in parallel, and synthesizes results. Each sub-agent has its own context window, sandbox, and lifecycle. Use sandbox scope 'tree' to propagate security restrictions, set timeouts to prevent runaway sessions, and monitor with sessions list. Sub-agents are ephemeral by default and cleaned up on completion.

Practice OpenClaw with hands-on challenges

Learn openclaw sub-agents & sessions_spawn hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw Sessions MemoryOpenclaw Multi AgentOpenclaw Multi Agent RoutingOpenclaw Security SandboxingOpenclaw Tools

Related Cheatsheets

Openclaw Cli Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.