How to Configure and Run OpenClaw Subagents

Only 36% of ClawHub skills pass security audits without issues, according to a 2026 analysis of the marketplace's 13,700+ community-built skills. That stat matters here because subagents inherit tool access from your configuration, and misconfigured tool policies can expose your entire gateway to untrusted skills running at depth. Understanding exactly how subagents work, what they can access, and how to restrict them is not optional.

OpenClaw subagents are isolated background agent runs that operate in their own sessions. You describe a task, the system spawns a new agent run, and that run executes independently from the parent. The spawn call is non-blocking: the parent gets confirmation immediately and can continue its own work while the subagent processes in the background.

This is different from sending a message to another agent. Each subagent gets its own context window, its own tool access governed by depth-based policies, and its own token budget. When it finishes, OpenClaw delivers a completion event back to the parent that includes the subagent's final reply, status, runtime statistics, and cost estimate.

The practical payoff is parallelism. If your main agent needs to research three topics, generate a report, and check file permissions, those five tasks can run simultaneously as subagents instead of sequentially. The parent spawns each one, yields until they complete, then synthesizes the results.

Before spawning any subagents, you need the right gateway configuration. The defaults live under agents.defaults.subagents in your gateway config, and per-agent overrides go in agents.list[].subagents.

Here are the settings that matter most:

maxSpawnDepth controls how deep subagents can nest. Range is 1 to 5. Set it to 1 and subagents are leaf workers that cannot spawn their own children. Set it to 2 and depth-1 subagents become orchestrators that can delegate further. The official docs recommend depth 2 for most orchestrator patterns. Going beyond 3 adds complexity without proportional benefit in almost every case.

maxConcurrent caps the total number of subagent runs across all agents in your gateway. The default is 8, which is the global lane limit. If you have three agents each trying to spawn four subagents simultaneously, the ninth spawn queues until a slot opens. Size this based on your hardware and API rate limits, not ambition.

maxChildrenPerAgent limits how many active children a single session can have. Default is 5, range is 1 to 20. This prevents a runaway orchestrator from consuming all concurrent slots.

runTimeoutSeconds sets a hard stop for subagent runs. Default is 0 (no timeout). For production workloads, always set a timeout. A subagent stuck in a loop with no timeout will hold a concurrency slot indefinitely.

delegationMode accepts suggest or prefer. In suggest mode, the agent decides whether to delegate or handle the task itself. In prefer mode, the agent is nudged toward delegation when the task fits a subagent pattern.

A working configuration looks like this:

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,
        "maxConcurrent": 8,
        "maxChildrenPerAgent": 5,
        "runTimeoutSeconds": 900,
        "delegationMode": "suggest",
        "announceTimeoutMs": 120000,
        "archiveAfterMinutes": 60
      }
    }
  }
}

The announceTimeoutMs (default 120000, or 2 minutes) controls how long the gateway tries to deliver a completion event before giving up. The archiveAfterMinutes (default 60) auto-archives finished subagent transcripts after an hour.

{
  "agents": {
    "list": [
      {
        "id": "orchestrator",
        "subagents": {
          "allowAgents": ["researcher", "writer", "reviewer"],
          "delegationMode": "prefer"
        }
      }
    ]
  }
}

The sessions_spawn tool is how you create a subagent. It accepts a task description and several optional parameters that control how the subagent behaves.

Required parameter:

• task (string): The task description. This is the only required field. Write it like a clear brief, not a vague hint. "Research the top 5 competitor pricing pages and summarize each in 3 bullets" works. "Look into competitors" does not.

Key optional parameters:

• taskName (string): A stable handle matching [a-z][a-z0-9_]{0,63}. Useful for referencing the subagent programmatically in logs and status checks.
• context: Either "isolated" (default) or "fork". This is the single most important choice after the task itself. More on this below.
• model (string): Overrides the model for this specific subagent run. Useful for cost optimization, like spawning a cheaper model for simple extraction tasks.
• thinking (string): Overrides the thinking level. Match this to task complexity.
• runTimeoutSeconds (number): Per-spawn timeout that overrides the global default.
• agentId (string): Target a different configured agent, if allowAgents permits it.
• thread (boolean, default false): When true, requests a channel thread binding for this subagent session.
• cleanup: Either "delete" or "keep" (default). Setting "delete" archives the subagent transcript after it announces its result.
• sandbox: Either "inherit" (default) or "require". Setting "require" enforces sandboxed execution even if the parent doesn't use it.

