# OpenClaw — Personal AI Assistant > **Website:** [openclaw.ai](https://openclaw.ai) · **Repo:** [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw) · **Docs:** [docs.openclaw.ai](https://docs.openclaw.ai) > **License:** MIT · **Runtime:** Node.js ≥ 22 · **No GPU required** --- ## What Is OpenClaw? OpenClaw is a self-hosted, local-first AI assistant that connects to your existing messaging channels. You run a **Gateway** on your machine (or a server), and it routes conversations between you and an LLM through WhatsApp, Telegram, Slack, Discord, iMessage, Signal, Microsoft Teams, and more. Think of it as: **your own private ChatGPT, accessible from any messaging app you already use.** ``` ┌──────────────────────────────────────────────────────────────────────┐ │ How OpenClaw Works │ │ │ │ WhatsApp ─┐ │ │ Telegram ─┤ │ │ Slack ────┤ ┌──────────────────────┐ ┌──────────────────┐ │ │ Discord ──┼────►│ Gateway │────►│ LLM Provider │ │ │ Signal ───┤ │ ws://localhost:18789 │ │ (Claude / GPT) │ │ │ iMessage ─┤ │ runs on YOUR machine│ │ via API │ │ │ Teams ────┤ └──────────┬───────────┘ └──────────────────┘ │ │ WebChat ──┘ │ │ │ ├── Browser control (CDP) │ │ ├── Cron jobs / webhooks │ │ ├── Skills (extensible tools) │ │ ├── macOS menu bar app │ │ └── iOS / Android companion nodes │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` ### Key Differentiator Unlike local LLM tools (Ollama, LM Studio), OpenClaw is a **cloud-model orchestrator** — it uses Claude or GPT-4 via API, not local models. The "local" part is the **Gateway** that handles routing, sessions, tools, and channel connections on your machine. --- ## Why Use It? | Benefit | Description | | ---------------- | --------------------------------------------------------------------- | | **Single inbox** | Talk to AI from WhatsApp, Telegram, Slack, etc. — no app switching | | **Always-on** | Gateway runs as a background daemon (launchd/systemd) | | **Privacy** | Messages route through YOUR Gateway, not a third-party service | | **Tools** | Browser control, cron jobs, webhooks, Gmail hooks, file access | | **Voice** | Wake word + Talk Mode on macOS/iOS/Android (ElevenLabs) | | **Multi-agent** | Route different channels to different agents with separate workspaces | | **Skills** | Extensible plugin system — bundled, managed, or custom skills | | **Free** | Open source, MIT licensed — you only pay for LLM API usage | --- ## Supported Channels | Channel | Protocol | Notes | | --------------------- | ------------------------- | --------------------------------------- | | **WhatsApp** | Baileys (unofficial) | Personal number, no Business API needed | | **Telegram** | grammY | Bot token required | | **Slack** | Bolt | Workspace app setup | | **Discord** | discord.js | Bot token required | | **Google Chat** | Chat API | Google Workspace required | | **Signal** | signal-cli | Requires linked device | | **iMessage** | BlueBubbles (recommended) | Requires macOS host with Messages.app | | **iMessage (legacy)** | imsg | Direct macOS Messages integration | | **Microsoft Teams** | Extension | Teams app setup | | **Matrix** | Extension | Any Matrix homeserver | | **WebChat** | Built-in | Served directly from Gateway | --- ## Supported Models OpenClaw supports multiple LLM providers with failover: | Provider | Recommended Model | Auth | | --------------------------- | ------------------------ | --------------------------------------- | | **Anthropic** (recommended) | Claude Opus 4.6 / Sonnet | Pro/Max subscription (OAuth) or API key | | **OpenAI** | GPT-4o / o1 | ChatGPT subscription (OAuth) or API key | | **Google** | Gemini | API key | | **Local (Ollama)** | Any local model | localhost:11434 | > **Recommendation from maintainer:** Anthropic Pro/Max with Opus 4.6 for best long-context and prompt-injection resistance. --- ## Installation on Windows (WSL2) OpenClaw works on Windows via WSL2 (strongly recommended by the project). ### Prerequisites - **Windows 11** with WSL2 and Ubuntu 24.04 - **Node.js ≥ 22** inside WSL2 - An **Anthropic** or **OpenAI** API key / subscription ### Step 1: Install Node.js 22+ in WSL2 ```bash # Install Node.js via nvm (recommended) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node --version # Should show v22.x.x ``` ### Step 2: Install OpenClaw ```bash # Install globally npm install -g openclaw@latest # Verify openclaw --version ``` ### Step 3: Run the Onboarding Wizard ```bash openclaw onboard --install-daemon ``` The wizard guides you through: 1. **Gateway setup** — picks port 18789, creates config 2. **Model authentication** — connect Anthropic or OpenAI (OAuth or API key) 3. **Channel pairing** — set up WhatsApp, Telegram, etc. 4. **Skills installation** — choose which tools to enable 5. **Daemon installation** — sets up systemd user service for auto-start ### Step 4: Verify ```bash # Health check openclaw doctor # Start gateway manually (if not using daemon) openclaw gateway --port 18789 --verbose # Send a test message openclaw agent --message "Hello, are you working?" ``` --- ## Installation on macOS ```bash # Install via npm (requires Node ≥ 22) npm install -g openclaw@latest # Run onboarding openclaw onboard --install-daemon # The daemon uses launchd on macOS — starts automatically on login ``` ### macOS App (Optional) OpenClaw has a native macOS menu bar app with: - Voice Wake (always-on wake word detection) - Talk Mode (voice conversation overlay) - WebChat (built-in web chat) - Canvas (agent-driven visual workspace) - Debug tools Download from [GitHub releases](https://github.com/openclaw/openclaw/releases) or build from source. --- ## Configuration Config lives in `~/.openclaw/config.yaml` (created by the wizard). ### Key Settings ```yaml # Gateway gateway: port: 18789 bind: '127.0.0.1' # loopback only (safe default) # Model models: default: 'claude-sonnet-4-20250514' fallback: 'gpt-4o' # Channels (add only what you use) channels: whatsapp: enabled: true telegram: enabled: true botToken: 'YOUR_BOT_TOKEN' discord: enabled: true botToken: 'YOUR_BOT_TOKEN' # Security dmPolicy: 'pairing' # unknown senders get a pairing code ``` ### Security Model (Important) OpenClaw connects to real messaging surfaces. **Treat all inbound DMs as untrusted.** | Setting | Value | Meaning | | -------------- | ------------------------------------------- | ------------------------------------------------- | | `dmPolicy` | `"pairing"` (default) | Unknown senders get a pairing code — must approve | | `dmPolicy` | `"open"` | Anyone can message the bot (⚠️ risky) | | Approve sender | `openclaw pairing approve ` | Adds sender to local allowlist | **Always run `openclaw doctor`** to check for risky DM policies. --- ## Windows-Specific Tips & Best Practices ### 1. Always Use WSL2 (Not Native Windows) OpenClaw strongly recommends WSL2 over native Windows PowerShell: - Better Node.js compatibility - Unix tooling works natively - Systemd support for daemon auto-start ```bash # Ensure systemd is enabled in WSL2 sudo nano /etc/wsl.conf # Add: # [boot] # systemd=true # Restart WSL wsl --shutdown # (from Windows PowerShell) ``` ### 2. Keep the Gateway Running ```bash # Check if daemon is running systemctl --user status openclaw-gateway # Start/stop/restart systemctl --user start openclaw-gateway systemctl --user stop openclaw-gateway systemctl --user restart openclaw-gateway # View logs journalctl --user -u openclaw-gateway -f ``` ### 3. WSL2 Networking The Gateway binds to `127.0.0.1:18789` inside WSL2. To access from Windows: ```bash # WSL2 localhost is automatically forwarded to Windows # Open in Windows browser: # http://localhost:18789 ``` ### 4. WhatsApp Pairing (Baileys) WhatsApp uses the unofficial Baileys library (no Business API needed): ```bash # During onboard, you'll scan a QR code with your phone # The session persists in ~/.openclaw/whatsapp/ # If WhatsApp disconnects: openclaw channel whatsapp reconnect # If QR expired, re-pair: openclaw channel whatsapp pair ``` **Warning:** WhatsApp via Baileys is unofficial — there's a small risk of account flagging if you send too many automated messages. Use responsibly. ### 5. Telegram Bot Setup ```bash # 1. Message @BotFather on Telegram # 2. /newbot → give it a name → get bot token # 3. Add token to config: openclaw config set channels.telegram.botToken "YOUR_TOKEN" openclaw restart ``` ### 6. Port Conflicts If port 18789 is in use: ```bash # Check what's using the port lsof -i :18789 # Change the port openclaw config set gateway.port 18790 openclaw restart ``` ### 7. Node.js Version Issues ```bash # OpenClaw requires Node ≥ 22 node --version # If too old, update via nvm nvm install 22 nvm alias default 22 ``` --- ## HP Z240 as an Always-On Gateway Host Your HP Z240 (i7-7700K, 32 GB RAM) is **perfect** for running OpenClaw as an always-on server: | Requirement | HP Z240 | Verdict | | ----------- | ---------------- | -------------------------------- | | CPU | i7-7700K 4.2 GHz | ✅ Way more than needed | | RAM | 32 GB | ✅ Gateway uses < 500 MB | | GPU | Not needed | ✅ Gateway is CPU-only | | Network | Wired Ethernet | ✅ Low latency, always-on | | Power | ~65W idle | ✅ Cheap to run 24/7 (~$5/month) | ### Ideal Setup: HP Z240 as Home Server ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Home Network Setup │ │ │ │ ┌─────────────────────┐ Tailscale ┌──────────────────────┐ │ │ │ HP Z240 (always-on) │◄═════════════════►│ Mac M4 Pro (daily) │ │ │ │ OpenClaw Gateway │ VPN mesh │ macOS app (optional) │ │ │ │ Docker services │ │ CLI / WebChat │ │ │ │ File server │ └──────────────────────┘ │ │ └──────────┬───────────┘ │ │ │ │ │ ├── WhatsApp / Telegram / Slack / Discord │ │ ├── Cron jobs (scheduled tasks) │ │ ├── Gmail hooks (email automation) │ │ └── WebChat (http://hp-z240:18789) │ │ │ │ Access from anywhere: │ │ - Tailscale Serve (tailnet-only, HTTPS) │ │ - Tailscale Funnel (public, password-protected) │ │ - SSH tunnel (fallback) │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` ### Remote Access via Tailscale ```yaml # In ~/.openclaw/config.yaml gateway: tailscale: mode: 'serve' # tailnet-only HTTPS (recommended) # mode: "funnel" # public HTTPS (requires password) auth: mode: 'password' password: 'your-strong-password' ``` ```bash # Install Tailscale on HP Z240 curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up # Now access Gateway from any Tailscale device: # https://hp-z240.your-tailnet.ts.net:18789 ``` --- ## Troubleshooting ### Gateway Won't Start ```bash # Check for errors openclaw gateway --verbose # Check port availability lsof -i :18789 # Check Node version node --version # Must be ≥ 22 # Run doctor openclaw doctor ``` ### Channel Disconnects ```bash # WhatsApp: session expired openclaw channel whatsapp pair # Re-scan QR # Telegram: bot not responding openclaw channel telegram restart # General: restart gateway openclaw restart ``` ### WSL2 Networking Issues ```powershell # From Windows PowerShell — restart WSL2 wsl --shutdown wsl # Check if systemd is working inside WSL2 systemctl --user status ``` ### Model Auth Failures ```bash # Re-authenticate openclaw auth login anthropic # or: openai # Check current auth openclaw auth status # Test model directly openclaw agent --message "Hello" --model claude-sonnet-4-20250514 ``` ### High Memory Usage ```bash # Check Gateway memory openclaw stats # Prune old sessions (if memory grows) openclaw session prune --older-than 7d # Restart to clear memory openclaw restart ``` ### Logs ```bash # Live logs journalctl --user -u openclaw-gateway -f # Or if running manually openclaw gateway --verbose 2>&1 | tee ~/openclaw.log # Log file location ls ~/.openclaw/logs/ ``` ### Updating ```bash # Update to latest stable npm update -g openclaw openclaw update --channel stable # Run doctor after update (handles migrations) openclaw doctor ``` --- ## CLI Quick Reference | Command | Description | | -------------------------------------- | ------------------------------ | | `openclaw onboard` | First-time setup wizard | | `openclaw gateway` | Start gateway (foreground) | | `openclaw gateway --verbose` | Start with debug logging | | `openclaw doctor` | Health check + migration | | `openclaw agent --message "..."` | Send a message to the agent | | `openclaw config set ` | Update config | | `openclaw channel restart` | Restart a channel | | `openclaw pairing approve ` | Approve a DM sender | | `openclaw auth login ` | Re-authenticate model provider | | `openclaw auth status` | Check auth status | | `openclaw session list` | List active sessions | | `openclaw session prune` | Clean old sessions | | `openclaw update` | Update OpenClaw | | `openclaw stats` | Gateway resource usage | --- ## Cost Estimate OpenClaw itself is free. You pay for LLM API usage: | Provider | Plan | Cost | Tokens | | ------------- | -------------- | ------------------------------ | --------------------- | | Anthropic Pro | $20/month | Generous limits | Best for personal use | | Anthropic Max | $100–200/month | Higher limits | Heavy use / coding | | OpenAI Plus | $20/month | GPT-4o access | Good alternative | | OpenAI API | Pay-per-token | ~$2.50/M input tokens (GPT-4o) | Flexible | | Anthropic API | Pay-per-token | ~$3/M input tokens (Sonnet) | Flexible | **Electricity for HP Z240:** ~$5/month at typical idle (~65W). --- ## Skills You'll Learn | Skill | What You'll Learn | Value | | --------------------- | -------------------------------------------------------- | --------------------------- | | **Self-hosted AI** | Running your own AI assistant infrastructure | Privacy-first AI deployment | | **Message routing** | Multi-channel bot architecture, WebSocket control planes | Backend engineering | | **Tailscale / VPN** | Secure remote access to home services | Networking / DevOps | | **Systemd services** | Managing background daemons on Linux | Linux administration | | **Bot development** | WhatsApp/Telegram/Slack bot patterns | Chat platform integrations | | **API orchestration** | Model failover, session management, tool use | AI infrastructure | | **Home lab** | Always-on server, Docker, remote access | Systems engineering | --- ## Further Reading - [Getting Started Guide](https://docs.openclaw.ai/start/getting-started) - [Channel Setup Docs](https://docs.openclaw.ai/channels) - [Security Guide](https://docs.openclaw.ai/gateway/security) - [Remote Access (Tailscale)](https://docs.openclaw.ai/gateway/tailscale) - [Skills / Tools](https://docs.openclaw.ai/tools/skills) - [Browser Control](https://docs.openclaw.ai/tools/browser) - [Canvas / A2UI](https://docs.openclaw.ai/platforms/mac/canvas) - [Docker Install](https://docs.openclaw.ai/install/docker) - [FAQ](https://docs.openclaw.ai/faq)