OpenClaw Self-Hosted Setup Guide

Complete technical documentation for deploying OpenClaw on your own infrastructure. Estimated time: 4-8 hours for experienced engineers.

⚠️ Warning: This setup requires advanced knowledge of Linux system administration, networking, Docker, reverse proxies, SSL certificates, and debugging. Proceed only if you're comfortable with terminal commands and server management. If anything goes wrong, you may need to start over from scratch.

💡 Skip the hassle: Let us handle all of this for just $99. We'll have you up and running in under 2 hours with zero technical work on your end.

Prerequisites

All items are required. Missing any will cause failures.

•Node.js ≥ 22.0.0 (not 20.x, not 18.x - must be exactly 22+)
•pnpm 8.15.0+ (npm and yarn will NOT work due to workspace dependencies)
•Ubuntu 22.04 LTS or Debian 12 (other distros may have compatibility issues)
•Minimum 4GB RAM, 2 vCPUs (will crash on smaller instances)
•Root or sudo access to the server
•Domain name with DNS access (required for SSL/WSS)
•Anthropic API key with sufficient credits ($20+ recommended)
•Cloudflare account (for DDoS protection and SSL termination)
•Redis 7.0+ (for session management and rate limiting)
•PostgreSQL 15+ (for persistent storage)
•Docker 24.0+ and Docker Compose v2
•nginx 1.24+ or Caddy 2.7+ (for reverse proxy)
•certbot (for Let's Encrypt SSL certificates)
•Python 3.11+ with pip (for build dependencies)
•build-essential, g++, make (for native module compilation)

Step 1: System Preparation & Dependencies

First, update your system and install all required dependencies. This may take 15-30 minutes.

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install build dependencies
sudo apt install -y build-essential g++ make python3 python3-pip \
  libssl-dev libffi-dev python3-dev cargo pkg-config \
  libsqlite3-dev libreadline-dev libbz2-dev libncurses5-dev \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  liblzma-dev libgdbm-dev libnss3-dev libgdbm-compat-dev

# Install Node.js 22 via nvm (DO NOT use apt nodejs)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# Verify Node version (must show v22.x.x)
node --version

# Install pnpm globally
npm install -g pnpm@latest

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose v2
sudo apt install docker-compose-plugin

# Install Redis
sudo apt install redis-server -y
sudo systemctl enable redis-server
sudo systemctl start redis-server

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib -y
sudo systemctl enable postgresql
sudo systemctl start postgresql

# Create database and user
sudo -u postgres psql -c "CREATE USER openclaw WITH PASSWORD 'your_secure_password_here';"
sudo -u postgres psql -c "CREATE DATABASE openclaw_db OWNER openclaw;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE openclaw_db TO openclaw;"

# Install nginx
sudo apt install nginx -y
sudo systemctl enable nginx

# Install certbot for SSL
sudo apt install certbot python3-certbot-nginx -y

Step 2: Clone & Configure Repository

Clone the repository and set up the complex configuration files.

# Clone the repository
git clone https://github.com/anthropics/claude-code.git /opt/openclaw
cd /opt/openclaw

# IMPORTANT: Checkout the correct branch
git checkout stable-v2.3.1

# Install dependencies (this may take 10-15 minutes)
pnpm install --frozen-lockfile

# If you get ERESOLVE errors, try:
pnpm install --frozen-lockfile --legacy-peer-deps

# Build native modules
pnpm rebuild

# Copy environment template
cp .env.example .env
cp config/default.example.yml config/default.yml
cp config/production.example.yml config/production.yml

Step 3: Environment Configuration

Configure all required environment variables. Missing or incorrect values will cause silent failures.

# Edit the .env file
nano .env

# Required environment variables (ALL must be set):
NODE_ENV=production
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_MODEL=claude-3-opus-20240229
ANTHROPIC_MAX_TOKENS=4096

# Database configuration
DATABASE_URL=postgresql://openclaw:your_secure_password_here@localhost:5432/openclaw_db
DATABASE_POOL_SIZE=10
DATABASE_SSL=false

# Redis configuration
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=
REDIS_TLS=false

# Server configuration
HOST=0.0.0.0
PORT=3000
WSS_PORT=18789
WSS_PATH=/ws
TRUST_PROXY=true

# Security settings
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
SESSION_SECRET=$(openssl rand -base64 32)
COOKIE_SECURE=true
CORS_ORIGIN=https://yourdomain.com

# Sandbox configuration
SANDBOX_MODE=non-main
SANDBOX_TIMEOUT=30000
SANDBOX_MEMORY_LIMIT=512mb
SANDBOX_CPU_LIMIT=1

# Rate limiting
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=info
LOG_FORMAT=json
LOG_FILE=/var/log/openclaw/app.log

Troubleshooting Common Issues

These are the most common issues you'll encounter.

EBADF: Bad File Descriptor

Usually caused by Node.js version mismatch or corrupted node_modules. Solution:rm -rf node_modules pnpm-lock.yaml && pnpm install

PTY Spawn Failures / ENOENT

Missing native dependencies. Run:sudo apt install python3 make g++ libsecret-1-dev

WebSocket Connection Refused

Check if WSS service is running: sudo systemctl status openclaw-wss

This looks like a lot of work...

Because it is. Skip the 4-8 hours of setup, debugging, and maintenance headaches. We'll handle everything and have you running in under 2 hours.

Let Us Set It Up for $99 →

No technical knowledge required. Just send us your API key and we handle the rest.