Sub-Agent Orchestration#

Spawn isolated sessions to execute tasks in parallel with appropriate model routing.

Critical: Sub-Agents Are Context-Blind#

Sub-agents do not see AGENTS.md, SKILL.md, SOUL.md, MEMORY.md, or any workspace context files. They only see:

1. The task string you provide
2. Whatever files you tell them to read (via paths in the task)
3. Inline attachments you pass at spawn time

Everything the sub-agent needs must be in the task spec or explicitly referenced as a file path. This includes output instructions, announce behavior, constraints, and domain knowledge.

When to Spawn#

Spawn when:

• Task benefits from a specialized model (code → Codex, research → Sonnet)
• Work can run in parallel while you continue
• Task is self-contained with clear success criteria
• Will block you for >10 seconds (the 10-Second Rule)

Don't spawn when:

• Trivial one-liner (just do it yourself)
• Task requires real-time conversation with the user
• Heavy coordination overhead exceeds benefit

Model Selection#

Task TypeModel (alias)Full pathNotesBrowser automationgpt54``openai-codex/gpt-5.4Default for all browser tasks. Native computer-use. thinking: high auto-applied.Code implementationcodex``openai-codex/gpt-5.3-codexOptimized for code genQuick code/bugscodex``openai-codex/gpt-5.3-codex-sparkFaster, simpler tasksResearch, writing, quick tasksgpt5``openai-codex/gpt-5.2Unlimited on Codex sub. Replaces sonnet/haiku for most work.Complex reasoningopus``anthropic/claude-opus-4-6Deep analysis (expensive)Huge context (>200K tokens)sonnet``anthropic/claude-sonnet-4-51M context window fallback

Use aliases when available. GPT-5.2 is unlimited on the Codex subscription — prefer it over Sonnet/Haiku for sub-agents unless you specifically need Sonnet's 1M context window.

sessions_spawn Parameters#

ParameterRequiredDefaultDescriptiontask✅—The full task description (only context the sub-agent gets)model—parent modelModel alias or full provider/model paththinking——off | low | medium | high``label——Label for logs/UI trackingrunTimeoutSeconds—config default or 0Abort after N secondscleanup—keep``delete | keep — delete removes session after completionthread—falseThread-bound routing (Discord/Slack)mode—run``run | session — defaults to session when thread=true``sandbox—inherit``inherit | require — require rejects if child isn't sandboxedagentId—current agentSpawn under another agent (must be in allowlist)attachments——Inline files: [{ name, content, encoding?, mimeType? }]

Key behaviors#

• Always non-blocking. Returns { status: "accepted", runId, childSessionKey } immediately.
• Sub-agents cannot spawn sub-agents. No nested spawning. Plan accordingly.
• Sub-agents get all tools EXCEPT session tools (no sessions_list/history/send/spawn). Configurable via tools.subagents.tools.
• Auto-archive: Sessions archive after agents.defaults.subagents.archiveAfterMinutes (default: 60).

Announce Mechanism#

After a sub-agent completes, OpenClaw runs an announce step that posts results to the requester's chat channel.

• Announce replies are normalized to Status / Result / Notes format
• Status comes from runtime outcome (success/failure/timeout), not model text
• If the assistant's final reply is empty, the latest toolResult is used as Result
• Include a stats line (runtime, tokens, sessionKey, cost)

Controlling announce behavior#

Sub-agent replies with...EffectNormal textPosted to requester's channel as the announceANNOUNCE_SKIPAnnounce is suppressed — nothing postedEmpty replyLatest toolResult becomes the Result

⚠️ Use ANNOUNCE_SKIP, not NO_REPLY. ANNOUNCE_SKIP is the specific mechanism for sub-agent announce suppression. NO_REPLY is a general silent-reply convention that may not suppress the announce step.

Task Specification — Structured Handoff Protocol#

Every spawn should follow this template. Remember: this is the only context the sub-agent receives.

Required Fields#

