OpenClaw Sub-Agents: Run Long Work Without Blocking the Main Chat

The main chat is the worst place to trap a long-running job.

When an agent is debugging a deploy, researching a gnarly issue, reviewing a repo, or waiting on a slow browser flow, the operator still needs the chat to stay useful. They may need to ask a quick question, stop the work, add context, or start a different task. If the main session is buried inside one slow operation, the agent stops feeling like an operator and starts feeling like a loading spinner with opinions.

OpenClaw sub-agents are built for that split. The official docs describe them as background agent runs spawned from an existing agent run. Each sub-agent gets its own session key shaped like agent:<agentId>:subagent:<uuid>, runs separately, and announces the result back to the requester chat when it finishes.

That is the important operating boundary: the parent stays available, the child gets isolated context, and the result comes back as a completion handoff instead of a pile of raw logs.

Use sub-agents when the work has weight

I would not spawn a sub-agent for a tiny answer. The overhead is real because each sub-agent has its own context and token usage. The docs call this out directly, and they recommend using cheaper sub-agent models for heavy or repetitive tasks when that makes sense.

But once the job has weight, isolation is worth it. Good sub-agent tasks include code fixes, bug hunts, browser automation, long research, release checks, log audits, and workflows where the child may need to run tools for several minutes. Those are the jobs where the parent should coordinate, not sit silently.

The simplest tool call is sessions_spawn. For OpenClaw-native sub-agents, the runtime defaults to subagent, so you do not have to set a runtime unless you are deliberately starting an ACP harness session.

{
  "task": "Audit the checkout flow, run the relevant tests, and return a concise result.",
  "label": "checkout-audit",
  "runTimeoutSeconds": 1800,
  "cleanup": "keep"
}

The useful fields are practical: task is required, label makes the run easier to inspect, runTimeoutSeconds stops an endless child turn, and cleanup controls whether the sub-agent session is kept or archived after announcement. If you omit runTimeoutSeconds, OpenClaw uses configured sub-agent defaults when present; otherwise the documented fallback is no timeout. For production operations, I do not like no-timeout children. Put a ceiling on the run.

The parent should own the brief

A weak sub-agent prompt creates weak work. "Look into this" is not enough. The parent should give the child the exact target, the required proof, the allowed scope, and the expected completion shape.

For example, a good parent brief for a website issue says which repo to use, what URL or page is broken, what tests or build checks matter, whether a preview deploy is required, and who owns the final user-facing completion update. That is not ceremony. It prevents the sub-agent from finishing with "I think it is fixed" when the operator needed a live URL, a commit, and a deploy check.

The docs also note a small but critical delivery detail: sessions_spawn does not accept channel delivery params such as target, channel, to, threadId, replyTo, or transport. If a spawned run needs to send to a channel, it should use message or sessions_send from inside that run. That means the parent must pass thread and channel context in the task text when the child needs to post somewhere specific.

Know what comes back

Sub-agent completion is not just a normal chat reply. The docs explain that OpenClaw runs an announce step when the child finishes. The handoff includes the result, runtime status, compact runtime and token stats, session identifiers, and the transcript path. The requester agent is supposed to rewrite that internal handoff in normal assistant voice, not paste raw metadata at the user.

That matters because sub-agent output is an operational artifact. The parent should convert it into a concise result: what changed, what proof passed, what is blocked, or what needs a decision. Raw child logs are for inspection, not for dumping into Slack or a customer thread.

The announce path is best-effort. The docs warn that if the gateway restarts, pending announce-back work can be lost. So for important jobs, I still want durable proof in the repo, task tracker, state file, deploy URL, or control surface. The announce tells the parent what happened. The artifact proves it.

Use thread-bound sessions only when follow-up belongs there

Most sub-agent work should be a one-shot run. The parent spawns it, the child finishes, and the parent summarizes. That is enough for many tasks.

Sometimes the child should stay attached to a thread. The docs say sessions_spawn can request thread: true, and when mode: "session" is used, it requires thread binding. In that shape, follow-up messages in the bound thread route back to the same sub-agent session.

{
  "task": "Stay with this support incident until the deploy proof is verified.",
  "thread": true,
  "mode": "session",
  "runTimeoutSeconds": 3600
}

