Course: Advanced OpenClaw | Pathway: Builder | Level: Advanced Estimated Reading Time: 18 minutes
You have a single OpenClaw agent running. It handles tasks, responds to messages, and follows its SOUL.md personality. That is a solid foundation — but it is also a ceiling.
Real-world AI workflows rarely fit inside a single agent. You might need one agent watching email, another managing a calendar, a third generating content, and a fourth coordinating all of them. This lesson covers how to design, build, and operate multi-agent systems in OpenClaw.
By the end, you will understand when to split work across agents, how workspace isolation works, how agents communicate, and the architectural patterns that keep multi-agent systems manageable.
The first question is always: do you actually need multiple agents?
Use a single agent when:
Split into multiple agents when:
A good rule of thumb: if you find yourself writing a SOUL.md that says "sometimes you do X, other times you do Y, and occasionally Z" — that is three agents trying to share one body.
Every OpenClaw agent gets its own workspace directory. This is not just organisation — it is a security boundary.
~/.openclaw/workspace/
agent-alpha/ # Content writer
agent-beta/ # Email handler
agent-gamma/ # Data analyst
Each workspace contains:
Why isolation matters:
When designing your agent team, think of workspaces as offices. Each agent works in its own office. They can pass messages through defined channels, but they do not rummage through each other's desks.
There are several common patterns for organising multi-agent teams. Choose the one that fits your workflow.
Each agent handles an independent domain. No agent-to-agent communication needed.
Agent: email-watcher → Checks inbox, sends replies
Agent: content-writer → Generates blog posts on schedule
Agent: system-monitor → Watches server health
This is the simplest pattern. Each agent has its own cron schedule, its own model, and its own SOUL.md. They never interact. You manage them individually.
Best for: Teams where tasks are genuinely independent.
Agents pass work along a chain. The output of one becomes the input of the next.
Agent: researcher → Gathers data, writes to shared file
Agent: writer → Reads data file, produces draft
Agent: reviewer → Reads draft, provides feedback
Pipeline agents communicate through files in a shared directory or through Telegram/Discord channels that multiple agents monitor.
Best for: Content production, data processing, quality assurance workflows.
One agent acts as a dispatcher, delegating tasks to specialist agents.
Agent: coordinator → Receives requests, assigns to workers
Agent: worker-code → Handles coding tasks
Agent: worker-email → Handles email tasks
Agent: worker-data → Handles data tasks
The coordinator uses subagent spawning or channel messaging to delegate. This pattern is powerful but adds complexity — the coordinator needs to understand what each worker can do.
Best for: General-purpose assistant systems that handle varied requests.
A lightweight agent watches for conditions, then triggers a capable agent to act.
Agent: watchdog → Cheap local model, runs every 5 min
Agent: responder → Expensive cloud model, runs on demand
The watchdog uses a small, fast model (like a local Ollama model) to check conditions. When it detects something that needs attention, it triggers the responder through a channel message or file flag.
Best for: Cost-effective monitoring where most checks find nothing.
OpenClaw agents do not share memory directly. This is by design — shared state is the enemy of reliability. Instead, agents communicate through defined channels.
The simplest approach. One agent writes a file, another reads it.
{
"sharedDirectory": "/Users/you/.openclaw/shared/inbox"
}
Agent A writes a JSON file to the shared directory. Agent B has a cron job that checks the directory for new files. This is reliable, auditable, and easy to debug — you can inspect the files yourself.
Tips for file-based communication:
If your agents are connected to Telegram or Discord, they can communicate through dedicated channels.
Create a private Telegram group or Discord channel that only your agents can see. Agent A posts a message when it needs something done. Agent B monitors the channel and picks up the request.
This works well when you want a human-readable log of agent interactions. You can join the channel yourself to observe and intervene.
OpenClaw supports spawning subagents — temporary agents created by a parent agent to handle a specific task. The subagent inherits configuration from the parent but runs in its own context.
Subagents are useful for:
The parent agent receives the subagent's output when it completes. Subagent sessions are cleaned up automatically.
Before writing any configuration, sketch your agent team on paper. Answer these questions:
Once you have your groups, each group becomes an agent. Give each agent:
Your openclaw.json defines all agents. Here is a simplified example of a three-agent team:
{
"agents": {
"email-handler": {
"model": "claude-sonnet-4-20250514",
"workspace": "email-handler",
"soul": "SOUL.md",
"channels": ["telegram:email-alerts"],
"cron": [
{ "schedule": "*/15 * * * *", "task": "Check inbox for new messages" }
]
},
"content-writer": {
"model": "ollama:llama3",
"workspace": "content-writer",
"soul": "SOUL.md",
"cron": [
{ "schedule": "0 9 * * 1-5", "task": "Generate daily content brief" }
]
},
"coordinator": {
"model": "claude-sonnet-4-20250514",
"workspace": "coordinator",
"soul": "SOUL.md",
"channels": ["telegram:command-channel"]
}
}
}
Notice that each agent has its own workspace, model, and schedule. The coordinator has no cron — it is event-driven, responding to messages on its Telegram channel.
Over-splitting. Do not create an agent for every tiny task. If two tasks always run together and share context, they belong in one agent. More agents means more configuration, more monitoring, and more things to break.
Shared state without coordination. Two agents writing to the same file at the same time will cause problems. If agents must share files, use a clear protocol — one writes, one reads, never both writing simultaneously.
Ignoring failure modes. What happens when Agent A writes a task for Agent B, but Agent B is down? Design your communication to handle this. File-based communication is naturally resilient — the file sits there until Agent B comes back.
Identical SOUL.md files. If all your agents have the same personality file, you are probably not using multi-agent architecture effectively. Each agent should have a personality tuned to its specific role.
Design a three-agent system for the following scenario:
You run a small business. You want agents to handle:
Sketch out the agent names, which model each would use (local vs cloud), the cron schedules, and how (if at all) they communicate.
There is no single right answer. The goal is to practice the thinking process before you start writing configuration.
Multi-agent architecture is about dividing work across focused, isolated agents that communicate through defined channels. The key principles are:
In the next lesson, we will dive into model strategy — choosing the right model for each agent and configuring fallback chains to handle failures gracefully.