Agent Bindings & Routing Priority

+15 Mana ✨
OpenClaw Multi-Agent Docs(DOCUMENTATION)

Introduction

When running multiple agents in a single OpenClaw gateway, the system needs rules to decide which agent handles each incoming message. Agent bindings define these rules through a priority-based routing hierarchy that evaluates bindings from most specific to least specific.

Key Concepts

  • Binding: A rule that maps a message context (channel, account, guild, team) to a specific agent. Each binding has a priority tier.
  • Routing Hierarchy: The order in which binding tiers are evaluated: peer > parent peer > guild+roles > guild > team > account > channel > default.
  • First-Match-in-Tier: Within a single priority tier, the first matching binding wins. Once a match is found, lower-priority tiers are not evaluated.
  • Default Agent: The fallback agent that handles messages when no specific binding matches.

Real World Context

A company runs three agents: a code-review agent for the engineering Discord server, a support agent for the customer WhatsApp line, and a general assistant as the default. Without routing priority, messages would go to a random agent. The binding system ensures each message reaches the right specialist based on where it came from and who sent it.

Deep Dive

The routing hierarchy has eight tiers, evaluated from highest to lowest priority:

json
{
  "agents": {
    "code-reviewer": {
      "bindings": [
        {
          "type": "guild",
          "guildId": "discord-eng-server-123",
          "roles": ["developer"]
        }
      ]
    },
    "support-bot": {
      "bindings": [
        {
          "type": "account",
          "accountId": "whatsapp-support-line"
        }
      ]
    },
    "general": {
      "bindings": [
        {
          "type": "default"
        }
      ]
    }
  }
}

This configuration shows three agents with different binding types. When a message arrives from a developer in the Discord engineering server, the guild+roles binding matches first (tier 3), routing to the code-reviewer. A message from the WhatsApp support line matches the account binding (tier 5), routing to the support-bot. Any other message falls through to the default binding (tier 8).

The full priority order is:

  1. Peer: Direct peer-to-peer binding (highest priority)
  2. Parent Peer: Binding inherited from a parent session
  3. Guild + Roles: Matches both the guild (server) and specific roles
  4. Guild: Matches the guild without role requirements
  5. Team: Matches a team identifier
  6. Account: Matches a specific account ID
  7. Channel: Matches a channel type (e.g., all Discord messages)
  8. Default: Catches everything else (lowest priority)

The first-match-in-tier rule means that if two bindings exist at the same priority level, the one defined first in the configuration wins.

Common Pitfalls

  1. Forgetting a default binding — Without a default agent, messages that do not match any binding are silently dropped. Always define at least one default binding.
  2. Overlapping guild bindings — If two agents both bind to the same guild without roles, the first one defined wins, which may not be the intended behavior. Use roles to differentiate.

Best Practices

  1. Use the most specific binding possible — Prefer guild+roles over guild-only bindings to avoid accidental routing.
  2. Document your routing topology — As the number of agents grows, maintain a routing diagram that maps bindings to agents for easy debugging.

Summary

  • Agent bindings route messages to the correct agent based on an eight-tier priority hierarchy
  • The hierarchy evaluates from peer (most specific) to default (least specific)
  • First-match-in-tier resolves conflicts within the same priority level
  • Always define a default binding to catch unmatched messages
  • Use roles and specific binding types to avoid routing ambiguity
✓ Completed