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