OpenClaw Complete Guide¶

Open-source, self-hosted, multi-channel AI personal assistant. ~191K GitHub stars. MIT license.

GitHub: https://github.com/openclaw/openclaw Install: npm install -g openclaw@latest Created by: Peter Steinberger (founder of PSPDFKit)

Table of Contents¶

What Is OpenClaw
The Viral Story
Architecture
Complete Feature List
Supported LLMs
Claude Code & Codex Integration
Multi-Agent / Swarms
Skills Ecosystem
Security History & Hardening
Real Monthly Costs
Moltbook: The AI Social Network
Media Coverage

What Is OpenClaw¶

OpenClaw is an open-source, self-hosted AI personal assistant that:

Runs on your own hardware (Mac, Linux, Windows via WSL2)
Connects to 13+ messaging platforms as its UI (WhatsApp, Telegram, Slack, Discord, iMessage, Signal, Teams, Google Chat, Matrix, Zalo, WebChat)
Uses cloud LLM APIs (Claude, GPT, DeepSeek, Grok, Gemini) to execute real tasks
Has "hands" -- can browse the web, manage files, send emails, control calendars, run system commands, make voice calls
Operates 24/7 with cron jobs, webhooks, and proactive automation
Stores all data locally -- your data never leaves your network

Core philosophy: "Your assistant. Your machine. Your rules."

Unlike ChatGPT or Claude's web interface, OpenClaw doesn't just answer questions. It acts autonomously.

What OpenClaw Is NOT¶

It is NOT a local LLM -- it calls cloud APIs (Claude, GPT, etc.)
It does NOT require expensive hardware -- a $5 VPS works
It is NOT enterprise-ready out of the box -- no native RBAC, SSO, or audit logging

The Viral Story¶

The Naming Saga (Five Names in 60 Days)¶

Date	Name	Why
Nov 2025	Warelay	Original name ("WhatsApp Relay")
Nov 2025	Clawdis	Brief interim
Nov 2025	Clawdbot	Wordplay on "Claude" + lobster mascot
Jan 27, 2026	Moltbot	Anthropic's legal team requested name change. Complied same-day.
Jan 30, 2026	OpenClaw	"The lobster has molted into its final form."

Reddit called it "the fastest triple rebrand in open source history." Each rename paradoxically generated MORE attention.

Growth Timeline¶

Date	Stars	Event
Jan 25	9,000	Initial viral moment
Jan 27	~15,000	Renamed to Moltbot
Jan 29	~50,000	Viral acceleration
Jan 30	106,000	Renamed to OpenClaw -- 34,168 stars in 48 hours (710/hr peak)
Feb 5	157,000+	Continued growth
Feb 14	~191,000	22,400+ forks, 8,664+ commits

Context: React took ~8 years to reach 100K stars. Linux ~12 years. OpenClaw did it in ~5 days.

Why It Went Viral¶

Moltbook -- AI-only social network launched alongside it. 770K+ AI agents in 4 days.
Demo effect -- One user's agent negotiated between two car dealers, saved $4,200 while the user sat in a meeting.
Influencer validation:
Andrej Karpathy: "genuinely the most incredible sci-fi takeoff-adjacent thing I have seen recently"
Elon Musk: commented it represented "early stages of singularity"
Simon Willison: described Moltbook as "the most interesting place on the internet right now"
TikTok/Twitter short demo videos drove mass non-technical adoption.
Stock impact -- Cloudflare's stock moved 14% within a week of launch.

Architecture¶

Hub-and-Spoke Design¶

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage /
BlueBubbles / Microsoft Teams / Matrix / Zalo / WebChat
        |
        v
  +---------------------------+
  |        Gateway            |
  |     (control plane)       |
  |   ws://127.0.0.1:18789   |
  +-------------+-------------+
                |
    +-----------+-----------+
    |           |           |
  Pi Agent   CLI       WebChat UI
  (RPC)    (openclaw)   macOS app
                        iOS/Android nodes

Core Components¶

Component	Description
Gateway	Node.js WebSocket server on `ws://127.0.0.1:18789`. Single source of truth. Exactly one per host.
Pi Agent Runtime	Orchestrates AI interactions: session resolution, context assembly, streaming invocation, tool execution
Channel Adapters	WhatsApp (Baileys), Telegram (grammY), Discord (discord.js), Slack (Bolt), iMessage (BlueBubbles)
Canvas	Agent-driven visual workspace on port 18793 (A2UI framework)
Control UI	Web dashboard on port 18789 for chat, agent management, settings, logs

System Prompt Architecture (The 9 Core Files)¶

OpenClaw loads 9 markdown files into every single message it processes. Customizing these is the single most impactful thing you can do. (Source: David Ondrej)

File	Purpose	What to Put Here
agents.md	Operating rules	Workflows, safety boundaries, permission rules, what NOT to do
soul.md	Personality	Tone, character, values, communication style
user.md	Info about YOU	Your identity, preferences, goals, routines, life context
memory.md	Long-term memory	Durable facts, lessons learned, API IDs, references
tools.md	Tool documentation	API docs, usage limits, gotchas, which tools to use when
identity.md	Agent's role	Name, role (marketing agent, coding agent, etc.)
heartbeat.md	Proactive checks	What to check every X minutes (email, calendar, tasks)
boot.md	Startup instructions	What to do when OpenClaw starts
bootstrap	Initial setup	Setup scripts and first-run config

