From 60aa6fd0efd94e1592cc9d1d8d3fc690b0933bef Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sun, 22 Feb 2026 14:32:22 -0800 Subject: [PATCH] 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. --- .../openclaw-personal-ai-assistant.md | 538 ++++++++++++++++++ 1 file changed, 538 insertions(+) create mode 100644 __LOCAL_LLMs/windows_specific/openclaw-personal-ai-assistant.md diff --git a/__LOCAL_LLMs/windows_specific/openclaw-personal-ai-assistant.md b/__LOCAL_LLMs/windows_specific/openclaw-personal-ai-assistant.md new file mode 100644 index 00000000..b9d86a78 --- /dev/null +++ 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 ` | 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)