Multi-Agent Routing: Bindings Config Patterns and Multi-Account/Channel Traffic Splitting

Chapter 34: Multi-Agent Routing — Bindings Configuration Patterns and Multi-Account/Multi-Channel Traffic Splitting in Practice

"One Agent cannot be the best assistant for everyone simultaneously. The Multi-Agent architecture lets each Agent focus on what it does best." — OpenClaw Multi-Agent Design Guide

34.1 Why Multiple Agents Are Needed

34.1.1 Limitations of Single-Agent Architecture

In the early stages of most AI Agent platforms, users used a single Agent to handle all requests. This architecture is simple and easy to use, but as usage scale expands, its limitations become apparent:

Problem 1: The Model Selection Dilemma

Different tasks have vastly different requirements for models:

Problem 2: Account and Channel Mixing

A cross-border trader might simultaneously operate:

• Personal WhatsApp (family and friends)
• Business WhatsApp (customers, suppliers)
• Telegram (tech community)
• Discord (product users)

If all messages flow into the same Agent, the Agent's memory mixes personal life and business information. An inappropriate context recall could cause serious privacy issues (for example, referencing family chat records when replying to a customer).

Problem 3: State Pollution

When Agent A is executing a long-running data analysis task, if a new urgent message arrives, it interrupts A's workflow, degrading the quality of both tasks.

34.1.2 What Multi-Agent Solves

OpenClaw's Multi-Agent architecture addresses these problems through:

1. Channel-level routing: WhatsApp messages → fast model, Telegram messages → high-quality model
2. Account-level isolation: Personal account → home Agent (personal memory), Business account → work Agent (business memory)
3. Load separation: Long tasks run on work Agent, not blocking home Agent responses
4. Cost optimization: High-frequency low-complexity requests → cheap model, low-frequency high-value requests → expensive model

34.2 Agent Complete Isolation Principles

Each Agent is completely isolated at the filesystem level — this is the foundation of Multi-Agent architecture security.

34.2.1 Directory Structure

~/.openclaw/
├── agents/
│   ├── main/                    ← main Agent's dedicated space
│   │   ├── config.json          ← main Agent-specific configuration
│   │   ├── memory/              ← main Agent's memory store
│   │   │   ├── conversations/
│   │   │   ├── embeddings/
│   │   │   └── index.json
│   │   ├── workspace/           ← main Agent's working directory
│   │   ├── session-store/       ← main Agent's Session persistence
│   │   │   ├── active/
│   │   │   └── archive/
│   │   └── logs/               ← main Agent's dedicated logs
│   │
│   ├── home/                    ← home Agent's dedicated space
│   │   ├── config.json
│   │   ├── memory/
│   │   ├── workspace/
│   │   └── session-store/
│   │
│   └── work/                    ← work Agent's dedicated space
│       ├── config.json
│       ├── memory/
│       ├── workspace/
│       └── session-store/
│
├── config.json                  ← Global configuration (including Bindings)
└── logs/                        ← Global logs

34.2.2 Three Dimensions of Isolation

Dimension 1: Filesystem Isolation

Each Agent can only access its own ~/.openclaw/agents/<agentId>/ directory. Cross-Agent file access is denied by default unless explicitly permitted through shared memory configuration.

Dimension 2: Session Store Isolation

Each Agent maintains an independent Session Store, storing:

• Current active conversation context
• Tool call history
• Intermediate state (status of tasks the Agent is executing)

The home Agent's Sessions are not visible to the work Agent, and vice versa.

Dimension 3: Memory Store Isolation

The Memory Store holds long-term knowledge extracted by the Agent from conversations:

• User preferences
• Important facts
• Historical decisions

By default, different Agents' memories are completely isolated. Cross-Agent memory access can be configured via memorySearch.qmd.extraCollections (see Chapter 35 for details).

34.3 Bindings Basic Configuration

Bindings are OpenClaw's routing rules engine, defining "which types of messages should be routed to which Agent."

34.3.1 How Bindings Work

Message arrives
    ↓
Gateway receives message
    ↓
Match Bindings rules in order (first matching rule takes effect)
    ↓
Route to corresponding Agent
    ↓
