Principle:Openclaw Openclaw Session Resolution
| Knowledge Sources | |
|---|---|
| Domains | Agent_Runtime, Routing |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Session resolution is the deterministic process of matching an inbound message to a specific agent using binding rules arranged in a most-specific-wins hierarchy, and then deriving a unique session key for that agent-channel-peer combination.
Description
When a message arrives at the OpenClaw gateway, the runtime must answer two questions: (1) which agent should handle this message, and (2) what session context (conversation history, workspace, configuration) should be loaded for it. Session resolution answers both questions in a single pass.
The resolution algorithm consults a set of bindings -- declarative rules in the OpenClaw configuration that map channel/account/peer/guild/team patterns to agent IDs. Each binding specifies a match block that constrains when it applies, and an agentId that identifies the target agent. The algorithm evaluates bindings in a strict specificity order: peer-level bindings (exact chat/group match) are checked first, followed by parent-peer bindings (thread inheritance), guild-level, team-level, account-level, wildcard-account (channel-level), and finally a default fallback.
Once an agent is selected, the algorithm derives a session key -- a hierarchical string that encodes the agent ID, channel, account, peer kind (dm/group/channel), and peer ID. The session key is the primary index into the session store and determines conversation isolation. A companion main session key provides a collapse point for direct-message sessions when the configuration uses "main" DM scope (the default), allowing a single conversation thread across channels for the same agent.
Usage
Apply this principle whenever:
- Adding new binding types or match criteria (e.g., matching on sender attributes).
- Modifying session key derivation (e.g., new DM scope modes or identity linking).
- Debugging why a message routes to an unexpected agent -- trace the binding evaluation order.
- Extending thread/topic support for a new channel -- ensure parent-peer inheritance works correctly.
Theoretical Basis
The resolution algorithm implements a specificity cascade, analogous to CSS selector specificity or firewall rule evaluation. Rules are evaluated from most specific to least specific, and the first match wins:
- Peer binding -- matches an exact peer (chat ID + kind). Highest specificity.
- Parent peer binding -- matches the parent of a thread/topic. Enables thread inheritance without per-thread bindings.
- Guild binding -- matches a Discord guild ID (or equivalent organizational unit).
- Team binding -- matches a Slack team ID (or equivalent workspace unit).
- Account binding -- matches a specific provider account (multi-account setups).
- Channel binding -- matches a channel with a wildcard (
*) account. Lowest explicit specificity. - Default -- falls back to the default agent from configuration. Lowest specificity overall.
The session key derivation follows a hierarchical namespace pattern:
agent:{agentId}:{channel}:{peerKind}:{peerId}
DM scope modes (main, per-peer, per-channel-peer, per-account-channel-peer) control how much of this hierarchy is used, trading conversation isolation for cross-channel continuity. Identity links allow multiple peer IDs (e.g., same user on different channels) to collapse into a single session.
All tokens are normalized (lowercased, trimmed) before comparison and key construction to ensure deterministic matching regardless of casing differences between channel adapters.