How OpenClaw works: gateway, sessions, models, plugins, and tools
Trace an OpenClaw message through Gateway auth, channel plugins, session routing, model fallback, agent tools, sandboxing, and replies.
The whole story in 6 lines
OpenClaw turns chat into bounded action by routing one authenticated message through deterministic sessions, registered capabilities...
- The Gateway is the authenticated control plane for operators, nodes, HTTP surfaces, and channel connections.
- Channel plugins own transport details while access policy decides whether an inbound sender may trigger the agent.
- Bindings choose one agent and dmScope determines the session key that owns context and serialization.
- Enabled native plugins register typed capabilities into the Gateway process and therefore share its trust boundary.
- Each serialized turn assembles context, selects a model and auth profile, then streams model and tool events.
- Tool policy decides what exists, sandboxing decides where it runs, and elevated changes only the exec path.
Setup
A Telegram message asks OpenClaw to summarize a private file. The request sounds ordinary, but completing it may expose local data and invoke a powerful tool.
Four terms keep the path clear. The Gateway is the control plane. A channel plugin speaks one chat service. A session key selects context. Tool policy limits callable actions.
The request now appears as one token facing six gates. Each gate either transforms routing information or narrows authority before the next component receives it.
We will follow that same token from Telegram to the final reply. Let us begin with the Gateway door and learn what it admits.
The Gateway Door
Our request first reaches the always running Gateway. Official architecture describes one control plane that owns messaging surfaces, sessions, tools, events, and paired node connections. The documented default binds this server to loopback, with authentication still required for local clients.
Operator clients and device nodes share the Gateway WebSocket transport, but they declare different roles. Nodes also claim explicit capabilities, commands, and permissions that the server checks.
The server sends a challenge before accepting the client. Which proof must arrive in the first request before ordinary methods can run?
A signed connect request passes the protocol gate, Gateway authentication, device pairing, and role scope checks. Only then does hello-ok return the negotiated protocol and allowed surface.
The Gateway is therefore an authenticated traffic controller, not the LLM itself. It also multiplexes requests, responses, and broadcast events over the negotiated connection. Next the Telegram channel will decide whether this sender may create a turn.
Channel Ingress
The Gateway door is open, so Telegram can deliver its provider shaped update. Channel code understands Telegram identifiers, threads, replies, media, and account configuration.
Before agent routing, the channel checks direct message policy and sender identity. Pairing is the documented default for many channels, which blocks unknown senders and returns a short approval code.
An allowed event becomes a common routing envelope with channel, account, peer, sender, and thread context. Before this envelope exists, who decides whether an unknown sender may trigger the agent?
The access gate now either passes one normalized envelope or stops the request with pairing. This is trigger authorization, which is separate from the tool authority used later.
Switch the Sender status control through both choices. Notice that Paired produces a routing envelope while Unknown ends at the pairing gate before any session is opened.
Channel plugins hide transport differences without choosing the final brain. Next deterministic bindings will select one agent and construct the session key for this sender.
Agent and Session Route
★ If you remember one thing · The same sender can share one main session or receive a channel-scoped session, depending on dmScope.
The admitted Telegram envelope reaches deterministic bindings. OpenClaw tests specific peer rules first, then parent, roles, guild, team, account, channel, and finally the default agent.
The selected agent contributes its workspace, auth profiles, model registry, and session store. The router then combines agent, channel, account, peer, and dmScope into a normalized session key.
Two people can now message the same agent. If direct messages use the shared main scope, where will both histories land?
The contrast is now visible. Shared main merges both tokens into one transcript, while per-channel-peer creates a distinct key for each Telegram sender and a separate serialized lane.
Switch the DM scope control between Shared main and Per sender. Watch the transcript paths merge or separate while the chosen agent remains unchanged.
A session key selects context and concurrency, but official security guidance says it is not an auth token. Next we will see how trusted plugin code supplies the capabilities used inside that session.
Plugin Registry
Routing selected the agent and session. At Gateway startup, OpenClaw separately discovers plugin manifests from configured, workspace, global, and bundled locations before runtime behavior is exposed. Discovery records origin and package metadata so later errors can name the responsible extension.
Core validates configuration and decides whether each candidate is enabled, disabled, blocked, or selected for an exclusive slot. That metadata pass can diagnose problems before running plugin code.
An enabled native module runs its register function and contributes typed capabilities to one central registry. What security boundary contains that plugin code?
The registry fans out into channel adapters, model providers, tools, hooks, HTTP routes, commands, and services. The inspected source snapshot performs discovery, safety checks, module loading, and API registration in that order.
This capability registry explains extension without magical autonomy. Plugins supply implementations and hooks, while core still owns routing, fallback, policy, and delivery. Next the selected provider joins the serialized agent loop.
Model and Agent Loop
The registry supplied a provider and tools, so the routed session can begin one serialized agent run. A per-session queue prevents overlapping turns from racing the same history.
OpenClaw prepares the workspace and builds a system prompt from base guidance, skills, bootstrap files, session messages, and per-run overrides. This is actual context assembly before inference.
The selected session model receives the first attempt. When a failover-worthy provider error appears, which action happens before the configured fallback model?
The chosen candidate now feeds the loop. Assistant deltas and tool calls stream as events, while lifecycle end or error closes the run and preserves usage plus transcript state.
Switch the Provider state control between Healthy and Rate limited. Notice that the same prepared context reaches the primary model or the next configured fallback candidate.
Model routing chooses where reasoning runs, but it does not grant actions. Next the requested file read meets tool policy, sandbox placement, and the special exec elevation gate.
Tool Boundaries and Reply
The model requests a file or command action, but a request is not authority. OpenClaw first filters built-in and plugin tools through profile, provider, global, agent, group, and sandbox policies.
Deny rules win, and a nonempty allowlist hides everything else. Owner-only checks can remove sensitive control plane tools for non-owner senders before execution is possible.
If a tool survives, sandbox configuration decides where it runs. Elevated changes only exec placement outside a sandbox. Can elevation resurrect an exec tool denied by policy?
The full boundary is now visible. A denied tool disappears, a sandboxed tool acts inside its container, and a host path reaches its own elevated and approval gates before changing the machine.
Switch the Execution path control through every choice. Compare a missing tool, a contained action, and a host gate. Then leave it on Sandboxed to solve the challenge.
Tool results return to the agent loop, and the final payload routes back to the originating channel without asking the model to choose a destination. Now let us step back and see the whole picture together.
Recap
We started at the Gateway door, where transport, shared secret or identity auth, device pairing, role, and scope checks decide which clients enter.
Then the Telegram channel translated one provider event and applied sender policy before producing the normalized routing envelope.
Bindings selected an agent, and dmScope converted sender context into either a shared or isolated session key for history and serialization.
Next the trusted plugin registry supplied typed channels, providers, tools, hooks, routes, and services to the running Gateway.
The serialized agent loop assembled context, selected a model and auth profile, then streamed model and tool events into the session.
Finally tool policy controlled availability, sandboxing controlled placement, and elevated changed only the exec path before the reply returned to Telegram.
Together these boundaries turn a chat message into a controlled action. The source-backed lesson ends there because provider internals and model reasoning remain outside OpenClaw itself.
The whole story in 6 lines
OpenClaw turns chat into bounded action by routing one authenticated message through deterministic sessions, registered capabilities...
- The Gateway is the authenticated control plane for operators, nodes, HTTP surfaces, and channel connections.
- Channel plugins own transport details while access policy decides whether an inbound sender may trigger the agent.
- Bindings choose one agent and dmScope determines the session key that owns context and serialization.
- Enabled native plugins register typed capabilities into the Gateway process and therefore share its trust boundary.
- Each serialized turn assembles context, selects a model and auth profile, then streams model and tool events.
- Tool policy decides what exists, sandboxing decides where it runs, and elevated changes only the exec path.