Accueil › OpenClaw › Docker

OpenClaw Docker : le déploiement recommandé pour la production

Docker est la méthode d’installation recommandée pour tout usage sérieux d’OpenClaw. Le container isole l’agent de votre système hôte, empêche les skills malveillantes d’accéder à vos fichiers personnels, et rend les mises à jour triviales (pull + restart). Si vous prévoyez de faire tourner OpenClaw 24/7 sur un VPS ou un serveur domestique, Docker devrait être votre premier choix.

Pourquoi Docker pour OpenClaw

Trois avantages concrets par rapport à une installation directe (npm).

Isolation de sécurité. L’agent tourne dans un container avec un accès limité au système hôte. Si une skill malveillante ou une injection de prompt tente d’accéder à vos fichiers, la frontière du container limite les dégâts. C’est la recommandation numéro un du guide de sécurité OpenClaw.

Reproductibilité. La même image Docker tourne de manière identique sur votre laptop, un VPS, ou un Raspberry Pi. Votre setup est défini dans un fichier docker-compose.yml. Changement de serveur ? Copiez le fichier, lancez une commande, terminé.

Nettoyage facile. Vous voulez repartir de zéro ? Supprimez le container et recréez-en un. Pas de fichiers résiduels, pas d’installations Node.js cassées, pas de dépendances orphelines.

Prérequis

Installation rapide avec le script officiel

La méthode la plus simple utilise le script setup fourni dans le repo officiel.

# Cloner le repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Lancer le setup (build local + onboarding automatique)
./scripts/docker/setup.sh

Le script construit l’image Gateway localement, lance l’onboarding interactif (choix du fournisseur, clé API, canaux), génère un token Gateway et l’écrit dans .env, puis démarre le Gateway via Docker Compose.

Pour utiliser une image pré-construite au lieu de builder localement :

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

Les images pré-construites sont publiées sur le GitHub Container Registry. Tags courants : main, latest, et des tags versionnés (ex: 2026.3.11).

Volumes créés

Le script crée deux répertoires sur l’hôte, montés comme volumes dans le container :

~/.openclaw/ : répertoire de configuration. Contient la mémoire OpenClaw, la configuration, les clés API tierces, et les données de session des canaux.

~/openclaw/workspace/ : répertoire de travail accessible à l’agent. Les fichiers créés par l’agent apparaissent ici. Vous pouvez aussi y placer des fichiers que vous voulez rendre accessibles à l’agent.

Ces volumes survivent au remplacement du container. C’est la clé de la persistance : vos données restent même quand vous mettez à jour l’image.

Docker Compose en détail

Fichier docker-compose.yml annoté

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"  # Control UI + API
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"    # Bridge
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-~/openclaw/workspace}:/home/node/.openclaw/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    init: true
    command: ["node", "dist/index.js", "gateway",
              "--bind", "${OPENCLAW_GATEWAY_BIND:-lan}",
              "--port", "18789"]
    healthcheck:
      test: ["CMD", "node", "-e",
             "fetch('http://127.0.0.1:18789/healthz')"]
      interval: 30s
      timeout: 10s
      retries: 3

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    profiles: ["cli"]
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-~/openclaw/workspace}:/home/node/.openclaw/workspace
    entrypoint: ["node", "dist/index.js"]

Commandes Docker Compose courantes

# Démarrer le Gateway
docker compose up -d

# Voir les logs en temps réel
docker compose logs -f openclaw-gateway

# Arrêter
docker compose down

# Redémarrer (après changement de config)
docker compose restart

# Exécuter des commandes CLI
docker compose run --rm openclaw-cli onboard
docker compose run --rm openclaw-cli channels login
docker compose run --rm openclaw-cli dashboard --no-open

# Entrer dans le container (shell)
docker compose exec openclaw-gateway bash

# Installer des paquets supplémentaires (en root)
docker compose exec -u root openclaw-gateway bash
apt-get update && apt-get install -y ripgrep

Connecter les canaux depuis Docker

# WhatsApp (scan QR code)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add 
  --channel telegram --token "VOTRE_TOKEN_BOT"

# Discord
docker compose run --rm openclaw-cli channels add 
  --channel discord --token "VOTRE_TOKEN_BOT"

