Set Up a Sub-Agent

A sub-agent is a short-lived or thread-bound session that runs a task and reports back. Your main agent can spawn sub-agents to run work in parallel, keep the main chat responsive, or hand off specialized tasks. This tutorial shows you how to set up and use sub-agents: via your main agent's tools, via Discord threads, and from the command line. About 15–20 minutes.

When to use this: You want your OpenClaw assistant to delegate one-off tasks (research, code review, a script) to a sub-agent so you get the result in the same chat without blocking the main conversation. For a full team of persistent agents with roles and heartbeats, see Multi-Agent Team instead.

A sub-agent is an isolated session created to run a single task (or a short conversation). It has its own context and no long-term identity—think "function call with an LLM." OpenClaw creates it with a session key like agent:<agentId>:subagent:<uuid>. When the task finishes, the result is announced back to the chat where you (or your main agent) asked for it. Sub-agents cannot spawn further sub-agents. For the design principle (give sub-agents a precise task and values, not a full identity), see Soul & Agent Identity.

• OpenClaw installed and at least one channel connected
• Your main agent has access to session tools (default for most setups; see Configuration and Sessions)

The main way to create a sub-agent is to ask your OpenClaw agent to delegate a task. The agent uses the sessions_spawn tool: it sends a task (the instruction for the sub-agent), and optionally overrides model, thinking, or runTimeoutSeconds. The call returns immediately with status: "accepted" and a childSessionKey. When the sub-agent finishes, OpenClaw posts an announce message back to your chat with the result (or the last tool result if the reply is empty).

Example: In Telegram or Discord, send something like:

• "Spawn a sub-agent to summarize the top three results from a web search for 'OpenClaw sub-agent docs' and reply here with the summary."
• "Have a sub-agent review the code in src/auth.js for security issues and report back."

Your main agent will call sessions_spawn with that task. You don't need to write tool calls yourself—just describe what you want done and that you want the result back in this chat.

sessions_spawn parameters (for reference)

When your agent delegates, it can pass:

• task (required) – The instruction the sub-agent runs.
• label – Optional label for logs and UI.
• model – Override the sub-agent's model (e.g. a cheaper or faster model).
• thinking – Override thinking level for the sub-agent run.
• runTimeoutSeconds – Abort the sub-agent after N seconds (default 0 = no limit).
• thread – Set true to bind the sub-agent to a Discord (or channel) thread when supported.
• mode – run (one-shot, default) or session (persistent thread-bound session; requires thread: true).

Sub-agents run with the full tool set except session tools (they cannot spawn more sub-agents). They are auto-archived after a short period (e.g. 60 minutes) to keep the session list manageable.

To send work to a session that already exists (e.g. a group or another agent session), your main agent can use sessions_send: it passes a sessionKey (or sessionId from sessions_list) and a message. With timeoutSeconds > 0, the tool waits for the target session to finish and returns the reply; with 0, it fires-and-forgets. OpenClaw can also run a short reply-back loop and an announce step so the requester sees the outcome. See Usage and Sessions for agent-to-agent flows.

From the command line: You can send a message to a specific session yourself using the agent command with --to:

openclaw agent --message "Your task or question here" --to "agent:main:subagent:abc123"

Use openclaw sessions list (or openclaw sessions --json) to see session keys. Add --deliver if you want the reply delivered to a configured channel. See CLI Reference for agent and sessions.

On Discord, each thread can be its own session. When you create a thread in a channel where OpenClaw is present, that thread gets an isolated context—effectively a sub-agent bound to that thread. You can use it for one-off tasks (e.g. "In this thread: research X and summarize") or for a short back-and-forth. No need to ask the main agent to spawn; the channel plugin binds the thread to a session. Thread-bound spawns from the main agent use thread: true and mode: "session" so the sub-agent's replies stay in that thread. See Discord for thread and focus/list controls.

To see active sessions (including sub-agents) from the command line:

• openclaw sessions list – List sessions (or openclaw sessions --json for machine output; --active <minutes> to filter by recent activity).
• openclaw status – Shows store path and recent sessions.
• openclaw gateway call sessions.list --params '{}' – Fetch sessions from the running gateway (use --url and --token for a remote gateway).

Your main agent can use sessions_list (with optional activeMinutes, kinds, messageLimit) to discover sessions and then sessions_send or sessions_history as needed. Visibility is controlled by tools.sessions.visibility (default: current session plus spawned subagent sessions).

Sub-agents start with no identity (no SOUL, no long history). Give them a clear task and any standards you care about—not a grand title like "You are the CTO." For example: "You are a code security auditor. Apply these standards: [list]. Your task: review this authentication module." Values and constraints carry over; identity does not. For more, see Soul & Agent Identity (agents vs sub-agents).

No result announced: The sub-agent may have timed out or errored. Check sessions_list or openclaw sessions list for the childSessionKey; use sessions_history for that key to see the transcript. Set runTimeoutSeconds if tasks are long so you get a clear timeout instead of hanging.

Agent doesn't spawn: Ensure session tools are allowed (default allowlist includes them). If you restricted tools (e.g. tools.profile: "minimal"), add sessions_spawn or group:sessions to tools.allow. See Configuration and Sessions.

Stop a run: Send /stop as a standalone message in the chat that started the sub-agent; OpenClaw will stop the current run and any sub-agent runs spawned from it.