​

Sub-agents

​

Slash command

• /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>]

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

​

Spawn behavior

• The spawn command is non-blocking; it returns a run id immediately.
• On completion, the sub-agent announces a summary/result message back to the requester chat channel.
• For manual spawns, delivery is resilient:
  • OpenClaw tries direct agent delivery first with a stable idempotency key.
  • If direct delivery fails, it falls back to queue routing.
  • If queue routing is still not available, the announce is retried with a short exponential backoff before final give-up.
• The completion handoff to the requester session is runtime-generated internal context (not user-authored text) and includes:
  • Result (assistant reply text, or latest toolResult if the assistant reply is empty)
  • Status (completed successfully / failed / timed out / unknown)
  • compact runtime/token stats
  • a delivery instruction telling the requester agent to rewrite in normal assistant voice (not forward raw internal metadata)
• --model and --thinking override defaults for that specific run.
• Use info/log to inspect details and output after completion.
• /subagents spawn is one-shot mode (mode: "run"). For persistent thread-bound sessions, use sessions_spawn with thread: true and mode: "session".
• For ACP harness sessions (Codex, Claude Code, Gemini CLI), use sessions_spawn with runtime: "acp" and see ACP Agents.

• 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.

​

Tool

• Starts a sub-agent run (deliver: false, global lane: subagent)
• Then runs an announce step and posts the announce reply to the requester chat channel
• Default model: inherits the caller unless you set agents.defaults.subagents.model (or per-agent agents.list[].subagents.model); an explicit sessions_spawn.model still wins.
• Default thinking: inherits the caller unless you set agents.defaults.subagents.thinking (or per-agent agents.list[].subagents.thinking); an explicit sessions_spawn.thinking still wins.
• Default run timeout: if sessions_spawn.runTimeoutSeconds is omitted, OpenClaw uses agents.defaults.subagents.runTimeoutSeconds when set; otherwise it falls back to 0 (no timeout).

• task (required)
• label? (optional)
• agentId? (optional; spawn under another agent id if allowed)
• model? (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)
• thinking? (optional; overrides thinking level for the sub-agent run)
• runTimeoutSeconds? (defaults to agents.defaults.subagents.runTimeoutSeconds when set, otherwise 0; when set, the sub-agent run is aborted after N seconds)
• thread? (default false; when true, requests channel thread binding for this sub-agent session)
• mode? (run|session)
  • default is run
  • if thread: true and mode omitted, default becomes session
  • mode: "session" requires thread: true
• cleanup? (delete|keep, default keep)
• sandbox? (inherit|require, default inherit; require rejects spawn unless target child runtime is sandboxed)
• sessions_spawn does not accept channel-delivery params (target, channel, to, threadId, replyTo, transport). For delivery, use message/sessions_send from the spawned run.

​

Thread-bound sessions

​

Thread supporting channels

• Discord (currently the only supported channel): supports persistent thread-bound subagent sessions (sessions_spawn with thread: true), manual thread controls (/focus, /unfocus, /agents, /session idle, /session max-age), and adapter keys channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours, and channels.discord.threadBindings.spawnSubagentSessions.

1. Spawn with sessions_spawn using thread: true (and optionally mode: "session").
2. OpenClaw creates or binds a thread to that session target in the active channel.
3. Replies and follow-up messages in that thread route to the bound session.
4. Use /session idle to inspect/update inactivity auto-unfocus and /session max-age to control the hard cap.
5. Use /unfocus to detach manually.

• /focus <target> binds the current thread (or creates one) to a sub-agent/session target.
• /unfocus removes the binding for the current bound thread.
• /agents lists active runs and binding state (thread:<id> or unbound).
• /session idle and /session max-age only work for focused bound threads.

• Global default: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours
• Channel override and spawn auto-bind keys are adapter-specific. See Thread supporting channels above.

• agents.list[].subagents.allowAgents: list of agent ids that can be targeted via agentId (["*"] to allow any). Default: only the requester agent.
• Sandbox inheritance guard: if the requester session is sandboxed, sessions_spawn rejects targets that would run unsandboxed.

• Use agents_list to see which agent ids are currently allowed for sessions_spawn.

• Sub-agent sessions are automatically archived after agents.defaults.subagents.archiveAfterMinutes (default: 60).
• Archive uses sessions.delete and renames the transcript to *.deleted.<timestamp> (same folder).
• 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.
• 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.

​

Nested Sub-Agents

​

How to enable

{
  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

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

​

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 maxSpawnDepth >= 2): Gets sessions_spawn, subagents, sessions_list, sessions_history so it can manage its children. Other session/system tools remain denied.
• Depth 1 (leaf, when maxSpawnDepth == 1): No session tools (current default behavior).
• Depth 2 (leaf worker): No session tools — sessions_spawn is always denied at depth 2. Cannot spawn further children.

​

Per-agent spawn limit

​

Cascade stop

• /stop in the main chat stops all depth-1 agents and cascades to their depth-2 children.
• /subagents kill <id> stops a specific sub-agent and cascades to its children.
• /subagents kill all stops all sub-agents for the requester and cascades.

​

Authentication

• The sub-agent session key is agent:<agentId>:subagent:<uuid>.
• The auth store is loaded from that agent’s agentDir.
• The main agent’s auth profiles are merged in as a fallback; agent profiles override main profiles on conflicts.

​

Announce

• The announce step runs inside the sub-agent session (not the requester session).
• If the sub-agent replies exactly ANNOUNCE_SKIP, nothing is posted.
• Otherwise delivery depends on requester depth:
  • top-level requester sessions use a follow-up agent call with external delivery (deliver=true)
  • nested requester subagent sessions receive an internal follow-up injection (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
• 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 is normalized to a stable internal event block:
  • source (subagent or cron)
  • child session key/id
  • announce type + task label
  • status line derived from runtime outcome (success, error, timeout, or unknown)
  • result content from the announce step (or (no output) if missing)
  • a follow-up instruction describing when to reply vs. stay silent
• Status is not inferred from model output; it comes from runtime outcome signals.

• Runtime (e.g., runtime 5m12s)
• Token usage (input/output/total)
• Estimated cost when model pricing is configured (models.providers.*.models[].cost)
• sessionKey, sessionId, and transcript path (so the main agent can fetch history via 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.

​

Tool Policy (sub-agent tools)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

{
  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"]
      },
    },
  },
}

​

Concurrency

• Lane name: subagent
• Concurrency: agents.defaults.subagents.maxConcurrent (default 8)

​

Stopping

• Sending /stop in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.
• /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 maxConcurrent as a safety valve.
• sessions_spawn is always non-blocking: it returns { status: "accepted", runId, childSessionKey } immediately.
• Sub-agent context only injects AGENTS.md + TOOLS.md (no SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, or BOOTSTRAP.md).
• Maximum nesting depth is 5 (maxSpawnDepth range: 1–5). Depth 2 is recommended for most use cases.
• maxChildrenPerAgent caps active children per session (default: 5, range: 1–20).