Skip to content
/ explain-openclaw Public

Multi-AI documentation for OpenClaw: architecture, security audits, deployment guide

47 stars 7 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

centminmod/explain-openclaw

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

52 Commits
01-plain-english
01-plain-english
 
 
02-technical
02-technical
 
 
03-deploy
03-deploy
 
 
04-privacy-safety
04-privacy-safety
 
 
05-worst-case-security
05-worst-case-security
 
 
06-optimizations
06-optimizations
 
 
07-moltbook
07-moltbook
 
 
08-security-analysis
08-security-analysis
 
 
99-reference
99-reference
 
 
explain-clawdbot-copilot-gpt-5.2
explain-clawdbot-copilot-gpt-5.2
 
 
explain-clawdbot-gemini-3.0-pro
explain-clawdbot-gemini-3.0-pro
 
 
explain-clawdbot-glm-4.7
explain-clawdbot-glm-4.7
 
 
explain-clawdbot-kilocode-kimi-k2.5
explain-clawdbot-kilocode-kimi-k2.5
 
 
explain-clawdbot-opus-4.5
explain-clawdbot-opus-4.5
 
 
README.md
README.md
 
 
logo3.png
logo3.png
 
 
logo3a.png
logo3a.png
 
 

Repository files navigation

OpenClaw

Explain OpenClaw (formerly Moltbot/Clawdbot) - Integrated Beginner + Technical Guide

Table of contents

This folder is an ultra in-depth guide to the OpenClaw framework, written for someone who is new to agent frameworks and wants both:

  • Plain-English understanding (what it is, what it does, what can go wrong)
  • Technical understanding (how the Gateway, channels, agents, sessions, tools, nodes, and plugins fit together)

It synthesizes and reconciles the following AI-generated summaries:

