Principle:Openclaw Openclaw Multi Agent Architecture

Multi-Agent Architecture

Multi-Agent Architecture is the principle of designing isolated agent workspaces with deterministic routing rules for sharing a single OpenClaw gateway across multiple personas. Rather than running separate gateway instances, the architecture allows a single process to host many fully-scoped "brains," each with its own workspace, session store, and authentication profiles.

Motivation

A common deployment pattern is running one OpenClaw gateway per server or device. When operators want multiple AI personas (e.g., a personal assistant and a work assistant, or separate agents for different family members), the naive approach is to run multiple gateway processes. This creates operational overhead: multiple ports, separate config files, and duplicated infrastructure.

Multi-agent architecture solves this by introducing a routing layer that maps inbound messages to isolated agent scopes within a single gateway process. Each agent maintains full isolation of its workspace files, session history, and authentication credentials, while sharing the underlying gateway infrastructure (channels, network, compute).

Core Concepts

Concept	Description
agentId	A unique identifier for one "brain." Normalized to lowercase with hyphens. The reserved id main is the implicit default agent.
Workspace	A directory containing persona-specific files (AGENTS.md, SOUL.md, TOOLS.md, etc.) that define the agent's behavior and personality.
Agent Directory (agentDir)	A state directory under ~/.openclaw/agents/<agentId>/agent that stores per-agent auth profiles, model registry, and configuration.
Session Store	Per-agent chat history and routing state stored under ~/.openclaw/agents/<agentId>/sessions.
Binding	A routing rule that maps an inbound message (by channel, accountId, peer, guildId, or teamId) to a specific agentId.
accountId	Identifies one channel account instance (e.g., WhatsApp account "personal" vs "biz"), enabling multiple phone numbers or logins on a single channel.

Isolation Guarantees

Each agent is fully isolated:

• Workspace files are independent. Changes to one agent's SOUL.md do not affect another.
• Auth profiles are per-agent. Credentials stored in one agent's agentDir are not shared unless explicitly copied.
• Sessions are keyed by agent. Direct chats collapse to agent:<agentId>:<mainKey>, preventing session cross-talk.
• Skills are per-agent via each workspace's skills/ folder, with shared skills available from ~/.openclaw/skills.

Important: workspace isolation sets the default working directory but does not enforce a hard sandbox. Absolute paths can reach other host locations unless sandboxing is explicitly enabled via per-agent sandbox configuration.

Routing Model

Bindings follow a most-specific-wins resolution hierarchy:

1. peer match (exact DM/group/channel id) -- highest priority
2. guildId match (Discord server)
3. teamId match (Slack workspace)
4. accountId match for a channel (specific account)
5. channel-level match (accountId: "*")
6. default agent fallback (agents.list[].default, else first list entry)

This deterministic evaluation order ensures that more specific rules always override broader ones, allowing operators to route individual conversations to specialized agents while maintaining a general-purpose default.

Single-Agent Mode

When no agents are configured, OpenClaw runs in single-agent mode. The implicit agent has agentId = "main", with workspace at ~/.openclaw/workspace and state at ~/.openclaw/agents/main/agent. This is fully compatible with the multi-agent model -- adding a second agent does not disrupt the default agent's operation.

Deployment Patterns

Common multi-agent configurations include:

• Multiple accounts on one channel: Two WhatsApp numbers routed to two agents via accountId bindings.
• Channel split: WhatsApp for everyday chat (fast model), Telegram for deep work (Opus model).
• DM split on shared account: Different WhatsApp DMs routed to different agents via peer bindings, all from one phone number.
• Family/group agent: A dedicated agent bound to a specific WhatsApp group with restricted tools and mention gating.

Related Concepts

• Per-agent sandbox and tool policies enforce least-privilege execution per agent.
• Workspace bootstrap files (AGENTS.md, SOUL.md, etc.) define agent persona and capabilities.
• Agent-to-agent messaging can be explicitly enabled for cross-agent communication.

Implementation

Implementation:Openclaw_Openclaw_AgentBinding_Type