# OpenClaw
OpenClaw (formerly Moltbot, originally Clawdbot) is an open-source, self-hosted personal AI assistant created by [[Peter Steinberger]]. It turns powerful language models like Claude into proactive digital coworkers capable of executing meaningful actions across devices. The project runs entirely on your own hardware—Mac, PC, Linux, or cloud server—without relying on external hosted services.
> Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞
## Name History
The project started as **Clawdbot**, with the name hinting at its origins from Claude and [[Claude Code]]. Following a trademark request from Anthropic to avoid confusion with their Claude-branded AI products, it was renamed to **Moltbot**. The project has since been renamed again to **OpenClaw**, reflecting its open-source nature while keeping the lobster theme.
You give natural-language commands, and it writes and executes code to get results.
## Key Features
- **Self-hosted & privacy-first**: Runs on your own hardware with full control, data stays on your machine
- **Multi-channel support**: Works through WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Google Chat, Microsoft Teams, Matrix, BlueBubbles, Zalo, IRC, LINE, Nostr, Twitch, Feishu, Nextcloud Talk, Synology Chat, Tlon, Mattermost, and WebChat via unified inbox
- **35+ model providers**: Anthropic, OpenAI, Google, Mistral, xAI, Groq, Ollama, vLLM, OpenRouter, Amazon Bedrock, and many more
- **System access**: Direct access to filesystem, browser automation, shell commands, email, calendar
- **Persistent memory**: Learns your preferences and context across sessions
- **Voice support**: Always-on speech recognition and talk mode for macOS/iOS/Android via ElevenLabs
- **Live Canvas**: Agent-driven visual workspace with A2UI support
- **Multi-agent routing**: Host multiple isolated agents on a single gateway with separate workspaces, sessions, and auth
- **ACP agents**: Spawn external coding harnesses (Claude Code, Codex, Gemini CLI, Pi, OpenCode, Kimi) as sessions
- **Sub-agents**: Background agent instances for parallelized work, orchestrator patterns, and nested delegation
- **Extensible**: Community skills via ClawHub or custom-built plugins
- **Self-improving**: Can autonomously create and modify its own skills
- **Hooks & automation**: Event-driven hooks, cron jobs, standing orders, webhooks, polls, and heartbeat monitoring
- **Context engine**: Pluggable context assembly with built-in compaction, vector search (BM25 + embeddings), and MMR re-ranking
- **Nodes**: iOS/Android devices as camera, screen capture, location, and voice endpoints
- **Web UIs**: Control UI, Dashboard, TUI, and WebChat interfaces
## Platform Support
- macOS (native menu bar app + node mode)
- Linux (daemon via systemd)
- Windows (via WSL2, strongly recommended)
- iOS and Android (as device nodes for screen recording, camera, notifications)
## Installation
### NPM (recommended)
Requires Node.js 24 (recommended) or 22.14+ LTS.
```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```
The wizard installs a daemon service (launchd/systemd) for continuous operation.
### One-liner
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
### From Source
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon
pnpm gateway:watch
```
Also available via Docker, Podman, Kubernetes, Nix, Ansible, and cloud providers (Hetzner, DigitalOcean, GCP, Azure, Oracle Cloud, Fly.io, Railway, Render, Northflank). Raspberry Pi supported. Experimental Bun runtime available.
Legacy `clawdbot` and `moltbot` commands remain available as compatibility shims.
## Configuration
Minimal setup via `~/.openclaw/openclaw.json`:
```json
{
"agent": {
"model": "anthropic/claude-opus-4-5"
}
}
```
Supports Anthropic (Claude Pro/Max) and OpenAI (ChatGPT/Codex) models via OAuth subscriptions. The project recommends Anthropic Pro/Max with Opus 4.5 for long-context strength and prompt-injection resistance.
## Usage Examples
### Starting the Gateway
```bash
openclaw gateway --port 18789 --verbose
```
### Sending Messages
```bash
openclaw message send --to +1234567890 --message "Hello from OpenClaw"
```
### Agent Interaction
```bash
openclaw agent --message "Ship checklist" --thinking high
```
### Chat Commands (in messaging apps)
- `/status` — session overview
- `/new` or `/reset` — clear context
- `/think <level>` — reasoning depth (off through xhigh)
- `/verbose on|off` — verbosity toggle
- `/activation mention|always` — group trigger mode
### Update Channels
Switch between release channels:
```bash
openclaw update --channel stable|beta|dev
```
## License
Open source under the **MIT License**. The runtime, gateway, CLI, default plugins, and skill scaffolding are all permissively licensed ; you can self-host, fork, and embed without copyleft obligations.
## Architecture
The Gateway WebSocket network provides a single control plane connecting channels, clients, tools, and events at `ws://127.0.0.1:18789`. Optional Tailscale Serve/Funnel enables remote access while keeping the gateway bound to loopback.
By default the gateway runs the bundled [[Pi Mono|Pi]] binary in RPC mode with per-sender sessions ; that is the out-of-the-box agent surface before you configure your own model provider, ACP backend, or sub-agents.
See [[OpenClaw Gateway]] for the gateway control plane in depth.
## Sub-systems and concept notes
For atomic deep-dives into individual concepts, see:
- [[OpenClaw Gateway]] ; control plane, transports, multi-gateway
- [[OpenClaw Multi-Agent Routing]] ; how messages reach the right agent
- [[OpenClaw Sub-Agents]] ; background agent instances and orchestrator pattern
- [[OpenClaw ACP Agents]] ; spawning external coding harnesses as sessions
- [[OpenClaw Skills]] ; skill format, discovery, ClawHub
- [[OpenClaw Hooks]] ; event-driven automation
- [[OpenClaw Standing Orders]] ; persistent autonomous operating authority
- [[OpenClaw Memory System]] ; daily and long-term memory, providers, search
- [[OpenClaw Nodes]] ; iOS/Android device endpoints
- [[OpenClaw Channels]] ; messaging surface and bindings
## Multi-Agent Routing
A single gateway can host multiple isolated agents, each with separate workspaces, authentication, and sessions. Messages are deterministically routed via bindings with priority: peer match > parent peer > guild+roles > guild > team > account > channel > default agent. Each agent gets its own `~/.openclaw/agents/<agentId>/` directory with independent session stores, auth profiles, and persona files (SOUL.md, AGENTS.md).
Use cases: split by personality (fast agent on WhatsApp, deep model on Telegram), per-person isolation on shared servers, family groups with restricted tools, different channel accounts routing to different agents.
Setup: `openclaw agents add <name>`, configure bindings in `openclaw.json`, restart gateway, verify with `openclaw agents list --bindings`.
## ACP Agents
[[Agent Client Protocol (ACP)|ACP]] sessions let OpenClaw spawn external coding harnesses as managed sessions. Supported harnesses via the `acpx` backend plugin: **[[Pi Mono|Pi]]**, **[[Claude Code]]**, **[[OpenAI Codex|Codex]]**, **OpenCode**, **[[Gemini CLI]]**, and **[[Kimi Code|Kimi]]**.
Configuration:
```json
{
"acp": {
"enabled": true,
"backend": "acpx",
"defaultAgent": "codex",
"allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"]
}
}
```
Key commands:
- `/acp spawn <agent>` — create and optionally bind a session (`--mode persistent|oneshot`, `--thread auto|here|off`)
- `/acp status` — display backend, mode, state, capabilities
- `/acp steer <msg>` — guide without replacing context
- `/acp cancel` / `/acp close` — stop work or terminate session
- `/acp model` / `/acp permissions` / `/acp timeout` — tune runtime
- `/acp doctor` — check backend health
Thread-bound sessions supported on Discord and Telegram. ACP sessions run on host runtime (not sandbox). Permissions can be preset to `approve-all`, `approve-reads` (default), or `deny-all` since no TTY exists for interactive prompts.
Install: `openclaw plugins install acpx && openclaw config set plugins.entries.acpx.enabled true`
## Sub-Agents
Sub-agents are background agent instances spawned from a main agent. They run in isolated sessions (`agent:<id>:subagent:<uuid>`), execute non-blocking, and announce results back to the requester's channel when complete.
Spawned via the `sessions_spawn` tool or `/subagents spawn <agentId> <task>`. Key parameters: task, label, model/thinking overrides, timeout, thread binding (Discord), sandbox mode.
Commands: `/subagents list`, `kill`, `log`, `info`, `send`, `steer`, `spawn`.
**Orchestrator pattern**: Set `maxSpawnDepth: 2` to allow sub-agents to spawn their own children (depth-2 leaf workers). Depth-1 orchestrators get session management tools; depth-2 workers do not. Result flow: depth-2 → depth-1 → main → user.
Concurrency: `maxConcurrent` (default 8), `maxChildrenPerAgent` (default 5), max nesting depth 5. Cost optimization: configure cheaper models for sub-agents via `agents.defaults.subagents.model`.
Auto-archive after 60 minutes (configurable). Tool denylists configurable per sub-agent.
## Memory System
Memory is stored as plain Markdown in the agent workspace:
- **Daily memory**: `memory/YYYY-MM-DD.md` — append-only daily log, today's and yesterday's entries auto-loaded
- **Long-term memory**: `MEMORY.md` — curated persistent information, loaded only in main/private sessions
Agent tools: `memory_search` (semantic recall across indexed snippets) and `memory_get` (targeted file reads).
Before context compaction, a silent agentic turn prompts the model to persist durable memories. Vector search supports multiple embedding providers (OpenAI, Gemini, Voyage, Mistral, Ollama, local GGUF) with hybrid BM25 + vector search, MMR diversity re-ranking, and temporal decay.
## Context Engine
Controls how the model context is assembled for each run. The built-in `legacy` engine handles message storage, context assembly within token budgets, history compaction/summarization, and post-turn persistence. Pluggable via plugins: install a custom engine with `openclaw plugins install`, then set `plugins.slots.contextEngine` to the engine's ID. Custom engines can inject dynamic system prompt additions.
## Skills & Plugins
Skills are directories containing a `SKILL.md` file with YAML frontmatter and instructions. They teach agents how to use tools and follow the AgentSkills-compatible format.
Loaded from three locations (highest precedence first): workspace `<workspace>/skills/`, managed `~/.openclaw/skills/`, and bundled skills. Gating via requirements: required binaries, env vars, config paths, and OS restrictions.
**ClawHub** (https://clawhub.com) is the public skills registry. Install: `clawhub install <skill-slug>`, update: `clawhub update --all`.
Plugins extend OpenClaw with custom channels, tools, context engines, and skills. Distributed via npm packages with `openclaw.plugin.json` manifests. Install: `openclaw plugins install <name>`.
## Automation
### Hooks
Event-driven handlers that fire on agent lifecycle events. Types: command events (`command:new`, `command:reset`, `command:stop`), session events (`session:compact:before/after`), agent events (`agent:bootstrap`), gateway events (`gateway:startup`), message events (`message:received`, `message:transcribed`, `message:preprocessed`, `message:sent`).
Auto-discovered from `<workspace>/hooks/`, `~/.openclaw/hooks/`, and bundled hooks. Each hook has a `HOOK.md` (metadata) and `handler.ts` (async TypeScript). Distributable as npm hook packs.
Built-in hooks: `session-memory` (saves context on `/new`), `bootstrap-extra-files` (injects files at bootstrap), `command-logger` (audit logging), `boot-md` (executes BOOT.md at startup).
CLI: `openclaw hooks list`, `info`, `check`, `enable/disable`, `install`.
### Standing Orders
Permanent operating authority for autonomous agent execution within defined boundaries. Define scope, triggers, approval gates, and escalation rules in workspace files (primarily AGENTS.md). Programs follow the Execute-Verify-Report pattern. Enforced via cron jobs for time-based triggers.
### Cron Jobs
Scheduled task execution. Standing orders define *what* the agent does; cron jobs define *when*. Also supports heartbeat monitoring and polls for event-driven automation.
## Nodes
iOS and Android devices connect as nodes to the gateway, providing:
- **Camera capture**: Take photos and send to the agent
- **Audio**: Voice notes, transcription, talk mode (always-on speech recognition)
- **Voice wake**: Wake word detection for hands-free interaction
- **Location**: Device location sharing
- **Media understanding**: Image, video, and document analysis
- **Screen recording**: Capture device screen for agent context
## Security Model
- **Personal sessions**: Main (personal) sessions execute tools on the host with full agent access
- **Group/Channel safety**: Non-main sessions can run in per-session Docker sandboxes via `sandbox.mode: non-main`
- **DM policies**: Pairing mode (default) requires allowlist approval; open mode requires explicit configuration
- **Sandbox restrictions**: Sandboxed sessions have denylist for browser, canvas, nodes, cron, Discord, and gateway access
## Use Cases
- **Overnight coding supervision**: Agents fix bugs and open PRs while you sleep
- **Daily briefings**: Automated summaries and task lists
- **Expense tracking**: Automatic categorization and reporting
- **Smart home orchestration**: Control devices through natural language
- **Cross-device workflows**: Coordinate actions across your devices
- **Browser automation**: Form-filling and data extraction
## OpenClaw vs Claude Code
| Aspect | OpenClaw | [[Claude Code]] |
|--------|----------|-----------------|
| Primary use | Personal assistant, orchestration | Direct coding in repos |
| Interface | Messaging apps (WhatsApp, Slack, etc.) | Terminal/CLI |
| Memory | Persistent long-term memory | Session-based |
| Scope | Cross-device, cross-app | Single codebase |
| Best for | Automation, coordination | Focused development |
Use [[Claude Code]] for the fastest direct coding loop inside a repository. Use OpenClaw when you want durable memory, cross-device access, and tool orchestration.
## Security Recommendations
```
# SSHD config (/etc/ssh/sshd_config)
PermitRootLogin no
sudo sshd -t && sudo systemctl reload ssh
# Brute-force protection → Auto-ban IPs after failed login attempts.
sudo apt install fail2ban -y
sudo systemctl enable --now fail2ban
# Install Tailscale (private VPN mesh network)
sudo curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Then connect the machine to your Tailscale account
# Optional: Disable Key Expiry for that machine
# SSH only via Tailscale → No more public SSH exposure.
Verify Tailscale is working first!
tailscale status
sudo ufw allow from 100.64.0.0/10 to any port 22 proto tcp
sudo ufw delete allow OpenSSH
Default-deny firewall → Block everything incoming by default
sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
Web ports private too → App only accessible from your devices.
sudo ufw allow from 100.64.0.0/10 to any port 443 proto tcp
sudo ufw allow from 100.64.0.0/10 to any port 80 proto tcp
Disable IPv6 (optional) → Reduces attack surface if unused.
sudo sed -i 's/IPV6=yes/IPV6=no/' /etc/default/ufw echo "net.ipv6.conf.all.disable_ipv6 = 1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p && sudo ufw reload
# Install OpenClaw
adduser openclaw && usermod -aG sudo openclaw && su - openclaw
curl -fsSL https://openclaw.ai/install.sh | bash
exec bash
...
Lock to owner only → Only you can message the bot.
{ "dmPolicy": "allowlist", "allowFrom": ["YOUR_TELEGRAM_ID"], "groupPolicy": "allowlist" }
Fix credential permissions → Don't leave secrets world-readable.
chmod 700 ~/.openclaw/credentials
chmod 600 .env
# Run security audit → Catches issues you missed - don't skip!
openclaw security audit --dee
# Verify everything
sudo ufw status ss -tulnp tailscale status openclaw doctor
```
## Useful commands
```
openclaw status
openclaw status --all
openclaw configure
openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
openclaw devices list
openclaw hooks list
openclaw hooks enable <name>
openclaw hooks disable <name>
```
## References
- Official website: https://openclaw.ai
- Documentation: https://docs.openclaw.ai
- Full docs index: https://docs.openclaw.ai/llms.txt
- GitHub: https://github.com/openclaw/openclaw
- Skills Hub: https://clawhub.com
- Security: https://docs.openclaw.ai/gateway/security
- ACP Agents: https://docs.openclaw.ai/tools/acp-agents
- Sub-Agents: https://docs.openclaw.ai/tools/subagents
- Multi-Agent Routing: https://docs.openclaw.ai/concepts/multi-agent
- Memory: https://docs.openclaw.ai/concepts/memory
- Skills: https://docs.openclaw.ai/tools/skills
- Hooks: https://docs.openclaw.ai/automation/hooks
- Standing Orders: https://docs.openclaw.ai/automation/standing-orders
- Context Engine: https://docs.openclaw.ai/concepts/context-engine
- Plugins: https://docs.openclaw.ai/plugins/building-plugins
- Community Discord: https://discord.com/invite/clawd
- More skills: https://github.com/VoltAgent/awesome-openclaw-skills
- Support on [[Cloudflare]]: https://blog.cloudflare.com/moltworker-self-hosted-ai-agent/
## Videos
- https://www.ted.com/talks/peter_steinberger_how_i_created_openclaw_the_breakthrough_ai_agent
- https://www.youtube.com/watch?v=zgNvts_2TUE
## Related
- [[AI Agents]]
- [[Claude Code]]
- [[OpenClaude]]
- [[Claude]]
- [[Peter Steinberger]]
- [[OpenClaw VPS Configuration Guide]]
- [[How to Connect OpenClaw to Chrome via Tailscale (Article)]]
- [[Pi Mono]]
- [[Scrapling]]
- [[Kimi K2.6]]
- [[Crabbox]] — OpenClaw's remote testbox for running tests/commands on ephemeral cloud machines