There is a useful exercise in software engineering that does not get taught often enough: pick a substantial open-source project, read the architecture carefully, and write down what you found. Not as a tutorial. Not as a contribution. As an architectural reading — the engineering equivalent of a music critic close-listening to a recording, naming the choices that were made, putting words around what makes the design work or not.
This post is that kind of reading, applied to OpenClaw — Peter Steinberger’s open-source, self-hosted, persistent AI agent. (The project began life as Clawdbot in November 2025, transited through Moltbot, and settled on OpenClaw around the time it crossed 100,000 GitHub stars.) I picked it because the architecture is more interesting than the lobster theme might lead you to expect. It is a clean, opinionated, resident agent — not a request/response service, but a long-running process you give a chunk of compute and watch over a span of days. The architectural pattern it crystallizes — gateway plus dual loop plus skills plus memory — turns out to be the one that several of the more thoughtful agent projects of 2025–26 converged on independently. It is worth understanding regardless of whether you ever run OpenClaw itself.
The reading is written for engineers who want to extract reusable architectural ideas, not as an installation guide. Section 18 of the source guide contains the citations to the official OpenClaw documentation if you want to follow up on any specific claim.
What it covers
Eighteen sections, about twenty-eight minutes.
§ 01–02 — Foundations. What OpenClaw is, where it came from (the Clawdbot → Moltbot → OpenClaw lineage), and the five pillars the official documentation organizes the system around — gateway, brain, hands, heartbeat, memory.
§ 03 — System topology. The block diagram. How the pieces are arranged, where the trust boundaries are, what runs in-process versus out-of-process. The local-first design choice and what it costs.
§ 04 — The Gateway. The front door. How messages from WhatsApp, Telegram, Slack, Discord, Signal, and iMessage all funnel through a single normalization layer before reaching the agent loop. The channel-adapter pattern.
§ 05 — Brain & Hands — the dual loop. The architectural heart of the system. Brain is the reasoning loop — LLM calls, planning, deciding what to do next. Hands is the execution loop — running tools, calling APIs, performing actions. Why they are kept separate, and what failure modes that separation prevents.
§ 06 — The Heartbeat. The mechanism that makes OpenClaw proactive rather than purely reactive. A scheduler that wakes the agent on a timer (or on external events) and lets it volunteer information instead of waiting to be asked. This is the architectural feature that distinguishes “persistent agent” from “chatbot.”
§ 07 — The Memory system. Short-term, working, and long-term memory, plus the layered approach to summarization that prevents context window explosion. Where the conventional knowledge-and-memory taxonomy maps onto OpenClaw’s specific choices.
§ 08 — Skills & the context economy. The progressive-disclosure pattern at work. Skills are markdown files (SKILL.md) that get loaded in stages — preview, then body, then references — so the agent can have a hundred skills available without paying for all of them on every turn.
§ 09 — The system-prompt blueprint. What lives in the always-on system prompt versus what gets lazily included. The discipline that keeps it from sprawling.
§ 10 — End-to-end message flow. A single message traced through the entire system. Channel → Gateway → Brain → tool selection → Hands → response → channel. With timing notes for where latency actually lives.
§ 11 — Security architecture. The single-operator trust model. What the agent can do (anything its tools allow). What it can’t (cross-operator boundaries; there’s no multi-tenancy). The hardening that comes from being self-hosted.
§ 12 — Deployment topologies. All-on-laptop, NAS-resident, VPS, and the hybrid options. Resource sizing. The trade-off between “always available” and “only when my laptop is open.”
§ 13 — Configuration & lifecycle. The config file. Process management. Logging. Updates. The boring-but-essential operational details that make the difference between something you deploy once and something you actually live with.
§ 14 — Anatomy of a skill. A worked example of one of the skills, file by file, taken apart and explained.
§ 15–17 — Lexicon, cheat sheet, reflection. A glossary (the lobster lexicon), a quick-reference card, and a closing section on why this architectural pattern matters beyond OpenClaw itself.
§ 18 — References. Citations and links to the source material, official documentation, and related work.
Read it
The field guide lives at its own URL with a warm-paper editorial layout — rust accent, petrol blue cross-references, ochre highlights. Eighteen sections, written as a careful architectural reading rather than a tutorial.
← Back to Autonomy