Use this for incidents, support investigations, or work where the operator will keep steering the same child in the same thread. Do not use it as a default for every task. Persistent child sessions are useful when continuity matters; otherwise they become another place for context to drift.

Do not confuse sub-agents with ACP

OpenClaw has another delegation surface: ACP sessions. The ACP docs are explicit about the difference. Use ACP when you want an external harness runtime such as Codex, Claude Code, Cursor, Gemini CLI, OpenCode, or another ACPX-backed agent. Use normal sub-agents when you want OpenClaw-native delegated runs.

The session keys make the distinction visible: ACP sessions use agent:<agentId>:acp:<uuid>, while sub-agents use agent:<agentId>:subagent:<uuid>. The spawn tool is still sessions_spawn, but for ACP you must set runtime: "acp" explicitly.

{
  "task": "Open the repo, fix the failing test, and summarize the commit.",
  "runtime": "acp",
  "agentId": "codex",
  "mode": "run"
}

There are safety implications. The ACP docs say ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox. A sandboxed requester session cannot spawn ACP sessions, and sandbox: "require" is unsupported for runtime: "acp". If you need sandbox-enforced execution, use runtime: "subagent".

That is the operator rule: use sub-agents for isolated native delegation, and ACP for external coding harnesses when host-runtime permissions are acceptable and configured.

Set defaults before you scale

Sub-agent defaults belong in configuration, not in every prompt. The docs list defaults for model, thinking, run timeout, archive behavior, depth, and concurrency. A simple default block keeps parent agents from inventing a new timeout or model policy every time they delegate.

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "openai/gpt-5.5",
        "runTimeoutSeconds": 1800,
        "maxSpawnDepth": 1,
        "maxConcurrent": 8
      }
    }
  }
}

Depth is worth treating carefully. By default, sub-agents cannot spawn their own sub-agents. The docs describe this as maxSpawnDepth: 1. You can enable an orchestrator pattern by setting maxSpawnDepth: 2, where a depth-1 orchestrator can spawn depth-2 workers and synthesize their results.

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,
        "maxChildrenPerAgent": 5,
        "maxConcurrent": 8,
        "runTimeoutSeconds": 1800
      }
    }
  }
}

That is powerful, but it should not be casual. The docs say depth-1 orchestrators get session management tools such as sessions_spawn, subagents, sessions_list, and sessions_history only when depth 2 is enabled. Depth-2 workers cannot spawn further children. There are also per-agent child limits and cascade stop behavior, so killing an orchestrator stops its workers.

The shape is sane: one parent, one optional orchestrator layer, leaf workers below it, and results flowing back up the chain. More than that is usually a management problem disguised as architecture.

Keep the tool surface tight

The default sub-agent tool policy is intentionally restricted around session controls. The docs say sub-agents get all tools except session tools and system tools by default. Session tools are added only for depth-1 orchestrators when nesting is enabled.

That prevents a normal leaf worker from becoming an accidental coordinator. It can do the assigned work, but it cannot freely spawn more sessions or manage the parent lane. If the task needs orchestration, make that explicit in the config and prompt.

Sandbox inheritance also matters. The docs say if the requester session is sandboxed, sessions_spawn rejects targets that would run unsandboxed. For operator work, that is the right default. A child should not silently escape the safety posture of the parent.

The runbook I trust

When I use sub-agents for serious work, I want the parent to do five things:

1. Name the job: give the child a label and a specific outcome.
2. Set a timeout: long work is fine; unbounded work is not.
3. Pass the proof requirement: build result, test output, live URL, state file, commit, or clear blocker.
4. Control delivery: decide whether the child posts directly or the parent summarizes exactly once.
5. Store the result: write durable task state when the result must survive a lost announce.

That is how you keep the main chat useful while still letting agents do real work. The parent coordinates. The child executes. The completion comes back as a verified result, not as a stream of half-finished thinking.

Sub-agents do not make agents magically better. They make responsibility clearer. That is usually the difference between an AI assistant that can answer questions and an AI operator that can keep multiple pieces of work moving without losing the room.

Want the complete guide? Get ClawKit — $9.99