Les équipes qui font tourner OpenClaw sous Docker Compose échouent rarement parce que les images ne tirent pas. Elles échouent parce que les journaux Gateway semblent sains alors que le navigateur ou le CLI signale connexion refusée, poignée WebSocket en échec ou erreurs de jeton — souvent à cause de l’adresse d’écoute (bind), de la publication de ports et du partage (ou non) d’espace réseau entre le CLI et le Gateway, et non de la clé API du modèle. Cet article propose six familles de symptômes d’astreinte, deux matrices « pas démarré » vs « démarré mais non routable », une carte bind / pare-feu / publication, des diagnostics copier-coller, un runbook en six étapes et trois KPI journaux. À croiser avec le runbook Docker de production, le triage doctor post-installation et le guide des probes Kubernetes : la production répond à comment déployer ; celui-ci répond à pourquoi les conteneurs ne se voient pas (ni l’hôte) comme vous le pensez.
Le plan de contrôle combine Gateway WebSocket/HTTP avec CLI / interface de contrôle, plus plusieurs conteneurs, bridges personnalisés et network_mode: service:.... Sans triage en couches, on tourne en rond sur les fichiers .openclaw sans vérifier si l’écouteur est joignable depuis l’espace de noms du CLI.
127.0.0.1 dans le conteneur ; l’hôte y accède via les ports publiés, alors qu’un autre service du même compose emprunte un chemin différent.gateway:18789 via le DNS du bridge alors que le Gateway n’expose la loopback qu’à la pile du service partagé — le classique « ça marchait une fois, plus après redémarrage ».curl sur l’hôte réussit par intermittence alors que les sondes dans le conteneur échouent après une montée de version qui laisse d’anciennes règles NAT.::1 ou enregistrements AAAA incorrects sur images allégées.Reportez-les sur le même ticket de changement que volumes, digests d’image et health checks issus de la prod : joignabilité vs exactitude de version.
Maintenez une topologie réseau d’une page dans le dépôt compose : quels services sur quel réseau, qui publie des ports, comment les portables de dev et la CI sonde la stack. Le DNS sur réseaux personnalisés diffère du bridge par défaut ; quand les noms de service échouent, lancez getent hosts ou nslookup dans le conteneur avant d’incriminer OpenClaw.
Lancez d’abord les commandes officielles doctor et gateway status (voir le guide post-installation). Ne faites pas tourner les jetons tant que vous n’avez pas prouvé qu’un écouteur existe.
| Signal | Classe probable | Première action | Anti-pattern |
|---|---|---|---|
| Pas de conteneur Gateway ou CrashLoop | Pas démarré | docker logs, OOM, probes qui tuent les pods | pull à l’infini sans contrôle des ressources |
Up mais pas d’écouteur ss dedans | Config / bind | Vérifier OPENCLAW_GATEWAY_BIND et la commande compose vs doc | Ne modifier que le /etc/hosts de l’hôte |
Écouteur OK, wget CLI en échec | Routage inter-namespaces | Envisager network_mode: "service:openclaw-gateway" | 0.0.0.0 aveugle sans modèle de menace |
| Navigateur hôte en échec, conteneur OK | Publication / proxy | Valider ports:, VPN, fichiers PAC | Désactiver TLS au hasard |
Alignez-vous sur les valeurs officielles gateway.bind telles que loopback, lan, tailnet et auto ; le compose doit aussi indiquer qui publie les ports.
| Objectif | Intention bind / env | Notes Compose | Sécurité |
|---|---|---|---|
| Portable local seulement | Loopback d’abord ; l’hôte frappe le port publié | 127.0.0.1:18789:18789 | Ne pas supposer que les autres services compose héritent de la joignabilité loopback |
| CLI fortement couplé au Gateway | Partager la pile réseau | network_mode: "service:openclaw-gateway" | Espace de ports partagé — éviter les doubles bind |
| Debug LAN | lan ou équivalent | 0.0.0.0 vs NIC explicite | Coupler aux règles pare-feu amont |
| Tunnel / proxy inverse | Gateway en loopback ; TLS au bord | Réseaux séparés ; vérifier le passage WebSocket | Pas de ports d’admin à nu sur Internet public |
# 1) Hôte : le port est-il vraiment publié ? docker compose ps curl -sv --max-time 2 http://127.0.0.1:18789/ || true # 2) Dans le conteneur gateway docker compose exec openclaw-gateway sh -lc 'ss -lntp 2>/dev/null || netstat -lntp' # 3) Depuis le conteneur CLI (renommer les services) docker compose exec openclaw-cli sh -lc 'wget -qO- --timeout=2 http://openclaw-gateway:18789/ || echo FAIL' # 4) Compose effectif docker compose config | sed -n '1,200p'
Attention : des retours terrain lient « le CLI n’atteint pas le Gateway » à des fichiers compose qui ne placent jamais le CLI dans l’espace réseau du Gateway. Validez le bloc de commandes sur une stack de test avant fusion en production.
Si les chemins d’installation manquent de clarté, commencez par le guide d’installation trois plateformes.
Upgrade et réécritures de chemin avant de toucher aux réglages TLS du Gateway.Compatible avec les sondes HTTP de l’article health-check Kubernetes quand vous promouvez la même stack vers l’orchestration.
ss dans le conteneur, nom de processus, service compose — tout écart mérite un ticket.docker port vs NAT iptables après rollouts — les chaînes obsolètes mordent encore en 2026.Étiquetez les journaux Gateway pour les échecs de poignée à part des 429/5xx amont ; si ces derniers dominent, basculez vers le guide failover fournisseurs.
Si les sondes HTTP ciblent la loopback alors que le trafic utilisateur entre par une autre interface, vous pouvez avoir des sondes vertes et des utilisateurs rouges ; alignez les URL de sondes sur la politique de bind du tableau 2 avant d’incriminer une release.
La mise en veille de Docker Desktop, les bascules VPN et les proxys locaux changent la résolution de localhost. L’automation de type production exige des politiques d’écoute reproductibles, des révisions compose auditées et des frontières hôte stables. Les portables ad hoc livrent rarement une sortie multi-régions avec isolation bare-metal, ce qui heurte les attentes de Gateway toujours actif.
Pour les équipes qui ont besoin d’un plan de contrôle joignable en astreinte, héberger le Gateway sur des Mac cloud professionnels bat en général le matériel personnel fragile. MACCOME fournit des nœuds bare-metal Mac Mini M4 / M4 Pro à Singapour, au Japon, en Corée, à Hong Kong, sur la côte est et la côte ouest des États-Unis. Après ce triage réseau, croisez SSH vs VNC avec le centre d’aide location Mac mini, puis finalisez sur les tarifs publics de location et les pages régionales.
Pilotez sur un hôte de test dédié, archivez les journaux, puis promouvez vers le dépôt compose partagé — évitez la connaissance tribale du seul network_mode.
Tout bind temporaire 0.0.0.0 exige un rollback documenté et une revue d’exposition ; le triage vise à aligner qui doit voir le plan de contrôle avec la conception des espaces de noms, pas à maximiser la surface d’écoute.
FAQ
En quoi cet article diffère-t-il du runbook Docker de production ?
La production couvre images, volumes et rollouts ; celui-ci couvre la joignabilité. Utilisez le centre d’aide location Mac mini avec le runbook de production conjointement.
La même matrice s’applique-t-elle sous WSL2 ?
Même ordre des opérations, autre chaîne localhost — empilez l’article de triage WSL2 par-dessus.
Où lire les régions et les conditions de location ?
Si le Gateway migre vers un Mac cloud, alignez-vous sur le guide multi-régions et les tarifs publics de location avant de figer la sortie SSH.