OpenClaw Architecture - Part 1: Control Plane, Sessions, and the Event Loop

The Agent Stack

SubscribeSign in

OpenClaw Architecture - Part 1: Control Plane, Sessions, and the Event Loop<br>Why it feels “alive”… and why it’s really just inputs + state + a loop

Vinoth Govindarajan<br>Feb 17, 2026

248

24

Share

Most AI agent demos feel magical.<br>OpenClaw feels autonomous.<br>But under the hood, it’s not magic - it’s a disciplined event-driven system.<br>OpenClaw is a self-hosted, open-source personal AI assistant that lives closer to your operating system than a typical chat app. Instead of chatting inside a browser tab, it connects to the messaging channels you already use (WhatsApp, Telegram, Slack, Discord, iMessage, WebChat, and more) and can execute real actions through tools.<br>A lot of people describe OpenClaw as “autonomous” or “always on.” The easiest way to demystify it is:<br>OpenClaw doesn’t become proactive because it “wakes up and thinks.” It feels proactive because it has more kinds of inputs than just your messages, and it processes them in a consistent loop.<br>That’s the elegant architectural secret.

1) What OpenClaw is (and what it isn’t)

What it is:<br>A Gateway (control plane) that receives events from many places and routes them.

An agent runtime that takes a “turn,” calls an LLM, uses tools, writes state, and replies.

OpenClaw’s own docs describe the Gateway WebSocket protocol as the single control plane that all clients connect to (CLI, web UI, macOS app, iOS/Android nodes, etc.).<br>What it isn’t:<br>A sentient system.

A continuously reasoning brain running in the background.

If it looks like it “had an idea at 3:00 AM,” it’s usually because a timer, schedule, webhook, or hook created an event at 3:00 AM , and the agent ran a normal turn.

2) The big picture: hub-and-spoke, with the Gateway at the center

If you’re visual, here’s the whole architecture in one diagram:

OpenClaw is essentially an event-driven, session-isolated, single-writer state machine built around a centralized control plane.

Key idea: the Gateway is the traffic controller and source of truth. The agent runtime is the worker that does the “thinking + doing.”

3) The Gateway: the central router (and source of truth)

OpenClaw runs a Gateway daemon that stays up, keeps connections alive, and coordinates the entire system. The docs are explicit:<br>All session state is owned by the Gateway

UI clients should query the Gateway rather than reading local session files directly

3.1 Sessions: isolation is deliberate (and configurable)

When you talk to OpenClaw from different places (DM vs group chat, Telegram vs Slack, etc.), you don’t want accidental context leaks. OpenClaw models this as session keys .<br>The session model is flexible, but the default concept is:<br>One primary DM-like session per agent (often called main)

Separate sessions for groups/channels/threads

Optional “secure DM mode” that isolates DMs per sender/channel/account to avoid leaking context between people

A simple mental model:

If you’re running OpenClaw for more than just yourself, secure DM mode matters because the default DM scope can share the same session context across DMs for continuity unless configured otherwise.<br>3.2 Where session state actually lives

OpenClaw stores session transcripts on disk as JSONL and keeps a store file that maps session keys to session ids and metadata. The docs show paths like:<br>Store: ~/.openclaw/agents//sessions/sessions.json

Transcripts: ~/.openclaw/agents//sessions/.jsonl

This matters for two reasons:<br>Durability : sessions survive restarts

Security : those files can contain sensitive content

4) The queue: how OpenClaw prevents “two thoughts at once” collisions

If multiple inputs arrive close together (a Slack DM + a heartbeat + a webhook), you do not want concurrent runs trampling the same session files or tool state.<br>OpenClaw addresses this with a lane-aware FIFO queue :<br>It guarantees only one active run per session

It can still allow parallelism across different sessions , up to configured caps

Here’s a simplified version of how that queue works:

OpenClaw also supports different queue behaviors (“modes”) such as:<br>collect (default): coalesce multiple messages into one follow-up turn

followup : always wait until the current run ends

steer : inject into the current run (at tool boundaries)

So the “sequential state machine” feeling is real per session , but the system can still run other sessions concurrently depending on configuration.

5) The protocol: everything speaks the same typed WebSocket language

A big reason OpenClaw can support many surfaces (CLI, web UI, desktop app, mobile nodes) is that it treats the Gateway as a proper control plane.<br>5.1 Three frame types: req / res / event

OpenClaw defines a simple WebSocket message model:<br>Request: { type: "req", id, method, params }

Response: { type: "res", id, ok, payload | error }

Event: { type: "event", event, payload, ... }

And the first frame must be a connect...