Hetzner

OpenClaw sur Hetzner (Docker, Guide de VPS de production)

Objectif

Exécuter une passerelle OpenClaw Gateway persistante sur un VPS Hetzner en utilisant Docker, avec un état durable, des binaires intégrés et un comportement de redémarrage sécurisé.

Si vous voulez « OpenClaw 24/7 pour ~5 $ », c’est la configuration la plus simple et fiable. Les tarifs de Hetzner changent ; choisissez le plus petit VPS Debian/Ubuntu et augmentez l’échelle si vous rencontrez des OOM.

Que faisons-nous (termes simples) ?

• Louer un petit serveur Linux (VPS Hetzner)
• Installer Docker (runtime d’application isolé)
• Démarrer la passerelle OpenClaw Gateway dans Docker
• Persister ~/.openclaw + ~/.openclaw/workspace sur l’hôte (survit aux redémarrages/reconstructions)
• Accéder à l’interface de contrôle depuis votre ordinateur portable via un tunnel SSH

La passerelle Gateway est accessible via :

• Transfert de port SSH depuis votre ordinateur portable
• Exposition directe du port si vous gérez vous-même le pare-feu et les jetons

Ce guide suppose Ubuntu ou Debian sur Hetzner.
Si vous êtes sur un autre VPS Linux, mappez les paquets en conséquence. Pour le flux générique Docker, voir Docker.

---

Chemin rapide (opérateurs expérimentés)

1. Provisionner le VPS Hetzner
2. Installer Docker
3. Cloner le dépôt OpenClaw
4. Créer des répertoires hôtes persistants
5. Configurer .env et docker-compose.yml
6. Intégrer les binaires requis dans l’image
7. docker compose up -d
8. Vérifier la persistance et l’accès à la passerelle Gateway

---

Ce dont vous avez besoin

• VPS Hetzner avec accès root
• Accès SSH depuis votre ordinateur portable
• Confort de base avec SSH + copier/coller
• ~20 minutes
• Docker et Docker Compose
• Identifiants d’authentification du modèle
• Identifiants du fournisseur en option
  • QR WhatsApp
  • Jeton de bot Telegram
  • Gmail OAuth

---

1) Provisionner le VPS

Créez un VPS Ubuntu ou Debian chez Hetzner.

Connectez-vous en tant que root :

ssh root@YOUR_VPS_IP

Ce guide suppose que le VPS est avec état. Ne le traitez pas comme une infrastructure jetable.

---

2) Installer Docker (sur le VPS)

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

Vérifier :

docker --version
docker compose version

---

3) Clonez le dépôt OpenClaw

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

Ce guide suppose que vous allez construire une image personnalisée pour garantir la persistance des binaires.

---

4) Créez des répertoires persistants sur l’hôte

Les conteneurs Docker sont éphémères. Tout l’état de longue durée doit résider sur l’hôte.

mkdir -p /root/.openclaw
mkdir -p /root/.openclaw/workspace

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

---

5) Configurez les variables d’environnement

Créez .env à la racine du dépôt.

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

Générez des secrets forts :

openssl rand -hex 32

Ne commitez pas ce fichier.

---

6) Configuration Docker Compose

Créez ou mettez à jour 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"

      # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
      # If you expose this publicly, read /gateway/security and firewall accordingly.
      # - "18793:18793"
    command: ["node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND}", "--port", "${OPENCLAW_GATEWAY_PORT}"]

---

7) Intégrez les binaires requis dans l’image (critique)

Installer des binaires dans un conteneur en cours d’exécution est un piège. Tout ce qui est installé lors de l’exécution sera perdu au redémarrage.

Tous les binaires externes requis par les compétences doivent être installés au moment de la construction de l’image.

Les exemples ci-dessous ne montrent que trois binaires courants :

• gog pour l’accès Gmail
• goplaces pour Google Places
• wacli pour WhatsApp

Ce sont des exemples, pas une liste complète. Vous pouvez installer autant de binaires que nécessaire en utilisant le même modèle.

Si vous ajoutez de nouvelles compétences plus tard qui dépendent de binaires supplémentaires, vous devez :

1. Mettre à jour le Dockerfile
2. Reconstruire l’image
3. Redémarrer les conteneurs

Exemple de Dockerfile

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

---

8) Construire et lancer

docker compose build
docker compose up -d openclaw-gateway

Vérifiez les binaires :

docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli

Sortie attendue :

/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

---

9) Vérifiez le Gateway

docker compose logs -f openclaw-gateway

Succès :

[gateway] listening on ws://0.0.0.0:18789

Depuis votre ordinateur portable :

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

Ouvrez :

http://127.0.0.1:18789/

Collez votre jeton de passerelle.

---

Ce qui persiste où (source de vérité)

OpenClaw s’exécute dans Docker, mais Docker n’est pas la source de vérité. Tout l’état de longue durée doit survivre aux redémarrages, reconstructions et reboots.

Composant	Emplacement	Mécanisme de persistance	Notes
Config Gateway	/home/node/.openclaw/	Montage de volume hôte	Inclut openclaw.json, jetons
Profils d’authentification de modèle	/home/node/.openclaw/	Montage de volume hôte	Jeton OAuth, clés API
Configurations de compétences	/home/node/.openclaw/skills/	Montage de volume hôte	État au niveau des compétences
Espace de travail de l’agent	/home/node/.openclaw/workspace/	Montage de volume hôte	Code et artefacts de l’agent
Session WhatsApp	/home/node/.openclaw/	Montage du volume de l’hôte	Préserve la connexion QR
Trousseau de clés Gmail	/home/node/.openclaw/	Volume de l’hôte + mot de passe	Nécessite GOG_KEYRING_PASSWORD
Binaires externes	/usr/local/bin/	Image Docker	Doit être inclus lors de la compilation
Runtime Node	Système de fichiers du conteneur	Image Docker	Reconstruit à chaque build d’image
Paquets OS	Système de fichiers du conteneur	Image Docker	Ne pas installer à l’exécution
Conteneur Docker	Éphémère	Redémarrable	Destruction sans risque