# Approuver un pairing
docker compose run --rm openclaw-cli pairing approve telegram CODE

Sandbox agent dans Docker

OpenClaw supporte un double niveau d’isolation. Le container principal isole le Gateway du système hôte. Quand le sandbox agent est activé, les commandes shell et les opérations sur les fichiers des agents sont exécutées dans des containers Docker supplémentaires à l’intérieur du Gateway (Docker-in-Docker).

# Activer le sandbox agent
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

Le sandbox nécessite l’accès au socket Docker (/var/run/docker.sock) et l’ajout du GID du groupe docker. Le setup script gère cette configuration automatiquement. Pour une activation manuelle, décommentez les lignes correspondantes dans le docker-compose.yml et configurez DOCKER_GID avec le GID du groupe docker de l’hôte.

Déploiement sur VPS

Configuration recommandée

Un VPS avec 2 vCPU, 4 Go de RAM et 40 Go de stockage SSD suffit pour un usage personnel avec un modèle cloud. Un VPS à 5-10 $/mois chez Hetzner (CX22 à 4,35 €/mois), DigitalOcean ou OVH fait l’affaire.

# Sur un VPS Ubuntu 22.04 frais
apt update && apt install -y docker.io docker-compose-v2 git

# Cloner et installer
git clone https://github.com/openclaw/openclaw.git
cd openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Sécurisation du VPS

Sur un VPS exposé à internet, le binding du Gateway est critique. Le script setup utilise OPENCLAW_GATEWAY_BIND=lan par défaut, ce qui rend le Gateway accessible depuis l’hôte. Pour un accès distant sécurisé, deux options :

Tailscale Serve/Funnel : accès sécurisé au dashboard sans configuration de reverse proxy. Idéal pour un usage personnel.

Reverse proxy (Nginx/Caddy) avec TLS : pour un accès via votre propre domaine avec HTTPS. Nécessite un nom de domaine et un certificat.

DigitalOcean propose un déploiement 1-Click avec Docker pré-configuré, firewall durci, exécution non-root, et isolation Docker automatique.

Navigateur Playwright dans Docker

Si vous avez besoin des fonctionnalités de navigation web (screenshots, remplissage de formulaires, navigation automatisée), installez Chromium via Playwright dans le container :

docker compose run --rm openclaw-cli 
  node /app/node_modules/playwright-core/cli.js install chromium

Pour persister les téléchargements du navigateur entre les redémarrages, configurez PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright et utilisez un volume persistant via OPENCLAW_HOME_VOLUME ou OPENCLAW_EXTRA_MOUNTS.

OpenClaw + Ollama dans Docker

Pour une installation entièrement locale (zéro coût API, confidentialité maximale), vous pouvez faire tourner OpenClaw et Ollama ensemble dans Docker. Cette configuration nécessite un GPU avec au moins 8 Go de VRAM pour les modèles légers (Qwen3.5 9B), 16 Go+ pour les modèles moyens (27B).

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    # ... config OpenClaw standard ...
    environment:
      - OPENAI_API_KEY=ollama-local
      - OPENAI_BASE_URL=http://ollama:11434/v1

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama_models:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  ollama_models:

Après le démarrage, tirez votre modèle dans le container Ollama :

docker compose exec ollama ollama pull qwen3.5:9b

Pour un VPS sans GPU, les modèles cloud restent la meilleure option. Un VPS à 5-10 $/mois avec les tokens API Claude Sonnet revient moins cher qu’un VPS GPU dédié.

Bonnes pratiques de production

Montages de volumes restrictifs

Ne montez que les répertoires strictement nécessaires. Évitez de monter votre répertoire home entier dans le container. Utilisez des montages read-only pour les fichiers que l’agent doit lire mais pas modifier :

volumes:
  - ~/.openclaw:/home/node/.openclaw:rw    # Config (lecture-écriture)
  - ~/documents:/home/node/docs:ro          # Documents (lecture seule)

Restriction réseau

Si votre agent n’a pas besoin d’accéder aux services du réseau local, isolez son réseau. Docker permet de créer des réseaux dédiés qui ne donnent accès qu’à internet (pour les appels API) sans exposer les services locaux.

