Most OpenClaw users discover the main features quickly: setting up the gateway, connecting Telegram, running shell commands. But there’s one capability that changes how you work entirely, and most people never touch it. Subagents let your OpenClaw agent spin up independent child sessions to handle tasks in parallel, in the background, or in complete isolation from the main conversation. Once you understand how they work, you’ll wonder how you managed without them.
What Is a Subagent in OpenClaw?
A subagent is a separate, isolated agent session that your main agent spawns to handle a specific task. Think of it like hiring a contractor for a focused job. The main agent (your primary session) delegates work, the subagent completes it, and the result gets reported back automatically.
Key things to understand about subagents:
- They run independently in their own session, with their own model context
- They don’t share memory with the parent by default (isolated context)
- They auto-announce completion back to the parent when done, so you don’t need to poll
- They can use all the same tools as the main agent, including file access, shell commands, and web search
This design makes subagents ideal for long-running work, parallel execution, or anything you want to keep out of the main conversation context.
Agent vs Subagent: What’s the Difference?
A regular agent turn happens inside your main session. The agent reads your message, uses tools, and replies. Everything happens sequentially, in the same context window, blocking the conversation until it’s done. For a full breakdown, see OpenClaw Agent vs Subagent: What’s the Difference?.
A subagent is a different kind of thing entirely. Here’s how they compare:
| Aspect | Agent Turn (Main Session) | Subagent |
|---|---|---|
| Isolation | Shares main context | Fully isolated by default |
| Context | Sees full conversation history | Only sees what you pass in the prompt |
| Lifecycle | Lives as long as the main session | Created for a task, completes, reports back |
| Blocking | Blocks the conversation while running | Runs in background, non-blocking |
| Parallelism | One task at a time | Multiple subagents run at the same time |
| Use cases | Short tasks, interactive work | Long jobs, parallel work, isolated tasks |
| Model | Same model as main session | Can specify a different model |
The key insight: subagents don’t block you. You can spawn three subagents, keep chatting with your main agent, and get all three results back when they finish. That’s a genuinely different way to work.
How to Spawn a Subagent in OpenClaw
The main tool for spawning subagents is sessions_spawn. When your agent calls this tool, it creates a new child session with a specific task prompt and optional configuration. For a complete walkthrough, see How to Spawn a Subagent in OpenClaw.
Here’s what you can configure when spawning:
- prompt: The task you want the subagent to complete (this is its entire job description)
- context: Either
isolated(default, fresh start) orfork(inherits the current conversation context) - mode: Use
runfor one-shot background tasks that complete and report back - model: Optionally override the model for this subagent (e.g. use a faster model for simple tasks)
- label: A human-readable name so you can identify the subagent later
Context: Isolated vs Fork
Isolated context (the default) means the subagent starts fresh. It only knows what you put in the prompt. This is what you want for most tasks because it keeps the subagent focused and prevents it from getting confused by irrelevant conversation history.
Fork context means the subagent inherits the current session transcript. Use this when the subagent genuinely needs to understand what has already happened in the conversation. The catch: fork context costs more tokens and can slow the subagent down if your conversation history is long. Most of the time, isolated is the right choice.
Realistic Example
Here’s what a subagent spawn looks like in practice. Imagine your main agent receives this task and delegates it:
// Main agent spawns a subagent with mode: run
sessions_spawn({
label: "research-competitor-pricing",
mode: "run",
context: "isolated",
prompt: `
You are a research assistant. Search the web for current pricing
for the top 5 AI personal assistant tools (excluding OpenClaw).
Compile a comparison table with: tool name, monthly price,
free tier availability, and key features.
Save the results to /workspace/competitor-pricing.md.
That is your only task. Complete it and stop.
`
});The subagent runs, does the research, writes the file, and auto-announces completion. The main session never blocks.
When Should You Use Subagents?
Not every task needs a subagent. But there are four clear situations where they shine:
1. Running Tasks in Parallel
This is the big one. Without subagents, your agent can only do one thing at a time. With subagents, you can spawn multiple child sessions simultaneously. Need to research three topics, write three blog posts, or process three files at once? Spawn three subagents and get all three done in the time it would take to do one.
2. Long Background Work
Some tasks take a while. Scraping a hundred pages, generating a detailed report, or running a complex analysis can take minutes. If that runs in your main session, you’re blocked. Run it as a subagent and you can keep using your main session for other things while the work happens in the background.
3. Context Isolation
Sometimes you want a task to happen without polluting your main conversation context. This is especially useful for sensitive operations, or when you’re going to repeat a similar task many times and don’t want the context window to bloat. Each isolated subagent starts clean.
4. Using a Different Model
Not every task needs your best (and most expensive) model. Simple formatting, data extraction, or translation tasks can run on a faster, cheaper model. Subagents let you specify a different model per task. Run complex reasoning on Sonnet, handle bulk text cleanup with a mini model, and keep costs under control.
Managing Subagents: List, Steer, and Kill
Once subagents are running, you can manage them through the subagents tool. The three main actions are:
- list: See all active subagents, their labels, status, and how long they’ve been running
- steer: Send a message to a running subagent to adjust its course (useful if the task changed)
- kill: Terminate a subagent immediately (for example, if it’s going in the wrong direction or you no longer need the result)
Completion is push-based. When a subagent finishes, it automatically announces its result back to the parent session. You don’t need to check status in a loop or poll for results. This is intentional design: polling is wasteful and unnecessary.
If you spawn a subagent and then yield with sessions_yield, your main agent goes quiet and waits. When the subagent announces completion, that result arrives as the next message. This is the cleanest pattern for one subagent blocking the parent.
For OpenClaw memory handling patterns, see our post on how to stop OpenClaw from forgetting things after a restart, which covers related workspace and session state concepts.
Real-World Example: Publishing Blog Posts with Subagents
Here’s a practical walkthrough showing why subagents matter. Suppose you want to publish three blog posts to your WordPress site. Each post needs research, writing, and publishing. Done sequentially in the main agent, that’s three long blocking operations in a row. If you want to go deeper on patterns, see OpenClaw Multi-Agent Orchestration.
With subagents, the main agent does this:
- Spawns Subagent A to research and write Post 1
- Spawns Subagent B to research and write Post 2
- Spawns Subagent C to research and write Post 3
- Calls
sessions_yieldand waits
All three subagents run in parallel. Each one completes its post, saves the draft, and reports back. Total time: roughly the same as writing one post, not three. The main agent receives all three results, then handles final review or publishing in one pass.
This pattern scales well. The same approach works for processing customer emails, generating social posts, running web research, or any repetitive multi-step task where the items don’t depend on each other.
For more on scheduling and automation patterns in OpenClaw, our post on what happens when OpenClaw cron fires but nothing arrives covers related timing and delivery concepts worth understanding.
Common Mistakes with OpenClaw Subagents
A few patterns come up repeatedly when people are new to subagents. Avoiding these will save you a lot of frustration. We cover all of them in detail in 7 Common OpenClaw Subagent Mistakes.
Polling for Results in a Loop
The most common mistake. After spawning a subagent, the main agent starts calling subagents list in a tight loop to check if it’s done yet. Don’t do this. Completion is push-based and auto-announces. Polling burns tokens, clutters the context, and adds latency. Use sessions_yield instead and let the result come to you.
Using Fork Context When You Don’t Need It
Fork context sends the entire current conversation transcript to the subagent. If your conversation is long, that’s a lot of tokens for a subagent that only needs a simple task description. Default to isolated context and only use fork when the subagent genuinely needs the history. Most task-based subagents don’t.
Not Setting a Timeout
Subagents can get stuck. A network issue, an unexpected tool response, or a confused model can leave a subagent running indefinitely. Set runTimeoutSeconds when spawning so the subagent gets automatically terminated if it runs too long. A reasonable default for most tasks is 120 to 300 seconds.
Vague Task Prompts
A subagent only knows what you put in its prompt. If your task description is vague, the subagent will make assumptions, and those assumptions might not match what you wanted. Write subagent prompts like you’re writing a spec for a contractor: specific, complete, and unambiguous. Include the expected output format and where to save results.
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.
Frequently Asked Questions
How do I use subagents in OpenClaw?
Your main agent uses the sessions_spawn tool to create a subagent. You provide a task prompt, choose context: isolated or fork, and optionally set a mode of run for one-shot background tasks. The subagent runs independently and auto-announces its result when done.
What is the difference between an OpenClaw sub agent and the main agent?
The main agent runs in your primary session and handles your direct conversations. A subagent is a child session created for a specific task. Subagents are isolated by default, run non-blocking in the background, and terminate when their task is complete. The main agent can spawn many subagents at the same time.
Can OpenClaw subagents run tasks in parallel?
Yes, that’s one of the main reasons to use them. You can spawn multiple subagents at the same time, and they all run simultaneously. This is significantly faster than running tasks one after another in the main session.
How does OpenClaw multi-agent orchestration work?
The main agent acts as an orchestrator. It breaks a complex task into smaller pieces, spawns a subagent for each piece with a specific prompt, and waits for results. When all subagents report back, the main agent combines the outputs or takes the next action. This is the core pattern behind OpenClaw multi-agent orchestration.
How do I spawn subagents in OpenClaw and get results back?
Use sessions_spawn with mode: run to create a background subagent. When the subagent finishes, it auto-announces its result to the parent session. You can call sessions_yield in the parent to wait for that announcement, or keep the parent active to receive results when they come in.
What happens if a subagent gets stuck or takes too long?
You can kill a stuck subagent using the subagents tool with action: kill and the subagent’s session ID. To prevent this situation, set runTimeoutSeconds when spawning so the subagent is automatically terminated if it runs past the limit. This is good practice for any long-running background task.
Final Thoughts
Subagents are one of those features that feel optional until you actually use them. Once you run your first parallel batch of tasks and see them all complete in the time it would have taken to do one, the model shifts. You start thinking about work differently: what can I delegate, what can run in parallel, what should be isolated from my main context?
The mechanics are straightforward. Spawn with sessions_spawn, use isolated context by default, set a timeout, write a clear task prompt, and let the push-based completion system do the rest. Start with one subagent on a task you already do regularly and see how it changes the workflow.
OpenClaw’s subagent system is genuinely useful once it clicks, and now you have everything you need to make it click.
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
This is the clearest explanation of subagents I have found so far. One question though: if I spawn multiple subagents in parallel, is there a limit to how many I can run at the same time? I tried spawning about 6 at once and it seemed to work but I want to make sure I am not hitting some hidden cap.
Great question, Priya. There is no hard-coded limit baked into OpenClaw itself, but practical limits come from your system resources (RAM, CPU) and your API rate limits with the model provider. Six concurrent subagents is totally reasonable. Where you will notice constraints is if each subagent is hitting the same API endpoint and you start seeing 429 rate limit errors. In that case, stagger the spawns slightly or use a model with higher rate limits for batch work.
This clarified a lot for me. I was spawning subagents for everything and wondering why my token usage was so high. Makes more sense now to be selective about it.
Thanks for reading, Tunde Adegoke. On OpenClaw Subagents Explained Delegate Tasks, 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.
Really useful post. I was using fork context for everything because I thought the subagent needed to know what was going on in the main session. Turns out I was just burning tokens for no reason. Switching to isolated and writing better task prompts made a noticeable difference in speed and cost.
Exactly right, Tobias. Fork context is one of those things that sounds useful in theory but in practice most subagent tasks are self-contained enough that they don’t need the full history. The rule of thumb I follow: if you can describe the task completely in the prompt without referencing the conversation, use isolated. You will get faster responses and lower token usage every time.
Thank you for the real-world blog publishing example, that is exactly the kind of use case I was looking for. Do subagents have access to the same workspace files as the main agent, or do they run in a completely separate environment? I want to make sure they can write to the same output folder.
Yes, subagents run on the same host machine and have full access to the same workspace directory. They are isolated at the session and context level, not the filesystem level. So you can absolutely have multiple subagents writing to the same output folder. Just be careful about race conditions if two subagents are writing to the same file at the same time. A clean pattern is to have each subagent write to a uniquely named file (like post-1.md, post-2.md) and then have the main agent merge or process them afterward.