OpenClaw avec Docker : guide complet

Introduction

Un déploiement OpenClaw Docker convient lorsqu’on veut isoler le Gateway, conserver son état dans des volumes et reproduire la même installation sur un poste ou un VPS. Il est utile pour une instance persistante, un test jetable ou un hôte où l’on ne souhaite pas installer Node globalement. Il est en revanche plus simple d’utiliser l’installateur natif pour un usage local classique. Ce tutoriel suit le flux Docker officiel : image publiée par le projet, script de préparation, onboarding, authentification, canaux et vérifications. Il remplace les anciens exemples Python, PostgreSQL et Redis qui ne correspondent pas à l’architecture actuelle.

Résumé rapide

1. Installer Docker Engine ou Docker Desktop et Docker Compose v2.
2. Utiliser ghcr.io/openclaw/openclaw:latest avec le script Docker officiel.
3. Persister ~/.openclaw et le workspace, puis protéger le token du Gateway.
4. Administrer l’instance avec openclaw-cli, jamais avec un faux endpoint HTTP.
5. Vérifier le Gateway, les canaux et les logs avant toute exposition réseau.

Comprendre l’architecture conteneurisée

OpenClaw n’est pas une bibliothèque Python à empaqueter dans un Dockerfile maison. Le cœur actuel est un Gateway Node/TypeScript de longue durée. Ce processus possède les connexions aux canaux, les sessions, le routage, les agents et le Control UI. Les clients et les nodes se connectent à son serveur WebSocket, qui écoute par défaut sur le port 18789. La configuration principale est un fichier JSON5 situé dans ~/.openclaw/openclaw.json ; les workspaces, bases SQLite, credentials et états de pairing vivent également sous le répertoire d’état.

Le déploiement officiel fournit deux services complémentaires. openclaw-gateway exécute le processus persistant. openclaw-cli sert aux opérations ponctuelles : onboarding, configuration, ajout d’un canal, affichage du dashboard ou approbation d’un appareil. Cette séparation évite d’installer une seconde copie de la CLI sur l’hôte et garantit que les commandes utilisent la même version que le Gateway.

Docker ne remplace pas le sandbox des outils. Conteneuriser le Gateway isole son runtime de l’hôte, tandis que le sandbox OpenClaw contrôle où les commandes d’un agent s’exécutent. Le sandbox est désactivé par défaut et peut lui-même utiliser Docker, Podman, SSH ou OpenShell. Pour une séparation forte entre utilisateurs qui ne se font pas confiance, un conteneur partagé ne suffit pas : il faut séparer les Gateways, les secrets et idéalement les comptes OS ou les hôtes. Le guide de sécurité OpenClaw détaille cette frontière de confiance.

Déployer OpenClaw avec Docker pas à pas

1. Vérifier les prérequis

La voie maintenue requiert Docker et Compose v2. Sur un petit VPS, l’image préconstruite évite le coût d’une construction locale.

docker --version
docker compose version

Ces commandes doivent simplement se terminer sans erreur. Ne recopiez pas un numéro de version affiché dans un ancien tutoriel : les versions évoluent. Si Docker manque sur votre serveur, installez-le selon votre distribution avant de continuer.

2. Récupérer le dépôt officiel et choisir l’image

Le script de préparation et le fichier Compose sont maintenus dans le dépôt officiel openclaw/openclaw. Depuis sa racine, sélectionnez l’image GHCR officielle puis lancez le setup :

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

L’alternative officielle sur Docker Hub est openclaw/openclaw:latest. Évitez les images openclaw/app, openclaw:1.4.2 ou les miroirs non identifiés : elles ne correspondent pas au registre et au cycle de publication documentés. En production, remplacez latest par un tag de release testé afin de rendre les mises à jour prévisibles.

Le script synchronise les variables, corrige les permissions, lance l’onboarding et démarre la composition. Depuis les sources, la commande produit une image locale openclaw:local. Sur une machine limitée, utilisez l’image préconstruite.

3. Conserver l’état utile

Le répertoire d’état contient beaucoup plus qu’un fichier de configuration : bases SQLite, sessions, profils d’authentification, pairing, plugins et autres métadonnées. Le workspace contient les fichiers de contexte, la mémoire Markdown et les skills de l’agent. Les perdre revient à reconstruire l’identité opérationnelle de l’instance.

Le setup officiel accepte notamment ces chemins :

