Principle:Openclaw Openclaw Binding Configuration

Binding Configuration

Binding Configuration is the principle of defining message-to-agent routing rules with match criteria (channel, accountId, peer, guildId, teamId) and a most-specific-wins resolution hierarchy. Bindings are the mechanism by which inbound messages are deterministically routed to the correct agent in a multi-agent gateway.

Motivation

In a multi-agent gateway, every inbound message must be routed to exactly one agent. Without explicit routing rules, all messages would go to the default agent. Bindings provide a declarative configuration surface that maps message metadata (which channel, which account, which peer, which guild/team) to a target agentId.

The binding system must handle several challenges:

• Specificity: A peer-level rule should override a channel-level rule.
• Conflict detection: Two agents cannot claim the same exact match rule.
• Idempotency: Re-applying the same binding to the same agent should be a no-op.
• Composability: Bindings can be added incrementally during agent creation or afterward.

Binding Structure

Each binding consists of:

Field	Type	Description
agentId	string	The target agent that receives matched messages.
match.channel	string	The channel identifier (e.g., "whatsapp", "telegram", "discord").
match.accountId	string (optional)	The channel account instance. Use "*" for any account on the channel.
match.peer	{ kind, id } (optional)	A specific DM, group, or channel peer. kind is one of "dm", "group", or "channel".
match.guildId	string (optional)	A Discord guild (server) id.
match.teamId	string (optional)	A Slack team (workspace) id.

Resolution Hierarchy

Bindings are evaluated in a strict most-specific-wins order:

1. Peer match -- Exact DM/group/channel id (highest specificity).
2. Parent peer match -- Thread parent peer binding for inheritance.
3. Guild match -- Discord guild id.
4. Team match -- Slack team id.
5. Account match -- Channel + specific accountId (no peer/guild/team qualifier).
6. Channel match -- Channel + wildcard accountId ("*").
7. Default -- Falls back to the default agent (first entry with default: true, or first list entry).

This hierarchy ensures that narrower rules always take precedence. For example, a binding that routes a specific WhatsApp group to an "opus" agent will override a broader binding that routes all WhatsApp messages to a "chat" agent.

Match Key Deduplication

Each binding is uniquely identified by a composite key: channel|accountId|peer.kind|peer.id|guildId|teamId. When applying new bindings:

• If the match key already exists for the same agent, the binding is skipped (idempotent).
• If the match key already exists for a different agent, a conflict is reported and the new binding is not applied.
• Only truly new match keys are added to the configuration.

Binding Lifecycle

Bindings can be:

• Created during agent provisioning (via the wizard or --bind flags).
• Added after creation through config editing.
• Removed when an agent is pruned (all bindings for that agentId are cleaned up).

Account Resolution

For channels that require account binding (e.g., WhatsApp with forceAccountBinding), the system automatically resolves the default account id if none is specified. This ensures that bindings are always complete and unambiguous.

Implementation

Implementation:Openclaw_Openclaw_ApplyAgentBindings