OpenClaw Multi-Agent Orchestration: Gateway Routing Guide (2026)

Introduction

A single AI assistant is enough for quick questions. Production work — coding, ops alerts, family chat, research — needs multiple personas that do not share sessions, credentials, or tool permissions. OpenClaw multi-agent orchestration solves that with one Gateway control plane and many isolated agents, each with its own workspace, auth, and session store.

OpenClaw is a local-first personal AI assistant (375k+ GitHub stars as of 2026) built around a Gateway that connects channels (WhatsApp, Telegram, Discord, Slack, and more) to agent brains. Official docs describe multi-agent routing: inbound messages hit a binding table and land on the correct agentId without cross-talk.

This guide covers:

1. What one OpenClaw “agent” actually is on disk
2. How bindings route messages (peer, account, channel)
3. A step-by-step runbook to add a second agent
4. How multi-agent orchestration extends beyond routing (delegation, workflows)
5. When to use native Gateway routing vs external orchestrator projects

If you already use Claude Code plugins such as Obra Superpowers for dev workflow or Understand Anything to map a repo, OpenClaw sits at a different layer: always-on assistant + channel routing, not IDE-only coding.

What one OpenClaw agent includes

Critical rule: Never reuse the same agentDir for two agents — that causes auth and session collisions. Each agent should have its own directory and workspace.

Source: OpenClaw multi-agent docs.

agentId vs accountId vs binding

Routing is deterministic: most-specific match wins; peer-level rules beat channel-wide defaults.

Gateway architecture (control plane)

Inbound message (WhatsApp / Slack / …)
        │
        ▼
   OpenClaw Gateway
        │
        ├─ Load bindings (first match wins)
        ├─ Resolve agentId
        └─ Dispatch to agent workspace + session
                │
                ▼
        LLM + tools + skills (per-agent allowlist)

The Gateway is not the product — it is the router and session manager. Each agent runs with its own tool policy (agents.list[].tools.allow/deny) and optional sandbox (sandbox.mode: "all" per agent).

Agent-to-agent messaging exists but is off by default:

tools: { agentToAgent: { enabled: false, allow: ["home", "work"], }, }

Enable only when you explicitly want delegation between personas. See multi-agent documentation for allowlist patterns.

Setup runbook: add a second agent

Step 1 — Install or update OpenClaw

Follow the official installer from github.com/openclaw/openclaw. Verify CLI:

openclaw --version

Step 2 — Create a new isolated agent

openclaw agents add coding

This creates workspace files and ~/.openclaw/agents/coding/. Repeat for other personas (social, alerts, etc.).

Step 3 — List agents and bindings

openclaw agents list --bindings

Confirm each agentId has a unique agentDir and workspace path.

Step 4 — Connect a channel account (example: WhatsApp)

openclaw channels login --channel whatsapp --account work

Link each phone/account before starting the Gateway. Credentials default under ~/.openclaw/credentials/whatsapp/<accountId>.

Step 5 — Edit openclaw.json bindings

Add agents.list entries and route accounts to agents (JSON5):

{ agents: { list: [ { id: "main", default: true, workspace: "~/.openclaw/workspace-main" }, { id: "coding", workspace: "~/.openclaw/workspace-coding" }, ], }, bindings: [ { agentId: "main", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "coding", match: { channel: "whatsapp", accountId: "work" } }, ], }

Order matters: Put peer-specific rules above channel-wide accountId: "*" fallbacks.

Step 6 — Restart Gateway and probe channels

openclaw gateway restart openclaw channels status --probe

Send a test message on each account; verify sessions stay isolated (agent:coding:… vs agent:main:…).

Step 7 — Optional: split models by channel

Route fast model to WhatsApp and a larger model to Telegram:

bindings: [ { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } }, { agentId: "opus", match: { channel: "telegram", accountId: "*" } }, ]

Each agent can set model: "anthropic/claude-sonnet-4-6" (or your provider) independently.

Multi-agent orchestration patterns

Routing (built into Gateway) answers: which agent handles this message?
Orchestration answers: how do multiple agents cooperate on one goal?

Pattern A — Native routing only (recommended first)

Best for: separate people, separate channels, separate personalities. No extra software.

Pattern B — Agent-to-agent delegation

Enable tools.agentToAgent with an explicit allowlist. One agent can spawn or message another for subtasks. Use when a “coordinator” persona should hand off research or coding — still within OpenClaw’s session model.

Pattern C — External orchestrator plugins

Community projects add workflow graphs on top of OpenClaw:

These do not replace Gateway bindings — they coordinate agents after routing delivers the session.

Recommended path:

• If you only need separate WhatsApp/Discord identities → Pattern A (bindings only).
• If one user triggers multi-step projects with specialist roles → Pattern B or C.
• If you need IDE-centric TDD workflow → pair with Obra Superpowers, not OpenClaw alone.

Security: per-agent sandbox and tools

Untrusted agents (e.g. a family group bot) should use sandbox + tool deny lists:

{ id: "family", sandbox: { mode: "all", scope: "agent" }, tools: { allow: ["read", "sessions_list", "sessions_history"], deny: ["write", "edit", "apply_patch", "browser", "exec"], }, }

tools.elevated is global and sender-based — not per-agent. For hard boundaries, deny exec on restricted agents.

Where to run the Gateway

OpenClaw is designed local-first: macOS, Linux, or Windows via WSL2. The Gateway should stay online for channel webhooks and session continuity. Teams sometimes run it on a dedicated Mac that stays powered 24/7 instead of a laptop — same idea as leaving a home server on, with SSH for admin. Remote setup basics are in our Mac mini M4 SSH guide; pick any host that matches your security model.

Troubleshooting

Wrong agent answers messages

Symptom: Work messages hit the personal agent.

Fix:

1. Run openclaw agents list --bindings and confirm rule order (peer rules first).
2. Ensure accountId in the binding matches channels.whatsapp.accounts keys.
3. Restart: openclaw gateway restart.

Auth or session bleed between agents

Symptom: OAuth or chats mixed between personas.

Fix: Verify unique agentDir per agentId. Never point two agents at ~/.openclaw/agents/main/agent. Re-login per agent if OAuth was shared by mistake:

openclaw channels login --channel whatsapp --account work

Gateway starts but channel probe fails

Symptom: openclaw channels status --probe shows disconnected.

Fix: Re-link credentials, check firewall for webhook ports, and confirm tokens (Discord Message Content Intent, Telegram BotFather token, etc.) per OpenClaw channel guides.

FAQ

OpenClaw multi-agent orchestration in 2026 starts with the Gateway: one process, many isolated agents, deterministic bindings from channels to brains. Use openclaw agents add, wire agents.list + bindings, restart, and probe — then layer agent-to-agent or external orchestrators only when routing alone is not enough.

Official reference: Multi-agent routing · Repository: openclaw/openclaw.