From bc8e7a0504a049ce726a18c7e8a4d9ea5c168b1f Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sun, 22 Feb 2026 14:42:29 -0800 Subject: [PATCH] docs(openclaw): add detailed install, secure setup & validation guide 7-phase step-by-step guide: - Phase 1: Install (Node.js, OpenClaw, onboarding wizard) - Phase 2: Secure the Gateway (config hardening, password, permissions) - Phase 3: Connect Channels (WhatsApp, Telegram, Discord, Slack, WebChat) - Phase 4: Harden the Host (Windows Firewall, WSL2, macOS, router) - Phase 5: Remote Access (Tailscale Serve setup) - Phase 6: Validate Security (run validate-security.sh) - Phase 7: Daemon & Auto-Start (launchd/systemd) Plus: 22-point verification checklist, maintenance schedule, emergency procedures, and quick reference card --- __LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md | 927 ++++++++++++++++++++++++++ 1 file changed, 927 insertions(+) create mode 100644 __LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md diff --git a/__LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md b/__LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md new file mode 100644 index 00000000..386e6a15 --- /dev/null +++ b/__LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md @@ -0,0 +1,927 @@ +# OpenClaw — Install, Secure & Validate Guide + +> Step-by-step guide to install OpenClaw, lock it down, and verify everything is secure. +> Covers **Windows (WSL2)**, **macOS**, and the **HP Z240 always-on server** scenario. + +--- + +## Table of Contents + +1. [Prerequisites](#1-prerequisites) +2. [Phase 1 — Install OpenClaw](#2-phase-1--install-openclaw) +3. [Phase 2 — Secure the Gateway](#3-phase-2--secure-the-gateway) +4. [Phase 3 — Connect Channels](#4-phase-3--connect-channels) +5. [Phase 4 — Harden the Host Machine](#5-phase-4--harden-the-host-machine) +6. [Phase 5 — Remote Access (Tailscale)](#6-phase-5--remote-access-tailscale) +7. [Phase 6 — Validate Security](#7-phase-6--validate-security) +8. [Phase 7 — Daemon & Auto-Start](#8-phase-7--daemon--auto-start) +9. [Post-Install Verification Checklist](#9-post-install-verification-checklist) +10. [Maintenance & Operations](#10-maintenance--operations) +11. [Emergency Procedures](#11-emergency-procedures) + +--- + +## 1. Prerequisites + +### Hardware + +| Requirement | Minimum | Recommended | +| ----------- | ---------- | --------------------------- | +| CPU | Any 64-bit | i5+ / Apple M-series | +| RAM | 2 GB free | 4 GB free | +| Disk | 500 MB | 2 GB (includes model cache) | +| GPU | Not needed | Not needed | +| Network | Broadband | Wired Ethernet (for server) | + +### Software + +| Component | Required Version | Check Command | +| ------------------- | --------------------------------------------- | ---------------- | +| **Node.js** | ≥ 22 | `node --version` | +| **npm** or **pnpm** | Latest | `npm --version` | +| **OS** | macOS 13+ / Ubuntu 22.04+ / Windows 11 (WSL2) | `uname -a` | + +### Accounts (at least one) + +| Provider | What You Need | Where to Get It | +| --------------------------- | ------------------------------- | ------------------------------------------- | +| **Anthropic** (recommended) | Pro/Max subscription OR API key | [anthropic.com](https://www.anthropic.com/) | +| **OpenAI** (alternative) | Plus subscription OR API key | [openai.com](https://openai.com/) | + +--- + +## 2. Phase 1 — Install OpenClaw + +### Step 1.1: Install Node.js 22+ + +#### macOS + +```bash +# Option A: via Homebrew +brew install node@22 + +# Option B: via nvm (recommended — lets you switch versions) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash +source ~/.bashrc # or source ~/.zshrc on macOS +nvm install 22 +nvm alias default 22 +``` + +#### Windows (WSL2) + +```bash +# Inside WSL2 Ubuntu terminal +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash +source ~/.bashrc +nvm install 22 +nvm alias default 22 +``` + +#### Verify + +```bash +node --version +# Expected: v22.x.x or higher + +npm --version +# Expected: 10.x.x or higher +``` + +### Step 1.2: Install OpenClaw + +```bash +npm install -g openclaw@latest +``` + +#### Verify + +```bash +openclaw --version +# Expected: vYYYY.M.D (e.g., v2026.2.15) + +which openclaw +# Expected: path to openclaw binary +``` + +### Step 1.3: Run the Onboarding Wizard + +```bash +openclaw onboard --install-daemon +``` + +The wizard walks you through: + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Onboarding Wizard Steps │ +│ │ +│ Step 1: Gateway Configuration │ +│ → Port (default 18789), bind address │ +│ │ +│ Step 2: Model Authentication │ +│ → Anthropic OAuth or API key │ +│ → OpenAI OAuth or API key (optional fallback) │ +│ │ +│ Step 3: Channel Setup │ +│ → Choose which channels to enable │ +│ → WhatsApp QR scan, Telegram bot token, etc. │ +│ │ +│ Step 4: Skills Selection │ +│ → Choose which tools to enable │ +│ │ +│ Step 5: Daemon Installation │ +│ → launchd (macOS) or systemd (Linux/WSL2) │ +│ → Auto-starts on login/boot │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +**Important during onboarding:** + +- When asked about bind address → enter `127.0.0.1` (NOT `0.0.0.0`) +- When asked about DM policy → choose `pairing` +- When asked about `system.run` → choose **disabled** unless you specifically need it + +### Step 1.4: Verify Installation + +```bash +# Check the gateway starts +openclaw gateway --verbose +# Should show: "Gateway listening on ws://127.0.0.1:18789" +# Press Ctrl+C to stop (daemon will handle it later) + +# Run health check +openclaw doctor +# Should show all green checks +``` + +--- + +## 3. Phase 2 — Secure the Gateway + +**Do this BEFORE connecting any channels.** + +### Step 2.1: Edit Configuration + +```bash +# Open config file +nano ~/.openclaw/config.yaml +# Or use any text editor +``` + +### Step 2.2: Apply Secure Configuration + +Replace or merge into your `config.yaml`: + +```yaml +# ============================================================ +# OpenClaw — SECURE CONFIGURATION +# ============================================================ + +gateway: + # CRITICAL: Bind to loopback only — never 0.0.0.0 + bind: '127.0.0.1' + port: 18789 + + # CRITICAL: Require password for WebChat and Control UI + auth: + mode: 'password' + # Generate a strong password (run this command, paste result below): + # openssl rand -base64 32 + password: 'PASTE_YOUR_GENERATED_PASSWORD_HERE' + + # Tailscale: serve = tailnet-only, funnel = public (avoid) + tailscale: + mode: 'off' # Enable later in Phase 5 + resetOnExit: true + +# CRITICAL: Unknown senders must be approved via pairing code +dmPolicy: 'pairing' + +# CRITICAL: Disable dangerous tools +tools: + browser: + enabled: false # Enable only when you actively need it + system: + run: + enabled: false # NEVER enable unless you fully understand the risk + notify: + enabled: true # Safe — just sends desktop notifications + +# Model configuration +models: + default: 'claude-sonnet-4-20250514' + # fallback: "gpt-4o" # Uncomment if you have OpenAI as backup +``` + +### Step 2.3: Generate a Strong Password + +```bash +# Generate a 32-character random password +openssl rand -base64 32 + +# Example output: K7x+Rf3bYz...long-random-string... +# Copy this and paste it into config.yaml under gateway.auth.password +``` + +### Step 2.4: Lock Down File Permissions + +```bash +# Only your user can read/write the config (contains API keys + password) +chmod 700 ~/.openclaw +chmod 600 ~/.openclaw/config.yaml + +# Verify +ls -la ~/.openclaw/ +# Should show: drwx------ (700) + +ls -la ~/.openclaw/config.yaml +# Should show: -rw------- (600) +``` + +### Step 2.5: Restart Gateway with Secure Config + +```bash +openclaw restart + +# Verify it picked up the new config +openclaw doctor +``` + +--- + +## 4. Phase 3 — Connect Channels + +Only connect channels AFTER security is configured. + +### Option A: WhatsApp + +```bash +# Initiate pairing — displays a QR code in terminal +openclaw channel whatsapp pair + +# On your phone: +# 1. Open WhatsApp → Settings → Linked Devices → Link a Device +# 2. Scan the QR code shown in the terminal +# 3. Wait for "WhatsApp connected" message +``` + +**Security notes for WhatsApp:** + +- Uses Baileys (unofficial library) — not endorsed by Meta +- Session tokens stored in `~/.openclaw/whatsapp/` +- Lock permissions: `chmod -R 700 ~/.openclaw/whatsapp/` +- Don't share your session files — they give full WhatsApp access + +### Option B: Telegram + +```bash +# 1. Open Telegram → message @BotFather +# 2. Send /newbot → follow prompts → get bot token +# 3. Configure: +openclaw config set channels.telegram.enabled true +openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN_HERE" +openclaw restart + +# 4. Message your bot on Telegram to verify +``` + +### Option C: Discord + +```bash +# 1. Go to https://discord.com/developers/applications +# 2. Create New Application → Bot → copy token +# 3. Enable: MESSAGE CONTENT intent +# 4. Configure: +openclaw config set channels.discord.enabled true +openclaw config set channels.discord.botToken "YOUR_DISCORD_BOT_TOKEN" +openclaw restart + +# 5. Invite bot to your server and DM it +``` + +### Option D: Slack + +```bash +# 1. Go to https://api.slack.com/apps → Create New App +# 2. Enable Socket Mode + Event Subscriptions +# 3. Add Bot Token Scopes: chat:write, channels:read, im:history, im:read +# 4. Install to workspace → copy Bot User OAuth Token +# 5. Configure: +openclaw config set channels.slack.enabled true +openclaw config set channels.slack.botToken "xoxb-YOUR-SLACK-TOKEN" +openclaw config set channels.slack.appToken "xapp-YOUR-APP-TOKEN" +openclaw restart +``` + +### Option E: WebChat (Built-In) + +WebChat is served by the Gateway automatically — no extra setup needed. + +```bash +# Open in browser (requires gateway auth password): +open http://localhost:18789 +# Or on Windows: start http://localhost:18789 +``` + +### Approve a New Sender (Pairing) + +When someone messages your bot for the first time, they get a pairing code: + +```bash +# View pending pairing requests +openclaw pairing list + +# Approve a specific sender +openclaw pairing approve whatsapp ABC123 + +# Approved senders are saved to a local allowlist +``` + +--- + +## 5. Phase 4 — Harden the Host Machine + +### 5A. Windows (WSL2) Hardening + +#### Windows Firewall + +```powershell +# Run in Windows PowerShell as Administrator + +# 1. Block ALL external access to OpenClaw port +New-NetFirewallRule -DisplayName "OpenClaw Block External" ` + -Direction Inbound -LocalPort 18789 -Protocol TCP ` + -Action Block -Profile Any + +# 2. Allow localhost only +New-NetFirewallRule -DisplayName "OpenClaw Allow Localhost" ` + -Direction Inbound -LocalPort 18789 -Protocol TCP ` + -Action Allow -RemoteAddress 127.0.0.1 -Profile Any + +# 3. Block WSL2 port range from external +New-NetFirewallRule -DisplayName "WSL2 Block External" ` + -Direction Inbound -LocalPort 18000-19000 -Protocol TCP ` + -Action Block -Profile Public,Private + +# Verify +Get-NetFirewallRule -DisplayName "*OpenClaw*","*WSL2*" | ` + Format-Table DisplayName,Enabled,Action +``` + +#### WSL2 Internal Hardening + +```bash +# 1. Enable systemd (required for daemon auto-start) +sudo tee -a /etc/wsl.conf > /dev/null << 'EOF' +[boot] +systemd=true +EOF +echo "Restart WSL with: wsl --shutdown (from Windows PowerShell)" + +# 2. Install and enable UFW firewall +sudo apt install -y ufw +sudo ufw default deny incoming +sudo ufw default allow outgoing +sudo ufw allow from 127.0.0.1 to any port 18789 +sudo ufw enable + +# 3. Disable SSH (not needed for OpenClaw) +sudo systemctl disable --now ssh 2>/dev/null || true + +# 4. Keep packages updated +sudo apt update && sudo apt upgrade -y + +# 5. Verify you are NOT root +whoami +# Must NOT be "root" +``` + +#### Windows Update + +```powershell +# In Windows PowerShell — check for updates +# Settings → Windows Update → Check for updates +# Enable: "Get the latest updates as soon as they're available" +``` + +### 5B. macOS Hardening + +```bash +# 1. Enable macOS firewall +# System Settings → Network → Firewall → Turn On + +# 2. Verify OpenClaw config permissions +chmod 700 ~/.openclaw +chmod 600 ~/.openclaw/config.yaml + +# 3. Keep macOS updated +softwareupdate --list +# Install any available updates + +# 4. Keep Homebrew updated +brew update && brew upgrade +``` + +### 5C. Router / Network (Both Platforms) + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ ROUTER CHECKLIST │ +│ │ +│ ✅ DO NOT forward port 18789 (or any OpenClaw port) to your host │ +│ ✅ DO NOT enable UPnP (automatic port forwarding) │ +│ ✅ DO set a strong router admin password │ +│ ✅ DO enable WPA3 (or WPA2 minimum) for WiFi │ +│ ✅ DO use wired Ethernet for the HP Z240 server │ +│ ✅ DO keep router firmware updated │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 6. Phase 5 — Remote Access (Tailscale) + +Use Tailscale to securely access your OpenClaw Gateway from other devices (e.g., Mac → HP Z240 server). + +### Step 5.1: Install Tailscale + +#### On the Server (HP Z240 / WSL2) + +```bash +# Install +curl -fsSL https://tailscale.com/install.sh | sh + +# Start and authenticate +sudo tailscale up + +# Follow the URL to log in — links this machine to your Tailscale account +``` + +#### On Your Other Devices + +Install Tailscale on your Mac, iPhone, etc. from [tailscale.com/download](https://tailscale.com/download). + +### Step 5.2: Enable Tailscale Serve (Tailnet-Only) + +```bash +# Edit config to enable Tailscale Serve +nano ~/.openclaw/config.yaml +``` + +Update the tailscale section: + +```yaml +gateway: + bind: '127.0.0.1' # Still loopback — Tailscale handles external routing + tailscale: + mode: 'serve' # Tailnet-only — NOT public + resetOnExit: true + auth: + mode: 'password' + password: 'YOUR_STRONG_PASSWORD' +``` + +```bash +# Restart +openclaw restart + +# Verify — access from another Tailscale device: +# https://your-server-name.your-tailnet.ts.net:18789 +``` + +### Step 5.3: Verify Tailscale Access + +```bash +# On the server — check Tailscale status +tailscale status +# Should show your devices connected + +# From your Mac — test access +curl -s https://hp-z240.your-tailnet.ts.net:18789/health +# Should get a response (may need auth) +``` + +### ⚠️ NEVER Use Tailscale Funnel Unless You Understand the Risk + +| Mode | Access | Risk | Use Case | +| ----------- | ------------------------ | ------- | ---------------------------------- | +| `off` | Localhost only | None | Default, single-machine | +| **`serve`** | **Tailnet devices only** | **Low** | **Recommended for remote access** | +| `funnel` | Public internet | HIGH | Only if you need webhook callbacks | + +--- + +## 7. Phase 6 — Validate Security + +### Step 6.1: Run the Security Validation Script + +```bash +# From the repo (copy to your server first) +bash validate-security.sh +``` + +Or download and run directly: + +```bash +# If on the server without the repo +curl -O https://raw.githubusercontent.com/YOUR_USER/learning_ai_common_plat/main/__LOCAL_LLMs/OPEN_CLAW/validate-security.sh +bash validate-security.sh +``` + +### Step 6.2: Read the Output + +The script produces color-coded output: + +``` +🦞 OpenClaw Security Validator + 2026-02-22 14:30:00 + Platform: wsl2 + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 1. OpenClaw Installation +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ✅ OpenClaw installed: v2026.2.15 + ✅ Node.js version: v22.12.0 (>= 22 required) + ✅ Config file exists + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 2. Gateway Configuration +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ✅ Gateway binds to loopback only: 127.0.0.1 + ✅ Gateway auth mode: password + ✅ Gateway password length: 44 chars + ✅ DM policy: pairing + ✅ Tailscale mode: serve + ✅ system.run tool: disabled + ✅ Browser control: disabled + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 3. File Permissions +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ✅ ~/.openclaw/ directory permissions: 700 + ✅ config.yaml permissions: 600 + ✅ Not running as root: myuser + + ... (continues for all 7 categories) ... + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + SECURITY SCAN SUMMARY +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + ✅ Passed: 18 + ❌ Failed: 0 + ⚠️ Warnings: 1 + + 🎉 ALL CLEAR — Your OpenClaw setup is secure! +``` + +### Step 6.3: Fix Any Issues + +If the script reports failures: + +1. Read each **RECOMMENDATION** in the output +2. Fix them in order (critical items first) +3. **Re-run the script** until all checks pass + +```bash +# Fix → re-run loop +bash validate-security.sh +# Fix issues... +bash validate-security.sh +# Repeat until all green +``` + +### Step 6.4: Run OpenClaw Doctor + +```bash +openclaw doctor +# This runs OpenClaw's built-in health check +# Fix any issues it reports +``` + +--- + +## 8. Phase 7 — Daemon & Auto-Start + +### macOS (launchd) + +The onboarding wizard installs a launchd service automatically. + +```bash +# Check status +launchctl list | grep openclaw + +# If not running, load it +launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist + +# View logs +tail -f ~/.openclaw/logs/gateway.log +``` + +### Linux / WSL2 (systemd) + +```bash +# Check status +systemctl --user status openclaw-gateway + +# Enable auto-start on login +systemctl --user enable openclaw-gateway + +# Start now +systemctl --user start openclaw-gateway + +# View logs +journalctl --user -u openclaw-gateway -f + +# Restart after config changes +systemctl --user restart openclaw-gateway +``` + +### WSL2: Ensure Systemd is Enabled + +```bash +# Check +grep "systemd=true" /etc/wsl.conf + +# If missing, add it +sudo tee -a /etc/wsl.conf > /dev/null << 'EOF' +[boot] +systemd=true +EOF + +# Restart WSL (from Windows PowerShell) +wsl --shutdown +# Then reopen WSL +``` + +### Verify Daemon is Running After Reboot + +```bash +# Reboot the machine (or restart WSL) +# Then check: +systemctl --user status openclaw-gateway # Linux/WSL2 +# or +launchctl list | grep openclaw # macOS + +# Test it's responding +openclaw agent --message "Are you running?" +``` + +--- + +## 9. Post-Install Verification Checklist + +Run through this manually after completing all phases: + +| # | Check | How to Verify | Status | +| --- | ------------------------------ | --------------------------------------------- | ------ | +| 1 | OpenClaw installed | `openclaw --version` | ☐ | +| 2 | Node ≥ 22 | `node --version` | ☐ | +| 3 | Config exists | `ls ~/.openclaw/config.yaml` | ☐ | +| 4 | Bind = 127.0.0.1 | `grep bind ~/.openclaw/config.yaml` | ☐ | +| 5 | Auth = password | `grep "mode:" ~/.openclaw/config.yaml` | ☐ | +| 6 | Password ≥ 20 chars | Check config | ☐ | +| 7 | dmPolicy = pairing | `grep dmPolicy ~/.openclaw/config.yaml` | ☐ | +| 8 | system.run disabled | `grep -A2 "run:" ~/.openclaw/config.yaml` | ☐ | +| 9 | browser disabled | `grep -A2 "browser:" ~/.openclaw/config.yaml` | ☐ | +| 10 | ~/.openclaw/ perms = 700 | `stat ~/.openclaw/` | ☐ | +| 11 | config.yaml perms = 600 | `stat ~/.openclaw/config.yaml` | ☐ | +| 12 | Not running as root | `whoami` | ☐ | +| 13 | Firewall active | UFW / Windows Firewall | ☐ | +| 14 | SSH disabled | `systemctl status ssh` | ☐ | +| 15 | No port forwarding | Check router admin | ☐ | +| 16 | Tailscale = serve (not funnel) | Check config | ☐ | +| 17 | Daemon running | `systemctl --user status openclaw-gateway` | ☐ | +| 18 | Doctor passes | `openclaw doctor` | ☐ | +| 19 | validate-security.sh passes | `bash validate-security.sh` | ☐ | +| 20 | Test message works | `openclaw agent --message "Hello"` | ☐ | +| 21 | Channel connected | Send message from phone | ☐ | +| 22 | Config not in git | Verify `.openclaw/` is gitignored | ☐ | + +--- + +## 10. Maintenance & Operations + +### Daily (Automatic) + +The daemon handles these — no action needed: + +- Gateway stays running +- Channels stay connected +- Sessions managed automatically + +### Weekly + +```bash +# 1. Check for OpenClaw updates +openclaw update --channel stable + +# 2. Run doctor (handles migrations) +openclaw doctor + +# 3. Check security +bash validate-security.sh + +# 4. Prune old sessions (saves memory) +openclaw session prune --older-than 30d +``` + +### Monthly + +```bash +# 1. Update Node.js +nvm install 22 --reinstall-packages-from=current + +# 2. Update OS packages +sudo apt update && sudo apt upgrade -y # Linux/WSL2 +brew update && brew upgrade # macOS + +# 3. Rotate API keys +# Anthropic: https://console.anthropic.com/account/keys +# OpenAI: https://platform.openai.com/api-keys +# Update config.yaml with new keys → openclaw restart + +# 4. Rotate Gateway password +NEW_PASS=$(openssl rand -base64 32) +openclaw config set gateway.auth.password "$NEW_PASS" +echo "New password: $NEW_PASS" +echo "Save this somewhere secure!" +openclaw restart + +# 5. Backup config +tar czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/ +chmod 600 ~/openclaw-backup-*.tar.gz +``` + +### Updating OpenClaw + +```bash +# Check current version +openclaw --version + +# Update to latest stable +npm update -g openclaw +openclaw update --channel stable + +# Run doctor after update (handles any migrations) +openclaw doctor + +# Restart daemon +systemctl --user restart openclaw-gateway # Linux/WSL2 +# or +launchctl stop com.openclaw.gateway && launchctl start com.openclaw.gateway # macOS +``` + +--- + +## 11. Emergency Procedures + +### Kill Everything Immediately + +```bash +# Stop the daemon +systemctl --user stop openclaw-gateway # Linux/WSL2 +launchctl stop com.openclaw.gateway # macOS + +# Kill any lingering processes +pkill -f "openclaw" || true +pkill -f "node.*openclaw" || true + +# Verify nothing is running +pgrep -a openclaw +# Should return nothing +``` + +### Someone Unauthorized Accessed Your Bot + +```bash +# 1. STOP the gateway immediately +systemctl --user stop openclaw-gateway + +# 2. Check who was approved +# Review pairing history in logs: +journalctl --user -u openclaw-gateway | grep "pairing\|approved\|authorized" + +# 3. Revoke all sessions +openclaw session list +openclaw session delete --all + +# 4. Rotate API keys at provider websites +# Anthropic: https://console.anthropic.com/account/keys → revoke old, create new +# OpenAI: https://platform.openai.com/api-keys → revoke old, create new + +# 5. Change Gateway password +NEW_PASS=$(openssl rand -base64 32) +openclaw config set gateway.auth.password "$NEW_PASS" + +# 6. Re-pair WhatsApp (new session) +rm -rf ~/.openclaw/whatsapp/ +openclaw channel whatsapp pair + +# 7. Restart with fresh state +openclaw restart + +# 8. Re-run security validation +bash validate-security.sh +``` + +### WhatsApp Session Compromised + +```bash +# 1. Unlink on your phone first: +# WhatsApp → Settings → Linked Devices → Tap the session → Log Out + +# 2. Delete local session +rm -rf ~/.openclaw/whatsapp/ + +# 3. Re-pair +openclaw channel whatsapp pair +``` + +### Gateway Keeps Crashing + +```bash +# 1. Check logs for errors +journalctl --user -u openclaw-gateway --since "1 hour ago" | tail -100 + +# 2. Run doctor +openclaw doctor + +# 3. Try starting manually with verbose logging +openclaw gateway --verbose + +# 4. Common fixes: +# Port conflict: +lsof -i :18789 +# Kill conflicting process, or change port in config + +# Node version issue: +node --version # Must be ≥ 22 + +# Corrupted config: +openclaw config validate + +# Nuclear option — re-onboard: +openclaw onboard +``` + +### Restore from Backup + +```bash +# 1. Stop gateway +systemctl --user stop openclaw-gateway + +# 2. Restore backup +tar xzf ~/openclaw-backup-YYYYMMDD.tar.gz -C ~/ + +# 3. Fix permissions (backup may not preserve them) +chmod 700 ~/.openclaw +chmod 600 ~/.openclaw/config.yaml + +# 4. Restart +systemctl --user start openclaw-gateway + +# 5. Verify +openclaw doctor +``` + +--- + +## Quick Reference Card + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ OpenClaw Quick Reference │ +│ │ +│ INSTALL │ +│ npm install -g openclaw@latest │ +│ openclaw onboard --install-daemon │ +│ │ +│ DAILY USE │ +│ openclaw agent --message "..." Talk to the assistant │ +│ openclaw session list View active sessions │ +│ openclaw pairing approve Approve a new sender │ +│ │ +│ MAINTENANCE │ +│ openclaw doctor Health check │ +│ openclaw restart Restart after config change │ +│ openclaw update --channel stable Update OpenClaw │ +│ bash validate-security.sh Security audit │ +│ │ +│ EMERGENCY │ +│ systemctl --user stop openclaw-gateway Stop immediately │ +│ openclaw session delete --all Revoke all sessions │ +│ rm -rf ~/.openclaw/whatsapp/ Reset WhatsApp │ +│ │ +│ KEY FILES │ +│ ~/.openclaw/config.yaml Main config (chmod 600) │ +│ ~/.openclaw/whatsapp/ WhatsApp session (chmod 700) │ +│ ~/.openclaw/logs/ Gateway logs │ +│ │ +│ PORTS │ +│ 18789 Gateway WebSocket + WebChat + Control UI │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ +```