🦞OpenClaw Guide
Hosting

Hosting OpenClaw on a VPS — Complete Guide

Step-by-step guide to running OpenClaw on a VPS including setup, optimization, SSH configuration, troubleshooting disconnects, and best practices for Hetzner, DigitalOcean, Contabo, and Google Cloud.

⚠️ The Problem

Users face multiple challenges hosting OpenClaw on VPS: WebSocket disconnects (error 1006), SSH connection issues between local OpenClaw and remote VPS, gateway token configuration confusion, incomplete setup on Raspberry Pi, skills not loading on Linux, and confusion about the web dashboard. Common errors include 'disconnected (1006): no reason', 'command not found' after interrupted setup, 'Config path not found: autonomy', and difficulty getting the gateway dashboard accessible.

🔍 Why This Happens

Root causes include: (1) Gateway not running or token mismatch between config and environment. (2) Cloud provider IPs (especially Hetzner) getting rate-limited by Discord. (3) Interrupted setup leaving incomplete configuration (no ~/.config/clawdbot directory). (4) SSH keys not properly configured for remote VPS access. (5) Confusion between gateway.token and gateway.auth.token config paths. (6) Resource constraints on minimal VPS instances. (7) ClawdHub CLI not available on Linux VPS without manual setup. (8) Raspberry Pi requiring arm64-compatible models.

✅ The Fix

VPS Requirements & Recommendations

Minimum specs:

  • 1 vCPU, 1GB RAM, 500MB disk

Recommended:

  • 2GB RAM (for logs, media processing, multiple channels)
  • Ubuntu LTS (most tested platform)

Best practices:

  • Run Gateway 24/7 — cron jobs won't fire if it sleeps
  • Back up workspace (~/clawd) to a private git repo
  • Keep state separate: ~/.clawdbot for config, ~/clawd for workspace

Initial VPS Setup

bash
# 1. Install Node.js 22+ (recommended method)curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs# 2. Install OpenClawcurl -fsSL https://clawd.bot/install.sh | bash# 3. Run initial configurationclawdbot configure# 4. Start the gatewayclawdbot gateway start

Fixing Interrupted Setup (RPi / VPS)

If setup was cancelled or interrupted and you get 'command not found':

bash
# Create config directory if missingmkdir -p ~/.config/clawdbot# Re-run configuration wizardclawdbot configure# If clawdbot command not found, reinstallcurl -fsSL https://clawd.bot/install.sh | bash

For Raspberry Pi specifically:

  • Ensure you're using arm64-compatible models if running local LLMs
  • Cloud API models (OpenAI, Anthropic, OpenRouter) work on all architectures

Fixing WebSocket Disconnect (1006) on Hetzner/Cloud VPS

bash
# 1. Check if gateway is runningclawdbot gateway status# 2. If not running, start itclawdbot gateway start# 3. Check logs for detailsclawdbot gateway logs

Common causes on cloud VPS:

  • Gateway process not running
  • Token mismatch between config and environment
  • Discord rate-limiting cloud IPs (try VPN temporarily)
  • Resource exhaustion
bash
# Check resourcesfree -hdf -h# Restart gatewayclawdbot gateway restart

Gateway Token Configuration

Important: The dashboard uses gateway.auth.token, NOT gateway.token.

bash
# Check current tokenclawdbot config get gateway.auth.token# Set a token if emptyclawdbot config set gateway.auth.token "your-secure-random-token"# Or use environment variableexport CLAWDBOT_GATEWAY_TOKEN="your-token-here"# Restart after changesclawdbot gateway restart

Token location summary:

  • ❌ gateway.token — ignored
  • ✅ gateway.auth.token — used by dashboard
  • ✅ CLAWDBOT_GATEWAY_TOKEN env var — also works

Connecting Local OpenClaw to Remote VPS via SSH

To have OpenClaw on your local machine control a remote VPS:

bash
# 1. Generate SSH key if you don't have onessh-keygen -t ed25519 -C "openclaw-vps"# 2. Copy public key to VPSssh-copy-id user@your-vps-ip# 3. Test connection manually firstssh user@your-vps-ip# 4. Configure OpenClaw to use SSH# Add to your TOOLS.md or workspace config:# SSH: user@your-vps-ip for web server management

For Contabo/DigitalOcean/Hetzner:

  • Ensure SSH is enabled in your VPS control panel
  • Check firewall allows port 22
  • Use key-based auth (more reliable than passwords)

