Skip to content

OpenClaw Explanation

OpenClaw follows a hub-and-spoke architecture centered on a long-lived Gateway control plane that mediates between user-facing messaging channels, operator clients, device nodes, and pluggable agent runtimes. This page explains how the pieces fit, why the project made its design choices, and how its security model and threat landscape work. Look-up facts (versions, ports, config keys, CVE table, hardening checklist) are in Reference; tasks are in How-to Guides.

High-Level Architecture

The diagram shows the current (2026.9.x) component layout: every surface connects to one Gateway per host, which owns channels, sessions, policy, and plugin loading, and hands prepared turns to an agent runtime.

graph TB
    subgraph Channels["Channel plugins"]
        WA["WhatsApp (Baileys)"]
        TG["Telegram (grammY)"]
        SL[Slack]
        DC[Discord]
        IM["iMessage (imsg)"]
        SIG["Signal (signal-cli)"]
        MORE["~26 more incl. Teams, Matrix, A2A"]
    end

    subgraph Clients["Operator clients"]
        CUI["Control UI + WebChat"]
        CLI["openclaw CLI / TUI"]
        APPS["macOS, iOS, Android, Windows Hub apps"]
    end

    subgraph Core["Gateway daemon (ws://127.0.0.1:18789)"]
        GW["Typed WS API + HTTP<br/>auth, pairing, presence"]
        SESS["Session store<br/>(per-agent SQLite)"]
        POL["Tool policy, approvals,<br/>exec-policy"]
        AUTO["Cron automations, hooks,<br/>webhooks, heartbeat"]
        PLUG["Plugin loader<br/>(channels, providers, memory, tools)"]
    end

    subgraph Runtimes["Agent runtimes"]
        OCR["openclaw embedded runtime"]
        CDX["codex app-server harness"]
        CLIB["claude-cli backend"]
        ACP["ACP harnesses<br/>(Claude Code, Gemini CLI, OpenCode)"]
    end

    subgraph Exec["Tool execution"]
        HOST["Gateway host (default)"]
        SBX["Sandbox backends<br/>Docker, Podman, SSH, OpenShell, Crabbox"]
        NODES["Nodes (role: node)<br/>camera, screen, system.run"]
    end

    LLM["Model providers<br/>(Anthropic, OpenAI, local, ...)"]
    HUB["ClawHub registry<br/>(skills, plugins)"]

    Channels --> GW
    Clients --> GW
    GW --> SESS
    GW --> POL
    GW --> AUTO
    PLUG --> GW
    HUB -.->|install| PLUG
    POL --> Runtimes
    Runtimes <--> LLM
    Runtimes --> Exec
    NODES <-->|WS| GW

Gateway — The Control Plane

The Gateway is a single daemon per host. It:

  • Owns all messaging surfaces - it is the only process that opens the WhatsApp (Baileys) session on a host; channel integrations load as plugins.
  • Exposes a typed WebSocket API - requests (health, status, send, agent), responses, and server-push events (agent, chat, presence, health, heartbeat, cron). TypeBox schemas define the protocol; JSON Schema and Swift models are generated from them.
  • Manages sessions and presence - session rows and transcripts live in per-agent SQLite databases.
  • Runs automations - cron-style automations, hooks, Gmail webhooks, and heartbeat check-ins.
  • Serves HTTP on the same port - the Control UI, hosted widgets (/__openclaw__/canvas/, /__openclaw__/a2ui/), optional OpenAI-compatible endpoints, and health probes.
  • Validates configuration strictly - openclaw.json must match the schema or the Gateway refuses to boot; openclaw doctor --fix owns migrations.

The Gateway binds to loopback (127.0.0.1:18789) by default. Clients and nodes all speak the same WS protocol; nodes declare role: node with explicit capabilities.

One Agent, Many Channels

The key architectural insight is that OpenClaw separates the interface layer (where messages arrive) from the assistant runtime (where intelligence lives). One persistent assistant is reachable through every messaging app, with state managed centrally on your hardware. The same Gateway can serve one person or a team whose members trust each other; configuration is the only difference.

Connection Lifecycle

Every WS client must send connect as its first frame, sign a challenge nonce with its device identity, and pass Gateway auth. Side-effecting methods need idempotency keys; events are not replayed, so clients refresh on gaps.

