Skip to Content

OpenClaw Docker VPS Deploy: A Developer's Step-by-Step Guide

Get OpenClaw running on your own VPS with Docker Compose, persistent storage, and production-ready security — no local install needed.

OpenClaw Docker VPS Deploy: A Developer's Step-by-Step Guide

You don't need to install Node.js, Python, or a dozen system packages to run OpenClaw. Docker handles all of it. This guide shows you exactly how to deploy OpenClaw on a VPS using Docker Compose — from a fresh server to a working AI agent gateway you can control from Telegram, Slack, or the web UI.

If you want a more detailed walkthrough of the initial setup wizard, check out How to Deploy OpenClaw on a VPS with Docker (Step-by-Step Guide). For context on why autonomous AI agents like OpenClaw are gaining traction, see our coverage of Microsoft's own OpenClaw-like agent efforts and Microsoft's Copilot agent testing for enterprise security.

What You Need Before You Start

Running OpenClaw in Docker is straightforward, but skimping on specs or skipping security steps will hurt you later.

  • VPS with 4 CPU cores and 8GB RAM minimum (4GB works for light use; 16GB recommended for multi-agent or browser automation)
  • Ubuntu 22.04/24.04 or Debian 12 — these are tested and well-supported
  • 40GB disk minimum (Docker images, container layers, and OpenClaw state add up fast)
  • Docker Engine 24.0+ and Docker Compose v2 installed
  • A domain or subdomain pointed at your VPS (strongly recommended for HTTPS)
  • API keys for at least one LLM provider (Anthropic, OpenAI, or a local endpoint via Ollama/LM Studio)

Firewall note: if you're running on a public VPS, review Docker's DOCKER-USER chain and your cloud provider's security groups before exposing any ports. OpenClaw's gateway defaults to port 18789.

1. Prepare Your VPS

Start with a clean server. Update packages, create a non-root user, and install Docker.

System updates and Docker install

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

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

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) 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

sudo usermod -aG docker $USER
newgrp docker

Verify Docker is working:

docker --version
docker compose version
docker run hello-world

Create project directory

mkdir -p ~/openclaw && cd ~/openclaw
git clone https://github.com/openclaw/openclaw.git .

2. Build or Pull the OpenClaw Image

You have two options: build locally from source, or use a pre-built image from GitHub Container Registry. Pre-built is faster; local build gives you the latest commits and full control.

Option A: Use a pre-built image (recommended for VPS)

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Option B: Build locally

./scripts/docker/setup.sh

The setup script handles onboarding, writes your .env file, generates a gateway token, fixes permissions, and starts the stack via Docker Compose. Expect it to take 5–15 minutes on first run depending on your VPS specs.

Airgapped or offline deploys

If your VPS has no outbound internet for image pulls, build on a machine with access, export the image, transfer it, then load and run offline:

# On build machine
docker pull ghcr.io/openclaw/openclaw:latest
docker save ghcr.io/openclaw/openclaw:latest -o openclaw-image.tar

# Transfer to VPS, then:
docker load -i openclaw-image.tar
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh --offline

3. Configure Environment Variables

The setup script creates a .env file. Review and edit it before going to production. Here are the key variables:

# LLM Provider (at least one required)
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...

# Gateway settings
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=18789

# Admin API
ADMIN_API_PORT=3000
ADMIN_API_SECRET=$(openssl rand -hex 32)

# Agent defaults
DEFAULT_MODEL=anthropic/claude-sonnet-4-5

# Docker-specific
OPENCLAW_SANDBOX=1
OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock

Security tip: never commit .env to Git. Add it to .gitignore immediately. For team deployments, use a secrets manager or Docker secrets instead of plain files.

4. Start the Stack and Verify

The setup script starts the gateway automatically. If you need to restart or verify:

docker compose up -d
docker compose ps
docker compose logs -f openclaw-gateway

Check health endpoints:

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz    # readiness

Get your dashboard URL:

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

5. Add a Reverse Proxy with HTTPS

Never expose port 18789 directly to the internet. Use Caddy, Nginx, or Traefik to terminate TLS and proxy to the gateway.

Caddy (simplest)

# Caddyfile
openclaw.yourdomain.com {
  reverse_proxy localhost:18789
}

Run Caddy in Docker alongside OpenClaw:

services:
  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - openclaw

networks:
  openclaw:
    external: true

Traefik (if you already use it)

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.openclaw.rule=Host(`openclaw.yourdomain.com`)"
  - "traefik.http.routers.openclaw.entrypoints=websecure"
  - "traefik.http.routers.openclaw.tls.certresolver=letsencrypt"

6. Connect Messaging Channels

OpenClaw shines when you can talk to it from anywhere. Telegram is the easiest channel to set up on a VPS.

Telegram bot setup

  1. Message @BotFather on Telegram and run /newbot
  2. Copy the bot token
  3. Add it to OpenClaw:
docker compose run --rm openclaw-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Approve the pairing request when OpenClaw messages you:

docker compose run --rm openclaw-cli pairing approve telegram

Now you can message your bot from any device and OpenClaw will respond.

7. Tips, Gotchas, and Troubleshooting

Here is what breaks when you run OpenClaw on a VPS — and how to fix it.

Build fails with OOM (exit 137)

pnpm install inside the Docker build can exhaust RAM. You need at least 2GB free during build, 4GB to be safe. If you're on a 2GB VPS, add swap or use the pre-built image instead:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Dashboard shows "pairing required"

If you see disconnected (1008): pairing required, list pending devices and approve yours:

docker compose exec openclaw-gateway \
  node dist/index.js devices list

docker compose exec openclaw-gateway \
  node dist/index.js devices approve

Local LLM providers (Ollama / LM Studio)

When OpenClaw runs in Docker, 127.0.0.1 is the container — not your host. Use host.docker.internal instead:

# For Ollama
OLLAMA_HOST=0.0.0.0:11434 ollama serve
# In OpenClaw config: http://host.docker.internal:11434

# For LM Studio
lms server start --port 1234 --bind 0.0.0.0
# In OpenClaw config: http://host.docker.internal:1234

Container keeps restarting

Check logs first. Common causes: missing API key, port conflict, or permission issues on mounted volumes. The built-in healthcheck will mark the container unhealthy if /healthz fails repeatedly.

docker compose logs --tail 100 openclaw-gateway
docker inspect --format='{{.State.Health.Status}}' openclaw-gateway

Persistent storage

OpenClaw mounts these directories by default. Make sure they survive container recreation:

  • ~/.openclaw → config, memory, auth profiles
  • ~/openclaw/workspace → agent files and output
  • ~/.config/openclaw → auth-profile encryption keys

Use Docker named volumes or host bind mounts. Avoid /tmp for anything you want to keep.

Closing Thoughts

Deploying OpenClaw on a VPS with Docker gives you a private, always-on AI agent that you control completely. No local dependencies. No vendor lock-in. Just a containerized gateway that answers to you.

The workflow is simple: prepare your VPS, pull or build the image, run the setup script, configure your providers, add a reverse proxy for HTTPS, and connect your favorite messaging channel. From there, iterate — add agents, enable sandboxing, wire up custom skills.

If you need help with production hardening, custom agent development, or enterprise integrations — reach out to our team. We design and deploy OpenClaw infrastructure for teams that need AI agents running securely at scale.

How to Self-Host Grafana: The Complete Developer Guide to Monitoring Dashboards
Build production-ready monitoring dashboards with Grafana, Prometheus, and Docker Compose — from zero to fully observable in one guide.