1. Objective — One sentence. What the sub-agent must accomplish.
2. Context — Structured facts. File paths, API endpoints, constraints, relevant decisions. Not narrative — a reference sheet.
3. Inputs — What files/data to read before starting. Be specific: paths, line ranges, sections.
4. Success criteria — How to verify done. Testable, not subjective.
5. Output contract — Where and how to deliver results. File path, format, schema.

Optional Fields#

1. Constraints — What NOT to do. Boundaries, things that already failed.
2. Domain knowledge — Project-specific context files to load (e.g., projects/foo/CONTEXT.md).
3. Decisions already made — Prevent re-litigating settled questions.

Announce instructions (include in every task)#

For silent sub-agents (results consolidated by parent):

text

Write your full analysis to [path].
Your final reply after writing the file should be ONLY: ANNOUNCE_SKIP

For sub-agents that should announce their own results:

text

Write results to [path].
Your final reply should summarize what you found — this will be posted to the chat.

Example (Good)#

text

OBJECTIVE: Analyze time-of-day patterns in Kalshi BTC spread bot single-fill losses.

CONTEXT:
- Bot code: projects/kalshi-arb/bot/spread_bot.py
- Trade log: projects/kalshi-arb/data/trades.csv (columns: timestamp, action, side, price, fill_type, pnl)
- Key finding: single-fills have 1.8% win rate vs ~83% for dual-fills
- Volume gate already exists at 150K trailing-1

INPUTS:
- Read trades.csv, filter to fill_type="single"
- Read spread_bot.py lines 180-220 (gating logic)

SUCCESS CRITERIA:
- Statistical breakdown of single-fill losses by hour (ET)
- Identify if specific time windows have >2x the loss rate
- Chi-squared or equivalent significance test

OUTPUT:
- Write analysis to projects/kalshi-arb/time-gating-analysis.md
- Include raw data table + recommendation

CONSTRAINTS:
- Don't modify bot code, analysis only
- Flag if sample size < 30 per bucket

Your final reply after writing the file should be ONLY: ANNOUNCE_SKIP

Example (Bad — Don't Do This)#

text

Look at the Kalshi bot trades and figure out if time of day matters
for single fills. The bot is in the projects folder somewhere.
Write up what you find.

The bad example forces the sub-agent to guess file locations, decide its own success criteria, and has no announce instructions.

Monitoring & Management#

subagents tool (primary orchestration)#

text

subagents(action="list")                              // List active sub-agents
subagents(action="steer", target="<id>", message="...") // Send follow-up instructions
subagents(action="kill", target="<id>")               // Kill a running sub-agent

Session tools (for history/cross-session)#

text

sessions_list({ kinds: ["other"], activeMinutes: 60 })  // Sub-agents are kind "other"
sessions_history({ sessionKey: "...", limit: 5 })        // Check output
sessions_send({ sessionKey: "...", message: "..." })     // Send to any session

Discovery#

text

agents_list()  // Discover which agentIds are allowed for sessions_spawn

Don't poll in loops. Check on-demand, when prompted, or for debugging.

Fallback Rules#

If a model is rate-limited:

1. Codex/GPT-5.2 limited → Use sonnet for code/research tasks
2. Sonnet limited → Use gpt5 for research tasks
3. All limited → Use opus directly (last resort, expensive)

Rate limits typically reset in 30-90 minutes.

Anti-Patterns#

❌ Spawning for trivial tasks — Just do simple things yourself ❌ Vague task specs — "Look into X" without success criteria or output contract ❌ Over-parallelization — Too many concurrent spawns = memory pressure ❌ Forgetting announce instructions — Every task must specify ANNOUNCE_SKIP or what to say ❌ Assuming sub-agents have context — They don't see your workspace files ❌ Using kinds: ["isolated"] — The correct kind for sub-agents is "other" ❌ Using NO_REPLY for announce suppression — Use ANNOUNCE_SKIP ❌ Expecting sub-agents to spawn their own sub-agents — They can't