An architectural field guide to the self-hosted, persistent, lobster-themed AI agent.
By Majid Mazouchi · Reading the architecture of Peter Steinberger's open-source agent
OpenClaw is a free, open-source autonomous agent — a long-running process that executes tasks on a user's behalf through large language models, using ordinary messaging apps as its interface instead of a bespoke chat window. Where most agents are summoned by a prompt, do one job, and stop, OpenClaw stays resident: it lives on your own hardware, remembers you, and speaks up only when something needs attention.
The project's name has migrated three times in two months. It began life in November 2025 as Clawdbot, a tongue-in-cheek nod to Anthropic's Claude. Trademark friction prompted a rename to Moltbot in late January 2026 (preserving the lobster motif), and three days later it settled on OpenClaw — the name that stuck as the repository rocketed past 100,000 GitHub stars. The system is local-first by design: inference can run against Anthropic, OpenAI, or fully local models, and by default no data leaves the machine.
This guide describes the architecture as of mid-2026. OpenClaw evolves quickly; treat module names and default ports as accurate-at-time-of-writing rather than frozen. Every factual claim is sourced in §18.
The official documentation reduces the system to five fundamental building blocks. Everything else — channels, skills, the canvas, the security perimeter — hangs off these. Holding them in mind is the fastest way to read the diagrams that follow.
The single front door. Routes every inbound message and outbound reply across channels over one WebSocket API.
The LLM reasoning core. Plans, decides, and chooses which tools to call within a structured loop.
The tools and effectors — shell, files, browser, web fetch — through which the Brain acts on the world.
Persistent state in plain Markdown plus a search index — survives restarts, updates, migrations.
A cron-driven pulse that periodically wakes the agent to check its task list and act proactively.
Architecturally OpenClaw is best understood as a hub-and-spoke system layered between the outside world and the host machine. Channels feed a single orchestrating Gateway; the Gateway drives a reasoning core that reads from memory and reaches for tools; a runtime enforces the security perimeter around all tool execution. The block diagram below is the canonical mental model — the remaining sections zoom into individual blocks.
The Gateway is where every message enters and every reply leaves. Its key design move is refusing to build a proprietary chat UI; instead it binds to channels you already use — WhatsApp, Telegram, Slack, a web widget, or any API endpoint — so there is no new app and no context switch. Internally it maintains the provider connections and exposes a typed WebSocket API with three traffic classes: requests, responses, and server-pushed events.
Inbound frames are validated against a JSON Schema before they are trusted. The server emits a stream of events — agent, chat, presence, health, heartbeat, cron — that clients subscribe to. Crucially, the Gateway is a single-writer per session: a command queue serialises actions so that exactly one Gateway controls one messaging session per host, eliminating the race conditions that plague multi-writer agent designs. It runs as a supervised service (systemd / launchd) on a default loopback port, 127.0.0.1:18789, and reports liveness through a health channel.
The Brain is the LLM-driven reasoning core; the Hands are the tools it invokes — shell commands, file reads and writes, browser automation, web fetches, scripts. What makes the pairing an agent rather than a chatbot is the control structure that wraps them: a dual loop.
Within a single turn, the Brain runs a reason–act cycle. It thinks about the goal, decides on a tool, calls it through the Hands, observes the result, and repeats until the task is resolved or it needs the human. Before any of this fires, a context-assembly step packages the conversation history, the relevant memory, and the operating instructions into one prompt.
Around the inner loop sits a queue of pending tasks. This is what lets a single user request spawn multi-step work that persists across turns, and what the Heartbeat (§06) consults when it wakes. The context window is treated like a finite, expensive cache: the runtime is careful about what it loads, which is exactly why skills are injected lazily rather than wholesale (§08).
The Heartbeat is the feature that separates OpenClaw from a reactive assistant. It is, architecturally, a cron-triggered agentic loop: at a fixed cadence the agent is woken, handed its current context and a checklist, and asked to evaluate whether anything needs doing. If nothing does, it returns a sentinel — HEARTBEAT_OK — which the Gateway silently swallows and never delivers. You are not pinged every interval; the agent merely checks every interval and speaks only when there is a reason.
This single mechanism underlies daily briefings, website-change monitoring, calendar-conflict warnings, and reminders pulled from earlier conversation. The cadence and the conditions live in a workspace file (HEARTBEAT.md, §09), so behaviour is edited like text, not recompiled.
Large language models are stateless — each call starts from nothing. OpenClaw's answer is a persistent memory layer that survives restarts, software updates, and even migrations between machines. The clever part is its dual representation: a human-readable surface and a machine-efficient index, kept in sync.
The surface is plain Markdown — files such as MEMORY.md that you can open in any editor and read or correct by hand. Underneath sits an index layer: a SQLite store, vector embeddings, and semantic search. When you ask a question, the system searches past conversations for semantically related material and injects that slice into the current turn, giving the stateless model the illusion of continuity. You get transparency (read your own memory in VS Code) and performance (the agent queries an optimised index) at once.
Because memory files are writable Markdown, they are also a persistence target. The January 2026 ClawHavoc incident saw malicious skills write payloads directly into MEMORY.md and SOUL.md to survive across sessions — see §11.
Capabilities in OpenClaw are not compiled plug-ins; they are Markdown files. Each skill lives at a path like ~/clawd/skills/<name>/SKILL.md and contains natural-language instructions for talking to an API or running a workflow. The agent reads these at runtime, so installing a skill is immediate — no recompilation, no server restart. You change what the agent can do, and how it behaves, by editing files in the workspace while the runtime continues to enforce execution, permissions, and sandboxing.
The subtle, important detail is that OpenClaw discovers skills broadly but injects them narrowly. Dumping every skill into every prompt would balloon the context window and degrade model quality, so the system prompt lists skills as metadata only — name, description, file path — and the model reads a full SKILL.md on demand, only when the current turn calls for it. The analogy is a developer with an IDE full of docs: you don't read every manual at startup, you look up the one you need.
Skills are distributed through ClawHub, the official directory, with each entry carrying a Skill Card describing what it does and where it came from, and scanned for hidden instructions before listing. That curation exists because skills are, functionally, untrusted code (§11).
An OpenClaw agent's personality and operating rules are not hard-coded — they are assembled at runtime from a stack of workspace files, all of them plain Markdown living in a git-backable directory. The system prompt the model actually sees is a composition of runtime scaffolding plus this project context. The blueprint below maps the principal files; editing them is how you make an agent yours without touching a line of source.
runtime scaffolding + ── project context ── (workspace Markdown)
Because the workspace is plain Markdown under version control, the prompt is auditable, diffable, and portable — the same property that makes it powerful makes it a tampering target if a skill can write to it.
Tracing one message — say, "Help me analyse this sales data" — through the whole stack ties the pieces together. The sequence diagram reads top to bottom; time flows downward along each lifeline.
OpenClaw's security model is deliberate and, for an engineer evaluating it, the most consequential part of the design. The starting premise is the single-operator trust boundary: a Gateway is not modelled as a multi-tenant, adversarial surface. Anyone with authenticated Gateway access is treated as a trusted operator — on the reasoning that such a person could already SSH into the host directly. This is a documented choice, not an oversight, and it mirrors how mainstream LLM products decline to treat prompt injection as a classical vulnerability solvable at the model layer.
The corollary is sharp: the sender is not the only threat surface — the content is. Even if only you can message the bot, any untrusted material it reads — web pages, emails, documents, attachments, pasted logs — can carry adversarial instructions. This is indirect prompt injection, and the standard mitigation is a read-only reader agent that summarises untrusted content before a tool-enabled agent ever touches it.
Because the model can be confused, the architecture assumes it will be and constrains blast radius instead. The strongest control is the tool allowlist: even if an attacker convinces the model to want a destructive command, it cannot run unless it is on the list. Untrusted sessions are run with a stripped tool profile (messaging only; filesystem, runtime, and admin tools denied by default), file writes to system paths are redirected into a sandbox, and secrets are injected via environment variables rather than the prompt.
Hundreds of ClawHub skills were found carrying malware — an info-stealer that harvested API keys, planted keyloggers, and wrote persistent payloads into MEMORY.md and SOUL.md. One posed as a crypto trading tool and lifted wallet credentials. The takeaway is blunt: treat every unverified skill as untrusted code, audit before install, and run new skills sandboxed with minimal permissions.
The same architecture scales down to a laptop and up to a VPS. All inference and state stay local by default, so the deployment decision is really about availability and exposure, not data residency. A common, hard-won piece of advice: do not run OpenClaw on your daily-driver or work machine — give it its own box.
Everything an operator tunes lives in one file: ~/.openclaw/openclaw.json, written in JSON5 (comments and trailing commas allowed). It is validated against a strict schema on every startup — add a key that doesn't exist, or give one the wrong type, and the Gateway refuses to boot rather than running misconfigured. Every field is optional; with no file present, OpenClaw falls back to safe defaults. Crucially, secrets do not live here: the config holds secretRef pointers (env / file / exec sources) while the actual credentials sit in ~/.openclaw/auth-profiles.json.
// JSON5 — comments + trailing commas OK. Strict-schema validated on boot. { channels: { telegram: { enabled: true, botToken: { secretRef: "env:TG_TOKEN" }, // never inline secrets dmPolicy: "pairing", // pairing | allowlist | open | disabled groupPolicy: "mention", // require an @-mention in groups allowFrom: ["tg:123456789"], }, }, session: { dmScope: "per-channel-peer" }, // isolate multi-user DMs agents: { defaults: { workspace: "~/clawd", model: { primary: "anthropic/claude-opus-4-6", // provider/model ref fallbacks: ["anthropic/claude-sonnet-4-6"], // auto-failover }, models: { "anthropic/claude-opus-4-6": { alias: "Opus", cacheControlTtl: 300 }, }, thinking: "medium", heartbeat: { intervalMin: 30 }, // the pulse cadence (§6) memory: { enabled: true }, skills: { autoInject: false }, // metadata only; body on demand (§8) sandbox: { mode: "non-main", // off | non-main | all docker: { image: "openclaw-sandbox:bookworm-slim", network: "none", readOnlyRoot: true }, }, }, }, }
OpenClaw hot-applies most edits the moment you save, but a handful of structural settings only take effect after the Gateway is bounced — and per-agent overrides of defaults-only keys are silently ignored, which is its own class of bug.
dmPolicy, allowFrom)gateway restartopenclaw doctor --fixEdit safely from the CLI rather than hand-patching: openclaw config set agents.defaults.models '<json>' --strict-json --merge adds entries without clobbering existing ones (a removal needs --replace), and openclaw config get <key> reads the resolved value from the running Gateway, not just the file. Need two agents on one box? Give each its own state directory with openclaw --profile work gateway run --port 18790 (or set OPENCLAW_HOME).
Models are referenced as provider/model, and a per-model api field selects the request dialect: "anthropic" for the Anthropic API, "openai-responses" for most OpenAI-compatible local servers, and "openai-completions" for Ollama. A primary agent model must support function/tool calling — the whole tool system depends on it. The embedded runtime (pi-mono) handles the actual LLM interaction and supports block streaming (emitting completed blocks as they finish); the date is kept timezone-only so the prompt stays cache-stable across turns. Fallbacks rotate automatically on rate limits or outages.
Service control lives under openclaw gateway install / start / stop / restart / status (the older openclaw daemon … is a legacy alias). When the config-enabled core auto-updater fires, it doesn't replace the package inside the live process: it launches a detached helper that runs the normal update path from outside the Gateway's process tree, so an in-flight turn isn't severed mid-thought.
Since capabilities are just Markdown (§8), the unit of extension is a folder — ~/clawd/skills/<name>/SKILL.md — with two distinct halves. The front-matter (name + description) is the cheap "card" that always sits in the system prompt so the model knows the skill exists; the body is the heavier payload, read just-in-time only when a turn actually invokes the skill. The annotated example below is representative of the shape; the comments mark which part goes where.
--- <- front-matter: the only part always resident in the prompt name: weather description: > Current conditions and short forecasts by city. Use when the user asks about weather, rain, temperature, or what to wear. --- # Weather skill <- body: loaded ON DEMAND, not always in context ## When to use Trigger on questions about current or upcoming weather for a place. ## How 1. Resolve the city name to coordinates. 2. GET https://api.example.com/forecast?lat={lat}&lon={lon} Authorization: Bearer ${WEATHER_API_KEY} # secret via env, not prompt 3. Summarise today plus the next three days in two sentences. ## Guardrails Read-only. No filesystem writes, no shell. Decline requests that resolve to a specific private home address.
The front-matter is what §8's lazy injection lists as metadata; the body is the payload pulled in only when needed. The ${WEATHER_API_KEY} pattern keeps secrets out of the prompt (§11), and the explicit Guardrails block is how a skill declares least-privilege intent — the runtime's allowlist still enforces it regardless of what the Markdown claims. On ClawHub, each published skill additionally carries a Skill Card and is scanned by SkillSpector before listing.
OpenClaw's documentation and community lean hard into the crustacean theme, which can obscure plain meanings. This glossary translates the vocabulary used throughout this guide.
A one-page distillation, built to survive printing. From the browser, Cmd / Ctrl-P → Save as PDF renders the whole guide — diagrams, fonts and all — at full fidelity.
:18789:18793~/.openclaw/openclaw.jsonauth-profiles.json~/clawdnpm i -g openclawonboard --install-daemongateway statusdashboardupdatedoctor --fixAGENTS.mdSOUL.mdUSER.mdHEARTBEAT.mdskills/*/SKILL.mdpairing…disabledoff · non-main · allanthropic · openai-*--channel stable/beta/devOpenClaw became one of the fastest-growing repositories of early 2026, and the enthusiasm was less about the specific tool than about the shape it crystallised. The combination — local Gateway + agentic loop + lazily-injected skills + persistent file-backed memory — is a readable, MIT-licensed instance of the same primitives that power production agent systems at serious AI labs. The vocabulary it popularised (the persistent "claw," the heartbeat, the SKILL.md) is now common shorthand, and vendor reference implementations and enterprise hardening kits have grown up around it.
For anyone designing their own multi-agent tooling, the lessons transfer cleanly: keep the orchestrator single-writer; treat the context window as a budget and inject capabilities just-in-time; make behaviour editable as version-controlled Markdown rather than code; and assume the model can be subverted, so put the real security boundary at the tool layer with allowlists and a sandbox. The lobster is a joke; the architecture is not.
Compiled June 2026. All diagrams are original schematic renderings prepared for this guide; prose is an independent synthesis of the sources above.