SearchBook a call

RESEARCH / PAPERS

published

OpenClaw: a self-hosted agent gateway for your chat apps

How OpenClaw works: a local Gateway that routes chat apps to an agent loop, with tools, sandboxes, plugins and SQLite state. Product, infra and code.

OpenClaw is a free, open-source personal AI assistant that you run on your own machine and talk to through the chat apps you already use, such as WhatsApp, Telegram, Slack and iMessage. It matters because it is the most widely adopted self-hosted agent of 2026, and because its design puts one long-running local process, the Gateway, between untrusted chat input and real tools that can run shell commands, read mail and drive a browser.

Facts at a glance

  • Maker: created by Peter Steinberger; stewarded since July 2026 by the OpenClaw Foundation, a United States 501(c)(3) non-profit.
  • First release: repository created 24 November 2025, under the earlier names Warelay and then Clawdbot. Renamed Moltbot on 27 January 2026 and OpenClaw on 30 January 2026.
  • Current version: 2026.9.7, published on GitHub on 30 September 2026. Versions are date-based.
  • Licence: MIT.
  • Pricing: free. No hosted tier and no enterprise edition. You pay your model provider directly.
  • Platforms: Gateway on macOS, Linux and Windows (Node.js 24.16 or later). Companion apps for macOS, iOS, Android, Windows and Linux.
  • Models: bring your own. Built-in transports for Anthropic, OpenAI (several application programming interface (API) styles), Azure OpenAI, Google Gemini and Vertex, and Mistral, plus provider plugins for dozens more, including local Ollama, vLLM and LM Studio.
  • Where it runs: on the user’s own hardware or server. Optional tool sandboxes in Docker, Podman, over Secure Shell (SSH), or on throwaway cloud machines.

First principles

Strip OpenClaw down and it is made of four things: inbound chat channels, a model, tools with real effects, and state on disk. Most of its design follows from the constraint each one brings.

  • Anyone who can message the assistant can write into its prompt. A chat channel delivers text from other people, and a model cannot reliably tell an instruction from data. The project’s own rule follows: “Treat inbound messages as untrusted input.” Control therefore has to sit outside the model. Pairing decides who may talk to it, tool policy decides what may run, the sandbox decides where it runs, and exec approvals pin the exact command.
  • The process next to every credential is the trust boundary. One Gateway owns every channel connection and runs beside the databases, workspace and credentials under ~/.openclaw. Whoever can drive it can reach all of them. That is why the docs say one Gateway is one trust boundary, and why mutually untrusted users need separate instances.
  • The default decides where tools run. Sandboxing is off by default. Unless the owner turns it on, tool execution happens on the host, and the host’s own permissions are the last line of defence.
  • A conversation is an ordered log. Two runs writing to one transcript at once would corrupt it. Per-session lanes serialize turns and a writer claim stops a superseded run from committing stale data, while separate conversations still run in parallel.
  • Context is finite. A long-running assistant eventually outgrows the model’s context window, so old turns must be summarized and durable facts moved into files. Compaction and the memory tiers exist for that.
  • Local-first moves the work as well as the data. Keeping state on the user’s machine keeps it out of a vendor’s cloud. It also makes the user the operator, responsible for updates, network exposure and backups.

Product

OpenClaw is an always-on assistant rather than a chat window. You install it, run an onboarding wizard that checks model access and creates a workspace, then connect one or more messaging channels. After that you message it like a contact. The project’s own description lists inbox triage, sending email, calendar work, form filling and web browsing as typical jobs. Commenters in a September 2026 Hacker News thread describe using it for email automation, job applications and home-lab management.

The docs folder has pages for around 30 messaging services, in line with the product site’s claim of 29 chat interfaces. Core ones are WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Google Chat and Matrix, with many regional services such as WeChat, LINE, Zalo and Feishu. A browser-based Control UI (user interface), a terminal UI (TUI) and a command-line interface (CLI) sit alongside the chat channels.

The assistant’s behaviour is shaped by plain Markdown files in its workspace: AGENTS.md for operating rules, SOUL.md for persona and tone, USER.md for user preferences, and MEMORY.md plus dated daily notes for memory. Skills, which are SKILL.md instruction files following the AgentSkills format, teach it how to use tools. Skills and plugins are shared through ClawHub, the project’s registry.

There are two deployment shapes. The default is one person on one laptop. The second is a shared team Gateway, fronted by Tailscale or Cloudflare Access, with roles, shared sessions and GitHub identity. The docs are explicit that one Gateway is one trust boundary, and that mutually untrusted tenants need separate instances. An experimental openclaw fleet command runs one hardened container per tenant for that case.