export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"
export OPENCLAW_AUTH_PROFILE_SECRET_DIR="$HOME/.openclaw-auth-profile-secrets"

Ne montez pas seulement un hypothétique /app/data. Vérifiez dans le Compose généré que le Gateway et la CLI voient les mêmes volumes. Si vous utilisez un backend CLI installé dans le home du conteneur, OPENCLAW_HOME_VOLUME permet de persister tout /home/node, pas seulement .openclaw.

4. Comprendre bind, port et authentification

Dans un conteneur, un bind loopback ne serait accessible qu’à l’intérieur de son espace réseau. Le setup Docker utilise donc OPENCLAW_GATEWAY_BIND=lan pour que la publication du port hôte fonctionne. Cela ne signifie pas qu’il faut publier le Gateway sur Internet. Limitez le mapping à l’interface locale ou filtrez-le avec le pare-feu de l’hôte.

Le port interne reste 18789; OPENCLAW_GATEWAY_PORT change le port publié sur l’hôte. Toute écoute non-loopback exige une authentification Gateway. Utilisez un token long, conservé dans l’environnement ou via un SecretRef, et ne le commitez jamais :

export OPENCLAW_GATEWAY_TOKEN="<token-long-et-aleatoire>"
export OPENCLAW_GATEWAY_PORT="18789"

Pour générer un token lorsque l’installation n’en possède pas, exécutez la commande documentée dans le conteneur CLI :

docker compose run --rm openclaw-cli doctor --generate-gateway-token

Le token protège le plan de contrôle WebSocket. Il ne remplace ni le pairing des appareils ni les politiques d’accès aux messages entrants.

5. Ouvrir le Control UI

Demandez à la CLI de produire l’URL du dashboard sans essayer d’ouvrir un navigateur dans le conteneur :

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

Ouvrez ensuite l’adresse locale indiquée. Si le port hôte a été modifié, adaptez uniquement ce port dans l’URL. Un navigateur inconnu peut créer une demande d’appairage ; inspectez-la puis approuvez son identifiant depuis la CLI :

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

N’utilisez pas /health, /api/agents/... ou une API FastAPI inventée pour piloter OpenClaw. Le plan de contrôle est une API WebSocket typée, et la CLI en est le client supporté.

6. Ajouter et contrôler les canaux

Pour WhatsApp, ouvrez le flux interactif de connexion. Pour Telegram ou Discord, fournissez le token demandé au plugin du canal :

docker compose run --rm openclaw-cli channels login
docker compose run --rm openclaw-cli channels add --channel telegram --token "<bot-token>"
docker compose run --rm openclaw-cli channels add --channel discord --token "<bot-token>"

Après configuration, interrogez l’état réel et les capacités :

docker compose run --rm openclaw-cli channels list
docker compose run --rm openclaw-cli channels status --probe

En automatisation, channels add --channel telegram --use-env valide TELEGRAM_BOT_TOKEN sans le copier dans openclaw.json. La variable doit alors rester disponible dans l’environnement du Gateway en fonctionnement. Les changements de canal valides peuvent être rechargés sans redémarrage complet.

7. Vérifier, lire les logs et mettre à jour

Contrôlez d’abord les conteneurs, puis utilisez les diagnostics applicatifs :

docker compose ps
docker compose logs --tail=200 openclaw-gateway
docker compose run --rm openclaw-cli status --all
docker compose run --rm openclaw-cli doctor --lint --json

Pour un contrôle depuis le processus Gateway, la composition officielle permet aussi :

docker compose exec openclaw-gateway sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

Avant une mise à jour, sauvegardez l’état et vérifiez l’archive. Récupérez ensuite un tag d’image précis, redémarrez et contrôlez le statut ainsi que les canaux. Le guide OpenClaw en production fournit la séquence de validation et de retour arrière.

Checklist de validation

• L’image provient de GHCR ou du miroir Docker Hub officiel.
• Le Gateway et la CLI partagent l’état et le workspace persistants.
• Le port hôte n’est pas directement ouvert à Internet.
• Une authentification par token ou mot de passe est active hors loopback.
• channels status --probe, status --all et doctor --lint passent.
• Les logs Docker sont rotatifs et la sauvegarde a été restaurée en test.

Exemple concret : un Gateway privé sur VPS

