homelab-optimized/docs/infrastructure/openclaw-installation-guide.md

# OpenClaw AI Assistant Installation Guide

## Overview

OpenClaw is a powerful AI assistant tool that provides a WebSocket gateway for AI interactions with support for multiple channels (Discord, Slack, etc.) and advanced features like browser control, voice commands, and device pairing.

**Installation Date:** February 16, 2026  
**OpenClaw Version:** 2026.2.15 (dc9808a)  
**Host:** seattle (100.82.197.124)  
**Installation Location:** `/root/openclaw`

## 🚀 Quick Access

- **Tailscale HTTPS URL:** https://seattle.tail.vish.gg/
- **Local Access:** http://127.0.0.1:18789/
- **WebSocket:** wss://seattle.tail.vish.gg (via Tailscale)

## 📋 Prerequisites

### System Requirements
- **Node.js:** v22+ (installed v22.22.0)
- **Package Manager:** pnpm (installed globally)
- **Operating System:** Linux (Ubuntu/Debian)
- **Network:** Tailscale for secure remote access

### Dependencies Installed
- Node.js upgraded from v20.20.0 to v22.22.0
- pnpm package manager
- 1003+ npm packages for OpenClaw functionality

## 🔧 Installation Steps

### 1. System Preparation
```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js v22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm globally
npm install -g pnpm

# Verify versions
node --version  # Should be v22.22.0+
pnpm --version
```

### 2. Clone and Build OpenClaw
```bash
# Clone the repository
cd /root
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build the project
pnpm build
```

### 3. Initial Setup
```bash
# Run setup command to create configuration
pnpm openclaw setup

# This creates configuration files in ~/.openclaw/
```

### 4. Network Configuration

#### UFW Firewall Rules
```bash
# Allow OpenClaw access from Tailscale network
sudo ufw allow from 100.64.0.0/10 to any port 18789 comment "OpenClaw - Tailscale only"

# Verify rule was added
sudo ufw status verbose
```

#### Tailscale Configuration
```bash
# Verify Tailscale is running
tailscale status

# Get this machine's Tailscale IP
tailscale ip -4
```

## 🚀 Running OpenClaw

### Production Mode (Recommended)
```bash
cd /root/openclaw

# Start with Tailscale serve for HTTPS access
pnpm openclaw gateway --port 18789 --bind loopback --tailscale serve --verbose --allow-unconfigured &
```

### Development Mode
```bash
# Start in foreground for debugging
pnpm openclaw gateway --port 18789 --bind loopback --verbose --allow-unconfigured
```

### Service Management
```bash
# Check status
pnpm openclaw status

# View logs
pnpm openclaw logs --follow

# Stop gateway
kill %1  # If running in background
```

## 🌐 Access Methods

### 1. Tailscale HTTPS (Recommended)
- **URL:** https://seattle.tail.vish.gg/
- **Features:** Full WebSocket support, secure HTTPS
- **Requirements:** Must be connected to the same Tailscale network
- **First-time setup:** Requires device pairing (see Device Pairing section below)

### 2. Local Access
- **URL:** http://127.0.0.1:18789/
- **Features:** Full functionality when accessed locally
- **Limitations:** Only accessible from the host machine

### 3. Direct IP Access
- **URL:** http://100.82.197.124:18789/
- **Features:** Basic HTTP interface
- **Limitations:** WebSocket connections require HTTPS (use Tailscale instead)

## 🔗 Device Pairing

OpenClaw requires device pairing for security. When you first visit the web interface, you'll see "disconnected (1008): pairing required".

### Pairing Process

1. **Visit the web interface** from your device (triggers pairing request)
2. **On the server, list pending requests:**
   ```bash
   cd /root/openclaw
   pnpm openclaw devices list
   ```

3. **Approve the pairing request:**
   ```bash
   pnpm openclaw devices approve <request-id>
   ```

4. **Refresh your browser** - the interface should now work

### Device Management Commands
```bash
# List all devices (pending and paired)
pnpm openclaw devices list

# Approve a pending device
pnpm openclaw devices approve <request-id>

# Reject a pending device
pnpm openclaw devices reject <request-id>

# Revoke access for a paired device
pnpm openclaw devices revoke <device-id> <role>
```

## ⚙️ Configuration

