Get in touch

How to install OpenClaw on a VPS

How to Install OpenClaw on a VPS — Complete Step-by-Step Guide (2026) 🛠️ Installation Guide How to Install OpenClaw on a VPS A complete step-by-step walkthrough from a fresh Ubuntu…

How to Install OpenClaw on a VPS — Complete Step-by-Step Guide (2026)
🛠️ Installation Guide

How to Install OpenClaw on a VPS

A complete step-by-step walkthrough from a fresh Ubuntu 22.04 server to a running OpenClaw agent connected to your messaging apps.

🐧 Ubuntu 22.04 LTS
🐳 Docker + Docker Compose
⏱ ~30 minutes

Steps in This Guide

00Prerequisites & Requirements 01Connect to Your VPS via SSH 02Update System & Install Docker 03Deploy OpenClaw with Docker Compose 04Configure Environment Variables 05Start OpenClaw & Run Onboarding 06Connect Your Messaging Channels 07Verify & Test Your Agent 08Post-Install Security Checklist
Step 00

Prerequisites & Requirements

Gather everything you need before starting — this saves time mid-install.

🖥️

VPS with Ubuntu 22.04

Min 4 GB RAM, 40 GB NVMe SSD, root access

🔑

AI Provider API Key

Anthropic, OpenAI, or Google — have it ready

💬

Messaging App Account

Telegram Bot token is easiest to start with

💻

SSH Client

Terminal on Mac/Linux, PuTTY or Windows Terminal on PC

New to VPS Hosting?

If you haven’t chosen a hosting provider yet, read our VPS comparison guide first. For the most beginner-friendly experience, Hostinger’s 1-click OpenClaw setup skips most of this guide entirely.

Step 01

Connect to Your VPS via SSH

Your hosting provider will email you an IP address, username (usually root), and password after provisioning. Use those to connect.

Mac / Linux Terminal SSH command

$ ssh root@YOUR_SERVER_IP

Replace YOUR_SERVER_IP with the IP address from your hosting provider’s email. Accept the fingerprint prompt by typing yes.

Windows Using Windows Terminal or PowerShell

PS> ssh root@YOUR_SERVER_IP
SSH Key Authentication (Recommended)

Once logged in, consider switching from password to SSH key authentication — it’s more secure and eliminates the risk of brute-force attacks. See our security guide for the exact commands.

Create a non-root user (best practice)

Running OpenClaw as root is not recommended. Create a dedicated user:

# Create a new user named ‘openclaw’ $ adduser openclaw $ usermod -aG sudo openclaw $ usermod -aG docker openclaw # Switch to the new user $ su – openclaw
Step 02

Update System & Install Docker

Always start with a fully updated system. Then install Docker Engine — the container runtime OpenClaw requires.

Update packages

$ sudo apt update && sudo apt upgrade -y

Install Docker Engine (official method)

# Install prerequisites $ sudo apt install -y ca-certificates curl gnupg # Add Docker’s official GPG key $ sudo install -m 0755 -d /etc/apt/keyrings $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /etc/apt/keyrings/docker.gpg $ sudo chmod a+r /etc/apt/keyrings/docker.gpg # Set up the repository $ echo “deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo “$VERSION_CODENAME”) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # Install Docker Engine and Docker Compose $ sudo apt update $ sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker is running

$ sudo docker run hello-world # You should see: “Hello from Docker!”

Add your user to the docker group (avoids needing sudo)

$ sudo usermod -aG docker $USER $ newgrp docker
Don’t Use the Snap Package

Ubuntu may suggest installing Docker via snap. Avoid this — use the official Docker repository as shown above. The snap version can have compatibility issues with OpenClaw’s Docker Compose configuration.

Step 03

Deploy OpenClaw with Docker Compose

Create the OpenClaw directory structure and Docker Compose configuration.

Create the OpenClaw directory and navigate to it

$ mkdir -p ~/openclaw $ cd ~/openclaw

Create the Docker Compose file

~/openclaw/docker-compose.yml
$ cat > docker-compose.yml << 'EOF' version: ‘3.8’ services: openclaw: image: openclaw/gateway:latest container_name: openclaw restart: unless-stopped ports: – “127.0.0.1:3000:3000” volumes: – ./data:/app/data env_file: – .env environment: – NODE_ENV=production EOF
Port Binding Note

The port is bound to 127.0.0.1:3000 (localhost only). This means the OpenClaw Control UI is not publicly accessible by default — you access it via SSH tunnel. This is the correct security posture. Do not change this to 0.0.0.0 without adding authentication first.

Pull the latest OpenClaw image