Une petite équipe veut lancer OpenClaw sur un VPS, connecter Telegram et garder le Control UI privé. Elle récupère le dépôt officiel, sélectionne ghcr.io/openclaw/openclaw:latest pour le premier test, définit un token Gateway et exécute ./scripts/docker/setup.sh. Le port 18789 n’est pas autorisé dans le pare-feu public.

Depuis un poste d’administration, l’opérateur ouvre un tunnel :

ssh -N -L 18789:127.0.0.1:18789 user@vps

Il ouvre ensuite le dashboard sur l’adresse loopback, approuve le navigateur si nécessaire, puis ajoute Telegram depuis openclaw-cli. La vérification porte sur quatre signaux : conteneur actif, santé du Gateway, probe du canal et absence d’erreur dans les logs récents. L’équipe remplace ensuite latest par le tag exact validé et sauvegarde les volumes.

Ce scénario prouve le point essentiel : Docker fournit le runtime et la persistance, mais l’accès distant reste un sujet de réseau et d’authentification. Le port n’a pas besoin d’être public pour que les canaux sortants fonctionnent. Si l’usage devient multi-utilisateur avec des personnes non mutuellement fiables, l’équipe crée des Gateways séparés plutôt que de multiplier les agents dans un seul conteneur.

Bonnes pratiques

Épinglez une release en production et testez-la sur une copie de l’état. Une migration SQLite peut empêcher un retour au code précédent ; le rollback repose donc sur une sauvegarde vérifiée. Activez la rotation des logs Docker et surveillez le disque.

Ne confondez pas workspace et sandbox. Un workspace est le répertoire de travail par défaut, mais les chemins absolus restent accessibles si le sandbox est désactivé. Limitez les outils, les credentials et les mounts selon le rôle de chaque agent. N’exposez jamais le socket Docker au Gateway sans nécessité : il donne un pouvoir très élevé sur l’hôte.

Enfin, administrez la configuration avec openclaw configure, openclaw config set ou le Control UI. Le fichier openclaw.json est strictement validé et rechargé à chaud ; un ancien openclaw.yaml ne doit pas être conservé comme source de vérité. Pour les incidents, commencez par openclaw doctor, puis corrélez avec les logs et le monitoring OpenClaw.

Questions fréquentes

Quelle image Docker utiliser pour OpenClaw ?

L’image officielle principale est ghcr.io/openclaw/openclaw, avec un miroir openclaw/openclaw sur Docker Hub. Utilisez latest pour un essai, puis un tag de release précis après validation. Évitez openclaw/app, les images anonymes et les anciens exemples construits sur Python : ils ne représentent pas le Gateway Node/TypeScript actuel.

Docker suffit-il à sécuriser OpenClaw ?

Non. Le conteneur isole le runtime, mais il faut encore protéger l’authentification du Gateway, limiter l’exposition réseau, contrôler le pairing, restreindre les outils et sauvegarder l’état. Pour des utilisateurs hostiles entre eux, utilisez des Gateways et des comptes OS séparés. Un unique conteneur partagé n’est pas une frontière de sécurité multi-tenant.

Où se trouve la configuration dans un conteneur OpenClaw ?

La configuration canonique reste ~/.openclaw/openclaw.json, au format JSON5, dans le home vu par le Gateway. Le setup Docker monte ce répertoire depuis l’hôte. Le workspace est généralement ~/.openclaw/workspace. Ces emplacements doivent être persistés et accessibles aussi au service openclaw-cli utilisé pour l’administration.

Comment consulter les logs du Gateway conteneurisé ?

Utilisez docker compose logs -f openclaw-gateway pour la sortie du conteneur et docker compose run --rm openclaw-cli logs --follow pour le journal applicatif via la CLI. Pour un canal précis, utilisez channels logs --channel <nom>. Évitez de laisser un niveau debug permanent, car il augmente le volume et le risque d’exposer du contexte sensible.

Articles liés

Docker est adapté quand l’isolation et la reproductibilité justifient une couche supplémentaire. Pour une installation personnelle simple, l’installateur Node reste plus direct ; pour un serveur, ajoutez sécurité, sauvegarde et supervision avant de considérer le déploiement terminé.

• Installer OpenClaw avec la méthode actuelle
• Déployer OpenClaw sur un VPS
• Choisir un hébergement OpenClaw
• Sécuriser le Gateway OpenClaw
• Mettre OpenClaw en production
• Comprendre l’architecture OpenClaw