Multi-Agent Orchestration with OpenClaw: Building Your AI Team

Introduction: Why One Agent Isn’t Enough

A single AI agent is powerful. But complex workflows demand a team.

Think about your own work — you delegate. The same principle applies to AI agents. A researcher gathers data, a coder builds, a writer drafts, a reviewer checks. No single person (or agent) does it all well.

Multi-agent orchestration coordinates multiple AI agents, each with specialized roles, to accomplish tasks too complex or too slow for one agent alone.

In this guide, you’ll learn:

• Why multi-agent systems outperform single agents
• How to architect an AI team with OpenClaw
• Practical patterns for task delegation using sessions_spawn
• Security considerations for multi-agent deployments

“Context appears at disparate sources, by user activity or changes in the user’s environment: what they’re working on changes, emails appear, documents are edited, it’s no longer sunny outside, the available tools have been updated. This context is not always where the AI runs (and the AI runs as closer as possible to the point of user intent). So the job of making an agent run really well is to move the context to where it needs to be.”

— Matt Webb (@genmon), interconnected.org

---

Why Multi-Agent Systems?

The Single-Agent Bottleneck

A single AI agent hits walls fast:

1. Context window limits: Even large models can only hold so much information at once
2. Task switching overhead: Jumping between research, coding, and writing degrades output quality
3. No specialization: A generalist agent is adequate at everything, expert at nothing
4. Single point of failure: If it gets stuck, the whole workflow stalls
5. Sequential execution: One agent means one task at a time

The Multi-Agent Advantage

With multiple agents:

✅ Specialization: Each agent focuses on what it does best — research, coding, analysis, or writing
✅ Parallel execution: Multiple tasks run simultaneously via sessions_spawn
✅ Contextual depth: Each agent maintains focused, domain-specific context
✅ Fault tolerance: One agent failing doesn’t stop the others
✅ Cost efficiency: Route simple tasks to cheaper models, complex ones to stronger models

---

Multi-Agent Patterns

Pattern 1: Leader-Worker (Hierarchical)

One orchestrator agent delegates tasks to specialized worker agents. This is OpenClaw’s native pattern via sessions_spawn.

Architecture

┌─────────────────────┐
│    Orchestrator     │  ← User interacts here
│ (Claude Opus 4.5)  │
└──────────┬──────────┘
           │ sessions_spawn
   ┌───────┼───────┬──────────┐
   │       │       │          │
┌──▼──┐ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐
│Code │ │Data │ │Write│ │ QA  │
│Agent│ │Agent│ │Agent│ │Agent│
└─────┘ └─────┘ └─────┘ └─────┘
  Each announces results back to orchestrator

When to Use

• Complex multi-step workflows
• Tasks requiring different skill sets or models
• When you need a central coordinator that stays responsive

Example: Code Review Workflow

User request: “Review this pull request and generate a report.”

Orchestrator (Kev):

1. Spawns Code Agent: “Analyze this PR for bugs and code quality issues.”
2. Spawns Data Agent: “Fetch git history and check for breaking changes.”
3. Both run in parallel, announce results back.
4. Spawns Write Agent: “Draft a review summary from these findings.”
5. Returns final report to user.

OpenClaw Implementation

OpenClaw supports multi-agent orchestration through two complementary mechanisms: agent routing (isolated agents with separate workspaces) and sub-agents (spawned tasks via sessions_spawn).

Agent routing gives each agent its own workspace, sessions, and identity:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-sonnet-4-5"
    },
    list: [
      {
        id: "orchestrator",
        default: true,
        identity: { name: "Orchestrator", emoji: "🎯" },
        workspace: "~/.openclaw/workspace-orchestrator",
        model: "anthropic/claude-opus-4-5"
      },
      {
        id: "code-agent",
        identity: { name: "Code Reviewer", emoji: "💻" },
        workspace: "~/.openclaw/workspace-code",
        model: "anthropic/claude-sonnet-4-5"
      },
      {
        id: "data-agent",
        identity: { name: "Data Analyst", emoji: "📊" },
        workspace: "~/.openclaw/workspace-data",
        model: "openai/gpt-5.2"
      }
    ]
  },
  bindings: [
    { agentId: "orchestrator", match: { channel: "whatsapp" } }
  ]
}

Sub-agents let any agent spawn background tasks that announce results back:

// The orchestrator's AGENTS.md instructs it to delegate:
// "Use sessions_spawn to delegate research and coding tasks."

// At runtime, the orchestrator calls:
// sessions_spawn task="Analyze PR #42 for bugs" agentId="code-agent"
// sessions_spawn task="Check git history for breaking changes" agentId="data-agent"