Limites de ressources

Configurez des limites de mémoire et de CPU pour prévenir un agent emballé de consommer toutes les ressources du serveur :

services:
  openclaw-gateway:
    # ... config ...
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.5'

Logging structuré

Configurez la rotation des logs Docker pour éviter que les fichiers de logs ne remplissent le disque :

services:
  openclaw-gateway:
    # ... config ...
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Fuseau horaire

Pour que les cron jobs et les timestamps soient dans votre fuseau horaire, ajoutez la variable TZ :

environment:
  - TZ=Europe/Paris

Maintenance et mises à jour

# Mettre à jour OpenClaw
docker compose pull          # Tirer la dernière image
docker compose up -d         # Recréer le container
docker image prune -f        # Nettoyer les anciennes images

# Sauvegarde avant mise à jour
docker compose run --rm openclaw-cli backup create

# Vérifier l'installation après mise à jour
docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli doctor --fix

# Monitorer la santé
curl -fsS http://127.0.0.1:18789/healthz  # Liveness
curl -fsS http://127.0.0.1:18789/readyz   # Readiness

L’image Docker inclut un HEALTHCHECK intégré qui ping /healthz. Si les checks échouent, Docker marque le container comme unhealthy et les systèmes d’orchestration peuvent le redémarrer automatiquement.

Gestion de l’espace disque

Surveillez la croissance du disque dans le container. Les hotspots principaux : le dossier media/ (médias reçus via les canaux), les fichiers de session JSONL, les logs de cron dans cron/runs/*.jsonl, et les logs rotatifs sous /tmp/openclaw/. Un nettoyage périodique de ces répertoires prévient les problèmes de disque plein. Planifiez un cron job sur l’hôte pour supprimer les fichiers de plus de 30 jours dans media/ et les logs archivés. Sur un VPS à disque limité (20-40 Go), surveillez l’espace disponible avec docker system df pour anticiper les problèmes avant qu’ils n’affectent le service.

Dépannage

Port 18789 déjà utilisé

Changez le port dans le docker-compose.yml : remplacez "18789:18789" par "18790:18789" (ou tout autre port libre). Le port interne du container (18789) reste le même, seul le port exposé sur l’hôte change.

Container tué (exit 137)

L’exit code 137 indique un OOM kill : le container manque de mémoire. Solutions : augmentez la RAM du VPS (2 Go minimum, 4 Go recommandé), réduisez la taille de la fenêtre de contexte dans la config agent, ou limitez le nombre de sessions concurrentes.

Données perdues après redémarrage

Les volumes ne sont pas configurés correctement. Vérifiez que ~/.openclaw et ~/openclaw/workspace sont bien montés dans le docker-compose.yml. Ne jamais utiliser docker compose down -v (le flag -v supprime les volumes). Utilisez des volumes nommés explicites pour plus de robustesse.

Erreurs de permissions dans le container

L’image officielle tourne en utilisateur node (non-root). Si les volumes montés appartiennent à root sur l’hôte, le processus node n’a pas les droits d’écriture. Ajustez les permissions des répertoires hôte : chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace (1000 est l’UID de l’utilisateur node dans le container).

OAuth qui ne fonctionne pas en mode headless

Si vous choisissez OpenAI Codex OAuth ou Claude OAuth pendant le wizard, le flux ouvre une URL dans un navigateur. En Docker ou sur un serveur headless, il n’y a pas de navigateur. La solution : copiez l’URL complète de redirection sur laquelle vous atterrissez (y compris les paramètres de callback) et collez-la dans le wizard pour terminer l’authentification. Pour éviter ce problème, préférez l’authentification par clé API plutôt qu’OAuth sur les déploiements Docker.

Docker daemon ne démarre pas

Si Docker lui-même refuse de démarrer, vérifiez que le service est actif (sudo systemctl start docker), que votre utilisateur est dans le groupe docker (sudo usermod -aG docker $USER, puis déconnexion/reconnexion), et que le port n’est pas bloqué par un autre service. Sur certains VPS, Docker nécessite des permissions spécifiques pour les cgroups v2.

Questions fréquentes