$ docker compose pull # This downloads the latest OpenClaw Docker image (may take 1–2 minutes)
Step 04

Configure Environment Variables

The .env file is where you store your API keys and configuration. Treat this file like a password — never share it or commit it to version control.

Create the .env file

$ nano .env

Minimum required configuration

~/openclaw/.env
# ─── Required ──────────────────────────────────────── # Port the Gateway listens on PORT=3000 # Secure password to access the setup wizard (choose a strong one) SETUP_PASSWORD=choose-a-strong-password-here # Where OpenClaw stores state and workspace data OPENCLAW_STATE_DIR=/app/data/.openclaw OPENCLAW_WORKSPACE_DIR=/app/data/workspace # ─── AI Provider (add the one you’re using) ────────── # For Anthropic Claude: ANTHROPIC_API_KEY=sk-ant-your-key-here # For OpenAI GPT: # OPENAI_API_KEY=sk-your-key-here # For Google Gemini: # GOOGLE_API_KEY=your-key-here
Protect This File

Set restrictive permissions on your .env file immediately after creating it:

$ chmod 600 .env
Where to Get API Keys

Anthropic: console.anthropic.com → API Keys  |  OpenAI: platform.openai.com → API Keys  |  Google: aistudio.google.com → Get API Key. Set a spending limit before deploying.

Step 05

Start OpenClaw & Run the Onboarding Wizard

Launch the OpenClaw container and connect to the onboarding interface.

Start the container

$ docker compose up -d # -d runs it in detached mode (background)

Verify it’s running

$ docker ps # You should see the ‘openclaw’ container with status ‘Up’ $ docker logs openclaw # Should show startup messages without errors

Access the Control UI via SSH tunnel

On your local machine (not on the server), open a new terminal and run:

# Run this on your local machine local $ ssh -L 3000:localhost:3000 root@YOUR_SERVER_IP

Now open http://localhost:3000 in your browser. You should see the OpenClaw setup wizard.

Onboarding Wizard

The wizard will guide you through: confirming you understand OpenClaw’s capabilities and risks, choosing your AI provider and model, setting a gateway token for security, and running a first test conversation. Complete all steps before moving on.

Enable auto-start on server reboot

The restart: unless-stopped in your Compose file handles this — Docker will automatically restart OpenClaw after a server reboot as long as Docker itself starts on boot.

$ sudo systemctl enable docker
Step 06

Connect Your Messaging Channels

Telegram is the easiest starting point. Here’s how to connect it — then your agent is reachable from your phone.

1. Create a Telegram Bot via BotFather

Open Telegram and search for @BotFather. Send /newbot, choose a name and username for your bot, and copy the API token it gives you.

2. Add the token to your .env file

# Add to your .env file TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here

3. Restart OpenClaw to apply the new configuration

$ docker compose down && docker compose up -d

4. Start a conversation with your bot

Search for your bot’s username in Telegram, tap Start, and send your first message. You should see a response within a few seconds.

WhatsApp Setup

WhatsApp requires scanning a QR code via OpenClaw’s Control UI, which links your WhatsApp account (or a dedicated number) to the gateway. See the Control UI → Channels section after completing Telegram setup first.

Step 07

Verify & Test Your Agent

Before setting up automations, confirm everything is working correctly.

  • Send “Hello” to your Telegram bot — you should get a response within 5 seconds
  • Ask it something simple: “What’s today’s date?” — tests the AI connection
  • Ask it to “summarize this URL: [any website]” — tests web browsing capability
  • Check Docker logs for any errors: docker logs openclaw --tail 50
  • Verify the container restarts after a reboot: sudo reboot, wait 2 minutes, send a message
  • Confirm your AI provider dashboard shows usage (token consumption)

Useful management commands

# View live logs $ docker logs -f openclaw # Restart OpenClaw $ docker compose restart # Update to latest version $ docker compose pull && docker compose up -d # Check resource usage $ docker stats openclaw
Step 08

Post-Install Security Checklist

Before you start using OpenClaw in production, complete these security steps. See our full security hardening guide for detailed instructions on each.

  • Set a strong, unique gateway auth token (not the default)
  • Enable SSH key authentication and disable password login
  • Enable UFW firewall: allow only ports 22, 80, 443
  • Set spending limits on your AI provider account
  • Set file permissions: chmod 600 .env
  • Never expose port 3000 directly to the internet
  • Enable automated weekly backups of your ~/openclaw/data directory
  • Schedule the update script: docker compose pull && docker compose up -d weekly

Installation Complete — What’s Next?

Secure your instance, protect against API cost overruns, and learn how to keep OpenClaw running reliably.

Security Hardening Guide → Prevent Runaway API Costs →