sequenceDiagram
    participant C as Client (Control UI / CLI / node)
    participant G as Gateway
    C->>G: req connect (device identity, auth token, signed challenge)
    G-->>C: res hello-ok (presence + health snapshot)
    G-->>C: event presence
    G-->>C: event tick
    C->>G: req agent (idempotency key)
    G-->>C: res agent ack (runId, status accepted)
    G-->>C: event agent (streaming output)
    G-->>C: res agent final (runId, status, summary)

New device IDs require pairing approval; direct loopback connects can be auto-approved, while LAN and tailnet connects need explicit approval. Pairing is device-based and pinned to platform metadata.

Pi Runtime — The Agent Core

OpenClaw's original agent loop was built on pi, Mario Zechner's minimal coding-agent toolkit (earendil-works/pi; the README still credits it). Early-2026 architecture write-ups described the Gateway dispatching turns over RPC to a pi-based runtime.

As of 2026.9, the docs describe this layer as agent runtimes:

Runtime family Examples Who owns the model loop
Embedded (built-in) openclaw runtime OpenClaw's embedded runner: native tool loop, context assembly
Embedded (plugin harness) codex (Codex app-server), copilot (external plugin) The vendor harness, with OpenClaw tools bridged in
CLI backend claude-cli (drives the installed Claude Code executable) The local CLI process; model ref stays canonical
ACP-hosted Claude Code, Gemini CLI, OpenCode, Cursor via ACP/acpx External harness through the Agent Client Protocol

Providers (anthropic, openai, ...) authenticate and name models; runtimes execute the prepared turn; channels carry messages. Keeping those layers separate is how OpenClaw treats vendor harnesses as swappable plugins rather than privileging any one lab.

Design Philosophy

The pi-era design was deliberately minimal: a short system prompt and a small core tool set (read, write, edit, bash), with the idea that the agent extends itself by writing code rather than downloading plugins. The current project keeps the "small core" principle but formalizes it differently (VISION.md):

  • Core carries a per-call tax. Every core tool, prompt line, and config key reaches every model request, so core additions face the strictest review.
  • Plugins, skills, channels, and apps carry no such tax. New capabilities should usually ship as plugins; new skills go to ClawHub first.
  • Recurring demand defines interfaces. When several PRs wire in the same kind of capability, the answer is a contract in core/SDK, with implementations as plugins.
  • Terminal-first setup. Onboarding shows auth, permissions, and security posture up front instead of hiding them behind convenience wrappers.
  • TypeScript for hackability. OpenClaw is mostly orchestration (prompts, tools, protocols), so a widely known language keeps it easy to modify.

Built-in tool categories now include runtime (exec, process, terminal), files (read, write, edit, apply_patch), web (web_search, web_fetch), browser control, messaging, memory, human input (ask_user, secrets), and Code Mode.

Execution Model

A message from a channel becomes a session turn: the Gateway authorizes the sender, resolves the agent and session, assembles context, and lets the runtime drive the model and tools under policy.

sequenceDiagram
    participant U as Sender (WhatsApp, Telegram, ...)
    participant GW as Gateway
    participant RT as Agent runtime
    participant LLM as Model provider
    participant T as Tools (host, sandbox, or node)
    U->>GW: Inbound message
    GW->>GW: DM policy, pairing, allowlist, mention gate
    GW->>RT: Prepared turn (session, bootstrap files, memory)
    RT->>LLM: Inference request with visible tools
    LLM-->>RT: Response + tool calls
    RT->>GW: Tool call for policy and approval check
    GW->>T: Execute allowed tool
    T-->>RT: Tool results
    RT->>LLM: Continue with results
    LLM-->>RT: Final response
    RT-->>GW: Transcript + state update
    GW-->>U: Reply via channel

Session Architecture — Trees, Not Logs

Early-2026 architecture articles highlighted a pi-derived session model in which sessions are trees, not flat logs: the agent could branch off to diagnose a broken tool, then rewind to the main branch and summarize, keeping the main context clean and recovering in-band.

In current releases, sessions are stored as rows and transcripts in per-agent SQLite (~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite), and the Control UI supports forking, pinning, grouping, and archiving sessions (2026.7.1). Sub-agents run in their own child sessions (agent:<agentId>:subagent:<uuid>) and announce results back. In-session branching survives in a new form: the Control UI's Rewind to here and Fork from here actions (sessions.rewind, sessions.fork) repoint or copy a session at a user message, and the append-only store keeps each earlier transcript as a branch you can switch back to (sessions.branches.list / sessions.branches.switch). Rewind moves chat context only; files and other tool side effects are not reverted (Control UI chat docs, checked 2026-09-27).

