To spawn a subagent in OpenClaw, you call the sessions_spawn tool, pass it a task string that describes the job, and set mode: "run". OpenClaw then spins up an isolated child agent, runs it in the background, and automatically announces the result back to your session when it finishes. Most AI agents run one task at a time. They wait, execute, wait some more. That is fine for simple jobs. But if you are building anything serious in OpenClaw, this one tool changes the whole picture: it lets you delegate work to a child agent, hand it a task description, and get back to your main flow while the subagent runs independently. This guide walks you up the ladder, from your first single spawn to running parallel fleets and managing them in production.
If you want a conceptual overview first, check out the OpenClaw subagents explained pillar post. Here we are going hands-on.
Level 1: Spawn Your First Subagent
Start with the simplest possible case: one subagent, one clearly scoped job, one result. When you call sessions_spawn, you are asking OpenClaw to spin up a child agent session with its own isolated execution context. The essential pieces are a task string, a mode, and a runTimeoutSeconds cap. Here is a minimal but realistic example. Imagine you want a subagent to scrape a pricing page and return the result as JSON.
sessions_spawn({
task: `You are a data extraction agent.
Fetch the page at https://example.com/pricing using web_fetch.
Extract all plan names and their monthly prices.
Return the result as a JSON array like: [{"plan": "Starter", "price": "$9/mo"}, ...]
Do not summarize or explain. Return raw JSON only.`,
mode: "run",
model: "openai/gpt-4o-mini",
label: "pricing-scraper",
context: "isolated",
runTimeoutSeconds: 120
})The subagent starts immediately, fetches the page, extracts the data, and when finished, its result is automatically delivered back to you. You do not need to poll for it.
Note that if your subagent needs to run exec commands, you may need to account for approval settings. See how exec approval behavior works in OpenClaw before building automation-heavy agents.
That is the entire baseline: spawn, let it run, receive the result. Once this single-agent pattern feels natural, the next step is running several of them at the same time.
Level 2: Run Multiple Subagents in Parallel
This is where OpenClaw subagents really shine. Instead of running one agent and waiting, you can spawn several agents at once, let them work simultaneously, and collect results when they finish. The pattern looks like this:
// Spawn three subagents at once -- they run in parallel
sessions_spawn({ task: "Fetch competitor A pricing and return JSON", label: "comp-a", mode: "run", runTimeoutSeconds: 180 })
sessions_spawn({ task: "Fetch competitor B pricing and return JSON", label: "comp-b", mode: "run", runTimeoutSeconds: 180 })
sessions_spawn({ task: "Fetch competitor C pricing and return JSON", label: "comp-c", mode: "run", runTimeoutSeconds: 180 })
// Yield -- pause your current session and wait for all children to report back
sessions_yield({ message: "Waiting for all pricing subagents to complete" })The key here is sessions_yield. After spawning your subagents, call sessions_yield to hand control back to OpenClaw. Your session will wake up automatically when child agents report their results. No polling required. No loops. Just yield and wait.
Parallel spawning is ideal for:
- Researching multiple URLs or topics at once
- Running batch file processing jobs
- Generating several content drafts in parallel
- Performing independent API calls that do not depend on each other
Parallel spawning is the second rung of the ladder. It multiplies your throughput without multiplying your effort, as long as each child’s job is truly independent.
Level 3: Track and Manage Running Subagents
Once you have several agents running, you need visibility and control. OpenClaw provides the subagents tool for monitoring and controlling child sessions. The three actions you will use most are:
- list : Shows all active subagent sessions with their labels, status, and how long they have been running.
- steer : Sends a message to a running subagent to adjust its behavior mid-task. Useful if you realize the agent needs course correction.
- kill : Terminates a subagent immediately. Use this when a subagent is stuck, going off-track, or no longer needed.
// Check status of all running subagents
subagents({ action: "list" })
// Steer a specific subagent
subagents({ action: "steer", label: "comp-a", message: "Focus only on the annual pricing table, skip monthly." })
// Kill a runaway subagent
subagents({ action: "kill", label: "comp-c" })A practical rule: if a subagent has been running more than twice its expected time, check on it with list before deciding whether to steer or kill.
Management is the difference between a demo and a reliable workflow. list, steer, and kill are the three controls that keep a fleet from drifting off track.
Level 4: Collect Results and Orchestrate Like a Pro
With parallelism and management in place, the final rung is clean orchestration. OpenClaw uses push-based completion. When a subagent finishes, its final message is automatically delivered to your session. You do not need to poll or loop. The flow works like this:
- You spawn one or more subagents.
- You call
sessions_yieldto suspend your session. - Child agents run in the background.
- When a child finishes, OpenClaw auto-announces its result to you.
- Your session wakes up and receives the result as the next message.
For multiple subagents, you will receive results as each child completes. If you spawned three agents and two finish quickly, your session wakes up twice before the third reports in. Each wake-up delivers that child’s final output.
To make result handling clean, instruct each subagent to format its output clearly. Something like “Your final response must be a JSON object with keys X, Y, Z” keeps parsing straightforward. Avoid vague instructions like “return your findings”. That leads to inconsistent output that is harder to process programmatically.
The pro move is to design for the result format from the start. A precise output contract on the way in means clean, parseable results on the way out.
sessions_spawn Parameters: Full Reference
Here are the parameters you will use most, collected in one place for quick lookup.
- task (required) : The job description. This is a plain-text string that tells the subagent exactly what to do. Be specific. The subagent has no memory of your current conversation.
- mode: “run” : Runs the subagent as a one-shot background job. It executes until complete and then auto-announces the result back to you.
- model : Override the model for this subagent. Use a cheaper, faster model (like
openai/gpt-4o-mini) for lightweight tasks to save cost and speed up turnaround. - label : A human-readable name for the session. Useful for tracking when you have several subagents running in parallel.
- context: “isolated” vs “fork” :
isolatedgives the subagent a fresh start with no history.forkcopies your current conversation context into the child. Useforkonly when the child genuinely needs your conversation history. Default isisolated. - runTimeoutSeconds : Always set this. Without a timeout, a stuck subagent runs forever and burns credits. A reasonable default for most tasks is 300 (5 minutes).
Ampere.sh is built for running AI agents around the clock. Fast ARM servers, low cost, and no config headaches. It is how most serious OpenClaw users keep their agents always on.
FAQ
Can a subagent spawn its own subagents?
Yes, but only within the allowed nesting depth. OpenClaw typically enforces a maximum depth to prevent runaway recursion. Check your instance configuration for the current limit. In most setups, one level of nesting (parent spawns child, child does not spawn further) is the practical working pattern.
How do I pass data from my session into the subagent task?
Embed the data directly in the task string. Since the task is just a string, you can interpolate variables before passing it. For larger data payloads, write the data to a temp file and instruct the subagent to read from that path.
What happens if a subagent hits its runTimeoutSeconds limit?
OpenClaw terminates the subagent and reports a timeout error back to your session. The child session is cleaned up automatically. Always set runTimeoutSeconds to a realistic upper bound so you know roughly when to expect results or failures.
Should I use context: “fork” or context: “isolated”?
Default to isolated. Isolated subagents are cheaper to run because they start with no prior context to process. Use fork only when the subagent genuinely needs to understand the current conversation to do its job. Forking is more expensive and slower to initialize.
How many subagents can I run at once?
This depends on your OpenClaw plan and the concurrency limits of your underlying model provider. In practice, spawning 3 to 5 parallel subagents is a stable, cost-effective pattern for most workflows. Very large parallel fleets can run into rate limits at the model API level, so monitor for 429 errors when scaling up.
For more on this, check out our guide on running multiple subagents in parallel.
For more on this, check out our guide on 7 common subagent mistakes to avoid.
The Takeaway
Learning how to create sub-agents in OpenClaw unlocks a fundamentally different way of building workflows. Instead of one agent doing everything sequentially, you orchestrate a team. Each subagent handles a focused task. Results come back automatically. Your main agent stays clean and supervisory.
Start simple: spawn one subagent with a well-scoped task, verify the output, then layer in parallelism once you understand the result format. The sessions_spawn and sessions_yield combination is the core pattern. Get comfortable with those two, and the rest follows naturally.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting — your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
Really solid breakdown. One question: when I call sessions_yield after spawning three agents, does my main session block completely until all three finish? Or does it wake up each time one of them completes?
Great question, Yuki. Your main session wakes up each time a child reports in, not after all of them finish. So if you spawn three agents and one completes early, you get that result right away. The other two results arrive separately as they finish. It is push-based, so each completion triggers its own wake-up.
Glad it helped. On Spawn Subagent OpenClaw Step by, the big win is usually getting the first pass right and then refining from there. That tends to save a lot of time later.
Great question. For Spawn Subagent OpenClaw Step by, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.
Followed this and had a subagent running in under 10 minutes. The part about context inheritance was the bit I had been missing.
Thanks for reading, Rafael Bustamante. On Spawn Subagent OpenClaw Step by, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
I tried spawning subagents with context: fork and the initialization time is noticeably slower. Does the fork copy the entire conversation history or just a summary?
Fork copies the full conversation context, which is why you see that slower startup. The child has to load and process all of that history before it can begin working. That is exactly why isolated is the better default for most jobs. Unless the subagent truly needs prior context, isolated starts faster and costs less.
Thanks for reading, rerealizeadmin. On Spawn Subagent OpenClaw Step by, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
Great question. For Spawn Subagent OpenClaw Step by, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.
Is there a way to pass structured data to the subagent without just stuffing it into the task string? For large objects it starts to feel messy.
The cleanest approach for large payloads is to write the data to a temp file in your workspace before spawning, then pass the file path in the task string. Something like: write the JSON to /tmp/payload.json, then tell the subagent to read from that path. The subagent can use the read tool to load it. Keeps your task string short and the data structured.
Thanks for reading, rerealizeadmin. On Spawn Subagent OpenClaw Step by, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
Great question. For Spawn Subagent OpenClaw Step by, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.