Sub-agents

Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (

) and, when finished, announce their result back to the requester chat channel. Each sub-agent run is tracked as a background task.

Primary goals:

• Parallelize "research / long task / slow tool" work without blocking the main run.
• Keep sub-agents isolated by default (session separation + optional sandboxing).
• Keep the tool surface hard to misuse: sub-agents do not get session tools by default.
• Support configurable nesting depth for orchestrator patterns.

Slash command

Use

to inspect or control sub-agent runs for the current session:

text
Copy
/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

shows run metadata (status, timestamps, session id, transcript path, cleanup). Use for a bounded, safety-filtered recall view; inspect the transcript path on disk when you need the raw full transcript.

Thread binding controls

These commands work on channels that support persistent thread bindings. See Thread supporting channels below.

text
Copy
/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

Spawn behavior

starts a background sub-agent as a user command (not an internal relay) and sends one final completion update back to the requester chat when the run finishes.

Non-blocking, push-based completion

Manual-spawn delivery resilience

Completion handoff metadata

Modes and ACP runtime

Context modes

Native sub-agents start isolated unless the caller explicitly asks to fork the current transcript.

Use

sparingly. It is for context-sensitive delegation, not a replacement for writing a clear task prompt.

Tool:

text

Copy

sessions_spawn

Starts a sub-agent run with

on the global lane, then runs an announce step and posts the announce reply to the requester chat channel.

Availability depends on the caller's effective tool policy. The

and profiles expose by default. The profile does not; add or use for agents that should delegate work. Channel/group, provider, sandbox, and per-agent allow/deny policies can still remove the tool after the profile stage. Use from the same session to confirm the effective tool list.

Defaults:

• Model: inherits the caller unless you set
  text

  Copy

  agents.defaults.subagents.model
  (or per-agent
  text

  Copy

  agents.list[].subagents.model
  ); an explicit
  text

  Copy

  sessions_spawn.model
  still wins.
• Thinking: inherits the caller unless you set
  text

  Copy

  agents.defaults.subagents.thinking
  (or per-agent
  text

  Copy

  agents.list[].subagents.thinking
  ); an explicit
  text

  Copy

  sessions_spawn.thinking
  still wins.
• Run timeout: if
  text

  Copy

  sessions_spawn.runTimeoutSeconds
  is omitted, OpenClaw uses
  text

  Copy

  agents.defaults.subagents.runTimeoutSeconds
  when set; otherwise it falls back to
  text

  Copy

  0
  (no timeout).

Tool parameters

The task description for the sub-agent. Optional human-readable label. Spawn under another agent id when allowed by `subagents.allowAgents`. `acp` is only for external ACP harnesses (`claude`, `droid`, `gemini`, `opencode`, or explicitly requested Codex ACP/acpx) and for `agents.list[]` entries whose `runtime.type` is `acp`. ACP-only. Resumes an existing ACP harness session when `runtime: "acp"`; ignored for native sub-agent spawns. ACP-only. Streams ACP run output to the parent session when `runtime: "acp"`; omit for native sub-agent spawns. Override the sub-agent model. Invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result. Override thinking level for the sub-agent run. Defaults to `agents.defaults.subagents.runTimeoutSeconds` when set, otherwise `0`. When set, the sub-agent run is aborted after N seconds. When `true`, requests channel thread binding for this sub-agent session. If `thread: true` and `mode` omitted, default becomes `session`. `mode: "session"` requires `thread: true`. `"delete"` archives immediately after announce (still keeps the transcript via rename). `require` rejects spawn unless the target child runtime is sandboxed. `fork` branches the requester's current transcript into the child session. Native sub-agents only. Use `fork` only when the child needs the current transcript.

Thread-bound sessions

When thread bindings are enabled for a channel, a sub-agent can stay bound to a thread so follow-up user messages in that thread keep routing to the same sub-agent session.

Thread supporting channels

Discord is currently the only supported channel. It supports persistent thread-bound subagent sessions (

with ), manual thread controls (, , , , ), and adapter keys , , , and .

Quick flow

Manual controls

Config switches

• Global default:
  text

  Copy

  session.threadBindings.enabled
  ,
  text

  Copy

  session.threadBindings.idleHours
  ,
  text

  Copy

  session.threadBindings.maxAgeHours
  .
• Channel override and spawn auto-bind keys are adapter-specific. See Thread supporting channels above.

See Configuration reference and Slash commands for current adapter details.

Allowlist

List of agent ids that can be targeted via explicit `agentId` (`["*"]` allows any). Default: only the requester agent. If you set a list and still want the requester to spawn itself with `agentId`, include the requester id in the list. Default target-agent allowlist used when the requester agent does not set its own `subagents.allowAgents`. Block `sessions_spawn` calls that omit `agentId` (forces explicit profile selection). Per-agent override: `agents.list[].subagents.requireAgentId`.

If the requester session is sandboxed,