You customize these via natural language ("Show me user.md", "Update soul.md to be more concise"). See Power User Guide for detailed examples.

Living Files Theory¶

Files on a device with an AI agent are "living files" -- the AI accesses, updates, and references them 24/7. Files on Google Drive or your laptop are "dead files" -- they only get used when you manually remember them. Every research result, conversation insight, and piece of knowledge should be saved as a markdown file in your agent's workspace so it becomes permanent context. (Source: David Ondrej)

Additional context assembly: - Dynamic context -- Session history, relevant skills, semantic memory search results

Memory System¶

Stored in ~/.openclaw/memory/<agentId>.sqlite
Hybrid search: Vector similarity (semantic) + BM25 (keyword relevance)
Voyage AI embeddings (v2026.2.6+)
Memory files: MEMORY.md (curated facts), daily notes (memory/YYYY-MM-DD.md)
Auto-reindexing with 1.5-second file watcher debounce

Data Storage¶

Type	Location
Config	`~/.openclaw/openclaw.json` (JSON5)
Sessions	`~/.openclaw/sessions/`
Memory	`~/.openclaw/memory/<agentId>.sqlite`
Credentials	`~/.openclaw/credentials/` (0600 permissions)
Skills	`~/.openclaw/workspace/skills/`

Latency Profile¶

Operation	Time
Access control	<10ms
Disk load	<50ms
Prompt assembly	<100ms
First model token	200-500ms
Tool execution	100ms-3s

Complete Feature List¶

Messaging Channels (13 core, 21 total with plugins)¶

Core: WhatsApp, Telegram, Discord, Slack, Signal, iMessage (via BlueBubbles), Google Chat, Microsoft Teams, Matrix, Zalo, Zalo Personal, WebChat (built-in)

Optional plugins: IRC, Feishu, Mattermost, LINE, Nextcloud Talk, Nostr, Tlon, Twitch

Built-in Tools¶

Shell command execution
File system read/write/edit
Browser automation (Playwright/Chromium)
Web search
Voice calls (ElevenLabs TTS, Telnyx, Twilio)
Gmail integration
GitHub integration
Calendar management (CalDAV -- iCloud, Google, Fastmail, Nextcloud)
Camera snapshots, screen recording
System notifications

Automation & Scheduling¶

Cron jobs -- Standard cron syntax + ISO 8601
Heartbeats -- Periodic wake-up for proactive behavior
Webhooks -- External trigger integration
One-shot jobs -- Schedule a single future task, auto-deletes after execution
Isolated sessions -- Cron jobs can run in isolated contexts

Voice & Speech¶

VoiceWake -- Always-on speech trigger (macOS/iOS/Android)
TalkMode -- Continuous conversation overlay
ElevenLabs -- Audio synthesis integration
Whisper -- Voice message transcription

Visual Workspace (Live Canvas)¶

Agent-driven UI (A2UI framework)
Real-time visualization of agent reasoning
Runs on separate server (port 18793)
Supports macOS native views, iOS/Android WebView, web browsers

Companion Apps¶

macOS menu bar app with health monitoring
iOS node for Canvas, camera, screen recording
Android node with SMS support

Security Features (v2026.2.12)¶

Skill code safety scanner + VirusTotal partnership
SSRF hardening with explicit deny policy
Authentication for loopback browser control routes
Auto-generated auth tokens on startup
Gateway token authentication for Control UI
Node pairing (approval + token required)
Credential redaction from config responses
Docker sandboxing for tool execution
Voice call hardening (inbound allowlist, anonymous caller rejection)

Supported LLMs¶

Provider	Models
Anthropic	Claude Opus 4.6, Sonnet 4.5 (recommended)
OpenAI	GPT-5.3-Codex, GPT-4o
xAI	Grok 4
Google	Gemini 3 Pro
Baidu	Qianfan
DeepSeek	V3.2, R1
Zhipu AI	GLM-5, GLM-4.7
Local	Any model via Ollama, LM Studio, etc.

OAuth support: Claude Code subscriptions, OpenAI Codex subscriptions, Google AI Pro (no separate API key cost).

Model failover: Automatic key cooldown on failure, rotation between authentication profiles, fallback chains.

Multi-agent routing: Different sessions can use different models (e.g., Discord uses Claude Sonnet, Telegram support uses GPT-4o).

Claude Code & Codex Integration¶

How It Works¶

OpenClaw can spawn and orchestrate Claude Code and Codex CLI through its coding-agent skill
AgentSkills standard is cross-platform -- skills work in OpenClaw, Claude Code, and Cursor
OAuth mechanism supports Claude Code subscriptions (no separate API key needed)
Users report: "managing Claude Code / Codex sessions I can kick off anywhere, autonomously running tests, capturing errors through Sentry webhooks, resolving them and opening PRs"