How it is sold. It is not sold. The product site states there is no subscription, hosted tier or paid version. The Foundation is funded by donors; the README names Amazon, OpenAI, Red Hat and the University of Michigan among them, and the Foundation’s launch post names OpenAI as an inference sponsor and Michigan as the largest donor. Costs fall on the user as model API bills or existing subscriptions. OpenClaw can reuse a Claude Code login or a ChatGPT sign-in through its harness plugins, and the docs warn that those routes draw on the signed-in subscription’s limits.

What it is compared with. OpenClaw’s own “Why OpenClaw” page compares itself with Nous Research’s Hermes Agent. Hacker News commenters name Hermes, the Pi agent and Claude Code as places users moved to after early 2026. The Foundation’s launch post names NVIDIA’s NemoClaw and Microsoft Scout as partner products built on it.

Infrastructure

Where OpenClaw runs: one Gateway on the user's machine as the trust boundary, chat networks and a signed-in Mac for iMessage on the way in, paired devices, optional tool sandboxes, bring-your-own model providers, and a single daily telemetry check.Where OpenClaw runs: one Gateway on the user's machine as the trust boundary, chat networks and a signed-in Mac for iMessage on the way in, paired devices, optional tool sandboxes, bring-your-own model providers, and a single daily telemetry check.
Where OpenClaw runs: one Gateway on the user's machine as the trust boundary, chat networks and a signed-in Mac for iMessage on the way in, paired devices, optional tool sandboxes, bring-your-own model providers, and a single daily telemetry check.

Where it runs. Everything that holds state runs on the user’s machine: the Gateway process, its SQLite databases, the workspace and credentials. Only model inference and channel traffic leave the host by default. The Gateway binds to 127.0.0.1:18789 by default. Remote access is meant to go through Tailscale, a virtual private network (VPN), an SSH tunnel or an identity-aware proxy, not a public bind.

Model providers. A shared library, @openclaw/ai, implements eight API families: Anthropic Messages, OpenAI Completions, OpenAI Responses, Azure OpenAI Responses, ChatGPT/Codex Responses, Google Generative AI, Google Vertex and Mistral Conversations. Provider plugins add many more, from Bedrock and OpenRouter to local servers. Model failover, retries and credentials are handled by the application layer around that library.

Agent runtimes. A model can execute through OpenClaw’s own built-in loop, through an embedded plugin harness (the Codex app-server, GitHub Copilot), or through a CLI backend such as Claude Code. The runtime is chosen per model or provider with agentRuntime.id. An official OpenAI Responses route can switch to the Codex harness automatically.

Distribution and updates. A shell or PowerShell installer that provisions Node.js, the openclaw npm package, desktop installers, Docker (ghcr.io/openclaw/openclaw), Nix and guides for most cloud hosts. Release notes for 2026.9.7 credit 344 contributors and 2,818 pull requests in that release alone. Releases are signed by the Foundation.

What it needs. Node.js 24.16+ or 26.1+, a model credential, and accounts for any channels. Docker or Podman only if you enable sandboxing. Optional cloud workers use the Crabbox tool to lease machines on providers such as Amazon Web Services (AWS).

Telemetry and data. By default the only call home is a daily GET to telemetry.openclaw.ai carrying version, operating system, Node.js version and central processing unit (CPU) architecture in the User-Agent. There is no install or machine identifier. Cloudflare derives an approximate location from that request, and records are kept for three months. Anonymous feature statistics (configured channels, provider families, plugin list, sessions created in the last 24 hours) are opt-in. update.checkOnStart: false turns off both. Prompts go to whichever model providers and channels you configure.

Engineering

Components. The codebase is a TypeScript pnpm monorepo with Swift apps for Apple platforms, Android and Linux apps, and two Rust crates (a Gateway client and a node host). The Gateway is the single long-lived daemon. It owns every channel connection, exposes a typed WebSocket API, runs a scheduler for cron and maintenance, and serves the Control UI and widget assets over Hypertext Transfer Protocol (HTTP) on the same port. Clients (Control UI, CLI, macOS app) and nodes (phones, other computers, headless hosts) connect to the same WebSocket server and declare a role.

Protocol. Frames are JavaScript Object Notation (JSON) text over WebSocket. The first frame must be connect; anything else closes the socket. Requests use {type:"req", id, method, params} and get {type:"res", id, ok, payload|error}. The server also pushes event frames for agent, chat, presence, health, heartbeat and cron. Side-effecting methods such as send and agent require idempotency keys. Every client signs a challenge nonce with a device identity, and new devices need pairing approval, except local loopback which can be auto-approved. Schemas are written in TypeBox, compiled to JSON Schema, and used to generate Swift models. Events are not replayed; clients refresh on gaps.

