Linux

How to install OpenClaw on a Linux VPS

By ColossusCloud's Team February 16, 2026

What is OpenClaw?

OpenClaw is an open-source, self-hosted AI assistant that connects to messaging platforms like WhatsApp, Telegram, Discord, Slack, Signal, and many others. Unlike cloud-based AI assistants, OpenClaw runs on your own server, giving you full control over your data and conversations.

OpenClaw can manage calendars, read and draft emails, automate browser tasks, run scheduled jobs, and interact with over 50 integrations. It supports multiple AI providers including Claude, GPT-4, Gemini, and local models through Ollama. Because it is self-hosted, you only pay for the API calls to your chosen AI provider.

Running OpenClaw on a VPS is ideal for keeping it online 24/7, so your AI assistant is always reachable through your messaging apps regardless of whether your personal computer is on.

Prerequisites

Before you start, you will need:

  • A Linux VPS running Ubuntu 22.04 or 24.04 LTS with at least 4GB RAM
  • SSH access with root or sudo privileges
  • Basic familiarity with the Linux command line
  • An API key from at least one AI provider (OpenAI, Anthropic, Google, etc.)

OpenClaw’s resource usage depends on how many messaging channels and automations you run:

  • 2GB RAM, 1 vCPU — bare minimum for light testing with a single channel
  • 4GB RAM, 2 vCPUs — recommended for daily use with multiple channels and tool-heavy workflows
  • 8GB+ RAM, 4 vCPUs — comfortable for browser automation, multiple parallel agents, and heavy usage

You can deploy a VPS in any of our six data center locations and scale resources up later if needed.

Step 1: Update the system

Connect to your VPS over SSH and make sure everything is up to date:

sudo apt update && sudo apt upgrade -y

Step 2: Install Docker and Docker Compose

OpenClaw’s recommended deployment method is Docker. Install Docker Engine and the Compose plugin:

sudo apt install -y ca-certificates curl gnupg
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

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

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group so you can run Docker commands without sudo:

sudo usermod -aG docker $USER

Log out and back in (or run newgrp docker) for the group change to take effect. Then verify Docker is working:

docker --version
docker compose version

Step 3: Clone the OpenClaw repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Step 4: Run the setup script

OpenClaw includes a setup script that handles the initial configuration, builds the Docker image, and starts the gateway:

./docker-setup.sh

This script will:

  1. Generate a gateway token and save it to .env
  2. Build the OpenClaw Docker image
  3. Run the onboarding wizard (which walks you through AI provider setup)
  4. Start the gateway via Docker Compose

During the onboarding wizard, you will be asked to select your AI provider and enter your API key. Have your API key ready from whichever provider you chose (OpenAI, Anthropic, Google, etc.).

Once setup completes, the script prints the URL for the Control UI, which defaults to:

http://YOUR_VPS_IP:18789/

Step 5: Access the Control UI

Open a web browser and navigate to http://YOUR_VPS_IP:18789/. You will need the gateway token that was generated during setup to log in. If you need to retrieve the token or the dashboard URL again, run:

docker compose run --rm openclaw-cli dashboard --no-open

From the Control UI you can configure AI models, manage channels, review conversation history, and adjust settings.

Step 6: Connect a messaging channel

OpenClaw supports WhatsApp, Telegram, Discord, and many other messaging platforms. Here are setup commands for the most popular ones.

WhatsApp

docker compose run --rm openclaw-cli channels login

This generates a QR code in your terminal. Scan it with the WhatsApp app on your phone to link the channel.

Telegram

First, create a bot through BotFather on Telegram and copy the bot token. Then run:

docker compose run --rm openclaw-cli channels add --channel telegram --token "YOUR_BOT_TOKEN"

Discord

Create a bot in the Discord Developer Portal, copy the bot token, and run:

docker compose run --rm openclaw-cli channels add --channel discord --token "YOUR_BOT_TOKEN"

After adding a channel, restart the gateway to pick up the new configuration:

docker compose restart openclaw-gateway

Step 7: Verify everything is running

Check that the OpenClaw gateway container is healthy:

docker compose ps

You should see the openclaw-gateway container listed with a status of Up. You can also run the built-in health check:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Send a test message through whichever messaging channel you connected. If OpenClaw responds, your setup is complete.

Step 8: Secure your instance

This step is not optional. An unsecured OpenClaw instance exposes your AI provider API keys, your private conversations, and your connected messaging accounts to anyone who can reach your server. Anyone with access to the Control UI or the gateway port could send messages through your WhatsApp, Telegram, or Discord accounts and run up charges on your AI provider.

Set up a firewall with UFW

By default, your VPS may have all ports open. Use UFW (Uncomplicated Firewall) to restrict access to only the ports you actually need:

sudo apt install -y ufw