### Configuration Files Location
```
~/.openclaw/
├── config.json          # Main configuration
├── credentials.json     # API keys and tokens
└── sessions/           # Session data
```

### Key Configuration Options
```json
{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789
  },
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "context": "200k"
  }
}
```

## 🔐 Security Considerations

### Firewall Configuration
- Port 18789 is restricted to Tailscale network (100.64.0.0/10)
- No public internet access to OpenClaw gateway
- HTTPS enforced for WebSocket connections

### Authentication
- Control UI requires HTTPS or localhost access
- Tailscale provides secure tunnel with automatic certificates
- No additional authentication configured (uses --allow-unconfigured)

### Network Security
- Tailscale serve mode provides automatic HTTPS certificates
- All traffic encrypted via Tailscale's WireGuard protocol
- Access limited to authorized Tailscale devices

## 🛠️ Troubleshooting

### Common Issues

#### 1. Device Pairing Required
**Symptom:** "disconnected (1008): pairing required"
**Solution:** 
1. Visit the web interface to trigger pairing request
2. Run `pnpm openclaw devices list` on the server
3. Approve the request with `pnpm openclaw devices approve <request-id>`
4. Refresh your browser

#### 2. WebSocket Connection Failures
**Symptom:** "control ui requires HTTPS or localhost (secure context)"
**Solution:** Use Tailscale HTTPS URL instead of direct IP access

#### 3. Port Already in Use
```bash
# Kill existing process
pnpm openclaw gateway --force --port 18789

# Or find and kill manually
lsof -ti:18789 | xargs kill -9
```

#### 3. Node.js Version Issues
```bash
# Verify Node.js version
node --version

# Should be v22.22.0 or higher
# If not, reinstall Node.js v22
```

#### 4. Tailscale Serve Not Working
```bash
# Check Tailscale status
tailscale status

# Restart Tailscale if needed
sudo systemctl restart tailscaled

# Verify serve configuration
tailscale serve status
```

### Log Files
```bash
# OpenClaw logs
tail -f /tmp/openclaw/openclaw-2026-02-16.log

# System logs
journalctl -u tailscaled -f
```

## 📊 System Status

### Current Configuration
- **Host:** seattle.tail.vish.gg
- **Tailscale IP:** 100.82.197.124
- **Gateway Port:** 18789
- **Bind Mode:** loopback (with Tailscale serve)
- **Agent Model:** anthropic/claude-opus-4-6
- **Context Window:** 200k tokens

### Installed Features
- Device pairing (`/pair` command)
- Phone control (`/phone` command)
- Voice commands (`/voice` command)
- Browser control service
- Canvas hosting
- Bonjour discovery

### Network Status
- UFW firewall: Active with Tailscale rules
- Tailscale: Connected and serving HTTPS
- Gateway: Running in background
- WebSocket: Available via wss://seattle.tail.vish.gg

## 🔄 Maintenance

### Regular Tasks
```bash
# Update OpenClaw
cd /root/openclaw
git pull
pnpm install
pnpm build

# Restart gateway
kill %1
pnpm openclaw gateway --port 18789 --bind loopback --tailscale serve --verbose --allow-unconfigured &
```

### Backup Configuration
```bash
# Backup configuration
tar -czf openclaw-config-$(date +%Y%m%d).tar.gz ~/.openclaw/

# Backup installation
tar -czf openclaw-install-$(date +%Y%m%d).tar.gz /root/openclaw/
```

### Security Audit
```bash
# Run security audit
pnpm openclaw security audit --deep

# Check for updates
pnpm openclaw update check
```

## 📚 Additional Resources

- **OpenClaw Documentation:** https://docs.openclaw.ai/
- **CLI Reference:** https://docs.openclaw.ai/cli/gateway
- **Tailscale Documentation:** https://tailscale.com/kb/
- **GitHub Repository:** https://github.com/openclaw/openclaw

## 🎯 Next Steps

1. **Configure API Keys:** Add your AI model API keys to `~/.openclaw/credentials.json`
2. **Set Up Channels:** Configure Discord, Slack, or other communication channels
3. **Customize Settings:** Modify `~/.openclaw/config.json` for your needs
4. **Security Review:** Run `pnpm openclaw security audit --deep`
5. **Monitoring:** Set up log monitoring and alerting

---

**Installation completed successfully on February 16, 2026**  
**OpenClaw is now accessible at:** https://seattle.tail.vish.gg/