…while verifying key claims against the repo’s canonical docs (../docs/**) and code (../src/**). When something conflicts, assume:

Repo docs + code win. Model summaries are supporting material.

What is OpenClaw? (30-second version)

OpenClaw is a self-hosted AI assistant platform. You run an always-on process called the Gateway on a machine you control (a Mac mini at home or an isolated VPS). The Gateway connects to messaging apps (WhatsApp/Telegram/Discord/iMessage/… via built-in channels + plugins), receives messages, runs an agent turn (the “brain”), optionally invokes tools/devices, and sends responses back.

Key idea: your Gateway host is the trust boundary. If it’s compromised (or configured too openly), your assistant can be turned into a data-exfil / automation engine.

Official docs starting point:

The four deployment scenarios this guide focuses on

  1. Standalone Mac mini (local-first, high privacy)
  • The Gateway runs on a Mac mini you own.
  • Default best practice: keep it loopback-only (gateway.bind: "loopback") and access it locally.
  • Optional remote access should be via SSH tunnels or Tailscale Serve, not public ports.
  1. Isolated VPS server (remote, locked down)
  • The Gateway runs on a small Linux VPS.
  • Fastest path: DigitalOcean 1-Click Deploy pre-configures security hardening automatically.
  • Default best practice: keep it loopback-only and access it via SSH tunnel or tailnet.
  • Harden the host like any admin system (dedicated user, firewall, patching, log hygiene).
  1. Cloudflare Moltworker (serverless, managed infrastructure)
  • The Gateway runs inside Cloudflare's Sandbox SDK container on their global edge network.
  • No hardware to manage; automatic scaling and isolation.
  • Uses R2 for persistence, AI Gateway for model routing, Browser Rendering for web automation.
  • Proof-of-concept; requires Cloudflare Workers paid plan ($5/month minimum).
  1. Docker Model Runner (local AI, zero API cost)
  • Run LLMs locally via Docker Desktop's Model Runner.
  • Zero API costs after initial model download.
  • Complete privacy — no data leaves your machine.
  • Requires Docker Desktop 4.40+ and compatible hardware (Apple Silicon, NVIDIA GPU, or AMD GPU).

Start here (recommended reading order)

1) Plain English

2) Privacy + safety first (highly recommended)

3) Technical overview (how it works)

4) Deployment runbooks

5) Reference

Quick start (safe-ish defaults)

The repo strongly recommends using the onboarding wizard; it sets up:

  • a working Gateway service (launchd/systemd)
  • auth/provider credentials
  • safe access defaults (pairing, token)

Install

Recommended installer:

curl -fsSL https://openclaw.ai/install.sh | bash

Alternative:

npm install -g openclaw@latest

Onboard + install background service

openclaw onboard --install-daemon

Verify

openclaw gateway status
openclaw status
openclaw health

Security audit

Three levels of security auditing:

# Read-only scan of config + filesystem permissions (no network calls)
openclaw security audit

# Everything above + live WebSocket probe of the running gateway
openclaw security audit --deep

# Apply safe auto-fixes first, then run full audit to show remaining issues
openclaw security audit --fix
Flag What it adds Modifies system?
(none) Scans config, filesystem permissions, channel policies, model hygiene, plugin trust, attack surface summary (50+ check IDs across 12 categories) No — read-only
--deep All base checks + live WebSocket probe of running gateway (5 s timeout), verifies auth handshake No — read-only probe
--fix Applies safe fixes before running the full audit: chmod 600/700 on state/config/credentials, flips groupPolicy open→allowlist, sets logging.redactSensitive off→"tools". Report shows remaining issues post-fix Yes — safe defaults only; no destructive changes

Note: --fix runs the fix pass before the audit (src/cli/security-cli.ts:46), so the report you see reflects the hardened state. Any findings that remain are issues --fix cannot auto-resolve.

If you only do one security thing, do this:

openclaw security audit --fix

See the full command reference for what each check covers, what --fix changes, and which documented issues the audit can and cannot detect.

(Security audit docs: https://docs.openclaw.ai/gateway/security)

How to think about OpenClaw (beginner mental model)

OpenClaw is easiest to understand as 6 layers:

  1. Gateway (control plane) — one long-running process that owns:

    • message ingress/egress
    • sessions + transcripts
    • routing rules
    • plugin loading
    • tool execution policy + sandboxing
    • node/device pairing and invocations

  2. Channels — adapters from Telegram/WhatsApp/etc. into a normalized message/event shape.

  3. Routing + sessions — decides which “agent/session” handles which chat.

  4. Agent runtime — takes context (system prompt + history + attachments), calls your chosen model provider, streams responses, and can request tools.

  5. Tools — optional capabilities beyond text (web fetch/search, browser control, exec, cron, nodes/devices).

  6. Surfaces — where you interact:

    • chat apps (WhatsApp/Telegram/…)
    • Control UI dashboard (web)
    • macOS menu bar app

This matters because your security choices mostly reduce to:

  • Who can trigger the agent? (pairing + allowlists + group policies)
  • What can the agent do once triggered? (tools/sandboxing/nodes)
  • What can the agent reach? (network exposure, filesystem access, accounts)

FAQ (Beginner → Intermediate → Advanced)

This FAQ is intentionally long and practical; it’s the “things you’ll actually Google at 2am.”

Beginner FAQ

Q: What should I install this on: my laptop, a Mac mini, a VPS, or Cloudflare?

  • Mac mini (recommended for most privacy-first users): always-on, easy local access, no cloud exposure by default.
  • VPS (recommended for always-on + remote access): great uptime, but higher security responsibility. DigitalOcean 1-Click handles hardening automatically.
  • Cloudflare Moltworker (low-maintenance serverless): no hardware to manage, pay-as-you-go, but proof-of-concept status.
  • Docker Model Runner (maximum privacy + zero cost): run local LLMs via Docker Desktop for complete privacy and no API fees. Requires Apple Silicon, NVIDIA, or AMD GPU.
  • Laptop (okay for learning/dev): simplest to start, but sleeps often and you may be tempted to expose it.

See runbooks:

Q: Is OpenClaw "an AI model" like ChatGPT?

No. OpenClaw is a self-hosted assistant platform that talks to models (Anthropic/OpenAI/etc.) and wraps them with routing, sessions, tools, and chat integrations.

Q: What runs on my machine?

The main always-on process is the Gateway (default port 18789) which multiplexes:

  • a WebSocket control plane
  • the dashboard/control UI (HTTP)
  • optional HTTP endpoints (OpenAI-compatible APIs)

See: https://docs.openclaw.ai/gateway

Q: Where is my data stored?

By default, OpenClaw stores state under ~/.openclaw/ (or ~/.openclaw-<profile>/ for profiles). This includes config, credentials, and session transcripts.

See: https://docs.openclaw.ai/gateway/security ("Credential storage map")

Q: Does OpenClaw have telemetry?

This repo's positioning is local-first control. Still, your chosen model provider will receive whatever text/media is sent to it for inference, unless you run a local model.

Q: What’s the safest first setup?

  • Run on a single-user machine you control (Mac mini).
  • Keep the Gateway loopback-only.
  • Use pairing/allowlists so only you can talk to it.
  • Don’t enable powerful tools until you understand the blast radius.

Use the wizard:

openclaw onboard --install-daemon

Q: I opened the dashboard and it says “unauthorized” or keeps reconnecting.

The Gateway likely has auth enabled and the UI is missing the token/password.

Fast fixes:

  • Run openclaw dashboard (it prints a tokenized URL).
  • If remote: bring up an SSH tunnel first: 
    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
    then open http://127.0.0.1:18789/?token=....

See: https://docs.openclaw.ai/help/faq (Control UI unauthorized)

Q: What does “pairing” mean?

Pairing is owner approval for:

  • DM pairing (who can message the bot)
  • device/node pairing (which devices can connect)

See: https://docs.openclaw.ai/start/pairing

Intermediate FAQ

Q: What's the difference between openclaw gateway and openclaw gateway restart?

  • openclaw gateway runs the Gateway in the foreground in your terminal.
  • openclaw gateway restart restarts the background service (launchd/systemd).

See: https://docs.openclaw.ai/help/faq

Q: What port does OpenClaw use?

gateway.port controls the single multiplexed port for WebSocket + HTTP. Precedence is:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

See: https://docs.openclaw.ai/help/faq

Q: I want remote access. Should I set gateway.bind: "lan"?

Usually no.

Preferred patterns:

  • Loopback + SSH tunnel (universal)
  • Loopback + Tailscale Serve (best UX)

Only bind to LAN/tailnet when you understand the auth requirements.

See: https://docs.openclaw.ai/gateway/remote and https://docs.openclaw.ai/gateway/tailscale

Q: Can I run multiple Gateways on one host?

Yes, but it’s usually unnecessary; one Gateway can run multiple channels and agents.

If you do, you must isolate:

  • config path (OPENCLAW_CONFIG_PATH)
  • state dir (OPENCLAW_STATE_DIR)
  • workspace (agents.defaults.workspace)
  • port (gateway.port)

See: https://docs.openclaw.ai/gateway/multiple-gateways

Q: How do I see what OpenClaw is doing?

Use:

openclaw status --all
openclaw logs --follow

See: https://docs.openclaw.ai/help/faq (log locations)

Advanced FAQ

Q: What’s the real security risk: “public bot”, prompt injection, or host compromise?

All three matter, but the practical order is:

  1. Inbound access (DM/group policies)
  2. Tool blast radius (exec/browser/web)
  3. Network exposure (bind modes, proxies, auth)
  4. Host compromise (OS hardening, keys, patching)

See: https://docs.openclaw.ai/gateway/security

Q: How do plugins/extensions affect my threat model?

Plugins run in-process with the Gateway. Treat them like installing arbitrary code.

Recommendation:

  • only install plugins you trust
  • prefer pinned versions
  • keep an explicit allowlist if supported

See: https://docs.openclaw.ai/gateway/security ("Plugins/extensions")

Q: If I want “maximum privacy”, do I need a local model?

A local model is the strongest privacy posture because it avoids sending content to a third-party provider. However, it changes the safety profile: smaller/weak local models can be easier to prompt-inject and may handle tool policies worse.

See: https://docs.openclaw.ai/gateway/local-models

Q: How do I make sure different people’s DMs don’t leak context to each other?

Consider DM session isolation (multi-user mode) so each peer gets an isolated DM session, and use identity linking only where appropriate.

For multi-agent setups, each agent can also be scoped independently: per-agent sandbox isolation, tool allow/deny policies, and workspace access controls prevent one agent's context from leaking into another. See per-agent access scoping for details.

See: https://docs.openclaw.ai/gateway/security ("DM session isolation") and https://docs.openclaw.ai/concepts/session

See: openclaw security audit command reference

See: Official Security Advisories (CVEs/GHSAs)

See: Security audit analysis (Issue #1796)

See: Second security audit (Medium article)

See: Post-Merge Security Hardening

See: Open Upstream Security Issues

See: Ecosystem Security Threats

Worst-Case Security Scenarios

Purpose: This section documents what can go wrong in the worst possible misconfiguration or compromise scenarios for each deployment type.

Read this if: You're evaluating OpenClaw for sensitive use cases, want to understand the blast radius of potential failures, or need to build a threat model for your organization.

See the detailed breakdown in 05-worst-case-security/.

Quick Reference: Deployment Risk Profiles

Deployment Trust Boundary Biggest Risk Recovery Complexity
Mac Mini Your hardware Physical access, cloud sync Medium (rotate keys)
VPS/1-Click Shared infra Internet exposure, root compromise High (rebuild VPS)
Moltworker Cloudflare No egress filtering, R2 breach Very High (no local control)

Key Findings from Code Analysis

Based on source code review of:

  • src/gateway/net.ts - Network binding with fallback chains
  • src/gateway/auth.ts - Authentication mechanisms
  • src/agents/bash-tools.exec.ts - Shell execution
  • src/pairing/pairing-store.ts - Credential storage
  • src/security/audit.ts - Security audit checks

Critical vulnerabilities if misconfigured:

  1. Silent binding fallback - Loopback failure → 0.0.0.0 exposure (src/gateway/net.ts:159-164)
  2. Dangerous auth flags - dangerouslyDisableDeviceAuth bypasses device verification (src/config/types.gateway.ts:69-72)
  3. No encryption at rest - Credentials protected only by file permissions (0o600/0o700)
  4. Egress-free Moltworker - Sandbox can exfiltrate to any server

Scenario Documentation

Document Coverage
Overview Attack surface comparison, decision guide, severity levels
Mac Mini Risks Physical access, cloud sync trap, silent network exposure
VPS Risks Internet exposure, multi-tenant risks, credential storage
Moltworker Risks Trust boundaries, egress filtering, R2 single point of failure
Cross-Cutting Prompt injection, tool execution, channel tokens, supply chain
ClawHub Marketplace Risks Skills marketplace supply chain, ClawHavoc campaign, social engineering
Prompt Injection Attacks 20 attack examples with data exfiltration scenarios
Misconfiguration Examples 10 real mistakes with step-by-step fixes
Incident Response Containment, credential rotation, recovery procedures

See: AI Model Analysis Comparison

Official docs (high-signal links)

About

Multi-AI documentation for OpenClaw: architecture, security audits, deployment guide

Topics

clawdbot moltbot openclaw openclaw-security clawdbot-security moltbolt-security

Resources

Readme
Activity

Stars

47 stars

Watchers

0 watching

Forks

7 forks
Report repository