Lobster — The Workflow Engine

Lobster is a typed, local-first workflow runtime that turns skills and tools into composable pipelines with approval gates.

Why Lobster Exists

Complex workflows need many back-and-forth tool calls, each costing tokens and each giving the model a chance to drift. Lobster moves orchestration into a typed runtime: one call instead of many.

LLMs do what LLMs are good at: writing code, analyzing code, running tests. Lobster does what code is good at: sequencing, counting, routing, retrying.

Key Properties

Property Detail
Determinism Pipelines are data - easy to log, diff, replay, review
Resumable state Halted workflows return needs_approval with a resumeToken (or short approval ID); approve and continue without re-running earlier steps
Safety Timeouts, output caps (maxStdoutBytes), sandbox checks, and allowlists enforced by the runtime
Execution The official @openclaw/lobster plugin runs the embedded runtime in-process in the Gateway; no external subprocess
Grammar Intentionally tiny DSL; workflow files end in .lobster, .yaml, .yml, or .json
Distribution Optional plugin, not installed by default; enabled with tools.alsoAllow: ["lobster"]

For orchestration across many detached tasks, OpenClaw also has Task Flow (openclaw tasks flow), which gives Lobster runs a durable flow record.

Multi-Agent Pipeline Example

A community-built dev pipeline (DEV Community, 2026) chains programmer, reviewer, and tester agents with bounded retries:

graph LR
    subgraph Lobster["Lobster Pipeline"]
        CODE[Programmer Agent] --> REVIEW[Reviewer Agent]
        REVIEW -->|Pass| TEST[Tester Agent]
        REVIEW -->|"Fail (max 3 iterations)"| CODE
        TEST -->|Pass| DONE[Done]
        TEST -->|Fail| CODE
    end

Code, review (max 3 iterations), test, done - with no human in the loop unless something breaks or a side effect needs approval.

Resilience & State

Early articles described a write-ahead queue so interrupted tasks resume from a checkpoint instead of restarting. The current mechanisms are documented differently:

  • Background tasks and Task Flow - sub-agent runs and detached work are tracked as tasks with a durable ledger.
  • Recovery after restarts - 2026.9.6 added recovery for unfinished work after Gateway restarts.
  • Guarded state migrations - state is schema-versioned; startup migrations write verified SQLite backups first and refuse (exit code 78) rather than risk corrupting state.
  • Last-known-good config - the Gateway keeps a trusted copy after each successful start; openclaw doctor --fix restores it.

Multi-Agent Patterns

OpenClaw supports three distinct multi-agent patterns:

1. Sub-Agents

Background runs spawned from the main agent (sessions_spawn). They run in parallel in isolated sessions, optionally sandboxed, do not get session or message tools by default, and announce results back. Nesting depth is configurable for orchestrator patterns.

Best for: long-running research, batch processing, code review.

2. Multi-Agent Routing

Separate agents on one Gateway (agents.entries), each with its own workspace, session store, sandbox, and tool policy, bound to different channels or accounts (openclaw agents bind).

Best for: home/work separation, different personas, restricted channel-facing agents. Not a security boundary between mutually untrusted people - see Security Model.

3. Agent Teams

Community-built orchestration systems (SWAT, OpenMOSS, Mission Control, ClawTeam) add structured coordination on top of OpenClaw; the core also ships a Swarm tool and Code Mode for orchestrating concurrent agents from code.

Best for: complex pipelines with review loops, 24/7 operations.

NemoClaw Integration (NVIDIA)

NemoClaw (Apache 2.0, alpha) is NVIDIA's reference stack for running agents inside NVIDIA OpenShell sandboxes, with guided onboarding, managed inference, network policy, snapshots, and lifecycle commands. OpenClaw is the default agent; Hermes and LangChain Deep Agents Code are also supported. Separately, OpenClaw itself can use OpenShell as a sandbox backend.

The diagram shows the NemoClaw layering: the agent runs inside an OpenShell sandbox, and every outbound call passes the OpenShell policy engine, which binds provider credentials only to authorized endpoints.

