Vish/homelab-optimized

Fork 0

Files

Gitea Mirror Bot 11d496f233

Documentation / Build Docusaurus (push) Failing after 17m32s

Details

Documentation / Deploy to GitHub Pages (push) Has been skipped

Details

Sanitized mirror from private repository - 2026-04-19 08:46:29 UTC

2026-04-19 08:46:29 +00:00

8.3 KiB

Raw Blame History

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

# 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

# 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

# Run setup command to create configuration
pnpm openclaw setup

# This creates configuration files in ~/.openclaw/

4. Network Configuration

UFW Firewall Rules

# 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

# Verify Tailscale is running
tailscale status

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

🚀 Running OpenClaw

Production Mode (Recommended)

cd /root/openclaw

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

Development Mode

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

Service Management

# 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

Visit the web interface from your device (triggers pairing request)

On the server, list pending requests:

cd /root/openclaw
pnpm openclaw devices list

Approve the pairing request:

pnpm openclaw devices approve <request-id>

Refresh your browser - the interface should now work

Device Management Commands

# 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

{
  "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:

Visit the web interface to trigger pairing request
Run pnpm openclaw devices list on the server
Approve the request with pnpm openclaw devices approve <request-id>
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

# 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

# Verify Node.js version
node --version

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

4. Tailscale Serve Not Working

# Check Tailscale status
tailscale status

# Restart Tailscale if needed
sudo systemctl restart tailscaled

# Verify serve configuration
tailscale serve status

Log Files

# 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

# 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

# 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

# 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

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

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

8.3 KiB Raw Blame History