From Message to Action: Routing, Sessions, and the Agent Loop
OpenClaw’s defining behavior is not that a model can answer a message; it is that the Gateway turns an inbound message into a controlled, stateful turn. This chapter follows that path from sender admission to reply delivery, so you can tell which decision chose the agent, which state supplied context, which runtime performed the work, and why a failure at one stage does not necessarily mean the same thing as a failure at another.
Consider a message sent from Telegram while an earlier task is still running. OpenClaw does not immediately hand the text to a model. It first decides whether the sender and conversation may trigger the agent, which configured agent owns the route, which session should receive the context, and whether the new message should steer or wait behind the current run. Only then does the model enter the picture.
Admission comes before reasoning
The first useful distinction is between admission and routing. Admission asks whether a message is allowed to become a request. Routing asks where an admitted request should go. They are related, but combining them creates dangerous ambiguity: knowing which agent would handle a message does not mean that the sender is allowed to invoke it.
For a direct message, the channel’s DM policy and sender allowlist are evaluated first. In pairing mode, an unknown sender receives a short pairing code and the message is not processed until an operator approves it. In allowlist mode, the sender must match the configured entries. An open policy is not simply “accept anything”; the documented configuration still requires an effective wildcard or a matching normalized entry. Pairing approval grants direct-message access only. It does not authorize the same person to speak in a group or bypass that group’s rules.
Group messages add separate gates. The channel can disable groups, allow only named groups, or admit a broader set of groups through an allowlist. Within an admitted group, sender authorization can still restrict who may trigger the agent. Mention gating then decides whether a message that passed those access checks is an actual request. A message without a mention may be retained as context or treated as quiet room activity, depending on configuration, but it is not automatically equivalent to a direct command.
This separation matters in a practical case. Suppose a team allows OpenClaw into a support room but wants only the on-call group to trigger it. The room allowlist answers “may this conversation be considered?” The sender allowlist answers “may this person trigger work here?” Mention gating answers “did this message address the assistant?” A DM pairing approval answers none of the group questions. Each gate describes a different fact about the inbound event.
After admission, OpenClaw resolves an agent through ordered bindings. The most specific match wins: an exact peer can override a parent conversation, a wildcard peer can override a broader channel rule, and guild, team, account, or channel matches provide progressively wider fallbacks. If several fields are present in one binding, they must all match. A channel-wide rule is therefore not supposed to erase a more specific assignment merely because both agents are configured.
This is where the concept of an agent becomes concrete. An agent is not only a model name or personality prompt. It owns a workspace, agent-local authentication and model state, and a session store. A company may route a work Slack account to one agent and personal Telegram messages to another, or route one particular room to a specialized agent while leaving the rest of the channel on the default. The binding selects the agent whose workspace and session state will be used.
The next choice is the session. A session is the durable conversation context that the Gateway associates with a route. OpenClaw’s personal default collapses direct messages into the agent’s main session, allowing a conversation started in one direct-message surface to continue in another. Groups, rooms, and channels are isolated by default, so a busy work room does not automatically become part of the private rolling conversation. Operators can change this with DM and group scope settings or a specific route binding, but that is a deliberate context-sharing decision.
A session key is consequently a routing selector, not an authorization token. It helps the Gateway find the right context and control concurrency; it does not prove who is allowed to read or mutate that context. Authorization comes from the channel, device, or operator policy that admitted the request and from the method-specific checks applied later. This distinction prevents a common design error: hiding a session identifier is not a substitute for access control.
The reply route is also kept separate from the session choice. A trusted room may share an agent’s main context while replies still return to that room. Conversely, two conversations may use related agent state while remaining separate sessions and separate delivery destinations. OpenClaw’s goal is to let the Gateway share the right context without making the model guess where a response should be sent.
The result of these stages can be summarized as a chain of facts: a sender was admitted; a conversation was identified; an agent was selected; a session was selected; a delivery route was retained. None of those facts requires model reasoning. They are control-plane decisions that make the later model turn possible.
The admitted turn is a controlled loop
Once an event becomes a request, OpenClaw enters the agent loop. In broad terms, the loop assembles context, selects a model and runtime, calls the model, executes any requested tools, streams progress, persists the resulting messages, and decides whether another model step is required. The sequence is iterative because a tool result can change what the agent needs to do next.
The queue is part of the mechanism, not just an implementation convenience. Runs are serialized per session so two turns do not write the same conversation or operate on shared session resources at the same time. A separate global lane can limit total parallel work across sessions. That allows unrelated conversations to proceed concurrently without allowing two owners to race through one session.
When a new message arrives during an active run, the default behavior is steering. OpenClaw tries to inject the message at a runtime boundary rather than starting a second run against the same session. A tool that has already started is allowed to finish; unstarted sequential calls can be skipped, and the model then sees the new input before a later tool or model decision. If the runtime cannot accept a steer, the message waits for a later turn. Follow-up mode always waits, collect mode combines queued messages into one later turn, and interrupt mode stops the active run before handling the newest message.
This behavior gives the user a more useful choice than “wait” or “cancel.” A correction can change an agent’s direction without discarding work already completed. A burst of related messages can be collected rather than triggering one model call per line. An urgent request can interrupt. The important invariant is that queue behavior remains attached to the session owner; it does not create a second uncontrolled path around the Gateway.
Before inference, OpenClaw prepares the context the runtime is allowed to see. That can include the agent workspace, user-editable bootstrap instructions, eligible skills, recent session history, and any channel metadata that belongs in the prompt. The system keeps these inputs bounded because context is a finite resource. A skill may teach the model how to use an existing tool, but it does not automatically grant that tool. A channel label may explain where the message came from, but it does not become a system instruction merely because it appears in the prompt.
Tool calls pass through their own admission boundary. The runtime resolves the requested tool, validates its arguments, and can run a before-call policy or hook before implementation begins. Tools that are safe to run in parallel can overlap; sequential tools wait for the preceding call. If a call is denied or a steer arrives before launch, OpenClaw records a paired result rather than silently deleting the model’s request from the transcript. That keeps the conversation structurally valid and tells the next model step what did not happen.
The loop emits distinct streams for assistant text, tool activity, and lifecycle state. A client may see a run start, partial assistant output, tool progress, and a terminal result. Streaming is therefore a view of the run, not proof that the external channel has accepted the final message. The Gateway also sanitizes tool results before emitting or logging them, and it tracks messaging-tool sends so an internal send does not become a duplicate assistant confirmation.
Persistence has an equally important ownership rule. Before streaming, an admitted run records an active writer claim for the session. Transcript appends and rewrites must present that expected owner, and the storage transaction checks the claim before committing. If a run is superseded, it cannot simply write its late result over the newer turn. This is one reason the Gateway, rather than each client or runtime, must own the session writer.
The vocabulary around models introduces another boundary. A provider describes how OpenClaw authenticates, discovers, and names model references. A model is the selected model for the turn. A runtime or harness is the loop that drives the model and its tools. A channel is the transport where the conversation enters and leaves. OpenClaw’s built-in runtime is one option; plugin runtimes such as Codex can own more of the native model loop or thread state, while OpenClaw continues to own the channel, policy, and surrounding integration. A provider name alone does not tell you which runtime executed a completed turn.
That separation makes fallback behavior more precise. OpenClaw first attempts bounded recovery with the current model and can rotate among eligible authentication profiles for that provider. If the failure is suitable for model failover, it can try the next configured model. The fallback answers the current turn; it does not silently rewrite the session’s selected model for the future. An explicit user model choice is treated more strictly: if that exact selection fails, the system reports the failure instead of hiding it behind an unrelated configured fallback.
Execution and delivery can diverge. A runtime may finish successfully while the external channel is unavailable. A message may be committed to a Gateway-owned conversation while an external send fails. A client’s wait request may time out even though the underlying run continues, because waiting and cancellation are different operations. Conversely, a terminal timeout is a failed turn even if earlier tool calls produced useful partial work. OpenClaw keeps these distinctions because “the model answered,” “the session recorded the result,” and “the recipient saw it” are different operational claims.
The complete path is therefore less like a single prompt-and-response exchange than a small transaction system around a model. Admission establishes authority to enter. Routing establishes ownership of context. Queueing establishes which run may touch that context. The runtime produces actions and text inside those constraints. The Gateway persists and delivers the outcome. Once that structure is visible, the next question is how new capabilities enter the loop without forcing the Gateway to own every provider, channel, tool, and workflow directly.