How to Set Up OpenClaw on Hetzner VPS

Prerequisites

• ✓A Hetzner VPS running Ubuntu or Debian with root access
• ✓SSH access from your laptop to the VPS as root
• ✓Docker and Docker Compose installed on the VPS (you install them in this guide)
• ✓Model auth credentials for the providers you plan to use
• ✓Optional provider credentials such as a WhatsApp QR, Telegram bot token, or Gmail OAuth details
• ✓About 20 minutes to complete the setup

Steps

1. 1

   Provision the Hetzner VPS and connect

   Create an Ubuntu or Debian VPS in Hetzner and connect as root. This guide assumes the VPS is stateful and not treated as disposable infrastructure.

   bashCopy

   ssh root@YOUR_VPS_IP

2. 2

   Install Docker on the VPS

   Install Docker and basic tools so you can run the OpenClaw Gateway in an isolated container runtime. Then verify that both Docker and Docker Compose are available.

   bashCopy

   apt-get update
   apt-get install -y git curl ca-certificates
   curl -fsSL https://get.docker.com | sh
   
   docker --version
   docker compose version

3. 3

   Clone the OpenClaw repository

   Clone the OpenClaw repository onto the VPS and change into the project directory. You will build a custom image from this repository to guarantee binary persistence.

   bashCopy

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

4. 4

   Create persistent host directories

   Create directories on the host to store OpenClaw configuration and workspace data so they survive container restarts and rebuilds. Set ownership to match the container user (uid 1000).

   bashCopy

   mkdir -p /root/.openclaw/workspace
   
   # Set ownership to the container user (uid 1000):
   chown -R 1000:1000 /root/.openclaw

5. 5

   Configure environment variables for the gateway

   env` file in the repository root to define the OpenClaw image, gateway token, bind settings, ports, and config directories. Use `openssl` to generate strong secrets and keep this file out of version control.

   bashCopy

   OPENCLAW_IMAGE=openclaw:latest
   OPENCLAW_GATEWAY_TOKEN=change-me-now
   OPENCLAW_GATEWAY_BIND=lan
   OPENCLAW_GATEWAY_PORT=18789
   
   OPENCLAW_CONFIG_DIR=/root/.openclaw
   OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
   
   GOG_KEYRING_PASSWORD=change-me-now
   XDG_CONFIG_HOME=/home/node/.openclaw
   
   openssl rand -hex 32

6. 6

   Configure Docker Compose for the OpenClaw Gateway

   env` file, environment variables, and volume mounts. Bind the gateway to loopback on the VPS and map the persistent config and workspace directories.

   yamlCopy

   services:
     openclaw-gateway:
       image: ${OPENCLAW_IMAGE}
       build: .
       restart: unless-stopped
       env_file:
         - .env
       environment:
         - HOME=/home/node
         - NODE_ENV=production
         - TERM=xterm-256color
         - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
         - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
         - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
         - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
         - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
         - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
       volumes:
         - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
         - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
       ports:
         # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
         # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
         - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
       command:
         [
           "node",
           "dist/index.js",
           "gateway",
           "--bind",
           "${OPENCLAW_GATEWAY_BIND}",
           "--port",
           "${OPENCLAW_GATEWAY_PORT}",
           "--allow-unconfigured",
         ]

7. 7

   Follow the shared Docker VM runtime steps

   Use the shared Docker VM runtime guide to bake required binaries into the image, build and launch the container, understand what persists where, and handle updates. This keeps your Hetzner setup aligned with the common Docker host flow.

   textCopy

   https://docs.openclaw.ai/install/docker-vm-runtime#bake-required-binaries-into-the-image
   https://docs.openclaw.ai/install/docker-vm-runtime#build-and-launch
   https://docs.openclaw.ai/install/docker-vm-runtime#what-persists-where
   https://docs.openclaw.ai/install/docker-vm-runtime#updates

8. 8

   Access the gateway via SSH tunnel from your laptop

   After the container is running, create an SSH tunnel from your laptop to the VPS so you can reach the Control UI on localhost. Then open the gateway URL in your browser and authenticate with the configured shared secret.

   bashCopy

   ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

Configuration

Troubleshooting

mkdir -p /root/.openclaw/workspace
chown -R 1000:1000 /root/.openclaw

Frequently asked questions