Cible : ingénieurs qui lisent la doc Docker officielle mais oscillent entre timeouts de build local, échecs de pull GHCR, conflits sur le port 18789 et droits de volume qui bloquent Skills sans chemin ordonné du clone à la Control UI. Résultat : standardiser sur docker-setup.sh plus OPENCLAW_IMAGE optionnel, et partager le travail avec Docker production, Docker réseau et volumes/droits. Plan : six pièges, matrice, runbook en six étapes, tableau de triage, trois KPI, conclusion.
Le flux officiel suppose Docker Engine, Compose, disque et sortie cohérents. Mélangé avec npm global ou un autre checkout compose, l’échec ressemble à « OpenClaw est cassé ». Six cas fréquents 2025–2026 :
docker build sur un CI faible sans passer à OPENCLAW_IMAGE.docker-setup.sh ne peut pas lier la Control UI.~/.openclaw—écritures Skills/état en échec alors que l’UI semble « morte ».compose pull infini.OPENCLAW_IMAGE (GHCR)Choisir un chemin principal dans le ticket et documenter le rollback sur l’autre—éviter le mélange verbal.
| Dimension | Build source par défaut | OPENCLAW_IMAGE tire GHCR |
|---|---|---|
| Idéal pour | Modifs Dockerfile perso, debug cache build, pas de sortie ghcr | Temps jusqu’à l’UI le plus court, bande passante limitée, CI qui met en cache les images plutôt que les dépôts |
| Prérequis | CPU/RAM suffisants ; cache de couches en Go | ghcr.io ou miroir interne joignable ; épingler au-delà du seul latest |
| Risques | Timeouts de build, cache gonflé, contention CPU | Auth/limites de débit, dérive de tag, décalage config vs binaire |
| Rollback | Passer à l’image préconstruite en gardant le même chemin de volume de données | Revenir au digest précédent ou au build source ; journaliser les changements compose |
Note : les dépôts upstream évoluent ; les commandes supposent un checkout avec docker-setup.sh à la racine—noter commit et chemin du script si votre fork diffère.
docker version et Compose v2 ; disque pour couches/volumes (aligné sur le tableau ressources de la production).docker-setup.sh exécutable (chmod +x si besoin).export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest—en production épingler digest ou tags stables, pas seulement suivre les tags../docker-setup.sh ; les journaux montrent pull/build et compose up sans sortie immédiate non nulle.http://127.0.0.1:18789 (révision différente → port selon le build) ; la page charge, pas de connexion refusée.# Préférer GHCR (remplacer le tag selon la politique) export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./docker-setup.sh # Après succès, la Control UI doit charger (ex. port 18789) # open http://127.0.0.1:18789
De haut en bas ; ne pas changer image, réseau et volumes en même temps.
| Symptôme | Vérifier d’abord | Lire aussi |
|---|---|---|
| Timeout build / OOM | Passer à OPENCLAW_IMAGE ; limiter la parallélisation buildkit ; purger le cache | Docker production (ressources) |
| 401/403/TLS au pull | Listes proxy pour ghcr.io ; miroir interne—pas seulement le registre npm | Runbook npm (proxy) |
address already in use :18789 | docker ps pour conteneurs obsolètes ; arrêter l’ancien compose ou remapper le port selon la doc | Docker réseau |
| Permission denied sur volumes | UID/GID hôte vs utilisateur conteneur ; montages nommés vs bind | Checklist volumes/Skills |
| UI charge mais canal muet | Écarter modèle/canaux ; puis codes jeton/WS | Jumelage/jetons |
~/.openclaw hôte (ou chemin équipe) sur les montages compose ; snapshot taille et droits avant/après upgrade.Si les notes de version upstream divergent, faire confiance à upstream ; cet article fournit des points de contrôle d’ingénierie.
Veille, disques fragmentés et restes Docker Desktop s’opposent à CPU dédié, sortie stable, volumes auditables et frontières de jetons. Conteneurs éphémères sans digest épinglé, sans contrat de volume ni healthcheck, cassent au premier trafic réel.
Les équipes qui hébergent Gateway longtemps sur Apple Silicon stable gagnent après cette boucle minimale avec les Mac cloud MACCOME multi-régions et locations flexibles—consulter les tarifs publics et le centre d’aide location Mac mini avec les articles production et jumelage.
Pilote : exécuter les six étapes sur un hôte distant dédié, noter digest et snapshots de volumes, puis fixer conditions mensuelles/trimestrielles et supervision.
FAQ
Lire d’abord cet article ou Docker production ?
Ce runbook pour le premier chemin UI réussi ; la production pour fenêtres de changement, rollback et supervision. Tarifs : tarifs de location Mac mini.
OPENCLAW_IMAGE entre-t-il en conflit avec la CLI npm globale ?
Les conflits se concentrent sur ports, variables et répertoires de données ; un Gateway principal par hôte. Ordre de migration : runbook d’installation npm.
Puis-je exposer 18789 publiquement ?
Mettre reverse proxy et TLS devant—lire les sections sécurité des articles production/reverse-proxy plutôt que lier 0.0.0.0 aveuglément. Aide : centre d’aide location Mac mini.