rejects targets that would run unsandboxed.

Discovery

Use

to see which agent ids are currently allowed for . The response includes each listed agent's effective model and embedded runtime metadata so callers can distinguish PI, Codex app-server, and other configured native runtimes.

Auto-archive

• Sub-agent sessions are automatically archived after
  text

  Copy

  agents.defaults.subagents.archiveAfterMinutes
  (default
  text

  Copy

  60
  ).
• Archive uses
  text

  Copy

  sessions.delete
  and renames the transcript to
  text

  Copy

  *.deleted.<timestamp>
  (same folder).
• text

  Copy

  cleanup: "delete"
  archives immediately after announce (still keeps the transcript via rename).
• Auto-archive is best-effort; pending timers are lost if the gateway restarts.
• text

  Copy

  runTimeoutSeconds
  does not auto-archive; it only stops the run. The session remains until auto-archive.
• Auto-archive applies equally to depth-1 and depth-2 sessions.
• Browser cleanup is separate from archive cleanup: tracked browser tabs/processes are best-effort closed when the run finishes, even if the transcript/session record is kept.

Nested sub-agents

By default, sub-agents cannot spawn their own sub-agents (

). Set to enable one level of nesting — the orchestrator pattern: main → orchestrator sub-agent → worker sub-sub-agents.

json5
Copy
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
      },
    },
  },
}

Depth levels

Announce chain

Results flow back up the chain:

1. Depth-2 worker finishes → announces to its parent (depth-1 orchestrator).
2. Depth-1 orchestrator receives the announce, synthesizes results, finishes → announces to main.
3. Main agent receives the announce and delivers to the user.

Each level only sees announces from its direct children.

Tool policy by depth

• Role and control scope are written into session metadata at spawn time. That keeps flat or restored session keys from accidentally regaining orchestrator privileges.
• Depth 1 (orchestrator, when
  text

  Copy

  maxSpawnDepth >= 2
  ): gets
  text

  Copy

  sessions_spawn
  ,
  text

  Copy

  subagents
  ,
  text

  Copy

  sessions_list
  ,
  text

  Copy

  sessions_history
  so it can manage its children. Other session/system tools remain denied.
• Depth 1 (leaf, when
  text

  Copy

  maxSpawnDepth == 1
  ): no session tools (current default behavior).
• Depth 2 (leaf worker): no session tools —
  text

  Copy

  sessions_spawn
  is always denied at depth 2. Cannot spawn further children.

Per-agent spawn limit

Each agent session (at any depth) can have at most

(default ) active children at a time. This prevents runaway fan-out from a single orchestrator.

Cascade stop

Stopping a depth-1 orchestrator automatically stops all its depth-2 children:

• text

  Copy

  /stop
  in the main chat stops all depth-1 agents and cascades to their depth-2 children.
• text

  Copy

  /subagents kill <id>
  stops a specific sub-agent and cascades to its children.
• text

  Copy

  /subagents kill all
  stops all sub-agents for the requester and cascades.

Authentication

Sub-agent auth is resolved by agent id, not by session type:

• The sub-agent session key is
  text

  Copy

  agent:<agentId>:subagent:<uuid>
  .
• The auth store is loaded from that agent's
  text

  Copy

  agentDir
  .
• The main agent's auth profiles are merged in as a fallback; agent profiles override main profiles on conflicts.

The merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.

Announce

Sub-agents report back via an announce step:

• The announce step runs inside the sub-agent session (not the requester session).
• If the sub-agent replies exactly
  text

  Copy

  ANNOUNCE_SKIP
  , nothing is posted.
• If the latest assistant text is the exact silent token
  text

  Copy

  NO_REPLY
  /
  text

  Copy

  no_reply
  , announce output is suppressed even if earlier visible progress existed.

Delivery depends on requester depth:

• Top-level requester sessions use a follow-up
  text

  Copy

  agent
  call with external delivery (
  text

  Copy

  deliver=true
  ).
• Nested requester subagent sessions receive an internal follow-up injection (
  text

  Copy

  deliver=false
  ) so the orchestrator can synthesize child results in-session.
• If a nested requester subagent session is gone, OpenClaw falls back to that session's requester when available.

For top-level requester sessions, completion-mode direct delivery first resolves any bound conversation/thread route and hook override, then fills missing channel-target fields from the requester session's stored route. That keeps completions on the right chat/topic even when the completion origin only identifies the channel.

Child completion aggregation is scoped to the current requester run when building nested completion findings, preventing stale prior-run child outputs from leaking into the current announce. Announce replies preserve thread/topic routing when available on channel adapters.

Announce context

Announce context is normalized to a stable internal event block:

Terminal failed runs report failure status without replaying captured reply text. On timeout, if the child only got through tool calls, announce can collapse that history into a short partial-progress summary instead of replaying raw tool output.

Stats line

Announce payloads include a stats line at the end (even when wrapped):

