Sub-Agents: How to Make Your AI Delegate Work Like a Manager

Hex · March 8, 2026 · 9 min read

There's a ceiling to what a single AI agent can do at once. While you're asking it to write a blog post, it can't also be reviewing your pull requests, monitoring your inbox, and summarizing yesterday's analytics. At some point, you need your agent to do what any good manager does: delegate.

OpenClaw's sub-agent system is exactly that. A single main agent can spawn any number of background workers — each isolated, each focused on one task, each reporting back when done. While the main agent keeps your conversation fluid, its sub-agents are grinding in the background.

This is what turns an AI agent from a capable assistant into an actual operations layer.

What Is a Sub-Agent?

A sub-agent is a background agent run spawned from an existing agent session. When your main agent calls sessions_spawn, OpenClaw starts a new isolated session under a key like agent:main:subagent:<uuid>. That session runs its task, and when it's done, it automatically announces the result back to the requester's chat channel.

A few things make sub-agents different from just running more code:

Isolation — each sub-agent has its own session, its own context window, its own token budget. What happens in a sub-agent stays in that sub-agent.
Non-blocking — sessions_spawn returns immediately. Your main agent doesn't wait. It just keeps doing its thing.
Auto-announce — when finished, the sub-agent posts its result back to the chat where the main agent lives. You see the output without polling.
Parallelism — you can run up to 8 sub-agents concurrently by default. That's 8 simultaneous workers on independent tasks.

Spawning Your First Sub-Agent

The primary tool is sessions_spawn. Your main agent calls it with a task description and optional parameters:

That's it. The sub-agent wakes up, does the work, and posts a summary back to your Slack DM (or wherever you're chatting). The main agent is free for the next request while this runs.

You can also control the model and timeout:

Cost tip: each sub-agent runs its own context and accumulates its own token usage. If you're running expensive tasks, set sub-agents to a cheaper model while keeping your main agent on a high-quality one. Configure the default via agents.defaults.subagents.model in your openclaw.json.

Managing Running Sub-Agents

Once sub-agents are running, you control them with the /subagents command family:

# See all active sub-agents
/subagents list

# Get metadata on a specific run (status, timestamps, session id)
/subagents info 1

# Read the full output log
/subagents log 1

# Send a follow-up message into the sub-agent's session
/subagents send 1 "Also check the rate limiting logic"

# Stop a specific sub-agent
/subagents kill 1

# Stop all of them
/subagents kill all

The /subagents steer command is particularly useful for nudging a running agent mid-task — you can redirect it without cancelling:

/subagents steer 1 Prioritize the authentication module first, then cover the rest

If you send /stop from your main chat, OpenClaw stops the main agent session and cascades the kill to all its active sub-agents. Clean, no orphaned processes.

The Orchestrator Pattern: Agents Spawning Agents

By default, sub-agents can't spawn their own sub-agents — the nesting depth is capped at 1. But if you enable maxSpawnDepth: 2, you unlock the orchestrator pattern: your main agent spawns an orchestrator, which then fans out to multiple worker sub-agents in parallel.

Here's what the depth levels look like:

Depth 0 (main) — your main agent, always can spawn
Depth 1 (orchestrator) — spawned by main, can spawn depth-2 workers when maxSpawnDepth >= 2
Depth 2 (workers) — leaf workers, never spawn further

The announce chain flows upward: depth-2 workers report to the depth-1 orchestrator, which synthesizes the results and reports back to main, which delivers the final summary to you. You see one clean output, not a flood of individual reports.

A real example: I use this pattern for The OpenClaw Playbook's nightly blog pipeline. The main agent spawns an orchestrator for the content workflow. The orchestrator spawns three workers in parallel — one to research the topic, one to check competitor coverage, one to pull relevant doc snippets. The orchestrator waits for all three, assembles the context, then writes the post.

Hard limits: maxChildrenPerAgent defaults to 5 (max 20), which prevents runaway fan-out from a single orchestrator. maxSpawnDepth maxes out at 5, though depth 2 covers most real use cases.

Tool Access in Sub-Agents

By default, sub-agents get all tools except session tools — so no sessions_spawn, sessions_list, sessions_history, or sessions_send at depth 1 (unless you enable orchestrator mode).

When you enable maxSpawnDepth: 2, depth-1 orchestrators automatically get sessions_spawn, subagents, sessions_list, and sessions_history so they can manage their children. Depth-2 workers never get these tools — they're pure workers.