Each sub-agent runs in its own session (agent:<agentId>:subagent:<uuid>), and when finished, announces its result back to the orchestrator’s chat channel.

---

Pattern 2: Peer-to-Peer (Collaborative)

Agents work as equals, passing tasks to each other based on expertise.

Architecture

┌──────┐       ┌──────┐
│Agent1│◄─────►│Agent2│
└───┬──┘       └───┬──┘
    │              │
    │   ┌──────┐   │
    └──►│Agent3│◄──┘
        └──────┘

When to Use

• Research and exploration tasks
• When no single agent “owns” the workflow
• Collaborative problem-solving with iterative refinement

Example: Research Workflow

User request: “Research OpenClaw security best practices.”

Agent 1 (Web Search): Searches for articles and documentation.
Agent 2 (Summarizer): Summarizes findings from Agent 1.
Agent 3 (Critic): Critiques Agent 2’s summary, identifies gaps.
Agent 1: Searches for missing information based on Agent 3’s feedback.
Agent 2: Refines summary with new data.

In OpenClaw, peer-to-peer communication requires enabling tools.agentToAgent:

{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["search-agent", "summarizer", "critic"]
    }
  }
}

---

Pattern 3: Pipeline (Sequential)

Agents process data in a fixed sequence, each adding value.

Architecture

Input → Agent1 → Agent2 → Agent3 → Output

When to Use

• ETL (Extract, Transform, Load) workflows
• Content creation pipelines
• Data processing chains

Example: Blog Post Pipeline

User request: “Write a blog post about prompt injection.”

Agent 1 (Researcher): Gathers information about prompt injection.
Agent 2 (Writer): Drafts a blog post based on research.
Agent 3 (Editor): Edits for clarity, SEO, and style.
Agent 4 (Publisher): Formats and publishes to CMS.

In OpenClaw, pipelines are orchestrated by chaining sessions_spawn calls, where each sub-agent’s announce triggers the next step.

---

Real-World Example: AI Team with Sub-Agents

Let’s build a practical AI team using OpenClaw’s sessions_spawn — the most common multi-agent pattern.

The Setup

An orchestrator agent (“Kev”) stays responsive to the user while spawning specialized sub-agents for real work:

Role	Agent ID	Model	Purpose
Orchestrator	kev	Claude Opus 4.5	Coordinates, delegates, stays responsive
Developer	rex	Claude Sonnet 4.5	Code, debugging, deployments
Researcher	scout	GPT-5.2	Web research, analysis
Writer	echo	Claude Sonnet 4.5	Content, reports, documentation

Configuration

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4-5",
      subagents: {
        maxConcurrent: 8,
        archiveAfterMinutes: 60
      }
    },
    list: [
      {
        id: "kev",
        default: true,
        identity: { name: "Kev", emoji: "🦈" },
        workspace: "~/.openclaw/workspace-kev",
        model: "anthropic/claude-opus-4-5",
        subagents: {
          allowAgents: ["rex", "scout", "echo"]
        }
      },
      {
        id: "rex",
        identity: { name: "Rex", emoji: "🦖" },
        workspace: "~/.openclaw/workspace-rex",
        model: "anthropic/claude-sonnet-4-5",
        sandbox: { mode: "all", scope: "agent" }
      },
      {
        id: "scout",
        identity: { name: "Scout", emoji: "🔍" },
        workspace: "~/.openclaw/workspace-scout",
        model: "openai/gpt-5.2",
        tools: {
          allow: ["read", "web_search", "web_fetch", "browser"],
          deny: ["write", "edit", "exec"]
        }
      },
      {
        id: "echo",
        identity: { name: "Echo", emoji: "🦜" },
        workspace: "~/.openclaw/workspace-echo",
        model: "anthropic/claude-sonnet-4-5"
      }
    ]
  },
  bindings: [
    { agentId: "kev", match: { channel: "whatsapp" } }
  ],
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"]
    }
  }
}

How It Works

1. User messages Kev via WhatsApp: “Build a landing page for our new product.”
2. Kev stays responsive, spawning tasks:

   sessions_spawn task="Research competitor landing pages" agentId="scout"
   sessions_spawn task="Write landing page copy" agentId="echo"

3. Scout and Echo work in parallel, each in their own session.
4. Results announce back to the WhatsApp chat automatically.
5. Kev coordinates: “Now Rex, build the page using Scout’s research and Echo’s copy.”

   sessions_spawn task="Build landing page with these specs..." agentId="rex"

Key Sub-Agent Behaviors