The agent loop. An agent request resolves the session, persists metadata, and returns a runId at once. The run then waits in a lane-aware queue: one lane per session key, then a global lane capped by agents.defaults.maxConcurrent. This serializes turns within a conversation while letting conversations run in parallel. Before streaming, the run records a writer claim in SQLite, and every transcript write must match it, so a superseded run cannot commit stale data. The runtime builds a system prompt from fixed sections (tooling, execution bias, messaging, workspace, sandbox, runtime facts), injects workspace files and a skills snapshot, then streams model output. Tool calls emit tool events, text emits assistant events, and phases emit lifecycle events. The default run budget is 48 hours. The model idle watchdog is 120 seconds for cloud providers and 300 seconds for self-hosted ones.

Context management. When a session nears the model’s context limit, or a provider returns an overflow error, OpenClaw compacts older turns into a summary stored in the transcript, keeping tool calls paired with their results. New configs default to a “safeguard” mode that validates summaries before writing them. Before compacting, the agent is prompted to save notes to memory.

Memory. Memory is plain files plus one SQLite index. The docs define tiers: human-written instructions, a small curated core (MEMORY.md, USER.md) loaded at session start, episodic daily notes and transcripts reached through memory_search and memory_get, and standing intents stored in SQLite that fire on triggers. A background “dreaming” pass promotes material from daily notes into the curated core through deterministic gates. The docs treat the write path as the security boundary against memory poisoning.

Tools and permissions. Built-in tools are grouped: runtime (exec, process, code_execution), filesystem (read, write, edit, apply_patch), sessions and sub-agents, memory, web search and fetch, UI (browser, screen, canvas), automation (cron), messaging, nodes, and media generation. OpenClaw is both a Model Context Protocol (MCP) client, over standard input and output (stdio), Server-Sent Events (SSE) and Streamable HTTP, and an MCP server. Tool availability passes through five policy layers: profile, provider profile, global and per-agent allow/deny, provider allow/deny, and a sandbox-only policy. Deny always wins. Host shell commands also pass exec approvals, which bind the exact argument list (argv), working directory and resolved executable, and refuse to run if a script file changed after approval. Plugins can intercept calls with before_tool_call.

Sandboxing. Sandboxing is off by default. When enabled, only tool execution moves; the Gateway stays on the host. Modes are off, non-main (sandbox everything except the owner’s main session) and all. Backends are Docker, Podman, SSH, OpenShell and Crabbox cloud boxes, and workspace access can be none, read-only or read-write. An “elevated” escape hatch lets authorised senders run exec on the host. The README is blunt about inbound content: “Treat inbound messages as untrusted input.”

State and storage. Everything lives under ~/.openclaw: openclaw.json for config, state/openclaw.sqlite for the shared control plane (registries, approvals, plugin state), and one openclaw-agent.sqlite per agent holding sessions, transcript events (JSON or Zstandard-compressed), memory indexes and model auth profiles. Schemas are versioned; older builds refuse newer databases, and openclaw doctor --fix owns migrations. The multi-tenant docs note that OAuth tokens sit in plaintext in SQLite.

Extensibility. Plugins register capabilities through a typed software development kit (SDK) of about 150 entrypoints: text inference providers, CLI backends, embeddings, speech, image, music and video generation, web search and fetch, channels, discovery and migration. The repository ships 173 extension packages. Plugin hooks cover the loop from before_model_resolve and before_prompt_build to agent_end, plus message and Gateway lifecycle events. Skills load from seven precedence levels, workspace first. Sub-agents can be spawned singly or fanned out with Swarm from Code Mode scripts.

Observed limits. One Gateway per host, and one WhatsApp session per Gateway. A Gateway is not a tenant isolation boundary. Tool policy filters by tool name, so allowing exec makes the filesystem writable even when write is denied. Sandbox bind mounts default to read-write.

Entity relationships

Entity diagram of OpenClaw's Gateway, agents, sessions, runs, tools, plugins and their relationships.Entity diagram of OpenClaw's Gateway, agents, sessions, runs, tools, plugins and their relationships.
Entity diagram of OpenClaw's Gateway, agents, sessions, runs, tools, plugins and their relationships.

The Gateway is the root. It hosts one or more agents, owns every channel connection, pairs with nodes and loads plugins. Each agent has exactly one workspace, the folder of Markdown files that shapes its persona and memory, and loads a snapshot of skills from that workspace and from shared locations.

