How to set up OpenClaw multi-agent routing and channel bindings

OpenClaw multi-agent routing lets one gateway host multiple isolated agent brains. The cleanest operational pattern is separate agents with separate workspaces, separate agentDir state, and bindings that route a specific account or sender to the right agent.

Who this is for

• You already run a stable single-agent OpenClaw setup.
• You want separate workspaces or personalities.
• You want to host multiple phone numbers, accounts, or people on one gateway.

What you need before you start

• A working OpenClaw gateway.
• A clear routing plan, such as one account per agent or one sender per agent.
• Enough disk space for separate workspaces and per-agent state.

Step-by-step setup

Step 1: Add the extra agents

Expected result: OpenClaw creates new isolated agent entries and workspaces that you can wire into bindings next.

Step 2: Open the active config file

Expected result: the CLI prints the config path you should edit, usually under ~/.openclaw/.

Step 3: Add a clean two-account routing config

Edit the file printed in the previous step and add a block like this:

This follows the official multi-agent and configuration-reference pattern: one accountId per agent, no session or credential reuse across agents.

Step 4: Validate the config

Expected result: validation succeeds and the bindings schema is accepted.

Step 5: Restart the gateway

Expected result: the gateway comes back with the new routing table.

Step 6: Verify bindings and channel health

Expected result: both agents appear, the bindings are visible, and the linked channel accounts probe successfully.

Verify it worked

1. openclaw agents list --bindings shows the account-to-agent mapping you intended.
2. Each agent has its own workspace and agentDir.
3. Sending traffic through each bound account lands in the correct agent instead of leaking into another session.

Common problems and fixes

Sessions or credentials are colliding across agents

Do not reuse agentDir. The official multi-agent docs explicitly warn that shared agentDir values cause auth and session collisions.

The config validates, but traffic still lands on the wrong agent

Inspect the binding match fields against the official reference. match.channel is required, while accountId and peer are optional selectors.

I want different access policies per agent

Use per-agent sandbox and tool overrides instead of trying to share one global policy:

FAQ

What is the safest multi-agent pattern to start with?

Use one account or phone number per agent. It is simpler than DM splitting on one shared account and preserves cleaner routing boundaries.

Can I route two different people through the same WhatsApp number?

Yes. The docs show a DM split pattern that matches specific senders with peer.kind and sender IDs, but they also note that direct chats still collapse to the agent’s main session, so separate agents are required for real isolation.

Can each agent have a different sandbox or tool policy?

Yes. The official multi-agent sandbox and tools docs support agents.list[].sandbox and agents.list[].tools overrides per agent.

Official sources

• Multi-Agent Routing
• Channel Routing
• Configuration Reference
• Multi-Agent Sandbox & Tools