• Non-blocking: sessions_spawn returns immediately with { status: "accepted", runId, childSessionKey }.
• Automatic announce: When a sub-agent finishes, it posts a summary back to the requester’s chat.
• Cost-aware: Each sub-agent has its own token usage. Use cheaper models for simple tasks.
• No nesting: Sub-agents cannot spawn sub-agents (prevents runaway fan-out).
• Auto-archive: Sessions are cleaned up after archiveAfterMinutes (default: 60).

---

Task Delegation Strategies

Strategy 1: Channel-Based Routing

Route different channels to different agents — fast responses on WhatsApp, deep work on Telegram:

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5"
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-5"
      }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

Strategy 2: Peer-Based Routing

Route specific DMs or groups to specific agents:

{
  bindings: [
    // This specific person gets the Opus agent
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    // Family group gets a restricted agent
    { agentId: "family", match: { channel: "whatsapp", peer: { kind: "group", id: "120363999@g.us" } } },
    // Everything else goes to the default
    { agentId: "chat", match: { channel: "whatsapp" } }
  ]
}

Peer bindings always take precedence over channel-wide rules.

Strategy 3: Queue Management

Control how inbound messages behave when an agent is already processing:

{
  messages: {
    queue: {
      mode: "collect",        // steer | followup | collect
      debounceMs: 1000,       // Wait before processing batch
      cap: 20,                // Max messages in queue
      drop: "summarize"       // What to do when cap is hit
    },
    inbound: {
      debounceMs: 2000        // Batch rapid messages from same sender
    }
  }
}

---

Inter-Agent Communication

Pattern 1: Sub-Agent Announce

The primary communication pattern. Sub-agents report results back to the requester’s chat:

User → Orchestrator → sessions_spawn → Sub-Agent
                                            │
                                    (works in background)
                                            │
                              Announce result back to chat

Announce payloads include status, runtime, token usage, and estimated cost — giving the orchestrator full visibility into what happened.

Pattern 2: Shared Workspace

Agents read and write to shared directories. Each agent has its own workspace, but you can point multiple agents at shared folders:

{
  agents: {
    list: [
      {
        id: "researcher",
        workspace: "~/project/research"
      },
      {
        id: "writer",
        workspace: "~/project/content"
      }
    ]
  }
}

The researcher writes findings to ~/project/research/output/, and the writer reads them. Simple, file-based coordination.

Pattern 3: Agent-to-Agent Messaging

For direct inter-agent communication, enable the opt-in agentToAgent tool:

{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["home", "work"]
    }
  }
}

This is off by default — agent-to-agent messaging must be explicitly enabled and allowlisted.

---

Security in Multi-Agent Systems

⚠️ Multi-agent systems amplify security risks. If one agent is compromised, it can poison the entire workflow.

“The ability for agents to write to each other’s settings and configuration files opens up a fascinating, and concerning, novel category of exploit chains. What starts as a single indirect prompt injection can quickly escalate into a multi-agent compromise, where one agent ‘frees’ another agent and sets up a loop of escalating privilege and control.”

— Johann Rehberger, embracethered.com

Risk 1: Agent Impersonation

Attack: Malicious input tricks an agent into impersonating another.

Defense:

• Channel authentication: Use OpenClaw’s pairing system for DMs
• Allowlists: Restrict which senders can trigger each agent
• Isolated auth: Each agent has its own agentDir with separate auth-profiles.json — never share agentDir across agents

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"]
    },
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: ["tg:123456789"]
    }
  }
}

Risk 2: Prompt Injection Propagation

Attack: Malicious input to Agent 1 propagates through sub-agent chains.

Defense:

• Tool restrictions: Limit what each agent can do
• Sandbox isolation: Run untrusted agents in Docker containers
• No nesting: Sub-agents cannot spawn sub-agents, preventing recursive injection chains

{
  agents: {
    list: [
      {
        id: "public-agent",
        sandbox: {
          mode: "all",       // Always sandboxed
          scope: "agent"     // One container per agent
        },
        tools: {
          allow: ["read", "web_search"],
          deny: ["exec", "write", "edit", "apply_patch", "browser"]
        }
      }
    ]
  }
}

Risk 3: Privilege Escalation

Attack: Low-privilege agent spawns work under a high-privilege agent.

Defense:

• Allowlists for spawn targets: Control which agents can be targeted via sessions_spawn
• Per-agent tool policies: Each agent has independent allow/deny lists
• Sandbox layering: Mix access levels in one gateway

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" }
        // Full access — no tool restrictions
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro"
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "session_status"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
        },
        subagents: {
          allowAgents: []  // Cannot spawn under other agents
        }
      }
    ]
  }
}