• Runtime (e.g.
  text

  Copy

  runtime 5m12s
  ).
• Token usage (input/output/total).
• Estimated cost when model pricing is configured (
  text

  Copy

  models.providers.*.models[].cost
  ).
• text

  Copy

  sessionKey
  ,
  text

  Copy

  sessionId
  , and transcript path so the main agent can fetch history via
  text

  Copy

  sessions_history
  or inspect the file on disk.

Internal metadata is meant for orchestration only; user-facing replies should be rewritten in normal assistant voice.

Why prefer

text

Copy

sessions_history

is the safer orchestration path:

• Assistant recall is normalized first: thinking tags stripped;
  text

  Copy

  <relevant-memories>
  /
  text

  Copy

  <relevant_memories>
  scaffolding stripped; plain-text tool-call XML payload blocks (
  text

  Copy

  <tool_call>
  ,
  text

  Copy

  <function_call>
  ,
  text

  Copy

  <tool_calls>
  ,
  text

  Copy

  <function_calls>
  ) stripped, including truncated payloads that never close cleanly; downgraded tool-call/result scaffolding and historical-context markers stripped; leaked model control tokens (
  text

  Copy

  <|assistant|>
  , other ASCII
  text

  Copy

  <|...|>
  , full-width
  text

  Copy

  <｜...｜>
  ) stripped; malformed MiniMax tool-call XML stripped.
• Credential/token-like text is redacted.
• Long blocks can be truncated.
• Very large histories can drop older rows or replace an oversized row with
  text

  Copy

  [sessions_history omitted: message too large]
  .
• Raw on-disk transcript inspection is the fallback when you need the full byte-for-byte transcript.

Tool policy

Sub-agents use the same profile and tool-policy pipeline as the parent or target agent first. After that, OpenClaw applies the sub-agent restriction layer.

With no restrictive

, sub-agents get all tools except session tools and system tools:

• text

  Copy

  sessions_list
• text

  Copy

  sessions_history
• text

  Copy

  sessions_send
• text

  Copy

  sessions_spawn

remains a bounded, sanitized recall view here too — it is not a raw transcript dump.

When

, depth-1 orchestrator sub-agents additionally receive , , , and so they can manage their children.

Override via config

json5
Copy
{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

is a final allow-only filter. It can narrow the already-resolved tool set, but it cannot add back a tool removed by . For example, includes / but not the tool. To let coding-profile sub-agents use browser automation, add browser at the profile stage:

json5
Copy
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

Use per-agent

when only one agent should get browser automation.

Concurrency

Sub-agents use a dedicated in-process queue lane:

• Lane name:
  text

  Copy

  subagent
• Concurrency:
  text

  Copy

  agents.defaults.subagents.maxConcurrent
  (default
  text

  Copy

  8
  )

Liveness and recovery

OpenClaw does not treat

absence as permanent proof that a sub-agent is still alive. Unended runs older than the stale-run window stop counting as active/pending in , status summaries, descendant completion gating, and per-session concurrency checks.

After a gateway restart, stale unended restored runs are pruned unless their child session is marked

. Those restart-aborted child sessions remain recoverable through the sub-agent orphan recovery flow, which sends a synthetic resume message before clearing the aborted marker.

Automatic restart recovery is bounded per child session. If the same sub-agent child is accepted for orphan recovery repeatedly inside the rapid re-wedge window, OpenClaw persists a recovery tombstone on that session and stops auto-resuming it on later restarts. Run

to reconcile the task record, or to clear stale aborted recovery flags on tombstoned sessions.

Stopping

• Sending
  text

  Copy

  /stop
  in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.
• text

  Copy

  /subagents kill <id>
  stops a specific sub-agent and cascades to its children.

Limitations

• Sub-agent announce is best-effort. If the gateway restarts, pending "announce back" work is lost.
• Sub-agents still share the same gateway process resources; treat
  text

  Copy

  maxConcurrent
  as a safety valve.
• text

  Copy

  sessions_spawn
  is always non-blocking: it returns
  text

  Copy

  { status: "accepted", runId, childSessionKey }
  immediately.
• Sub-agent context only injects
  text

  Copy

  AGENTS.md
  +
  text

  Copy

  TOOLS.md
  (no
  text

  Copy

  SOUL.md
  ,
  text

  Copy

  IDENTITY.md
  ,
  text

  Copy

  USER.md
  ,
  text

  Copy

  HEARTBEAT.md
  , or
  text

  Copy

  BOOTSTRAP.md
  ).
• Maximum nesting depth is 5 (
  text

  Copy

  maxSpawnDepth
  range: 1–5). Depth 2 is recommended for most use cases.
• text

  Copy

  maxChildrenPerAgent
  caps active children per session (default
  text

  Copy

  5
  , range
  text

  Copy

  1–20
  ).

Related

• ACP agents
• Agent send
• Background tasks
• Multi-agent sandbox tools