Agent processes and replies

34.3.2 Minimal Bindings Configuration

// openclaw.json
{
  "bindings": [
    {
      "agentId": "fast",
      "match": {
        "channel": "whatsapp"
      }
    },
    {
      "agentId": "opus",
      "match": {
        "channel": "telegram"
      }
    }
  ]
}

Explanation:

• All messages from WhatsApp → fast Agent (uses low-latency model)
• All messages from Telegram → opus Agent (uses high-quality model)
• Messages not matching any rule → falls back to default Agent (see section 34.5)

34.4 Channel-Based Traffic Splitting in Detail

34.4.1 Channel Identifier Reference

OpenClaw supports the following channel identifiers:

34.4.2 Complete Channel-Based Traffic Splitting Configuration Example

{
  "agents": {
    "list": [
      {
        "id": "fast",
        "model": "claude-haiku-4",
        "description": "Fast response Agent for instant messaging channels",
        "maxResponseTokens": 500,
        "systemPrompt": "You are a concise, efficient assistant. Keep replies short — no more than 3 sentences per message."
      },
      {
        "id": "opus",
        "model": "claude-opus-4",
        "description": "High-quality Agent for channels requiring deep analysis",
        "maxResponseTokens": 4000,
        "systemPrompt": "You are a professional consultant assistant. Provide deep analysis and detailed recommendations."
      },
      {
        "id": "email-agent",
        "model": "claude-sonnet-4",
        "description": "Email handling Agent",
        "maxResponseTokens": 2000,
        "systemPrompt": "You are a professional business email assistant. Use formal, professional tone."
      }
    ]
  },
  "bindings": [
    {
      "agentId": "fast",
      "match": {
        "channel": "whatsapp"
      },
      "options": {
        "typingIndicator": true,
        "maxResponseDelay": 2000
      }
    },
    {
      "agentId": "fast",
      "match": {
        "channel": "sms"
      }
    },
    {
      "agentId": "opus",
      "match": {
        "channel": "telegram"
      }
    },
    {
      "agentId": "email-agent",
      "match": {
        "channel": "email"
      }
    },
    {
      "agentId": "opus",
      "match": {
        "channel": "api"
      }
    }
  ]
}

34.5 Account-Based Traffic Splitting: Personal/Business Isolation Configuration

34.5.1 Typical Account-Splitting Scenario

Cross-border trader Alex's configuration requirements:

Requirements:
- Personal WhatsApp (+1-555-0001): family and friends, personal life
- Business WhatsApp (+1-555-0002): customers, suppliers, trade business
- Personal Telegram (@alex_personal): tech community
- Business Telegram (@alex_biz): customer channel

Desired behavior:
- Business channel Agent knows product catalog, pricing policy, customer records
- Personal channel Agent maintains personal life context, not mixed with business info

34.5.2 Complete Multi-Account Traffic Splitting Configuration

{
  "agents": {
    "list": [
      {
        "id": "home",
        "model": "claude-haiku-4",
        "description": "Personal life assistant",
        "systemPrompt": "You are Alex's personal assistant, helping with daily life matters. Keep a relaxed, friendly tone."
      },
      {
        "id": "work",
        "model": "claude-sonnet-4",
        "description": "Business assistant",
        "systemPrompt": "You are Alex's business assistant, focused on cross-border trade. Familiar with product catalog and customer relationships. Maintain a professional attitude.",
        "memory": {
          "collections": ["business-knowledge", "customer-records", "product-catalog"]
        }
      },
      {
        "id": "tech",
        "model": "claude-opus-4",
        "description": "Technical discussion assistant",
        "systemPrompt": "You are a technical expert assistant, specializing in programming, architecture design, and technical discussions."
      }
    ]
  },
  "bindings": [
    {
      "agentId": "home",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    },
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "biz"
      }
    },
    {
      "agentId": "home",
      "match": {
        "channel": "telegram",
        "accountId": "alex_personal"
      }
    },
    {
      "agentId": "tech",
      "match": {
        "channel": "telegram",
        "accountId": "alex_biz"
      }
    }
  ],
  "channels": {
    "whatsapp": {
      "accounts": [
        {"id": "personal", "phone": "+15550001"},
        {"id": "biz", "phone": "+15550002"}
      ]
    },
    "telegram": {
      "accounts": [
        {"id": "alex_personal", "username": "alex_personal"},
        {"id": "alex_biz", "username": "alex_biz"}
      ]
    }
  }
}