After calling sessions_spawn, you get back { status: "accepted", runId, childSessionKey } immediately. The subagent is now running in the background.

Persist Subagent Output Across Sessions

OpenClaw subagents generate files that disappear when sessions end. Fast.io gives your agents 50GB of persistent, searchable workspace storage with built-in RAG, no credit card required.

Sign Up Free

OpenClaw restricts what tools subagents can access based on their nesting depth. The deeper a subagent sits in the spawn hierarchy, the fewer capabilities it receives. Your main agent session has full tool access, but subagents at each subsequent level lose session management tools progressively. Leaf workers at the deepest level get only standard tools like file operations and web search, with no ability to spawn further children or interact with other sessions.

This layered restriction serves as a security boundary. When your subagents pull in ClawHub skills from the 13,700+ marketplace, depth-based policies prevent an untrusted skill from spawning its own subagents or accessing session management capabilities it should not have. You can tighten this further with explicit allow and deny lists in your gateway configuration, specifying exactly which tools are available at each depth.

The general principle: grant the minimum tool surface each subagent needs, and rely on OpenClaw's depth restrictions as a backstop. Review the official subagent documentation for the exact tool matrix at each depth level and configuration syntax for custom policies.

The real power of subagents shows up when you combine parallel execution with persistent storage. Here is a concrete pattern: a research orchestrator that spawns three subagents in parallel, collects their results, and stores the output in a shared workspace.

The orchestrator agent receives a task like "Research competitor pricing for X, Y, and Z." It spawns three isolated subagents, one per competitor. Each subagent searches the web, gathers pricing data, and writes a summary. The orchestrator calls sessions_yield to wait for all three completions, then synthesizes a combined report.

Without persistent storage, that report exists only in the orchestrator's context window. When the session ends, it is gone. For one-off questions that is fine. For a team that runs this research weekly, you need the output somewhere durable.

Local filesystems work if every agent runs on the same machine, but they break the moment you scale to multiple containers or need to share results with humans. Object storage (S3, GCS) adds durability but not searchability. You upload a PDF and can retrieve it by key, but you cannot ask "what was the pricing trend we found last month?" without building your own retrieval layer.

Fast.io workspaces fill this gap by combining file storage with built-in intelligence. Upload the research report and it is automatically indexed for semantic search and RAG queries. A human teammate can open the workspace, ask Ripley AI "what did the competitor analysis find about enterprise pricing?", and get a cited answer pointing to the exact file and passage.

The agent side uses the Fast.io MCP server to write files directly into a shared workspace. No local disk, no manual transfer. The orchestrator spawns subagents, collects results, generates the report, and uploads it to the workspace in a single pipeline.

For teams running OpenClaw agents that produce files (reports, datasets, generated code, analysis artifacts), the handoff problem is just as important as the orchestration problem. Fast.io's free agent plan includes 50GB storage, 5,000 credits per month, and 5 workspaces with no credit card required. Enough to persist subagent output from day one.

OpenClaw provides slash commands for inspecting subagent state without leaving your chat session.

/subagents list shows all subagent runs for the current session, including their status, run IDs, and task names.

/subagents log <id> [limit] [tools] dumps the transcript for a specific subagent run. Add the tools flag to include tool call details. The limit parameter caps how many entries you see.

/subagents info <id> displays run metadata: model used, tokens consumed, runtime, status, and session key.

For Discord users, /focus <target> binds a thread to a specific subagent session so you can interact with it directly. /unfocus removes the binding.

Common problems and fixes:

Subagent stuck with no output: Check runTimeoutSeconds. If set to 0 (no timeout), a subagent in a loop will never terminate. Set a reasonable timeout for every production deployment.

Announce not delivered: Announce delivery is best-effort. A gateway restart loses pending announces. If you restart the gateway while subagents are running, their results may not reach the parent. For critical workflows, check /subagents list after a restart to see if any runs completed during downtime.

Concurrent slot exhaustion: If spawns are queuing unexpectedly, check maxConcurrent (global cap, default 8) and maxChildrenPerAgent (per-session cap, default 5). Reduce the number of parallel spawns or increase the limits if your hardware supports it.

Context injection missing: Subagents only receive AGENTS.md and TOOLS.md from the gateway context. They do not get SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, or BOOTSTRAP.md. If your subagent needs personality or memory context, pass it explicitly in the task parameter or use fork mode.

Cascading stops: Running /stop on a parent agent stops all its child subagent runs. This is intentional but can surprise you if a parent and child are working on unrelated follow-up tasks.