HetznerHetzner

Objectif

Exécuter un OpenClaw Gateway persistant 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 souhaitez « OpenClaw 24/7 pour ~5 $ », c’est la configuration la plus simple et la plus fiable. Les tarifs Hetzner peuvent changer ; choisissez le plus petit VPS Debian/Ubuntu et augmentez l’échelle si vous rencontrez des erreurs de mémoire insuffisante (OOM).

Rappel du modèle de sécurité :

Les agents partagés en entreprise conviennent lorsque tout le monde se trouve dans la même limite de confiance et que l’exécution est exclusivement professionnelle.
Maintenez une séparation stricte : VPS/exécution dédiés + comptes dédiés ; aucun profil personnel Apple/Google/navigateur/gestionnaire de mots de passe sur cet hôte.
Si les utilisateurs sont adversaires les uns envers les autres, séparez par passerelle/hôte/utilisateur du système d’exploitation.

Voir Sécurité et Hébergement VPS.

Que faisons-nous (en termes simples) ?

Louer un petit serveur Linux (VPS Hetzner)
Installer Docker (environnement d’exécution d’application isolé)
Démarrer l’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

Cet état ~/.openclaw monté inclut openclaw.json, agents/<agentId>/agent/auth-profiles.json par agent, et .env.

Le 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, adaptez les paquets en conséquence. Pour le flux générique Docker, voir Docker.

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

Provisionner le VPS Hetzner
Installer Docker
Cloner le dépôt OpenClaw
Créer des répertoires persistants sur l’hôte
Configurer .env et docker-compose.yml
Intégrer les binaires requis dans l’image
docker compose up -d
Vérifier la persistance et l’accès à la 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 de provider optionnels
- QR WhatsApp
- Jeton de bot Telegram
- OAuth Gmail

Provisionner le VPS
Créez un VPS Ubuntu ou Debian sur Hetzner.

Connectez-vous en tant que root :
Fenêtre de terminal
```
ssh root@YOUR_VPS_IP
```
Ce guide suppose que le VPS est avec état. Ne le traitez pas comme une infrastructure éphémère.

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

Cloner le dépôt OpenClaw
Fenêtre de terminal
```
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.
Créer des répertoires persistants sur l'hôte
Les conteneurs Docker sont éphémères. Tout état durable doit résider sur l’hôte.
Fenêtre de terminal
```
mkdir -p /root/.openclaw/workspace

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.openclaw
```
Configurer les variables d'environnement
Créez .env à la racine du dépôt.
Fenêtre de terminal
```
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
```
Définissez OPENCLAW_GATEWAY_TOKEN lorsque vous souhaitez gérer le jeton de passerelle stable via .env ; sinon configurez gateway.auth.tokenOpenClaw avant de compter sur les clients à travers les redémarrages. Si aucune source n’existe, OpenClaw utilise un jeton uniquement à l’exécution pour ce démarrage. Générez un mot de passe de trousseau et collez-le dans GOG_KEYRING_PASSWORD :
Fenêtre de terminal
```
openssl rand -hex 32
```
Ne commitez pas ce fichier.

Ce fichier .env est pour l’environnement conteneur/exécution tel que OPENCLAW_GATEWAY_TOKENOAuthAPI. L’authentification stockée du fournisseur par OAuth/clé API réside dans le `~/.openclaw/agents/
/agent/auth-profiles.json` monté.

DockerConfiguration 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"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured n’est qu’une commodité pour l’amorçage, ce n’est pas un remplacement pour une configuration de passerelle appropriée. Définissez toujours l’authentification (gateway.auth.token ou mot de passe) et utilisez des paramètres de liaison sûrs pour votre déploiement.

DockerÉtapes d'exécution VM Docker partagées
Utilisez le guide d’exécution partagé pour le flux d’hôte Docker courant :

HetznerAccès spécifique à Hetzner

Après les étapes communes de construction et de lancement, effectuez la configuration suivante pour ouvrir le tunnel :

Prérequis : Assurez-vous que la configuration sshd de votre VPS autorise le transfert TCP. Si vous avez durci votre configuration SSH, vérifiez /etc/ssh/sshd_config et définissez :

AllowTcpForwarding local

local autorise les transferts locaux ssh -L depuis votre ordinateur portable tout en bloquant les transferts distants depuis le serveur. Le définir sur no fera échouer le tunnel avec : channel 3: open failed: administratively prohibited: open failed

Après avoir confirmé que le transfert TCP est activé, redémarrez le service SSH (systemctl restart ssh) et exécutez le tunnel 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 le secret partagé configuré. Ce guide utilise le jeton de passerelle par défaut ; si vous avez basculé vers l’authentification par mot de passe, utilisez plutôt ce mot de passe.

La carte de persistance partagée réside dans Docker VM Runtime.

Infrastructure as Code (Terraform)

Pour les équipes préférant les workflows d’infrastructure-as-code, une configuration Terraform maintenue par la communauté fournit :

Configuration Terraform modulaire avec gestion d’état à distance
Approvisionnement automatisé via cloud-init
Scripts de déploiement (bootstrap, deploy, backup/restore)
Durcissement de la sécurité (pare-feu, UFW, accès SSH uniquement)
Configuration du tunnel SSH pour l’accès à la passerelle

Dépôts :

Infrastructure : openclaw-terraform-hetzner
Configuration Docker : openclaw-docker-config

Cette approche complète la configuration Docker ci-dessus avec des déploiements reproductibles, une infrastructure versionnée et une récupération automatisée après sinistre.

Étapes suivantes

Configurer les canaux de messagerie : Canaux
Configurer la passerelle : Configuration de la passerelle
Gardez OpenClaw à jour : Mise à jour