34.6 Default Fallback Behavior When Binding Match Fails

When a received message doesn't match any Binding rule, OpenClaw has the following fallback strategies:

34.6.1 Configuring a Default Agent

{
  "bindings": [
    {
      "agentId": "fast",
      "match": {"channel": "whatsapp"}
    },
    {
      "agentId": "opus",
      "match": {"channel": "telegram"}
    }
  ],
  "defaultAgent": "main",          // Route to main Agent when no match
  "unmatchedBehavior": "route-to-default"
}

34.6.2 Fallback Behavior Options

{
  "unmatchedBehavior": "route-to-default"
  // Other options:
  // "drop"           - Silently drop the message
  // "reply-error"    - Reply with error message
  // "queue"          - Place in pending queue
}

34.6.3 Debugging Binding Matches

# See which Agent a message was routed to
openclaw routing debug --channel whatsapp --accountId personal

# Output:
# Message routing debug for channel=whatsapp accountId=personal
# Checking binding rules in order:
#   Rule 1: match.channel=whatsapp, match.accountId=personal → MATCH → agentId=home
#   Routing to: home Agent
#   home Agent status: active (last active: 2 minutes ago)

34.7 Discord Application: Advanced Configuration with Guild ID + Roles

Discord offers richer routing dimensions than other channels, including servers (Guilds), channels, and user roles.

34.7.1 Discord Channel-Specific Match Fields

34.7.2 Discord Multi-Server, Multi-Role Configuration Example

{
  "bindings": [
    {
      "agentId": "admin-assistant",
      "match": {
        "channel": "discord",
        "guildId": "123456789012345678",
        "hasRole": "admin"
      },
      "description": "Admin-only assistant with full operation permissions"
    },
    {
      "agentId": "support-bot",
      "match": {
        "channel": "discord",
        "guildId": "123456789012345678",
        "channelId": "987654321098765432",
        "hasRole": "verified"
      },
      "description": "Technical support channel for verified users"
    },
    {
      "agentId": "public-bot",
      "match": {
        "channel": "discord",
        "guildId": "123456789012345678",
        "channelType": "text",
        "mentionBot": true
      },
      "description": "Public channels, requires @-mentioning the bot to trigger"
    },
    {
      "agentId": "dm-agent",
      "match": {
        "channel": "discord",
        "channelType": "dm"
      },
      "description": "DM handling, all DMs from all servers route here"
    }
  ]
}

34.8 Multi-Agent Cross-Workspace Shared Memory Configuration

In some scenarios, multiple Agents need to share portions of the knowledge base. For example, both home and work Agents need to know the user's language preferences and basic personal information.

34.8.1 Shared Memory Collections Configuration

{
  "memory": {
    "sharedCollections": [
      {
        "name": "user-profile",
        "description": "Basic user information, readable by all Agents",
        "allowedAgents": ["home", "work", "tech", "main"],
        "writeAgent": "main"
      },
      {
        "name": "language-preference",
        "description": "User language and communication preferences",
        "allowedAgents": ["home", "work", "tech"],
        "writeAgent": "any"
      }
    ],
    "agentCollections": {
      "home": ["personal-life", "family-contacts"],
      "work": ["business-knowledge", "customer-records"],
      "tech": ["code-snippets", "tech-notes"]
    }
  }
}

34.8.2 Memory Access Control Matrix

Memory Access Matrix (✓ = accessible, ✗ = no access)

              user-profile  personal-life  business-knowledge  code-snippets
home Agent        ✓              ✓               ✗                  ✗
work Agent        ✓              ✗               ✓                  ✗
tech Agent        ✓              ✗               ✗                  ✓
main Agent        ✓              ✗               ✗                  ✗

34.9 Common Multi-Agent Architecture Patterns

34.9.1 Pattern 1: Expert Specialization

Scenario: User has needs across multiple specialized domains

