60aa6fd0ef
Covers: what it is, installation on Windows/WSL2 and macOS, channels, models, configuration, security, HP Z240 as always-on gateway host, Tailscale remote access, troubleshooting, CLI reference, and skills.
19 KiB
19 KiB
OpenClaw — Personal AI Assistant
Website: openclaw.ai · Repo: github.com/openclaw/openclaw · Docs: 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 |
|---|---|---|
| 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 |
| 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
# 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
# Install globally
npm install -g openclaw@latest
# Verify
openclaw --version
Step 3: Run the Onboarding Wizard
openclaw onboard --install-daemon
The wizard guides you through:
- Gateway setup — picks port 18789, creates config
- Model authentication — connect Anthropic or OpenAI (OAuth or API key)
- Channel pairing — set up WhatsApp, Telegram, etc.
- Skills installation — choose which tools to enable
- Daemon installation — sets up systemd user service for auto-start
Step 4: Verify
# 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
# 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 or build from source.
Configuration
Config lives in ~/.openclaw/config.yaml (created by the wizard).
Key Settings
# 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 <channel> <code> |
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
# 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
# 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:
# 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):
# 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
# 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:
# 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
# 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
# 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'
# 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
# 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
# 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
# From Windows PowerShell — restart WSL2
wsl --shutdown
wsl
# Check if systemd is working inside WSL2
systemctl --user status
Model Auth Failures
# 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
# Check Gateway memory
openclaw stats
# Prune old sessions (if memory grows)
openclaw session prune --older-than 7d
# Restart to clear memory
openclaw restart
Logs
# 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
# 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 <key> <value> |
Update config |
openclaw channel <name> restart |
Restart a channel |
openclaw pairing approve <ch> <code> |
Approve a DM sender |
openclaw auth login <provider> |
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 |