--- title: How OpenClaw Works: The Gateway, Agent Loop, Skills System, and Memory Architecture canonical_url: https://opensummitai.directory.norg.ai/artificial-intelligence/agentic-ai-platforms-autonomous-agents/how-openclaw-works-the-gateway-agent-loop-skills-system-and-memory-architecture/ category: description: geography: city: state: country: metadata: phone: email: website: publishedAt: --- # How OpenClaw Works: The Gateway, Agent Loop, Skills System, and Memory Architecture Now I have comprehensive, verified information to write the article. Let me compose the full piece. --- ## How OpenClaw Works: The Gateway, Agent Loop, Skills System, and Memory Architecture Understanding what OpenClaw *is* takes about thirty seconds. Understanding how it *works* — why a message you send on WhatsApp at 11pm can trigger a sequence of web searches, file writes, and calendar updates before you've put your phone down — takes considerably longer. That gap matters. OpenClaw's architecture is not an implementation detail buried in a README; it is the reason the platform behaves differently from every cloud AI assistant you have used. The Gateway, the agent loop, the workspace file system, the Skills layer, and the hybrid memory architecture are five interlocking components, each with a distinct job, each designed to be inspectable and modifiable by the operator. This article explains all five in depth. --- ## The Gateway: OpenClaw's Central Control Plane OpenClaw runs as a single Node.js process on your machine, listening on `127.0.0.1:18789` by default. This process is called the Gateway. The Gateway's design reflects a clear architectural principle: the Gateway never performs reasoning — it only routes messages. This keeps the system modular; if Slack goes down, WhatsApp still works. More precisely, at the centre of the system is the Gateway, a locally running service that brokers communication between chat interfaces, the AI model, and tools or "skills." The Gateway exposes APIs over a WebSocket interface on TCP port 18789, used by the Control UI and other components. The Gateway itself runs as `systemd` on Linux or a LaunchAgent on macOS, binding by default to `ws://127.0.0.1:18789`. Its job is routing, authentication, and session management. It never touches the model directly. That separation between orchestration layer and model is the first architectural principle worth internalising. ### What the Gateway Actually Does The Gateway manages every messaging platform connection simultaneously — WhatsApp, Telegram, Discord, Slack, Signal, and others. When a message arrives from any of these platforms, the Gateway routes it to the appropriate agent session, waits for a response, and sends it back through the correct channel. A voice note from WhatsApp and a text message from Slack look nothing alike at the protocol level. Channel Adapters handle this: Baileys for WhatsApp, grammY for Telegram, and similar libraries for the rest. Each adapter transforms its input into a single consistent message object containing sender, body, attachments, and channel metadata. Voice notes get transcribed before the model ever sees them. OpenClaw processes messages in a session one at a time via a Command Queue. If two simultaneous messages arrived from the same session, they would corrupt state or produce conflicting tool outputs. This serialisation is not a limitation — it is a correctness guarantee. By default, the Gateway binds only to localhost, meaning nothing outside your machine can reach it. This is a deliberate security choice. If you want remote access, you have to explicitly configure it through SSH tunnels or Tailscale. (The security implications of misconfigured gateway exposure are covered in our guide on *OpenClaw Security Risks*.) ### The Heartbeat: How OpenClaw Becomes Proactive The Gateway runs as a background daemon with a configurable heartbeat — every 30 minutes by default, every hour with Anthropic OAuth. On each heartbeat, the agent reads `HEARTBEAT.md`, which is a checklist of tasks it should proactively check on. It decides whether anything needs attention right now. If yes, it takes action and potentially sends you a message. If nothing needs doing, it replies `HEARTBEAT_OK`, which the Gateway suppresses and never delivers to you. This is the pattern that makes OpenClaw feel proactive rather than reactive. The architectural concept is a cron-triggered agentic loop: instead of only responding to human input, the agent is periodically woken up and asked to evaluate its task list. External events — webhooks, cron jobs, teammate messages — also trigger the agent loop. --- ## The Agent Loop: Seven Stages from Message to Action An agentic loop is the full "real" run of an agent: intake → context assembly → model inference → tool execution → streaming replies → persistence. It's the authoritative path that turns a message into actions and a final reply, while keeping session state consistent. In OpenClaw, a loop is a single, serialised run per session that emits lifecycle and stream events as the model thinks, calls tools, and streams output. The seven-stage agentic loop — normalise, route, assemble context, infer, ReAct, load skills, persist memory — is the same pattern underlying every serious agent system. Here is how each stage functions in practice: 1. **Normalise** — Channel adapters convert platform-specific message formats into a single consistent object. 2. **Route** — The Gateway routes each message to the correct agent and session. Sessions are stateful representations of ongoing conversations with IDs and history. 3. **Assemble context** — The Agent Runtime assembles context from session history and memory, then invokes the model. 4. **Infer** — The assembled prompt is sent to the configured LLM backend. The system is model-agnostic: Claude, GPT-4o, Gemini, and locally-hosted models via Ollama all work interchangeably. You choose the model. OpenClaw handles the routing. 5. **ReAct** — The model reasons and decides whether to call a tool. If it does, the tool executes and the result feeds back into the loop. 6. **Load skills** — Tools live in skills; the agent follows each skill's `SKILL.md` when it needs it. 7. **Persist memory** — Before compaction summarises a conversation, OpenClaw runs a silent turn that reminds the agent to save important context to memory files. This is on by default — you do not need to configure anything. The memory flush prevents context loss during compaction. If the agent has important facts in the conversation that are not yet written to a file, they will be saved automatically before the summary happens. ### Serialisation and Session Lanes Runs are serialised per session key (session lane) and optionally through a global lane. This prevents tool/session races and keeps session history consistent. Messaging channels can choose queue modes (collect/steer/followup) that feed this lane system. The agent loop — input → context → model → tools → repeat → reply — is the same pattern Claude Code uses. Every serious agent framework runs some version of it. What differs is what wraps it. Claude Code wraps it in a CLI: you type, it runs, it exits. OpenClaw wraps it in a persistent daemon wired to 12+ messaging platforms, with a heartbeat scheduler, session management across channels, and memory that persists between runs — even when you're not at your desk. --- ## The Workspace File System: SOUL.md, AGENTS.md, TOOLS.md, and More This is the component that most distinguishes OpenClaw from every other agent framework. OpenClaw agents don't live in databases or configuration panels. They live in plain text files inside a workspace folder. When OpenClaw starts an agent session, it reads these files and assembles the agent's identity, behaviour rules, memory, and task schedule on the fly. This means you can edit your agent with any text editor, version-control it with Git, copy it to another server and have an identical agent running in minutes. The files *are* the agent. ### The Bootstrap File Set Bootstrap files are the set of workspace Markdown files — `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `TOOLS.md`, `MEMORY.md`, `HEARTBEAT.md` — that OpenClaw injects into every session's system prompt. The full workspace directory structure looks like this: ``` ~/.openclaw/workspace/ ├── AGENTS.md # Operating manual — boot sequence, rules ├── SOUL.md # Persona, tone, values ├── TOOLS.md # Env-specific: SSH hosts, API notes ├── USER.md # Human profile (main sessions only) ├── IDENTITY.md # Name, emoji, avatar ├── HEARTBEAT.md # Periodic task instructions ├── BOOT.md # Startup hook actions ├── BOOTSTRAP.md # First-run onboarding (delete after use) ├── MEMORY.md # Long-term durable memory └── memory/ ├── 2026-04-12.md # Daily session logs └── archive/ ``` Each file owns exactly one concern: - **SOUL.md** — `SOUL.md` defines the agent's personality, values, tone, and behavioural boundaries. It's the first file OpenClaw injects into the agent's context at the start of every session. Think of it as the "character sheet." Without it, the agent is just a raw language model with no persistent identity. - **AGENTS.md** — `AGENTS.md` defines how the agent operates: memory management, safety rules, when to speak versus stay quiet. On session start, the agent reads today + yesterday + `MEMORY.md` when present. It captures decisions, preferences, constraints, and open loops. - **USER.md** — `USER.md` gives the agent context about the human it's working with. This is what makes an agent feel like it actually knows you, rather than starting cold every session. - **TOOLS.md** — TOOLS.md documents which tools the agent has access to and any usage notes specific to the setup. It's part documentation, part instruction set. Critically, this file doesn't grant or revoke permissions — OpenClaw handles that in config. ### Token Budget and File Size Limits Large bootstrap files are truncated when injected; operators can adjust limits with `agents.defaults.bootstrapMaxChars` (default: 20,000) and `agents.defaults.bootstrapTotalMaxChars` (default: 150,000). OpenClaw doesn't warn when a file is approaching the limit. It only warns after truncation has already happened, which means the agent was silently missing rules. Operators should audit file sizes regularly. Each bootstrap file owns one concern: `AGENTS.md` for rules, `SOUL.md` for personality, `USER.md` for user info, `IDENTITY.md` for agent identity, `TOOLS.md` for environment notes, `MEMORY.md` for learned patterns. Duplication across files wastes tokens on every single turn and creates conflicting instructions when one copy gets updated and the other doesn't. --- ## The Memory Architecture: JSONL Transcripts, MEMORY.md, and Hybrid Search OpenClaw's memory system is one of its most technically distinctive components. OpenClaw implements a radical departure from conventional AI memory systems: plain Markdown files as the source of truth, layered with hybrid semantic search. Unlike traditional RAG systems that hide data in vector databases, OpenClaw's approach prioritises transparency, human readability, and version controllability. ### The Three Memory Layers **Layer 1 — Daily JSONL/Markdown transcripts.** At the end of each session, the agent writes notes to `memory/YYYY-MM-DD.md`: what happened, what it learned, decisions that were made. Over time, it curates the important stuff into `MEMORY.md` — long-term memory that persists indefinitely. Things like preferences or known system quirks. Without this system, every conversation starts from zero. With it, the agent has months of context. **Layer 2 — MEMORY.md as durable long-term store.** `MEMORY.md` is for durable facts, preferences, and decisions. The system processes `memory/YYYY-MM-DD.md` daily logs into `MEMORY.md`, promotes recurring mistakes and hard-won rules to iron-law format, archives old logs, and checks for rules that have matured enough to move to a skill's `SKILL.md` instead. **Layer 3 — SQLite FTS5 + vector hybrid search.** With extensions like FTS5 (Full-Text Search) and `sqlite-vec` (Vector Search), OpenClaw provides a functional RAG stack in a single binary. ### How the SQLite Memory Index Works Memory indices live at `~/.openclaw/memory/{agentId}.sqlite` with core tables: `files` (tracks file paths, source type, content hash, and update timestamps for delta-based indexing), `chunks` (stores text segments with embeddings, line numbers, content hash, and model information), `embedding_cache` (cross-file deduplication using SHA-256 hashes prevents re-embedding identical content), `chunks_fts` (FTS5 virtual table enabling fast lexical search), and `vec_chunks` (vector acceleration via `sqlite-vec` extension, falling back to JS cosine similarity if unavailable). The chunking algorithm uses ~400 tokens per chunk with 80-token overlap, preserving context across chunk boundaries. ### Hybrid Search: Vector + BM25 BM25 keyword search (default 30% weight) uses SQLite's FTS5 full-text search for exact token matching. This excels at error codes, function names, and unique identifiers where semantic similarity would fail. The critical implementation detail: OpenClaw uses union, not intersection. Results from either search contribute to the final ranking. A chunk that scores high on vectors but zero on keywords is still included, ensuring comprehensive recall. OpenClaw's memory system is a lesson in right-sizing architecture. By choosing SQLite, the maintainers avoided the complexity of a distributed system for a single-user tool. They gained ACID compliance, portability, and a rich query language without the ops burden. SQLite is the right tool for the job because it offers total data privacy and instant startup for a single user. > **Known limitation:** OpenClaw's memory subsystem fails to enable FTS5 full-text search when running on Node.js 22+ because Node's built-in `node:sqlite` module is compiled without FTS5 support. Any code path that relies on `node:sqlite` for FTS5 virtual tables silently degrades to vector-only search. Memory search runs on vectors only — no BM25 hybrid re-ranking. The community-recommended fix is switching to `better-sqlite3`, which ships its own FTS5-enabled SQLite build. --- ## The Skills System: SKILL.md Directories and ClawHub Skills are the extensibility layer that transforms OpenClaw from a capable personal assistant into a platform. A skill is a versioned bundle of files — primarily a `SKILL.md` plus supporting resources — that teaches OpenClaw how to perform a specific task. Skills range from file storage and browser automation to database queries, email handling, and API integrations. ### How a SKILL.md Works Skills declare their runtime requirements — environment variables, binaries, install specifications — in the `SKILL.md` frontmatter. ClawHub's security analysis checks these declarations against actual skill behaviour. When the agent loop reaches the "load skills" stage, it reads the `SKILL.md` for each installed skill and injects the skill's instructions into the session context. Tools live in skills; the agent follows each skill's `SKILL.md` when it needs it. Environment-specific notes belong in `TOOLS.md`. ### Skill Scoping: Bundled, Global, and Workspace Skills can be scoped at three levels: - **Bundled** — Shipped with OpenClaw itself (browser control, file operations, Canvas) - **Global** — Installed via `clawhub install` to `~/.openclaw/skills/` and available to all agents - **Workspace** — Installed to the workspace `skills/` directory and available only to that agent ### ClawHub: The Skill Registry ClawHub is the public skill registry for OpenClaw: publish, version, and search text-based agent skills (a `SKILL.md` plus supporting files). It's designed for fast browsing and a CLI-friendly API, with moderation hooks and vector search. OpenClaw's public registry (ClawHub) hosts 13,729 community-built skills as of February 28, 2026. Think of ClawHub like npm for AI agents. Developers publish reusable skill packages, and anyone can search, install, and update them from the command line. The registry uses vector search, so you can find skills using natural language queries rather than exact keyword matches. Automatic skill discovery works through a conversational install flow: you can paste a skill's GitHub repository link directly into your assistant's chat and ask it to use it. The assistant will handle the setup automatically in the background. ### Notable Community Skills The ecosystem already covers a wide range of use cases. Highlights from the registry include: - `agent-memory-ultimate` — a production-ready memory system with daily logs, sleep consolidation, SQLite + FTS5, and WhatsApp/ChatGPT/VCF importers. - `better-notion` — full CRUD for Notion pages and databases - `apple-mail` — Apple Mail.app integration for macOS - `agent-team-orchestration` — orchestrates multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Security vetting is critical before installation. Agent skills can include prompt injections, tool poisoning, hidden malware payloads, or unsafe data handling patterns. OpenClaw has a VirusTotal partnership that provides security scanning for skills; each skill page on ClawHub includes the VirusTotal report. (The full threat landscape, including the documented ClawHavoc supply chain attack, is covered in our guide on *OpenClaw Security Risks*.) --- ## How the Three Layers Fit Together OpenClaw's three-layer architecture — channel, brain, body — separates concerns cleanly: messaging adapters handle protocol normalisation, the agent runtime handles reasoning, and tools handle real-world actions. The key insight is that OpenClaw separates the interface layer (where messages come from) from the assistant runtime (where intelligence and execution live). This means you get one persistent assistant accessible through any messaging app you already use, with conversation state and tool access managed centrally on your hardware. The practical implication: OpenClaw stores conversations, long-term memory, and skills as plain Markdown and YAML files under the workspace and `~/.openclaw`. You can inspect them in any text editor, back them up with Git, grep through them, or delete them. This transparency is not a design accident — it is the core data sovereignty guarantee that makes OpenClaw meaningful for privacy-conscious deployments, including Australian businesses subject to the Privacy Act 1988 (see our guide on *OpenClaw Managed Hosting in Australia*). --- ## Key Takeaways - **The Gateway is a WebSocket server, not a chatbot.** OpenClaw's architecture is surprisingly simple: a Gateway routes messages, an agent loop processes them with LLM and tools, memory is persisted as files, skills extend capabilities, and a heartbeat runs proactive checks. Understanding this separation is the foundation for everything else. - **The workspace file system is the agent.** Bootstrap files — `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `TOOLS.md`, `MEMORY.md`, `HEARTBEAT.md` — are injected into every session's system prompt, which is the full instruction set sent to the AI model at the start of each conversation. Editing these files is how you configure agent behaviour. - **Memory is a hybrid stack, not a black box.** The system combines human-readable Markdown daily logs, a durable `MEMORY.md` long-term store, and a SQLite-backed hybrid search index using FTS5 BM25 keyword ranking and vector similarity — all on local hardware, all inspectable. - **Skills are the extensibility primitive.** Skills extend OpenClaw's capabilities, allowing it to interact with external services, automate workflows, and perform specialised tasks. With over 13,000 community skills on ClawHub, the ecosystem covers most common automation needs out of the box. - **The heartbeat turns a reactive assistant into a proactive agent.** The cron-triggered loop — reading `HEARTBEAT.md`, deciding whether action is needed, acting or silently responding `HEARTBEAT_OK` — is the architectural feature that separates OpenClaw from every chat-based AI interface. --- ## Conclusion OpenClaw's architecture is elegant precisely because it is not novel. Its architecture is a clean, open-source implementation of the exact patterns that power every serious AI agent today: the agentic loop, tool use, context injection, and persistent memory. Once you understand how OpenClaw works, you understand how agents work in general. What makes it significant is that these patterns are implemented in a single inspectable Node.js process, with all state stored as plain text files you own and control. For readers building on this foundation, the natural next steps are exploring the full Skills ecosystem (see our guide on *OpenClaw Skills: How to Find, Install, and Build Custom Skills with ClawHub*), understanding the LLM backend options that power the inference step (see *OpenClaw LLM Compatibility: Choosing Between Claude, GPT-4, DeepSeek, and Local Models*), and hardening the deployment against the documented threat surface (see *OpenClaw Security Risks: Prompt Injection, Malicious Skills, and Safe Deployment Practices*). --- ## References - OpenClaw Documentation. "Agent Loop." *docs.openclaw.ai*, 2026. https://docs.openclaw.ai/concepts/agent-loop - OpenClaw Documentation. "Memory Overview." *docs.openclaw.ai*, 2026. https://docs.openclaw.ai/concepts/memory - OpenClaw Documentation. "Agent Workspace." *github.com/openclaw/openclaw*, 2026. https://github.com/openclaw/openclaw/blob/main/docs/concepts/agent-workspace.md - OpenClaw Documentation. "Default AGENTS.md." *docs.openclaw.ai*, 2026. https://docs.openclaw.ai/reference/AGENTS.default - Poudel, Bibek. "How OpenClaw Works: Understanding AI Agents Through a Real Architecture." *Medium*, February 2026. https://bibek-poudel.medium.com/how-openclaw-works-understanding-ai-agents-through-a-real-architecture-5d59cc7a4764 - Capodieci, Roberto. "AI Agents 003 — OpenClaw Workspace Files Explained." *Medium*, March 2026. https://capodieci.medium.com/ai-agents-003-openclaw-workspace-files-explained-soul-md-agents-md-heartbeat-md-and-more-5bdfbee4827a - Agarwal, Shivam. "How OpenClaw's Memory System Actually Works." *Medium*, February 2026. https://medium.com/@shivam.agarwal.in/agentic-ai-openclaw-moltbot-clawdbots-memory-architecture-explained-61c3b9697488 - PingCAP Engineering. "Local-First RAG: Using SQLite for AI Agent Memory with OpenClaw." *PingCAP Blog*, February 2026. https://www.pingcap.com/blog/local-first-rag-using-sqlite-ai-agent-memory-openclaw/ - Cen, Steven. "OpenClaw Explained: How the Hottest Agent Framework Works." *Medium*, March 2026. https://medium.com/@cenrunzhe/openclaw-explained-how-the-hottest-agent-framework-works-and-why-data-teams-should-pay-attention-69b41a033ca6 - Paolo, P. "OpenClaw Architecture, Explained: How It Works." *Substack*, February 2026. https://ppaolo.substack.com/p/openclaw-system-architecture-overview - Acronis Threat Research Unit. "OpenClaw: Agentic AI in the Wild — Architecture, Adoption and Emerging Security Risks." *Acronis Blog*, February 2026. https://www.acronis.com/en/tru/posts/openclaw-agentic-ai-in-the-wild-architecture-adoption-and-emerging-security-risks/ - Stack Junkie Editorial. "How to Write AGENTS.md, SOUL.md, and TOOLS.md for OpenClaw." *Stack Junkie*, March 2026. https://www.stack-junkie.com/blog/openclaw-system-prompt-design-guide - Milvus Blog. "What Is OpenClaw? Complete Guide to the Open-Source AI Agent." *Milvus Blog*, February 2026. https://milvus.io/blog/openclaw-formerly-clawdbot-moltbot-explained-a-complete-guide-to-the-autonomous-ai-agent.md - OpenClaw GitHub. "Memory FTS5 Unavailable on macOS/Node 23: node:sqlite Compiled Without FTS5 Support." *GitHub Issues*, February 2026. https://github.com/openclaw/openclaw/issues/20987 - VoltAgent. "Awesome OpenClaw Skills." *GitHub*, 2026. https://github.com/VoltAgent/awesome-openclaw-skills - OpenClaw GitHub. "ClawHub: Skill Directory for OpenClaw." *GitHub*, 2026. https://github.com/openclaw/clawhub - OWASP. "OWASP Top 10 for Large Language Model Applications." *OWASP Foundation*, 2025. https://owasp.org/www-project-top-10-for-large-language-model-applications/