Installing Skills on Linux VPS

ClawdHub UI isn't available on headless Linux. Use CLI:

bash
# Install ClawdHub CLInpm i -g clawdhub# orpnpm add -g clawdhub# Search for skillsclawdhub search "web search"# Install a skillclawdhub install skill-slug# Update all skillsclawdhub update --all

If ClawdHub isn't working, install manually:

bash
# Create skills foldermkdir -p ~/clawd/skills# Clone skills repositorygit clone https://github.com/clawdbot/clawdbot.git ~/clawd-skillscp -r ~/clawd-skills/skills/* ~/clawd/skills/# Configure workspace skills directoryclawdbot config set skills.dir ~/clawd/skills# Restart to loadclawdbot gateway restart

Accessing the Gateway Dashboard

The web dashboard shows gateway status and connected clients.

bash
# Get dashboard URLclawdbot gateway status# Default: http://localhost:3333 (or configured port)# For remote access, use SSH tunnel:ssh -L 3333:localhost:3333 user@your-vps-ip# Then access http://localhost:3333 in your browser

For public access (not recommended without auth):

  • Set up nginx/caddy reverse proxy
  • Add SSL certificate (Let's Encrypt)
  • Configure gateway.auth.token for protection

Uninstalling OpenClaw on Linux

The docs may be missing this command:

bash
# For openclaw packagenpm uninstall -g openclaw# For clawdbot packagenpm uninstall -g clawdbot# orpnpm remove -g clawdbot# Remove config and datarm -rf ~/.clawdbotrm -rf ~/.config/clawdbot

Running Gateway as a Service (Systemd)

For production VPS, run as a systemd service:

bash
# Create service filesudo nano /etc/systemd/system/clawdbot.service
ini
[Unit]Description=Clawdbot GatewayAfter=network.target[Service]Type=simpleUser=your-usernameWorkingDirectory=/home/your-usernameExecStart=/usr/bin/clawdbot gateway start --foregroundRestart=alwaysRestartSec=10Environment=NODE_ENV=production[Install]WantedBy=multi-user.target
bash
# Enable and start servicesudo systemctl daemon-reloadsudo systemctl enable clawdbotsudo systemctl start clawdbot# Check statussudo systemctl status clawdbot# View logsjournalctl -u clawdbot -f

Discord Moderation on VPS

OpenClaw has basic moderation capabilities:

Supported:

  • ✅ React to messages, pin/unpin
  • ✅ Search message history, create threads
  • ✅ Manage channels, roles, categories
  • ✅ Kick/ban users via API

Not built-in:

  • ❌ Auto-moderation (spam detection)
  • ❌ Automated warnings/mutes
  • ❌ Anti-raid protection
  • ❌ Custom mod logs

For full moderation, integrate dedicated bots alongside OpenClaw.

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
clawdbot gateway startStart the gateway daemon
clawdbot gateway statusCheck gateway status and dashboard URL
clawdbot gateway logsView gateway logs for debugging
clawdbot gateway restartRestart gateway (fixes many issues)
clawdbot configureRun setup wizard (use after interrupted install)
clawdbot config set gateway.auth.token TOKENSet dashboard authentication token
clawdbot config get gateway.auth.tokenCheck current gateway token
npm uninstall -g openclawUninstall openclaw package (legacy)
npm uninstall -g clawdbotUninstall clawdbot package
ssh-copy-id user@vps-ipCopy SSH key to VPS for passwordless access
clawdhub search QUERYSearch for skills (Linux CLI)
clawdhub install SKILLInstall a skill on Linux VPS
sudo systemctl status clawdbotCheck systemd service status

Related Issues

    📚 You Might Also Like

    Blog

    VPS vs Mac Mini vs Raspberry Pi: Where Should You Run OpenClaw?

    The answer isn't \\"whichever is cheapest.\\" Each hosting option has a different threat profile, different failure modes, and different security implications.

    Guide

    How to Set Up OpenClaw on Mac Mini (Perfect Always-On Setup)

    The ideal dedicated AI assistant setup. Buy once, runs forever, no monthly fees for hosting.

    Comparison

    Hetzner vs DigitalOcean

    Which cloud VPS is right for your project?

    Integration

    Discord

    Add your AI assistant to Discord servers and DMs. Get help, manage tasks, and run automations directly from your Discord channels.

    🐙 Your AI should run your business.

    Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

    Join Vibe Combinator →