01 / 11
LIVE
OpenClaw
00 / intro

How OpenClaw
works under the hood

Architecture & technical flow

You already know what OpenClaw does and why it exists. Today we open the hood and look at what's inside; from the moment a message arrives on WhatsApp or Telegram to when the agent executes an action and responds.

◎ The engineering decisions that make a stateless LLM behave like a persistent assistant
01 / core concept

One process,
many channels,
one agent

OpenClaw is a Node.js daemon running continuously on hardware you control: a Mac Mini, a VPS, a home server.

  • Single process connects to all messaging channels
  • WhatsApp, Telegram, Slack, Discord, iMessage - 50+ adapters
  • The agent is the same across all of them: same state, same tools, same memory
◎ Not independent chatbots per channel. One brain, many mouths.
02 / architecture

Hub-and-spoke
architecture

The hub is the Gateway - a WebSocket server listening on port 18789, bound to localhost.

  • Channel bridges - messaging platform adapters
  • Control clients - desktop app, CLI, admin web UI
  • Nodes - devices exposing local capabilities (camera, screen, location)

Each client connects to the same WebSocket server, declares its role on handshake, and the Gateway routes accordingly.

03 / message lifecycle

A message's
journey

01
Channel Bridge Normalizes the message into a unified internal envelope - sender, content, attachments, thread context
02
Session Resolution Gateway maps the message to a session: main, group, or isolated
03
Lane Queue FIFO queue with concurrency control - one active run per session by default, avoiding race conditions
04
Agent Runtime Loads context, invokes the model, executes tools, persists updated state
04 / prompt assembly

What the
model sees

A fresh system prompt is assembled every turn from multiple workspace files:

SOUL.mdPersonality, tone, behavioral limits
AGENTS.mdOperational instructions, routing rules, security policies
USER.mdHuman context: name, timezone, preferences
TOOLS.mdEnvironment notes - SSH hosts, device configs
MEMORY.mdLearned patterns, distilled over time
IDENTITY.mdName, emoji, avatar
Limits bootstrapMaxChars 20k / file bootstrapTotalMaxChars 150k total
05 / agentic loop

The agentic
loop

The standard agent pattern, with OpenClaw's control layers on top.

  • Model responds with text (done) or a tool call (continue)
  • OpenClaw executes the tool, appends result to history, re-sends to model
  • Repeats until text-only response or 600s timeout
↺ Responses stream token-by-token back to the channel - the user sees the answer as it's generated

Model-agnostic: Anthropic, OpenAI, local models. Key rotation built in.

06 / tools & sandbox

What the agent
can do - and
how to limit it

shell exec
file r/w
browser (CDP)
cron jobs
webhooks
canvas
MCP
skills

Docker sandboxing - tool execution inside an isolated container, not the host.

offEverything on host
non-mainNon-main sessions sandboxed
allEverything sandboxed

Default: no network, no write access to root fs, isolated workspace. Not a perfect sandbox - reduces blast radius, not an absolute limit.

07 / memory

How a stateless
model remembers

L1
Session history Full conversation in JSONL on disk, replayed every turn
L2
Disk memory Daily Markdown notes → distilled to MEMORY.md. Hybrid retrieval: vector search + SQLite FTS5
L3
Compaction When history exceeds context window, oldest turns are summarized. Keeps ~20k tokens of recent messages intact

Compaction invalidates Anthropic's prompt cache - each unnecessary compaction is a reliability and cost problem.

08 / extensibility

Extending
without touching
the core

OpenClaw is plugin-first. Core is ~8MB after the 2026 refactor. Even model providers are external packages.

  • Skills - SKILL.md + optional scripts. 5,400+ on ClawHub. Model reads full content only when relevant.
  • Channel plugins - adapters for new messaging platforms
  • Provider plugins - new model APIs or local inference engines
  • Memory plugins - alternative backends (vector stores, knowledge graphs)

Plugin discovery: loader scans for openclaw.extensions in package.json, validates schemas, hot-loads.

09 / security

Where the
real risks are

⚠ Feb 2026 - CVE-2026-25253 (CVSS 8.8). RCE with one click from a malicious page. 30,000+ exposed instances. Default bind was 0.0.0.0.

Everything that makes it powerful is exactly what makes it dangerous: shell, filesystem, browser, email, external services.

Trust hierarchy: Operator → Gateway config → Allowed peers → AI model → Untrusted content

Hardening baseline:

  • Gateway bound to loopback only
  • Remote access via SSH tunnel or Tailscale
  • Sandboxing enabled + tool allowlists
  • Credentials in plaintext at ~/.openclaw/ - protect accordingly
10 / summary

The full picture

Platform message
→
Channel bridge normalizes
→
Gateway routes to session
→
Lane Queue serializes
→
Agent Runtime assembles prompt
→
Agentic loop (model ↔ tools)
→
Streaming response back to channel
◎ Key decision: separation of control plane (lightweight Gateway, one process, one host) from inference plane (any provider, anywhere). Simple file-based persistence. A stateless model behaving like a persistent assistant.
EXPLORER