graph TB
    subgraph Host["Host (nemoclaw CLI)"]
        NC["nemoclaw onboard / status / policy"]
        OSG["OpenShell gateway<br/>(sandbox lifecycle, auth boundary)"]
    end

    subgraph Sandbox["OpenShell sandbox"]
        OC["OpenClaw Gateway + agent"]
    end

    PE["Policy engine<br/>(filesystem, network, process, providers)"]
    PROV["Provider profiles<br/>(endpoint-bound credentials)"]

    subgraph Inference["Inference routes"]
        LOCAL["Local model<br/>(e.g. Nemotron, vLLM)"]
        CLOUD["Cloud provider<br/>(Claude, GPT)"]
    end

    NC --> OSG
    OSG -->|creates| Sandbox
    OC -->|every egress| PE
    PE --> PROV
    PROV --> LOCAL
    PROV --> CLOUD

NemoClaw/OpenShell adds:

  • Out-of-process policy enforcement - policies are enforced outside the agent, so a compromised agent cannot rewrite them (similar in spirit to browser tab isolation)
  • Four policy domains - filesystem and process rules locked at sandbox creation; network and provider rules hot-reloadable
  • Credential injection - provider credentials are injected at runtime and bound to authorized endpoints; they never land in the sandbox filesystem
  • Routed inference - local or cloud inference per provider configuration (NVIDIA's March 2026 launch material called this a "privacy router")
  • Compute drivers - OpenShell now supports Docker, Podman, MicroVM, and (experimental) Kubernetes; the launch-era description of "K3s inside a single Docker container" is historical

When to Use NemoClaw

  • Personal, non-confidential - plain OpenClaw with its own sandbox mode is usually sufficient
  • Confidential data or business use - NemoClaw or the OpenClaw openshell sandbox backend is recommended
  • Corporate adoption - a separated trust boundary (NemoClaw/OpenShell, cloud workers, or per-tenant gateways) is effectively required
  • Pattern - two instances: one everyday, one confidential behind OpenShell

History & Naming

OpenClaw went through several names between late 2025 and January 2026 (Lore, VISION.md):

  1. Warelay - the original WhatsApp relay/gateway.
  2. Clawd / Clawdbot - the assistant "Clawd" living in "Clawdbot" (Nov 25, 2025 - Jan 27, 2026).
  3. Moltbot - renamed January 27, 2026 after Anthropic asked for a name change over trademark concerns.
  4. OpenClaw - final rename on January 30, 2026 because "Moltbot never quite rolled off the tongue"; the repo moved to github.com/openclaw/openclaw.

In February 2026 Peter Steinberger announced he was joining OpenAI and that a non-profit foundation would steward the project (TechCrunch). The OpenClaw Foundation, an independent US 501(c)(3) chaired by Dave Morin, formally launched in July 2026 (press coverage dates the announcement to 2026-07-08) with a full-time team. Per the README, the Foundation employs the core team and signs releases; donors include Amazon, Lobster Computer Company, Offline Holdings, OpenAI, Red Hat, and the University of Michigan, with infrastructure support from Blacksmith, Convex, GitHub, NVIDIA, and Vercel. "OpenAI is a donor, not an owner."

Security Model

OpenClaw's security posture is the single most important consideration for anyone evaluating the platform. The project is explicit about what it does and does not defend (SECURITY.md):

  • Personal-assistant trust model. One trusted operator (or a team that trusts each other) per Gateway, potentially many agents. It is not a multi-tenant boundary between adversarial users.
  • Authenticated callers are operators. Shared-secret auth (token/password) grants full operator scopes, including on the OpenAI-compatible HTTP endpoints and POST /tools/invoke.
  • Session IDs are routing, not authorization. Session ownership and presence are usability features; one operator can see another's data on the same Gateway.
  • Host-first execution. agents.defaults.sandbox.mode defaults to off; tools run on the Gateway host for the main session unless sandboxing is configured.
  • Plugins are trusted code. Installing a plugin grants it Gateway-host trust; it is not sandboxed.
  • The model is untrusted. Prompt injection is assumed; boundaries come from auth, tool policy, approvals, and sandboxing, not from the model obeying instructions. Prompt injection alone is out of scope for vulnerability reports.
  • Public exposure is out of scope. Running the Gateway on the public internet contrary to the docs is not treated as a vulnerability.

Summary Verdict

OpenClaw's early months combined viral adoption, exposed-by-default deployments, and a fast-moving codebase, producing high-profile RCE CVEs (CVE-2026-25253, CVSS 8.8; CVE-2026-32922, CVSS 9.9), six-figure counts of internet-exposed instances, and a poisoned skill registry. Defaults have since tightened (loopback bind, mandatory auth, pairing, VirusTotal scanning), but sandboxing and exec approvals remain opt-in. Treat an OpenClaw Gateway as high-privilege infrastructure that needs deliberate hardening.

CVE Timeline

The verified CVE table (IDs, dates, CVSS, fixed versions) is in Reference. The pattern behind it:

  • January-February 2026 (Clawdbot/Moltbot era) - CVE-2026-25253: the Control UI accepted a gatewayUrl query parameter and auto-connected, leaking the Gateway token to an attacker-chosen host (one-click token theft leading to RCE). CVE-2026-24763 and CVE-2026-25157 were command-injection bugs in sandbox and SSH node paths. All three were fixed in 2026.1.29.
  • March 2026 - a burst of disclosures (reported as nine CVEs in four days, March 18-21). The most severe, CVE-2026-32922 (CVSS 9.9), let a caller with operator.pairing scope mint operator.admin tokens via device.token.rotate, reaching RCE on connected nodes through system.run. Fixed in 2026.3.11.
  • Ongoing - the project publishes GitHub Security Advisories continuously (647 repository advisories by 2026-08-27, per the project). The volume reflects a large attack surface, heavy researcher attention, and AI-generated scanner reports; the project warns that advisory counts are not a comparative safety score.

Correction

Earlier versions of this page listed placeholder IDs ("CVE-2026-3xxxx batch 1-9") with invented categories and March 4-7 dates, and described CVE-2026-25253 as an unauthenticated crafted-WebSocket-message RCE. Those rows were not verifiable and have been replaced with CVE records.

Threat Model

OpenClaw's attack surface is unusually broad for a self-hosted tool because it combines a network-reachable control plane, host code execution, a third-party skill/plugin registry, and LLM-mediated input from many channels. The project maps adversarial threats to MITRE ATLAS in its own threat model.

graph TB
    subgraph External["External attack surface"]
        INET["Public internet<br/>(misconfigured non-loopback bind)"]
        CHAN["Channel senders<br/>(WhatsApp, Telegram, groups)"]
        HUB["ClawHub skills and plugins<br/>(supply chain)"]
        WEB["Web pages, email, webhooks<br/>(indirect prompt injection)"]
    end

    subgraph Gateway["Gateway (127.0.0.1:18789)"]
        AUTH["Auth + device pairing"]
        DMP["DM policy, allowlists"]
        SESS["Sessions"]
        POL["Tool policy + approvals"]
        AUTO["Cron, hooks, webhooks"]
    end

    subgraph Exec["Execution"]
        EXEC["exec / process<br/>(host by default)"]
        FS["read / write / edit"]
        BROWSER["Browser control"]
        NODE["Nodes: system.run"]
        PLUGIN["In-process plugins"]
    end

    subgraph Data["Sensitive data"]
        MEM["MEMORY.md, USER.md,<br/>memory/*.md"]
        KEYS["Provider keys, channel tokens"]
        FILES["Host files, browser profiles"]
    end

    INET -->|token theft, auth bugs| AUTH
    CHAN --> DMP
    WEB -->|tool output| SESS
    HUB -->|install| PLUGIN
    AUTH --> SESS
    DMP --> SESS
    SESS --> POL
    AUTO --> POL
    POL --> EXEC
    POL --> FS
    POL --> BROWSER
    POL --> NODE
    EXEC --> Data
    FS --> Data
    PLUGIN --> Data
    BROWSER -->|SSRF| INET

    style INET fill:#d32f2f,color:#fff
    style HUB fill:#d32f2f,color:#fff
    style WEB fill:#e65100,color:#fff
    style EXEC fill:#d32f2f,color:#fff

Threat 1 — Gateway Exposure (135,000+ Instances)

In February 2026, SecurityScorecard's STRIKE team counted more than 135,000 OpenClaw instances reachable from the public internet across 82 countries, of which roughly 50,000 were reported exploitable via known RCE CVEs. At the time, reporting described deployments that bound to all interfaces with weak or missing auth and no WebSocket origin checks. Common causes:

  • Changing the bind to LAN/0.0.0.0 for remote access without a reverse proxy or firewall
  • Publishing Docker ports with -p 18789:18789 (all interfaces) instead of -p 127.0.0.1:18789:18789
  • Cloud VMs with no firewall rule on the Gateway port

Current releases bind to loopback by default, generate a token at onboarding, refuse WS connections when no auth path is configured, require pairing for non-loopback devices, and rate-limit failed auth. Container images still default to an exposed bind, and the project's docs treat public exposure as unsupported.

Threat 2 — Host Code Execution

With sandboxing off (the default), exec and the file tools act with the Gateway user's privileges on the host (or container). Code Mode's default node:vm executor is explicitly not a security boundary.

Attack chains:

  • A malicious skill instructs the agent to run a download-and-execute command
  • Prompt injection via a channel message, web page, or email causes attacker-chosen commands
  • A stolen Gateway token or scope-escalation bug grants full operator control
  • Node execution (system.run) extends reach to paired devices

Threat 3 — ClawHub Supply Chain

In February 2026 Koi Security audited 2,857 ClawHub skills and found 341 malicious (335 from one campaign, "ClawHavoc"), later updated to 824. The skills posed as crypto tools, Polymarket bots, YouTube utilities, and ClawHub typosquats, and used their instructions to get users or agents to install Atomic Stealer (macOS) or keyloggers (Windows). Earlier versions of this page gave a "341-900" range; the verified figures are 341, then 824.

Known malicious skill behaviors:

Category Behavior
Malware delivery Setup instructions that fetch and run a second-stage script or password-protected executable
Credential theft Harvest API keys, wallet keys, and browser data
Data exfiltration Read MEMORY.md or workspace files and send them out
Persistence Install cron jobs or modify workspace instructions
Prompt injection relay Inject instructions into the agent's context to override user intent

Scanning is not a guarantee

Since February 2026, ClawHub scans every skill with VirusTotal (including Code Insight) and rescans daily; skill pages also show ClawScan and static-analysis results, and openclaw skills verify checks a trust envelope. The maintainers call scanning "not a silver bullet": instruction-level prompt injection can slip through, pending or stale scans can still allow installation with a warning, and verification does not hash local files.

Threat 4 — Prompt Injection

The agent processes channel messages, tool output, web pages, and emails as model input. An attacker who can put text in front of the model can try to:

  • Override instructions to change agent behavior
  • Exfiltrate memory contents by asking the agent to read and relay them
  • Trigger commands disguised as legitimate requests
  • Push the agent to request approvals for harmful side effects

OpenClaw's position is that the model is not a trusted principal: mitigations are strict tool profiles for channel-facing agents, sandboxing, exec approvals, untrusted-content wrapping, turn taint for network-sourced tool output, and strong model tiers. Prompt injection that does not bypass one of those boundaries is not treated as a vulnerability.

Threat 5 — Channel Authentication Weaknesses

Each channel has its own identity model, so the boundary is uneven:

  • WhatsApp/Telegram/Signal - rely on platform sender identity; unknown DM senders get a pairing code by default
  • Group chats - allowlisted and usually mention-gated, but everyone in an allowed group can steer the agent within its tool grants
  • IRC - nicknames are spoofable; restrict with allowlists
  • Supplemental context - quoted, replied, or forwarded text from non-allowlisted senders may still reach the model on some channels
  • Webhooks and hooks - payloads are untrusted content; keep allowUnsafeExternalContent bypass flags off

There is no unified identity layer across channels; isolation comes from per-agent bindings, DM policy, and allowlists.

Threat 6 — Memory and Session Data Exposure

Memory is plain Markdown in the agent workspace (MEMORY.md, USER.md, memory/YYYY-MM-DD.md, DREAMS.md) and session transcripts live in SQLite under ~/.openclaw. Anyone who can write to ~/.openclaw is effectively an operator, and a compromised host exposes all memory. Protected secrets can be kept out of model context with SecretRefs and masked credential requests, but memory files themselves are not encrypted at rest: the docs describe no at-rest encryption option for them, and even the built-in Secret Store keeps values unencrypted in SQLite behind 0600/0700 permissions (docs checked 2026-09-27; use an external secret provider such as Vault or 1Password for stronger isolation).

Access Control Model

Gateway Authentication

Gateway auth applies to every connection, local or remote. Modes are shared secret (token or password), trusted-proxy (identity from a reverse proxy), Tailscale Serve identity headers, and none for private ingress only. Every client also carries a device identity that must be paired. The mechanism table is in Reference.

Roles are guardrails, not tenancy

Earlier versions of this page said OpenClaw has "no RBAC". Current releases have operator scopes (operator.admin, .read, .write, .approvals, .pairing) and, in the August 2026 source, gateway.roles with a deny-all default option. The project still states that roles and session ownership are collaboration guardrails inside one trust domain, not a boundary between adversarial users, and shared-secret HTTP callers always get full operator scopes.

Channel Bindings

Channel bindings associate a messaging identity (phone number, bot token, account) with an agent. They are the primary routing mechanism for multi-agent deployments:

  • One agent can be bound to multiple channels
  • Multiple agents on one Gateway can be bound to different channels or accounts
  • Sub-agents and Lobster pipelines can pass work between agents under tool policy

User Isolation

  • Single-user (recommended) - one user per host/VPS, one Gateway, one or more agents
  • Team - a shared Gateway is valid when members trust each other and the agent is business-only, on a dedicated machine and accounts
  • Mixed trust - separate Gateways and credentials per trust boundary, ideally separate OS users or hosts; the docs describe one Gateway "cell" per tenant for hosting

Network Security

Port 18789 Binding

The Gateway defaults to gateway.bind: "loopback", which is safe for single-machine use. lan, tailnet, and custom binds widen the attack surface and require auth plus a firewall. The project's preferred remote-access path is Tailscale Serve (the Gateway stays on loopback) or an SSH tunnel.

The diagram shows the recommended layout when a reverse proxy is used: only 443 is reachable, and the proxy forwards to the loopback-bound Gateway.

graph LR
    CLIENT["Remote client"] -->|"HTTPS / WSS"| RP["Reverse proxy<br/>(Caddy, nginx, Traefik)"]
    RP -->|"ws://127.0.0.1:18789"| GW["Gateway<br/>(gateway.trustedProxies set)"]
    TS["Tailscale Serve"] -->|"identity headers"| GW

    subgraph Firewall["Host firewall"]
        ALLOW["Allow 443/tcp inbound"]
        DENY["Deny 18789/tcp inbound"]
    end

    RP -.->|protected by| Firewall
    GW -.->|protected by| Firewall

    style DENY fill:#d32f2f,color:#fff
    style ALLOW fill:#2e7d32,color:#fff

TLS Requirements

The Gateway is loopback-first. For remote wss://, pin the certificate with gateway.remote.tlsFingerprint; plaintext ws:// is accepted only for loopback, private IP literals, .local, and Tailnet *.ts.net names. When a reverse proxy terminates TLS, it should also set HSTS, handle the WebSocket upgrade, and be listed in gateway.trustedProxies. The firewall recipe is in How-to Guides.

Sandboxing Approaches

OpenClaw Sandbox Backends

OpenClaw can move tool execution into a sandbox backend: docker (default backend), podman, ssh (remote machine), openshell, or crabbox (leased cloud box). Modes are off (default), non-main, and all; scope and workspace access (none, ro, rw) are configurable per agent. Tool allow/deny policy applies before sandbox rules, and tools.elevated is an explicit escape hatch that runs exec outside the sandbox. The docs call sandboxing "not a perfect security boundary" that nonetheless materially limits filesystem and process access.

NemoClaw is the most complete out-of-process option: the whole OpenClaw Gateway runs inside an OpenShell sandbox. See NemoClaw Integration (NVIDIA) for the architecture.

Security features:

Feature How It Works
Out-of-process policy enforcement OpenShell enforces policy outside the agent process; a compromised agent cannot modify or disable it
Endpoint-bound credentials Provider credentials are injected only after policy admits a request to an authorized endpoint; they are not written to the sandbox filesystem
Declarative YAML policies Filesystem, network, process, and provider rules; network policy can be enforced at HTTP method and path level
Routed inference Local or cloud inference per provider configuration
Isolated sandboxes One container (or MicroVM) per sandbox, created by the OpenShell gateway through a compute driver

Policy schema

An earlier version of this page showed a "conceptual" NemoClaw YAML policy (sandbox.filesystem, inference.sensitive_keywords, ...). That schema was invented and has been removed. For the real format, see OpenShell's sandbox policy quickstart and NemoClaw's network policies.

Docker Isolation

Running the Gateway itself in Docker isolates it from the host but, as the project notes, does not separate the agent loop, channel credentials, and shell from each other inside that container. Useful container hardening: minimal mounts, read-only root filesystem where possible, dropped capabilities, no-new-privileges, seccomp/AppArmor profiles, and loopback-only port publishing. A recipe is in How-to Guides.

Lobster Pipeline Safety Controls

Lobster enforces runtime safety constraints on workflow execution:

Control Purpose
Execution timeouts timeoutMs stops runaway pipelines
Output caps maxStdoutBytes limits captured output and result size
Tool allowlists Restrict which tools and commands a pipeline can invoke
Approval gates Side effects (send, post, delete) halt the workflow until explicitly approved
Sandbox checks Validate environment constraints before executing steps

These controls limit a compromised skill's use of Lobster as an escalation path but do not replace host-level sandboxing.

Secrets Management

Default (Insecure)

A basic install keeps secrets in environment variables and ~/.openclaw files. With host execution, any successful prompt injection or malicious skill that reaches exec or the file tools can read them.

Protected Secrets

Current releases provide several layers:

  • SecretRefs (env, file, exec, store sources) keep values out of openclaw.json; openclaw secrets audit flags plaintext
  • Masked credential requests (2026.8.1) let the agent ask for a credential without the value entering chat or model context
  • Secret egress proxy substitutes protected values only on the way out, with an opt-in destination allowlist for Gateway-hosted exec (August 2026)
  • NemoClaw/OpenShell bind credentials to authorized endpoints outside the sandbox

The project is explicit that egress allowlisting covers cooperating traffic only; raw sockets from unsandboxed host exec answer to an operator proxy or host policy.

Best Practices

  • Never store API keys in MEMORY.md, USER.md, or daily notes
  • Use SecretRefs and run openclaw secrets audit --check in CI
  • Use separate provider keys for OpenClaw to limit blast radius, and rotate after any suspected compromise
  • Monitor provider dashboards and openclaw gateway usage-cost for anomalous spend

ClawHub Skill Vetting

ClawHub is OpenClaw's registry for skills and plugins, with publishing, moderation, security audits, and per-release trust verdicts consumed at install time. Since the ClawHavoc incident it scans every skill with VirusTotal and shows ClawScan and static-analysis state. The current status table is in Reference.

What Auditing Exists

  • Automated scanning - VirusTotal (with Code Insight LLM analysis), ClawScan, static analysis; daily rescans
  • Trust envelopes - openclaw skills verify @owner/<slug> checks ClawHub's verdict for the installed version
  • Source inspection - skills are human-readable Markdown and scripts, so manual review is possible
  • Third-party scanners - for example Koi Security's Clawdex skill, which checks skills against a database of known-malicious entries

What Does Not Exist

  • A guarantee that a scanned skill is safe (instruction-level injection can evade scanners)
  • Blocking of installs while scans are pending or stale (installs proceed with a warning)
  • Hashing of local files by skills verify
  • Sandboxing of installed native plugins (they run in-process with Gateway trust)

Recommendation

Never install ClawHub skills or plugins without reading the source. Prefer bundled skills and verified org publishers, pin versions, restrict with plugins.allow and per-agent skill allowlists, and watch agent behavior after enabling anything new.

Audit Logging

Built-in Capabilities

  • Session transcripts - conversation history including tool calls and outputs (per-agent SQLite)
  • Message auditing - an audit surface for message activity (openclaw audit, Audit)
  • Task ledger - background tasks and flows with status history (openclaw tasks audit)
  • Structured export - OpenTelemetry and Prometheus export from the Gateway
  • Security audit - openclaw security audit findings with stable check IDs

Limitations

  • Logs and transcripts live on the same host the agent can act on; with unsandboxed exec the agent could alter them
  • Retention and tamper-resistance depend on exporting to an external collector
  • Promoted memories have no time-based retention bound (project statement)
  • Export OpenTelemetry to your SIEM with operator-owned retention and dropped-data monitoring
  • Host-level auditd or osquery for process and file monitoring
  • Container logging driver to an external collector (Loki, Elasticsearch)
  • Provider usage monitoring for anomalous token consumption

Comparison Note — Hermes Agent

Hermes Agent (Nous Research) is the comparison OpenClaw's own docs draw most often. Earlier versions of this page stated that Hermes had "zero CVEs"; that is not accurate as a blanket claim. OpenClaw's docs (2026-08-27 snapshot) note that Hermes had no advisories in its GitHub repository but does have CVEs published through third-party CNAs, and that advisory counts are not comparative safety scores. The architectural difference is where the trust boundary sits: Hermes' security policy says "the only security boundary against an adversarial LLM is the operating system," while OpenClaw can separate a trusted Gateway from untrusted, movable execution (sandboxes, nodes, cloud workers) with policy enforced in code. OpenClaw's broader surface - multi-channel gateway, host execution, third-party registry - still carries proportionally more risk when left at defaults. See OpenClaw vs Hermes Agent vs Claude Code.

Sources