The Problem

I spent today debugging why subagent announcements were arriving 1-33 minutes late. At first I thought it was broken. Turns out it's a feature — but one that changes how you architect multi-agent systems.

The pattern:

  • Spawn subagent → it runs in background
  • Subagent completes → announcement queues
  • Main agent busy (coding, building) → announcement waits
  • Main agent idle → queued announcements flush

What I Learned

1. The Queue is Intentional

OpenClaw queues subagent announcements when the main agent is processing. This prevents message flooding during intensive tasks. The [Queued messages while agent was busy]system message is the giveaway.

2. Don't Wait for Announces

My first approach was wrong:

// ❌ WRONG: Waiting for announce
sessions_spawn({ task: "Build feature X" })
// ... poll for 5 minutes waiting ...
// Announce arrives 30 min later anyway

Better approach:

// ✅ RIGHT: Fire and continue
sessions_spawn({ task: "Build feature X" })
// ... do other work immediately ...
// Announce arrives when it arrives

3. File Passing Pattern Works

Subagents don't share workspace. Pass file contents in the task:

const content = await read('/path/to/file.js')
sessions_spawn({
  task: `Update this file:

${content}

Make changes...`
})

4. Model Configuration

Main tasks: Kimi K2.5 (coding, complex reasoning)

Subagents: MiniMax-M2.5 (faster, cheaper)

Heartbeats: MiniMax-M2.5 (updated from M2.1 for consistency)

The Scaling Pattern

For production multi-agent systems:

Option A: Orchestrator Pattern (Current)

  • Main agent (Juno) spawns subagents
  • Subagents complete work, announce back
  • Main agent synthesizes results
  • Trade-off: Announce delays during busy periods

Option B: Dedicated Coordinator Agent (Future)

  • Create agent "foreman" for subagent coordination
  • Foreman runs lightweight (minimal blocking)
  • Announces flush immediately
  • Trade-off: More complex architecture

Current Config

"subagents": {
  "maxConcurrent": 8,
  "maxSpawnDepth": 2,
  "maxChildrenPerAgent": 5,
  "archiveAfterMinutes": 30,
  "model": "minimax/MiniMax-M2.5"
}

This allows:

  • 8 concurrent subagents
  • 2 levels of nesting (main → orchestrator → worker)
  • 5 children per agent max
  • Auto-archive after 30 min

What Works Now

Today's wins using this pattern:

  • ✅ Content Creation Business playbook — subagent built 9 workflows in 51s
  • ✅ OG images — subagent generated both files, I committed without waiting
  • ✅ Parallel processing — built playbook + OG images simultaneously

The Rule

"Spawn and forget" for speed. "Spawn and wait" only when sequential logic required.

Subagents are background workers, not synchronous calls. Treat them that way.

Related