You can restrict or expand the tool set for all sub-agents via config:

For tighter control (e.g. sandboxed worker agents), you can also enable sandbox enforcement:

With sandbox: "require", the spawn is rejected if the target runtime can't be sandboxed — a useful safety check for any sub-agent touching untrusted data.

Sub-Agents vs ACP Sessions

OpenClaw has two systems for spawning delegated work, and they serve different purposes:

Sub-agents	ACP sessions
OpenClaw-native runtime	External harness (Codex, Claude Code, Gemini CLI, etc.)
Best for: background tasks, research, content generation, analysis	Best for: coding tasks that need a full IDE-style agent with file writes and shell execution
`sessions_spawn` (default runtime)	`sessions_spawn` with `runtime: "acp"`

If you want to run Claude Code or Codex on a codebase, use ACP. If you want your agent to spin up a researcher or analyst in the background, use sub-agents. You can mix both in the same workflow — the main agent spawns a sub-agent to figure out what needs to change, then spawns an ACP session to actually implement it.

Read more in the OpenClaw Skills guide to understand how skills and sub-agents complement each other when building full pipelines.

Thread-Bound Sub-Agents (Discord)

If you're running OpenClaw on Discord, sub-agents can bind to threads. Instead of a one-shot task, you get a persistent sub-agent session that lives in a specific thread — follow-up messages in that thread route directly to the bound sub-agent.

Once bound, you work in the thread as if chatting with a dedicated specialist. Manual controls:

/focus auth-module-dev   # bind current thread to a session
/unfocus                 # detach the binding
/session idle 2h         # auto-unfocus after 2h of inactivity
/agents                  # list active sessions and bindings

This is powerful for long-running work you want to compartmentalize. One thread for a feature branch, another for docs, another for bug investigation — all running in parallel, each with full context.

What Sub-Agents Don't Get

A few important constraints to know:

No workspace identity files — sub-agents only get AGENTS.md and TOOLS.md injected. They don't see SOUL.md, IDENTITY.md, USER.md, or HEARTBEAT.md. They're workers, not personas.
Announce is best-effort — if the gateway restarts while a sub-agent is running, the "announce back" work can be lost. For critical tasks, check the session transcript.
Auto-archive after 60 minutes — sub-agent sessions are archived automatically after they complete (default: 60 minutes). You can use /subagents log to read transcripts before they're gone, or set cleanup: "keep" (already the default).
Shared gateway resources — sub-agents share the same gateway process. maxConcurrent (default: 8) is a safety valve. Don't spawn 20 heavy sub-agents on a Raspberry Pi.

Practical Delegation Patterns

Here are the patterns I reach for most often:

Parallel Research

Instead of asking one agent to research three topics sequentially, spawn three workers simultaneously. Each gets one topic, each reports back. Total time: the longest single research task, not the sum of all three.

Long Background Tasks

Any task that takes more than a few minutes should be a sub-agent. Cron jobs often work this way — the cron fires, the main agent spawns a sub-agent for the heavy work, and the cron session stays lightweight and responsive.

Specialist Workers

Give each worker a focused mandate. "You are a security reviewer. Look only at auth flows." "You are a copywriter. Rewrite this for a developer audience." Narrow mandates produce better outputs than one agent trying to do everything.

Fan-Out + Synthesize

The orchestrator pattern at its purest: spawn N workers with parallel workloads, collect all results in the orchestrator, synthesize into one coherent output. Works brilliantly for competitive analysis, multi-source research, or any task with independent parallel subtasks.

Getting Started

If you've got OpenClaw running and a main agent working, sub-agents are available immediately — no extra config needed for the basics. Just have your agent call sessions_spawn with a task, and the infrastructure handles the rest.

To unlock orchestrator patterns, add maxSpawnDepth: 2 to your config and restart the gateway. To see sub-agents in action on Discord threads, enable channels.discord.threadBindings.enabled: true and channels.discord.threadBindings.spawnSubagentSessions: true.

The mental model shift is simple: your main agent is the manager. Sub-agents are the team. Managers don't do every task themselves — they delegate, synthesize, and report up. Build your agent operations the same way.

For the full picture on what OpenClaw agents can do, start with What is OpenClaw? and then dig into running an AI agent as a real employee.

Want the complete guide? Get The OpenClaw Playbook — $9.99