Architecture:
  Telegram → Routing Agent (analyzes intent)
              ↓
         ┌────┴─────┬──────────┐
      Code Expert  Legal Advisor  Finance Advisor
      claude-opus   claude-sonnet  claude-sonnet

{
  "bindings": [
    {
      "agentId": "router",
      "match": {"channel": "telegram"}
    }
  ],
  "agents": {
    "list": [
      {
        "id": "router",
        "model": "claude-haiku-4",
        "systemPrompt": "Analyze user intent and route to the appropriate expert Agent. Code questions→coding, legal questions→legal, financial questions→finance."
      },
      {"id": "coding", "model": "claude-opus-4"},
      {"id": "legal", "model": "claude-sonnet-4"},
      {"id": "finance", "model": "claude-sonnet-4"}
    ]
  }
}

34.9.2 Pattern 2: Cost Optimization

Scenario: Reduce API costs by assigning low-value requests to cheaper models

Logic:
  Message arrives
    ↓
  Fast Agent (Haiku): assess complexity
    ├── Simple question → Reply directly (Haiku low cost)
    └── Complex question → Forward to opus Agent (high quality reply)

Cost comparison (estimate):
  All Opus: 100% cost
  Mixed mode (70% Haiku + 30% Opus): ~25% cost

34.9.3 Pattern 3: Language-Based Traffic Splitting

Scenario: Multilingual business, different languages handled by specialized models

{
  "bindings": [
    {
      "agentId": "chinese-agent",
      "match": {
        "channel": "whatsapp",
        "detectedLanguage": "zh"
      }
    },
    {
      "agentId": "english-agent",
      "match": {
        "channel": "whatsapp",
        "detectedLanguage": "en"
      }
    },
    {
      "agentId": "spanish-agent",
      "match": {
        "channel": "whatsapp",
        "detectedLanguage": "es"
      }
    },
    {
      "agentId": "multilingual-agent",
      "match": {
        "channel": "whatsapp"
      }
    }
  ]
}

34.10 Multi-Agent Operations and Debugging

34.10.1 Viewing Agent Status

# View running status of all Agents
openclaw agents status

# Example output:
# Agent ID    Status     Model              Sessions  Last Active
# ─────────────────────────────────────────────────────────────────
# home        running    claude-haiku-4     2         30s ago
# work        idle       claude-sonnet-4    0         5m ago
# tech        running    claude-opus-4      1         10s ago
# main        stopped    claude-opus-4      0         2h ago

# View detailed status of a specific Agent
openclaw agents status --id work --verbose

34.10.2 Switching Agent Context (Manual Testing)

# Send a test message to a specific Agent
openclaw send --agent home "Hello, how's the weather today?"

# View conversation history for a specific Agent
openclaw sessions list --agent work

# Clear all sessions for a specific Agent (use with caution)
openclaw sessions clear --agent home

34.10.3 Hot-Updating Binding Rules

# Update Bindings configuration (no service restart required)
openclaw config set bindings '...'
openclaw routing reload

# Verify routing rules have been updated
openclaw routing rules list

34.11 Summary

Multi-Agent routing is the key architectural feature that transforms OpenClaw from a "personal assistant" into an "enterprise-grade Agent platform." Through Bindings configuration, you can precisely control the processing path for every message, achieving the optimal balance across cost, quality, and isolation dimensions.

Core points:

1. Isolation is the foundation: Each Agent has an independent filesystem, Session Store, and memory store — this is the security guarantee of the Multi-Agent architecture
2. Bindings match in order: Rules are checked top-to-bottom; the first match takes effect
3. Account isolation over channel isolation: For high-privacy scenarios, use accountId rather than just channel to differentiate
4. Shared memory requires explicit authorization: Cross-Agent memory access should follow the principle of minimum necessity
5. Cost optimization delivers real value: Well-designed Agent specialization can dramatically reduce model API costs

In the next chapter, we dive deep into Sub-agents: how the non-blocking delegated execution mechanism enables Agents to achieve genuine parallelism when handling complex tasks.

Chapter keywords: Multi-Agent, Bindings, channel traffic splitting, account isolation, agentId, routing rules, Discord Guild, shared memory, cost optimization