A single OpenClaw agent is powerful. Multiple agents working together are transformative. This guide shows you how to set up agent teams where each member has a distinct role — a researcher, a coder, a scheduler — communicating through structured protocols and sharing context intelligently.

Why Multi-Agent?

Specialization

Each agent focuses on what it does best. A coding agent doesn't need browsing skills, and a research agent doesn't need file system access.

Parallel execution

Multiple agents can work simultaneously on different subtasks, dramatically reducing total completion time.

Context isolation

Each agent has its own context window. No single agent gets overwhelmed with too much information.

Cost optimization

Route simple tasks to cheaper models (Haiku) and complex reasoning to expensive ones (Opus). Save 40-60% on API costs.

Architecture Patterns

Hub-and-Spoke

One coordinator agent delegates to specialist agents. Best for structured workflows. The coordinator uses Sonnet/Opus, specialists use Haiku.

Coordinator → [Research Agent, Code Agent, Summary Agent]

Pipeline

Agents pass work sequentially. Agent A researches, Agent B writes, Agent C reviews. Good for content creation workflows.

Research → Writer → Reviewer → Publisher

Peer-to-Peer

Agents communicate directly with each other. More complex to configure but most flexible. Best for creative/exploratory tasks.

Agent A ↔ Agent B ↔ Agent C

Basic Setup: Dual Agent

Define agents in AGENTS.md with distinct roles and tools

# AGENTS.md - Define your agent team

## coordinator
role: You are the coordinator. Delegate research to @researcher.
model: claude-sonnet-4-20250514
tools: [delegate, memory]

## researcher  
role: You research topics thoroughly using web browsing.
model: claude-haiku-4-20250514
tools: [browse, search]

Verify both agents are registered

openclaw agents list

Test that the coordinator correctly delegates to the researcher

openclaw message --agent coordinator "Research the latest OpenClaw security updates"

Agent Communication

Structured messages

Agents communicate via typed message channels. Use @agent-name to address specific agents. Messages include context, priority, and expected response format.

Shared memory

Use a shared memory.md or SQLite database for facts that all agents need. Each agent can read but only write to its own section.

Task queues

For async workflows, use the built-in task queue. Agents pick up tasks based on their role and availability.

Model Assignment Strategy

Role	Model	Cost	Reason
Coordinator / Decision-maker	Claude Opus	$$$	Complex reasoning, planning, and delegation decisions
Core task executor	Claude Sonnet	$$	Balanced performance for most tasks
Simple/repetitive tasks	Claude Haiku	$	Fast, cheap. Summaries, formatting, data extraction
Heartbeat / Status checks	Gemini Flash	¢	Near-zero cost for routine health checks

Safety Guardrails

Set per-agent token limits to prevent runaway costs
Restrict each agent's tool access to only what it needs
Log all inter-agent communications for debugging
Use circuit breakers — if an agent loops 3+ times, halt and alert
Never give multiple agents write access to the same file
Test agent interactions in a sandbox before production

Common Issues

Agents talking in infinite loops

Set max_turns per conversation. Add explicit 'DONE' signals in agent protocols.

Coordinator ignores specialist output

Make the coordinator's SOUL.md explicitly state it must incorporate delegate responses.

Context window overflow

Summarize long outputs before passing between agents. Use the built-in context compressor.

High costs from agent chatter

Add message budgets per task. Use Haiku for inter-agent coordination messages.

Multi-Agent Checklist

✅ AGENTS.md defines clear roles for each agent

✅ Each agent has restricted tool access (principle of least privilege)

✅ Model tiers assigned based on task complexity

✅ Per-agent token/spending limits configured

✅ Inter-agent communication logging enabled

✅ Circuit breakers set for loop prevention

✅ Shared memory properly scoped (read vs. write)

✅ Tested in sandbox before production deployment

Why Multi-Agent?

Specialization

Each agent focuses on what it does best. A coding agent doesn't need browsing skills, and a research agent doesn't need file system access.

Parallel execution

Multiple agents can work simultaneously on different subtasks, dramatically reducing total completion time.

Context isolation

Each agent has its own context window. No single agent gets overwhelmed with too much information.