OpenClaw vs Claude Code¶

Aspect	OpenClaw	Claude Code
Scope	Full-life automation (email, calendar, messaging, coding, browsing)	Coding tasks in terminal/IDE
Interaction	Autonomous -- wakes up for tasks, runs 24/7	Task-driven -- you give it work
Channels	WhatsApp, Telegram, Slack, Discord, etc.	Terminal only
Non-coding	Emails, calendars, social media, voice calls	Cannot
Proactivity	Cron jobs, heartbeats, background tasks	None

Fun Fact¶

Peter Steinberger built OpenClaw using OpenAI's Codex, running 4-10 agents simultaneously. 6,600 commits in January alone. "Founder-as-orchestrator, agents-as-team."

Multi-Agent / Swarms¶

Native Multi-Agent Support¶

Each accountId routes to a different agent
One server hosts multiple phone numbers without mixing sessions
agentId = one "brain" (workspace, auth, session store)
accountId = one channel account instance
binding = routes inbound messages to agentId by (channel, accountId, peer)

Community Swarm Solutions¶

Project	Description
Clawe	Multi-agent coordination -- deploy teams of AI agents with own identity, workspace, scheduled heartbeats
Network-AI Swarm Orchestrator	Permission checker, blackboard shared state, handoff tax & budget tracking
OpenClaw Family	FlowGen infrastructure for multi-agent orchestration

Agent Teams RFC (Active)¶

GitHub Discussion #10036 proposes built-in Agent Teams: - Parallel task execution with shared state - Inter-agent messaging - Flexible coordination modes

Multi-Agent Architecture Pattern¶

                     ┌─────────────────┐
                     │  Reverse Proxy   │
                     │  (HTTPS/Caddy)   │
                     └────────┬────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
    ┌─────────▼──────┐ ┌─────▼──────┐ ┌──────▼─────────┐
    │ Agent: Sales   │ │ Agent: Ops │ │ Agent: Support │
    │ Profile: sales │ │ Profile:ops│ │ Profile:support│
    │ Port: 18790    │ │ Port:18791 │ │ Port: 18792    │
    │ WhatsApp Biz   │ │ Slack      │ │ Telegram       │
    └────────────────┘ └────────────┘ └────────────────┘

Skills Ecosystem¶

700+ community skills on ClawHub
50+ official integrations (Spotify, Hue, Obsidian, Twitter/X, GitHub, Trello, Apple Reminders, Sonos, RTSP cameras, etc.)
AgentSkills standard -- Cross-platform format compatible with Claude Code and Cursor
Skills are instruction documents (SKILL.md), not direct code execution
Runtime skill discovery with selective injection

Skill Safety¶

Skill code safety scanner (v2026.2.6+)
VirusTotal partnership for malware scanning
WARNING: 341 malicious skills (11.3% of marketplace) were found distributing Atomic Stealer malware. Always vet skills before installing.

Security History & Hardening¶

Major Incidents¶

CVE-2026-25253: One-Click RCE (CVSS 8.8) - Malicious web page could exfiltrate auth token via unvalidated WebSocket parameter - Cross-Site WebSocket Hijacking -- no origin header validation - Complete system compromise with a single browser click - Patched in v2026.1.29

ClawHavoc Campaign - 341 malicious skills installed Atomic Stealer malware on macOS - 14 malicious ClawHub contributors identified (compromised GitHub accounts)

Exposed Instances - 135,000+ instances found on public internet (Bitdefender/Censys/Shodan) - Full credentials exposed: API keys, bot tokens, OAuth secrets, conversation histories

Crypto Scams - Fake $CLAWD cryptocurrency hit $16M market cap before crashing 90%+ - Scammers hijacked abandoned @clawdbot handles within seconds of rename

Required Hardening (Enterprise Minimum)¶

See Enterprise Setup Guide for the complete checklist.

Real Monthly Costs¶

Usage Level	Monthly Cost	Notes
Light	$10-30	Casual messaging, few automations
Moderate	$35-82	Daily use, several cron jobs
Heavy	$162-762	Always-on, multiple agents, heavy automation

Costs come from LLM API token usage (primarily Claude/GPT). Users report burning $20 in tokens overnight. The token usage dashboard (v2026.2.6+) helps monitor this.

Launched January 28, 2026 by Matt Schlicht (CEO of Octane AI, NOT Steinberger).

Reddit-style social network designed exclusively for AI agents
AI agents post, comment, upvote, form communities called "submolts"
770,000+ active agents and 1M+ human visitors within 4 days
Agents discussed automation tricks, security vulnerabilities, philosophy, and formed "encrypted religions"
A $MOLT cryptocurrency token emerged (separate from the project)

Media Coverage¶

Forbes, CNBC, TechCrunch, IBM Think, The Verge, Ars Technica, ZDNET, WIRED, CNET, VentureBeat, Tom's Guide, The Hacker News, Fortune, Dark Reading, Security Boulevard, CoinMarketCap -- all covered OpenClaw extensively. Wikipedia has a full article.

Steinberger appeared on the Lex Fridman Podcast (#491).