Channels route inbound messages to sessions, keyed by agent and conversation. A session serializes runs, one at a time, and records transcript events in the per-agent SQLite database. Each run calls one resolved model provider and may invoke many tools.

Plugins are the extension seam: they register tools, model providers and channels. Nodes are paired devices that execute device-local commands, such as camera or screen capture, on behalf of tools.

Architecture

Flowchart of OpenClaw components from chat apps through the Gateway, queue, runtime, policy, sandbox and model APIs.Flowchart of OpenClaw components from chat apps through the Gateway, queue, runtime, policy, sandbox and model APIs.
Flowchart of OpenClaw components from chat apps through the Gateway, queue, runtime, policy, sandbox and model APIs.

Take one WhatsApp message. The WhatsApp channel plugin, built on the Baileys library, receives it inside the Gateway and hands a normalized event to the routing layer. If the sender is unknown, pairing blocks it until the owner approves a code. Otherwise the Gateway maps it to a session key and enqueues a run on that session’s lane.

When the lane frees, the run is admitted to the global lane and to an agent runtime, usually the built-in openclaw loop. The prompt builder reads AGENTS.md, SOUL.md, the curated memory files and the skills snapshot. The runtime streams a request to the configured model provider.

If the model asks for a tool, the call passes tool policy first. Shell and file tools then run on the host or in the configured sandbox; device commands go to a paired node; MCP tools go to their server. Results return to the model until it produces a final answer. Transcript events are committed to SQLite under the run’s writer claim, and the Gateway sends the reply back through the WhatsApp plugin, filtering a silent NO_REPLY token if the model chose not to answer an optional message.

Sequence of one agent request from a Control UI client through the Gateway, queue, runtime, model and tools.Sequence of one agent request from a Control UI client through the Gateway, queue, runtime, model and tools.
Sequence of one agent request from a Control UI client through the Gateway, queue, runtime, model and tools.

The sequence above shows the same path from a Control UI client, where the wire protocol is visible: connect, an immediate acknowledgement with a runId, streamed agent events, and a final response with status.

How it compares

Product Shape Where it runs Trust model
OpenClaw Chat-first assistant Gateway User’s machine or server Gateway trusted, execution optionally sandboxed
Hermes Agent Self-hosted agent harness User’s machine Its policy names the OS as the boundary
Claude Code, Codex Coding agent harnesses Developer machine Not reviewed here
Velofy Dexter Terminal coding agent that fans work out to parallel subagents Developer machine or remote box Hooks, optional seatbelt or bubblewrap sandbox, MCP tool approval

Hermes Agent is the peer OpenClaw’s docs compare against. The docs quote its security policy as treating the operating system as the only boundary against an adversarial model, and position OpenClaw’s separable Gateway and sandboxes as the difference. OpenClaw’s docs also concede that sandboxing is off by default.

Claude Code and Codex are both rivals and components: OpenClaw can run them as agent runtimes, so a model turn executes inside the vendor’s own harness while OpenClaw supplies channels, memory and scheduling.

Against Dexter, OpenClaw’s Swarm tool does a similar fan-out to OpenClaw sub-agents from a script. Dexter’s model fans out on its own, up to 8 subagents at once, each in a live tmux pane, and dexter fanout covers the scripted case. Against Troy, OpenClaw’s browser tool runs its own isolated Chromium profile and can also attach to a user’s signed-in Chrome through Chrome DevTools MCP; it is a browser client, not a browser that other agents attach to.

Our reading: OpenClaw is far broader than a coding agent and deeper on operations than most personal assistants. That breadth is also its cost. Hacker News commenters cite frequent breaking updates and complexity, and its defaults put tool execution on the host.

What we could not verify

  • The original name. The project’s lore page says Warelay came first; most press says Clawdbot or Clawd.
  • User numbers. The Foundation’s figure of 4.5 million new agents a week has no published method, and press figures for weekly users vary.
  • The exact date Steinberger’s move to OpenAI was announced: TechCrunch says 15 February 2026, Wikipedia says 14 February.
  • The size of the ClawHub malware campaign. Koi Security reported 341 malicious skills on 2 February 2026; other reports say 386, and later scans say over 800. We did not check what ClawHub moderation looks like today beyond the docs.
  • Whether “OpenClaw 2.0” is an official label. Wikipedia ties it to 2026.8.1; we found no such label in the changelog.
  • Which donors fund the Foundation. The README, the launch post and press each list a different set.
  • How well the sandbox and exec-approval controls hold up. We read the docs and code layout but did not run or test them.

Sources

All read on 2026-10-01. Repository files were read from openclaw/openclaw at commit 7208cd5.

← All papers