Allow SSH so you do not lock yourself out, then enable the firewall:

sudo ufw allow OpenSSH
sudo ufw enable

If you plan to use a reverse proxy with Nginx (recommended, covered below), allow HTTP and HTTPS traffic:

sudo ufw allow 'Nginx Full'

Do not open port 18789 in the firewall. The Control UI should only be reachable through the Nginx reverse proxy, not directly from the internet. Verify your rules:

sudo ufw status

You should see SSH and Nginx listed, but not port 18789.

Bind the gateway to localhost

By default the OpenClaw gateway binds to 0.0.0.0, which means it accepts connections from any IP address. Even with a firewall, it is safer to bind the gateway to 127.0.0.1 so it only listens for local connections. Open docker-compose.yml in the OpenClaw directory and change the ports mapping from:

ports:
  - "18789:18789"

to:

ports:
  - "127.0.0.1:18789:18789"

Then restart the gateway:

docker compose down
docker compose up -d openclaw-gateway

After this change, the Control UI will only be reachable from the server itself (or through a reverse proxy running on the same server).

Put the Control UI behind Nginx with HTTPS

With the gateway bound to localhost, set up Nginx as a reverse proxy with TLS encryption. Install Nginx and Certbot:

sudo apt install -y nginx certbot python3-certbot-nginx

Create an Nginx configuration file:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Save it to /etc/nginx/sites-available/openclaw, enable it, and obtain a TLS certificate:

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d your-domain.com

The Control UI is now available over HTTPS at https://your-domain.com. All traffic between your browser and the server is encrypted.

If you do not have a domain name, you can alternatively use an SSH tunnel to access the Control UI from your local machine without exposing the port at all:

ssh -L 18789:127.0.0.1:18789 your-user@your-vps-ip

Then open http://127.0.0.1:18789/ in your local browser. The connection travels through the encrypted SSH tunnel and the port is never exposed to the internet.

Protect your gateway token

The gateway token generated during setup is the key to your OpenClaw instance. Anyone who has this token can access the Control UI, read your conversations, change settings, and send messages through your connected accounts. Treat it like a password:

  • Do not share the token publicly or commit it to a Git repository
  • The token is stored in the .env file in the OpenClaw directory. Make sure this file is only readable by your user:
chmod 600 ~/openclaw/.env

Manage approved devices

OpenClaw tracks which browser sessions (devices) are authorized to use the Control UI. Periodically review the list and remove any you do not recognize:

docker compose run --rm openclaw-cli devices list

To remove a device:

docker compose run --rm openclaw-cli devices remove DEVICE_ID

Keep your API keys safe

Your AI provider API keys are stored in the OpenClaw configuration directory (~/.openclaw/). Make sure this directory is only accessible to your user:

chmod 700 ~/.openclaw

If you suspect a key has been compromised, rotate it immediately through your AI provider’s dashboard and update the key in OpenClaw’s settings.

Keeping OpenClaw running

Because you deployed with Docker Compose, the gateway container will restart automatically if it crashes or if your VPS reboots (Docker’s default restart policy handles this). To make sure Docker itself starts on boot:

sudo systemctl enable docker

Updating OpenClaw

OpenClaw is actively developed and new versions are released frequently. To update:

cd ~/openclaw
git pull
docker compose down
./docker-setup.sh

This pulls the latest code, rebuilds the image, and restarts the gateway with your existing configuration intact (stored in ~/.openclaw/).

Optional: install the shell helpers

For easier day-to-day management, install the ClawDock shell helpers:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.bashrc && source ~/.bashrc

This gives you convenient commands like clawdock-start, clawdock-stop, and clawdock-dashboard. Run clawdock-help to see all available commands.

Troubleshooting

Permission errors on ~/.openclaw/: The OpenClaw container runs as user node (UID 1000). If you see EACCES errors, fix ownership:

sudo chown -R 1000:1000 ~/.openclaw

Container not starting: Check the logs for errors:

docker compose logs openclaw-gateway

“Unauthorized” or “disconnected” in the Control UI: Fetch a fresh dashboard link and approve the device:

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve DEVICE_ID

High memory usage: OpenClaw uses roughly 200-400MB at idle. If you are running browser automation or multiple agents, consider scaling your VPS to 8GB RAM or more. You can resize your VPS through the Client Portal without losing data.

Next steps

With OpenClaw running on your VPS, you can explore:

  • Adding more messaging channels (Signal, Slack, iMessage, Microsoft Teams, and others)
  • Configuring scheduled tasks with cron jobs and webhooks
  • Setting up browser automation for web scraping and form filling
  • Enabling persistent memory so your assistant learns your preferences over time
  • Running local AI models with Ollama for fully private inference

Check the OpenClaw documentation for the full list of features and configuration options.

← Back to all how-to guides