Multi-Agent Routing: One Bot Per Channel

By default, OpenClaw runs a single agent. Every message from every channel goes to the same brain, the same workspace, the same personality. That works fine — until it doesn’t.

Maybe you want:

A professional assistant on WhatsApp and a casual bot on Discord
A family bot in the family group that’s sandboxed and limited
Multiple people sharing one Gateway with isolated agents
A fast model for daily chat and Opus for deep work

Multi-agent routing lets you run multiple isolated agents in one Gateway process. Each agent gets its own workspace, sessions, auth, and personality.

Core Concepts

What is “one agent”?

An agent is a fully isolated brain with:

Workspace — its own SOUL.md, AGENTS.md, USER.md, tools, and notes
State directory (agentDir) — auth profiles, model registry, per-agent config
Session store — separate chat history, no cross-talk
Skills — per-agent via workspace skills/ folder, plus shared skills from ~/.openclaw/skills

Auth profiles are per-agent. The main agent’s API keys aren’t shared automatically. If you want to share credentials, copy auth-profiles.json into the other agent’s agentDir.

Routing rules

Bindings are deterministic. OpenClaw picks one agent per inbound message using most-specific-wins:

Exact peer match (specific DM/group/channel)
Parent peer (thread inheritance)
Guild + roles (Discord role routing)
Guild (Discord)
Team (Slack)
Account (channel account ID)
Channel (any account, accountId: "*")
Default agent (first in list or default: true)

When multiple match fields are set on a binding, all must match (AND semantics).

Quick Start

Step 1: Create agents

openclaw agents add work
openclaw agents add home

Each agent gets its own workspace (~/.openclaw/workspace-<name>) with fresh SOUL.md, AGENTS.md, and USER.md.

Step 2: Create channel accounts

Each agent typically needs its own bot account:

Telegram: Create one bot per agent via @BotFather
Discord: Create one application/bot per agent at discord.com/developers
WhatsApp: Link one phone number per agent

Step 3: Add bindings

Edit ~/.openclaw/openclaw.json:

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
      },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "telegram", accountId: "default" } },
    { agentId: "work", match: { channel: "telegram", accountId: "work" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: { botToken: "HOME_BOT_TOKEN" },
        work: { botToken: "WORK_BOT_TOKEN" },
      },
    },
  },
}

Step 4: Restart and verify

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

Real-World Patterns

Pattern 1: WhatsApp Daily + Telegram Deep Work

Route WhatsApp to a fast model for everyday chat, and Telegram to Opus for serious work.

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "deep",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-deep",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "deep", match: { channel: "telegram" } },
  ],
}

Each agent has its own personality. The chat agent is snappy and short. The deep work agent is thorough and analytical. Different SOUL.md files, different vibes.

Pattern 2: Discord Bots Per Server Role

Two Discord bots in the same guild, each handling different channels:

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
  ],
  channels: {
    discord: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "MAIN_BOT_TOKEN",
          guilds: {
            "YOUR_GUILD_ID": {
              channels: {
                "GENERAL_CHANNEL_ID": { allow: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "CODING_BOT_TOKEN",
          guilds: {
            "YOUR_GUILD_ID": {
              channels: {
                "DEV_CHANNEL_ID": { allow: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}

Remember: each Discord bot needs Message Content Intent enabled.

Pattern 3: Family Bot (Sandboxed)

A dedicated agent for a family WhatsApp group, with restricted tools and sandboxing:

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family Bot",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: ["exec", "read", "sessions_list", "sessions_history"],
          deny: ["write", "edit", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "YOUR_GROUP_ID@g.us" },
      },
    },
  ],
}

This agent:

Only activates when mentioned (@family)
Can’t write files, control browsers, or schedule cron jobs
Runs in a sandboxed container
Is bound to one specific WhatsApp group

Pattern 4: One WhatsApp, Multiple People

Route different DMs to different agents on the same WhatsApp number:

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

Note: both people share the same WhatsApp number, but each gets a completely isolated agent. DM access control is global per WhatsApp account (not per agent).

Pattern 5: Override One Peer to a Different Agent

Keep WhatsApp on the fast agent, but route one specific DM to Opus:

{
  bindings: [
    // Peer bindings always win — keep them above channel-wide rules
    {
      agentId: "deep",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
    },
    // Everything else on WhatsApp goes to the chat agent
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

Peer matches always win over channel-wide rules. Order matters only within the same tier.

Per-Agent Configuration

Per-Agent Heartbeats

When any agent has a heartbeat block, only those agents run heartbeats:

{
  agents: {
    defaults: {
      heartbeat: { every: "30m", target: "last" },
    },
    list: [
      { id: "main", default: true },  // no heartbeat block → no heartbeats
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
        },
      },
    ],
  },
}

Per-Agent Sandbox and Tools

Each agent can have different security postures:

{
  agents: {
    list: [
      {
        id: "personal",
        sandbox: { mode: "off" },        // full host access
      },
      {
        id: "shared",
        sandbox: { mode: "all", scope: "agent" },  // sandboxed
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit"],
        },
      },
    ],
  },
}

Per-Agent Models

{
  agents: {
    list: [
      { id: "fast", model: "anthropic/claude-sonnet-4-5" },
      { id: "deep", model: "anthropic/claude-opus-4-6" },
    ],
  },
}

Broadcast Groups

Sometimes you want multiple agents to respond to the same group. Broadcast groups make this possible:

{
  broadcast: {
    strategy: "parallel",
    "GROUP_ID@g.us": ["agent1", "agent2"],
  },
}

Both agents run in parallel when a message comes into that group. Use this for logging agents alongside response agents, or when you want multiple perspectives.

Common Mistakes

Sharing agentDir across agents: Never reuse agentDir. Each agent needs its own state directory or you’ll get auth/session collisions.

Forgetting auth profiles: Each agent reads from ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. If you want a new agent to use the same API keys, copy the auth profile file.

Binding order confusion: Within the same specificity tier, first match wins. Put specific bindings (peer matches) above general ones (channel matches).

Missing Message Content Intent: Discord bots need this enabled. Without it, your bot sees events but can’t read message content.

The `openclaw agents` CLI

# Add a new agent (interactive wizard)
openclaw agents add <name>

# List agents with their bindings
openclaw agents list --bindings

# Check channel status
openclaw channels status --probe

What’s Next?

OpenClaw in 10 Minutes — Start with a single agent first
Crafting the Perfect SOUL.md — Give each agent a unique personality
5 Automations That Save Hours — Per-agent heartbeats and cron jobs

Multi-agent routing is where OpenClaw stops being a chatbot and starts being infrastructure.

Multi-Agent Routing: One Bot Per Channel

Multi-Agent Routing: One Bot Per Channel

Core Concepts

What is “one agent”?

Routing rules

Quick Start

Step 1: Create agents

Step 2: Create channel accounts

Step 3: Add bindings

Step 4: Restart and verify

Real-World Patterns

Pattern 1: WhatsApp Daily + Telegram Deep Work

Pattern 2: Discord Bots Per Server Role

Pattern 3: Family Bot (Sandboxed)

Pattern 4: One WhatsApp, Multiple People

Pattern 5: Override One Peer to a Different Agent

Per-Agent Configuration

Per-Agent Heartbeats

Per-Agent Sandbox and Tools

Per-Agent Models

Broadcast Groups

Common Mistakes

The openclaw agents CLI

What’s Next?

The `openclaw agents` CLI