Cost optimization

Route simple tasks to cheaper models (Haiku) and complex reasoning to expensive ones (Opus). Save 40-60% on API costs.

Architecture Patterns

Hub-and-Spoke

One coordinator agent delegates to specialist agents. Best for structured workflows. The coordinator uses Sonnet/Opus, specialists use Haiku.

Coordinator → [Research Agent, Code Agent, Summary Agent]

Pipeline

Agents pass work sequentially. Agent A researches, Agent B writes, Agent C reviews. Good for content creation workflows.

Research → Writer → Reviewer → Publisher

Peer-to-Peer

Agents communicate directly with each other. More complex to configure but most flexible. Best for creative/exploratory tasks.

Agent A ↔ Agent B ↔ Agent C

Basic Setup: Dual Agent

Define agents in AGENTS.md with distinct roles and tools

# AGENTS.md - Define your agent team

## coordinator
role: You are the coordinator. Delegate research to @researcher.
model: claude-sonnet-4-20250514
tools: [delegate, memory]

## researcher  
role: You research topics thoroughly using web browsing.
model: claude-haiku-4-20250514
tools: [browse, search]

Verify both agents are registered

openclaw agents list

Test that the coordinator correctly delegates to the researcher

openclaw message --agent coordinator "Research the latest OpenClaw security updates"

Agent Communication

Structured messages

Agents communicate via typed message channels. Use @agent-name to address specific agents. Messages include context, priority, and expected response format.

Shared memory

Use a shared memory.md or SQLite database for facts that all agents need. Each agent can read but only write to its own section.

Task queues

For async workflows, use the built-in task queue. Agents pick up tasks based on their role and availability.

Model Assignment Strategy

Role	Model	Cost	Reason
Coordinator / Decision-maker	Claude Opus	$$$	Complex reasoning, planning, and delegation decisions
Core task executor	Claude Sonnet	$$	Balanced performance for most tasks
Simple/repetitive tasks	Claude Haiku	$	Fast, cheap. Summaries, formatting, data extraction
Heartbeat / Status checks	Gemini Flash	¢	Near-zero cost for routine health checks

Safety Guardrails

Set per-agent token limits to prevent runaway costs

Restrict each agent's tool access to only what it needs

Log all inter-agent communications for debugging

Use circuit breakers — if an agent loops 3+ times, halt and alert

Never give multiple agents write access to the same file

Test agent interactions in a sandbox before production

Common Issues

Agents talking in infinite loops

Set max_turns per conversation. Add explicit 'DONE' signals in agent protocols.

Coordinator ignores specialist output

Make the coordinator's SOUL.md explicitly state it must incorporate delegate responses.

Context window overflow

Summarize long outputs before passing between agents. Use the built-in context compressor.

High costs from agent chatter

Add message budgets per task. Use Haiku for inter-agent coordination messages.

Multi-Agent Checklist

✅ AGENTS.md defines clear roles for each agent

✅ Each agent has restricted tool access (principle of least privilege)

✅ Model tiers assigned based on task complexity

✅ Per-agent token/spending limits configured

✅ Inter-agent communication logging enabled

✅ Circuit breakers set for loop prevention

✅ Shared memory properly scoped (read vs. write)

✅ Tested in sandbox before production deployment

Multi-Agent Setup Guide

Why Multi-Agent?

Specialization

Parallel execution

Context isolation

Cost optimization

Architecture Patterns

Hub-and-Spoke

Pipeline

Peer-to-Peer

Basic Setup: Dual Agent

Agent Communication

Structured messages

Shared memory

Task queues

Model Assignment Strategy

Safety Guardrails

Common Issues

Multi-Agent Checklist

▶ Related Resources

Multi-Agent Setup Guide

Why Multi-Agent?

Specialization

Parallel execution

Context isolation

Cost optimization

Architecture Patterns

Hub-and-Spoke

Pipeline

Peer-to-Peer

Basic Setup: Dual Agent

Agent Communication

Structured messages

Shared memory

Task queues

Model Assignment Strategy

Safety Guardrails

Common Issues

Multi-Agent Checklist

▶ Related Resources