The tool filtering order enforces defense-in-depth: global policy → agent policy → sandbox policy → subagent policy. Each level can only further restrict — never grant back denied tools.

---

Monitoring & Debugging Multi-Agent Systems

Challenge 1: Tracing Execution

With multiple agents and sub-agents, tracing who did what is essential.

Solution: OpenClaw’s logging system with per-agent session keys.

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools"
  }
}

Every sub-agent session is keyed as agent:<agentId>:subagent:<uuid>, making it straightforward to filter logs by agent.

Challenge 2: Inspecting Sub-Agents

Solution: Use the /subagents slash command in any chat:

/subagents list              # See all active sub-agents
/subagents info <id>         # Run metadata, status, timestamps
/subagents log <id> 50       # Last 50 transcript entries
/subagents stop <id>         # Kill a runaway sub-agent
/subagents send <id> <msg>   # Send a message to a running sub-agent

Challenge 3: Gateway Health

Solution: Monitor the Gateway and active sessions:

# Check Gateway status
openclaw gateway status

# List active sessions across all agents
openclaw sessions

# List agents and their bindings
openclaw agents list --bindings

# Follow logs in real time
openclaw logs --follow

# Run diagnostics
openclaw doctor

Challenge 4: Performance Bottlenecks

Sub-agent announce payloads include runtime and token usage, making it easy to spot slow or expensive agents. Configure sub-agent concurrency to prevent resource exhaustion:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 8  // Safety valve for parallel sub-agents
      }
    }
  }
}

---

Best Practices

1. Keep Agents Focused

Each agent should have one clear responsibility. Write it into their AGENTS.md.

❌ Bad: “Agent that codes, writes, researches, and manages infrastructure”
✅ Good: Separate coder, writer, researcher, and DevOps agents

2. Design for Failure

Agents will fail. Plan for it.

• Timeouts: Set runTimeoutSeconds on sessions_spawn to kill stuck sub-agents
• Auto-archive: Sessions clean up after archiveAfterMinutes (default: 60)
• Queue management: Use drop: "summarize" to handle message overflow gracefully

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 8,
        archiveAfterMinutes: 60
      }
    }
  },
  messages: {
    queue: {
      mode: "collect",
      cap: 20,
      drop: "summarize"
    }
  }
}

3. Limit Agent Autonomy

Don’t let agents run wild.

• Approval gates: Use dmPolicy: "pairing" for sensitive channels
• Tool restrictions: Use per-agent tools.allow / tools.deny
• Sandboxing: Run untrusted agents in Docker with sandbox.mode: "all"
• Spawn limits: Control which agents can target others via subagents.allowAgents

{
  agents: {
    list: [
      {
        id: "restricted-agent",
        sandbox: { mode: "all", scope: "agent" },
        tools: {
          allow: ["read", "web_search"],
          deny: ["exec", "write", "edit", "apply_patch"]
        },
        subagents: {
          allowAgents: []  // Cannot spawn under other agents
        }
      }
    ]
  }
}

4. Use the Right Model for the Job

Not every task needs the most expensive model. Route simple work to cheaper models and reserve heavy reasoning for complex tasks:

Task Type	Recommended Model	Why
Orchestration	Claude Opus 4.5	Complex reasoning, coordination
Coding	Claude Sonnet 4.5	Strong code generation, good cost/quality
Research	GPT-5.2	Broad knowledge, tool use
Simple triage	Gemini 3	Fast, cost-effective

Configure per-agent models in agents.list[].model, or override per-spawn:

sessions_spawn task="Quick categorization" model="google/gemini-3"

5. Test Agent Interactions

Test not just individual agents, but agent-to-agent handoffs.

# Send a test message directly to an agent
openclaw agent --agent rex --message "Run tests on the main branch"

# Verify agent routing
openclaw agents list --bindings

# Check sub-agent activity
# (in chat) /subagents list

---

Conclusion: Your AI Team Awaits

Multi-agent orchestration unlocks complex workflows that a single agent can’t handle. OpenClaw’s sessions_spawn makes this practical — spawn specialized agents, let them work in parallel, and get results announced back automatically.

Key takeaways:

• ✅ Use leader-worker, peer-to-peer, or pipeline patterns based on your workflow
• ✅ Specialize agents with focused AGENTS.md instructions and appropriate models
• ✅ Delegate via sessions_spawn to keep your orchestrator responsive
• ✅ Secure agent communication with per-agent sandboxing, tool restrictions, and spawn allowlists
• ✅ Monitor and debug with /subagents, logging, and openclaw doctor

Ready to build your AI team? Start with the OpenClaw documentation and the openclaw agents add wizard.