docs(local-llms): add OpenClaw personal AI assistant guide

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.
2026-02-22 14:32:22 -08:00 · 2026-02-22 14:32:22 -08:00 · 60aa6fd0ef
commit 60aa6fd0ef
parent 05a790de9f
1 changed files with 538 additions and 0 deletions
--- a/__LOCAL_LLMs/windows_specific/openclaw-personal-ai-assistant.md
+++ b/__LOCAL_LLMs/windows_specific/openclaw-personal-ai-assistant.md
@ -0,0 +1,538 @@
+# 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 <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
+
+```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 <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         |
+
+---
+
+## 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)