Public concerné : vous faites tourner Gateway et des conteneurs CLI ou agents via Docker Compose ; les journaux montrent Gateway actif, mais les sous-sessions renvoient gateway closed (1008): pairing required, ou le RPC est sain mais le pairing reste bloqué. Message clé : ce n’est généralement pas réglé en « réinstallant l’image » — il s’agit le plus souvent d’un mélange de surface d’écoute, jeton, plages de proxys de confiance (trustedProxies) et d’URL inter-conteneurs ; cet article propose une matrice de symptômes, un fragment Compose, un runbook en six étapes et trois KPI. Rôles : à lire avec docker-setup.sh officiel + GHCR, pairing et jeton, et triage réseau Docker.
Le Gateway OpenClaw gère les connexions longues et le routage ; quand la CLI ou les outils « sous-session / sous-agent » parlent au Gateway en WebSocket/HTTP, le processus seul ne suffit — le client doit être une identité réseau jugée fiable côté Gateway et le pairing doit être valide. Docker place chaque service dans son propre espace de noms réseau : si vous mettez http://127.0.0.1:18789 dans le conteneur CLI, le trafic ne touche que ce conteneur, pas l’hôte ni un autre service.
http://openclaw-gateway:18789 (exemple).172.16.0.0/12, 10.0.0.0/8, le CIDR de votre réseau custom) pour évaluer correctement l’identité client.OPENCLAW_GATEWAY_TOKEN : Gateway et CLI lisent des chemins de montage ou des variables différents — oscillation entre parfois OK et 401/1008.Contrairement au guide d’installation trois OS, avec Compose l’enjeu n’est pas « quel OS » mais quel réseau est considéré comme fiable par quel conteneur.
Lors d’une reproduction, conservez côte à côte trois empreintes de journaux : lignes de démarrage Gateway, pile du sous-agent, sous-réseau du réseau attachable depuis docker inspect — bien des 1008, comparés ainsi, tombent sur « plage de confiance non déclarée », pas sur le modèle ni le canal.
| Instantané | Vérifier en priorité (ordre) | Cause fréquente |
|---|---|---|
| Le conteneur A n’atteint pas 127.0.0.1:18789 | Passer à une URL par nom de service, puis ports publiés et adresse d’écoute | Mauvaise sémantique de localhost |
| RPC healthy mais sessions_spawn renvoie 1008 | Liste de pairing → trustedProxies → triade bind | Voie sous-agent vue comme externe / non appairée |
| Journaux avec trusted proxy / pairing | Aligner CIDR Compose et config gateway.auth | Sous-réseau absent de l’ensemble de confiance |
| Uniquement après changement de version | Comparer anciens / nouveaux bind/auth par défaut et volume .openclaw migré | Defaults plus stricts ou pairing obsolète |
Rappel : même avec le flux docker-setup.sh officiel, revalidez noms de service et volumes selon ce contrat réseau — voir le runbook GHCR et Control UI.
| gateway.bind (concept) | Adapté à | Frottement Compose |
|---|---|---|
| loopback | Monoconteneur tout-en-un ou accès hôte seul | Les autres services ne peuvent pas l’utiliser comme loopback local |
| lan / écoute personnalisée | Plusieurs services, RPC inter-conteneurs | Jeton / auth et surface exposée à réduire |
| trusted reverse proxy | Nginx/Caddy devant | Doit coïncider avec la checklist reverse proxy pour les sources aval |
trustedProxies (CIDR d’exemple)Le tableau ci-dessous est pédagogique : lisez votre sous-réseau réel via docker network inspect, ne copiez pas aveuglément.
| Type de réseau | Exemple de CIDR | Votre action |
|---|---|---|
| Bridge Docker par défaut | 172.17.0.0/16 (selon env.) | Vérifier si l’IP source perçue par Gateway est dans cette plage |
| Réseau custom Compose | par ex. 172.18.0.0/16–172.30.x.x | Ajouter le sous-réseau entier à trustedProxies (pas des IP de conteneurs isolées) |
| overlay / swarm | alloué par l’orchestrateur | Même logique : cible « sous-réseau », pas liste d’IP de pods instables |
OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789 (nom = service Compose).OPENCLAW_GATEWAY_TOKEN identique des deux côtés ; avec jeton fichier, vérifier la lisibilité du montage.openclaw gateway status → openclaw doctor → reproduire l’action sous-agent et filtrer les logs sur 1008 / pairing.# Extrait d’exemple (noms de service et env en placeholder — remplacer avant prod)
services:
openclaw-gateway:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
openclaw-cli:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
networks:
oc-net: { driver: bridge }
gateway.auth.token ou hash d’env entre conteneurs ; bloquer la release si divergence.Ces KPI sont des suggestions d’observabilité ; ce n’est pas un SLA du projet amont.
« L’image démarre » ne suffit pas : sous-agents et outils de session exigent un Gateway stable, une identité réseau prévisible et des volumes de config cohérents. Itérer en docker run monoconteneur sur un portable diffère fortement d’une pile Compose fixe avec volumes persistants sur Mac distant dédié — ce dernier cas se rapproche des tâches sans surveillance et planifiées.
Les VPS éphémères ou bureaux partagés peuvent suffire à une démo mais manquent souvent de ligne de base disque et réseau ; quand Gateway, reverse proxy et automatisation doivent vivre dans une même zone de confiance et scaler vite, des nœuds Apple Silicon multi-régions avec formules mensuelles ou trimestrielles surpassent souvent l’empilement manuel d’hôtes Docker jetables. MACCOME propose isolation physique et six emplacements pour séparer « Gateway toujours actif » et « machine build/signature » ; ouvrez les tarifs et le centre d’aide, puis câblez les variables d’environnement selon ce runbook.
En déploiement : d’abord boucler les six étapes dans un seul projet Compose, puis évaluer si Gateway et autres charges méritent des nœuds distants séparés.
Questions fréquentes
Quand le code 1008 apparaît, dois-je tout de suite passer bind en LAN ?
Commencez par le tableau 1 : souvent URL par nom de service ou trustedProxies, pas une écoute élargie sans analyse. Si vous exposez davantage, alignez jeton et pare-feu. Pairing : liste pairing et jeton.
Puis-je utiliser curl vers 127.0.0.1:18789 sur l’hôte à la place d’une sonde dans le conteneur ?
C’est un bon test côté hôte, mais pas un substitut à la connectivité conteneur → Gateway par nom de service — les espaces de noms diffèrent. Aide : centre d’aide location Mac mini.
Cela double-t-il l’article « triage réseau Docker » ?
Le triage réseau couvre namespaces Compose et CLI ; l’article Docker officiel les chemins d’images. Ce guide relie explicitement pairing sous-agent et trustedProxies. Suite possible : vérification MCP et Skills.