Hetzner

Provision the VPS

Create an Ubuntu or Debian VPS in Hetzner.

Connect as root:

ssh root@YOUR_VPS_IP

This guide assumes the VPS is stateful. Do not treat it as disposable infrastructure.

Install Docker (on the VPS)

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

Verify:

docker --version
docker compose version

Clone the OpenClaw repository

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

This guide assumes you will build a custom image to guarantee binary persistence.

Create persistent host directories

Docker containers are ephemeral. All long-lived state must live on the host.

mkdir -p /root/.openclaw/workspace

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

Configure environment variables

Create .env in the repository root.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

Set OPENCLAW_GATEWAY_TOKEN when you want to manage the stable gateway token through .env; otherwise configure gateway.auth.token before relying on clients across restarts. If neither source exists, OpenClaw uses a runtime-only token for that startup. Generate a keyring password and paste it into GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Do not commit this file.

This .env file is for container/runtime env such as OPENCLAW_GATEWAY_TOKEN. Stored provider OAuth/API-key auth lives in the mounted ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Docker Compose configuration

Create or update docker-compose.yml.

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",
      ]

--allow-unconfigured is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (gateway.auth.token or password) and use safe bind settings for your deployment.

Shared Docker VM runtime steps

Use the shared runtime guide for the common Docker host flow:

• Bake required binaries into the image
• Build and launch
• What persists where
• Updates

Hetzner-specific access

After the shared build and launch steps, complete the following setup to open the tunnel:

Prerequisite: Ensure your VPS sshd config allows TCP forwarding. If you have hardened your SSH config, check /etc/ssh/sshd_config and set:

AllowTcpForwarding local

local allows ssh -L local forwards from your laptop while blocking remote forwards from the server. Setting it to no will fail the tunnel with: channel 3: open failed: administratively prohibited: open failed

After confirming TCP forwarding is enabled, restart the SSH service (systemctl restart ssh) and run the tunnel from your laptop:

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

Open:

http://127.0.0.1:18789/

Paste the configured shared secret. This guide uses the gateway token by default; if you switched to password auth, use that password instead.