Workflow:Openclaw Openclaw Multi Agent Routing
| Knowledge Sources | |
|---|---|
| Domains | Agent_Runtime, Message_Routing, Configuration |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
End-to-end process for configuring multiple isolated agents on a single OpenClaw gateway, each with its own workspace, persona, and routing rules for handling messages from different channels or contacts.
Description
This workflow covers setting up multi-agent routing where a single OpenClaw gateway runs multiple agents simultaneously. Each agent has its own workspace (SOUL.md, AGENTS.md, etc.), session storage, model configuration, and tool permissions. Inbound messages are routed to the correct agent based on binding rules that match on channel type, account ID, group ID, or peer identity. This enables use cases like separate work and personal agents, family-safe agents with restricted tools, or specialized agents per messaging platform.
Key outputs:
- Multiple agents registered with distinct workspaces and personas
- Binding rules mapping channels and contacts to specific agents
- Per-agent sandbox and tool policy configuration
- Isolated session storage per agent
Usage
Execute this workflow when a single gateway needs to serve different personas or contexts. Common scenarios include separating work and personal assistants, creating a restricted family-safe agent, running different model configurations per channel, or handling different WhatsApp accounts with different agents.
Execution Steps
Step 1: Plan Agent Architecture
Determine how many agents are needed and what distinguishes each one. Consider the routing criteria (by channel, by contact group, by account), the persona and capabilities of each agent, and whether agents need different model providers or tool access levels.
Key considerations:
- Each agent needs a unique ID (e.g., "home", "work", "family")
- Each agent gets its own workspace directory with independent persona files
- Agents can share the same model provider or use different ones
- Sandbox policies can be set per-agent (none, non-main sessions, all sessions)
Step 2: Create Additional Agents
Add new agents using the CLI wizard or by editing the configuration file directly. The CLI wizard guides through workspace creation, model selection, and initial binding setup.
What happens:
- Agent entry added to agents.list[] in configuration
- New workspace directory created with bootstrap template files
- Agent-specific model configuration set (primary and fallback models)
- Agent ID registered with the gateway routing system
Step 3: Configure Routing Bindings
Define binding rules that determine which agent handles each inbound message. Bindings match on channel type, account ID, group ID, and peer identity. More specific bindings take precedence over general ones.
What happens:
- Binding entries added to configuration with match patterns
- Each binding maps a set of message attributes to an agent ID
- Precedence: exact peer match > guild/team ID > account ID > channel > default
- Unmatched messages fall through to the default agent
Step 4: Set Per Agent Tool Policies
Configure sandbox mode and tool allow/deny lists for each agent independently. This enables different trust levels, for example allowing the main agent full tool access while restricting a family agent to read-only operations.
Key considerations:
- Sandbox mode: "none" (host execution), "non-main" (sandbox for non-owner), "all" (always sandbox)
- Tool allow/deny lists override the default tool set per agent
- Elevated tool directives can be gated per agent
- Exec approvals can require companion app confirmation for sensitive tools
Step 5: Customize Agent Personas
Edit each agent's workspace files to set its unique persona, skills, and behavior. The SOUL.md file defines personality and tone. The AGENTS.md file sets agent instructions and capabilities. Skills can be loaded per-agent from the workspace skills directory.
What happens:
- SOUL.md edited with agent-specific personality and constraints
- AGENTS.md configured with agent-specific instructions and tool guidance
- Per-agent skills loaded from <workspace>/skills/ directory
- USER.md populated with agent-specific user context
Step 6: Verify Routing
Test that messages are routed to the correct agent by sending test messages on each configured channel and contact. Verify session isolation by checking that conversations do not cross agent boundaries.
What happens:
- Agent list displayed with binding information
- Test messages sent on each channel and contact group
- Session keys verified to include correct agent ID
- Logs checked for routing decisions and agent selection