Inside OpenClaw: Architecture, Core Technologies, and Security Risks

Project Background and History

OpenClaw (formerly Clawdbot and Moltbot) is a free MIT‑licensed AI‑agent framework created by Austrian developer Peter Steinberger, the founder of PSPDFKit. Launched in November 2025, it was renamed twice in January 2026 due to a trademark dispute with Anthropic. Within three months it amassed over 196 000 GitHub stars, more than 600 contributors, and over 10 000 commits, making it one of the fastest‑growing open‑source projects on GitHub.

Core Architecture: Three‑Layer Design

Processing a single message goes through seven stages and is organized into three layers:

First Layer – Message Entry & Channel Adapter

Different platforms (e.g., WhatsApp voice, Slack text) use distinct protocols. The Channel Adapter normalizes each platform (WhatsApp via Baileys, Telegram via grammY, etc.) into a unified message object containing sender, body, attachments, and channel metadata. Voice messages are transcribed before reaching the model.

Second Layer – Gateway Control Plane

The always‑running Gateway coordinates sessions, channel routing, tool distribution, and events. It binds to port 18789 and offers a control UI and WebChat interface. A typed WebSocket API validates inbound frames against JSON Schema and emits events such as agent, chat, presence, health, heartbeat, and cron. Idempotency keys are required for all side‑effect methods, and a short‑term deduplication cache is maintained. The Gateway routes messages to the appropriate agent and session, using a command queue to serialize messages per session and avoid state conflicts.

Third Layer – Agent Runtime (pi‑mono)

The runtime executes the end‑to‑end AI loop: it assembles context from session history and memory, calls the LLM, performs tool calls (browser automation, file ops, Canvas, cron, etc.), and persists the updated state.

Deep Dive into Core Technical Modules

1. Prompt Compiler

OpenClaw treats the system prompt as compiled output rather than static configuration. The prompt is generated from the runtime context—available tools, channel capabilities, identity files, and skills. Changing any input automatically changes the prompt. The full prompt structure includes tool list & description, safety guardrails, skill metadata, workspace info, current date‑time, heartbeat agreement, runtime metadata (host/OS/model/thinking level), and the contents of AGENTS.md, SOUL.md, USER.md, and HEARTBEAT.md.

2. Heartbeat Mechanism

A default timer triggers every 30 minutes. On each heartbeat the agent reads HEARTBEAT.md, decides whether any task requires attention, and either acts (potentially sending a message) or replies with HEARTBEAT_OK, which the Gateway hides from the user. This makes the agent appear proactive.

3. File‑Based Memory System

All memory is stored as Markdown files, avoiding external databases. Files are chunked into ~400‑token blocks with an 80‑token overlap, embedded via OpenAI, Gemini, or local GGUF models, and indexed in SQLite using sqlite‑vec. Retrieval mixes vector similarity and BM25 scoring:

finalScore = vectorWeight × vectorScore + textWeight × textScore

The workspace contains standard files such as AGENTS.md, SOUL.md, USER.md, MEMORY.md, SESSION‑STATE.md, HEARTBEAT.md, TOOLS.md, and a memory/ directory with daily raw logs. When the context window nears its limit, a silent agent round writes essential content to disk; the model replies NO_REPLY, which is never shown to the user, preventing “context compression forgetting”.

4. Skill System (SKILL.md)

A skill is a folder containing a SKILL.md file with natural‑language instructions, examples, and optional tool configuration. Skills are classified as bundled (built‑in), managed (from the ClawHub marketplace), or workspace‑level (local). Unlike static plugins, OpenClaw lets the LLM generate integration code for each skill automatically.

5. ReAct Reasoning Loop & Tool Layer

The loop follows input → context → model → tool → repeat → reply, the same pattern used by Claude Code. The difference lies in deployment: Claude Code runs as a CLI that exits after execution, whereas OpenClaw runs as a persistent daemon across more than twelve messaging platforms, equipped with a heartbeat scheduler, cross‑channel session management, and persistent memory. The tool layer provides browser control (CDP‑driven Chrome/Chromium), file system operations, shell execution, Canvas visual workspaces, camera/screen capture, MCP protocol extensions, cron jobs, and webhooks. Docker containers sandbox each tool execution.

6. Model‑Agnostic Design & Multi‑Model Routing

Providers are configured in openclaw.json. The Gateway routes requests based on this configuration, supporting auth‑profile rotation and exponential‑backoff failover. Most deployments use a cutting‑edge model for orchestration and a cheaper model for heartbeat and sub‑agent tasks.

7. OpenClaw‑RL: Reinforcement‑Learning Extension

OpenClaw‑RL is a standalone framework that enables RL training of agents in terminals, GUIs, software‑engineering environments, and tool‑calling scenarios. Its architecture decouples four asynchronous components: policy service, trajectory collector, PRM judge, and strategy trainer, allowing them to run without blocking each other.

Security Architecture and Risks

Security researchers discovered hundreds of malicious skills in the public ClawHub registry; Cisco’s analysis found that roughly 26 % of community‑submitted skills contain at least one vulnerability. The primary concern for adopters is how to deploy OpenClaw without exposing a supply‑chain attack surface.

A study from Northeastern University showed that even agents trained for “good behavior” can be coaxed into self‑destructive actions or secret leakage through human guilt manipulation or gaslighting.

OpenClaw vs. Hermes Agent: Comparative Summary

Architecture Core : OpenClaw uses a central Gateway; Hermes Agent centers on the agent’s own execution loop.

Tech Stack : OpenClaw – Node.js/TypeScript; Hermes – Python.

Memory Storage : OpenClaw – Markdown files + SQLite vector index; Hermes – SQLite FTS5 + LLM summarization.

Skill Learning : OpenClaw – static SKILL.md without auto‑creation; Hermes – autonomous skill creation and iterative improvement.

Proactivity : OpenClaw – Heartbeat every 30 min; Hermes – Cron + Heartbeat.

Ecosystem Maturity : OpenClaw – ClawHub marketplace, >230 k stars; Hermes – agentskills.io, still growing.

Onboarding Barrier : OpenClaw – lower, plug‑and‑play; Hermes – higher, complex configuration.

RL Support : OpenClaw – dedicated OpenClaw‑RL framework; Hermes – integrates Atropos environment.

Conclusion

The core contribution of OpenClaw is the integration of a persistent daemon, message gateway, file‑based memory, and proactive heartbeat into a single out‑of‑the‑box agent runtime, democratizing system‑level AI agents that were previously only feasible for large companies. The agent is no longer a static configuration but self‑configures from its environment, marking a deeper architectural shift.