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
This commit is contained in:
saravanakumardb1
parent
5667308629
commit
bc8e7a0504
927
__LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md
Normal file
927
__LOCAL_LLMs/OPEN_CLAW/SETUP_GUIDE.md
Normal file
@ -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 <ch> <c> 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 │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user