Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC
This commit is contained in:
Gitea Mirror Bot
345
docs/infrastructure/openclaw-installation-guide.md
Normal file
345
docs/infrastructure/openclaw-installation-guide.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 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/
|
||||
Reference in New Issue
Block a user