2026 OpenClaw Gateway : jumelage et conflits de jetons—onboarding bloqué, 1006/1008 et quand les variables d’environnement écrasent la configuration

Pourquoi changer gateway.auth.token ne supprime pas mismatch ? Six lectures erronées fréquentes

Dans le triage communautaire 2025–2026, les sujets jumelage et authentification du Gateway OpenClaw sont souvent confondus avec « le réseau est mort » : les journaux mélangent codes de fermeture et erreurs de modèle, ce qui oriente vers une panne LLM amont. Imprimez ces six pièges à côté de doctor post-install et santé Gateway sur la page d’accueil du wiki.

1. OPENCLAW_GATEWAY_TOKEN écrase silencieusement le fichier : les variables d’environnement injectées par conteneurs ou unités launchd priment ; gateway.auth.token sur disque est à jour mais le processus lit encore l’ancienne valeur, d’où « redémarrage et toujours mismatch ».
2. La CLI dans le conteneur pointe par défaut sur 127.0.0.1 : sans URL Gateway dans Compose vers le service openclaw-gateway, l’échec survient tôt au handshake ; les journaux ne montrent parfois que 1006/1008 sans erreur applicative, ce qui recoupe la checkliste de triage réseau Docker.
3. Des tâches lourdes avant la fin du jumelage : des étapes d’onboarding exigeant confirmation explicite ou persistance d’état ont été sautées par des pipelines scriptés ; le Gateway écoute mais la couche session n’est pas prête, d’où « parfois connecté, puis coupure immédiate ».
4. Chemins de configuration dupliqués : un arbre .openclaw sous le profil utilisateur et un autre sous le projet ; le chemin réellement chargé par la CLI n’est pas le fichier ouvert dans l’éditeur.
5. Anciens jetons dans les secrets CI : après rotation du jeton Gateway, les variables GitHub Actions ou GitLab CI ne sont pas synchronisées ; les jobs nocturnes inondent les journaux avec un mauvais jeton et masquent un vrai problème d’étiquettes de runner.
6. Traiter chaque 1006 comme un simple glitch réseau : sans distinguer « fermeture protocolaire propre » et « échec d’authentification ou de sous-protocole », on oscille entre l’article réseau et celui-ci sans converger.

Lien avec scripts d’installation officiels et chemins npm globaux : l’article d’installation garantit « binaires et versions Node sur PATH » ; celui-ci garantit « CLI et Gateway parlent le même jeton et le même endpoint WebSocket ». Les deux doivent figurer dans le même runbook de premier jour, dans l’ordre.

Tableau 1 : symptôme → pile probable → étape suivante (d’abord jumelage, puis réseau, puis modèles)

Cette matrice sert de premier triage : si une ligne correspond, obtenez une sortie de commande reproductible avant d’aller plus loin ; évitez de modifier jeton, Compose et reverse proxy simultanément.

Extraits exécutables : afficher « qui écrase le jeton » et « où la CLI se connecte vraiment »

Collez les sorties dans le ticket ; remplacez les racines placeholder par votre racine de configuration. Lors d’une revue avec volumes Docker et permissions, vérifiez que les montages ne masquent pas un nouveau volume avec un ancien répertoire de configuration.

Runbook en six étapes : de « pas de connexion » à une conclusion de jumelage reproductible

1. Geler les empreintes de version : noter CLI, tags d’image Gateway ou npm globals épinglés ; s’aligner sur l’article d’installation pour ne pas auto-mettre à jour pendant le debug.
2. Reproduire par couches : loopback direct → autre espace de noms réseau sur le même hôte (conteneur) → reverse proxy ; conserver un fragment de journal par couche montrant où ça casse.
3. Vider les sources d’override : retirer OPENCLAW_GATEWAY_TOKEN et injections similaires une par une, redémarrer jusqu’à environnement propre, puis rétablir une seule source de vérité dans le fichier.
4. Corriger l’URL WebSocket : dans les conteneurs, utiliser explicitement le nom de service et le bon port ; comparer à la règle « pas de 127.0.0.1 par défaut » de l’article réseau Docker.
5. Relancer le jumelage avec captures : suivre l’ordre d’onboarding officiel ; si doctor --deep existe dans votre build, l’utiliser dans la fenêtre de changement et archiver la sortie.
6. Écrire un test de régression : encoder le repro minimal en smoke CI (health seulement, pas de modèles lourds) pour empêcher le prochain merge Compose de réintroduire deux pistes de jetons.

Trois métriques « dures » pour tableaux de bord et fiches de changement

1. Nombre de sources de jeton : compter environnement, fichier de configuration, injection depuis le gestionnaire de secrets (préfixe de hash suffit) ; plus d’une source viole la politique—converger d’abord.
2. Taux de nouvelles tentatives de jumelage : journaliser retries d’onboarding versus succès ; un pic court signifie souvent double jeton ou mauvais hôte WebSocket, pas « le modèle est lent ».
3. Répartition 1006/1008 : agréger par semaine selon code de fermeture et mots-clés de journal voisins ; si 1008 monte avec des mots-clés d’auth, inspecter les en-têtes du reverse proxy avant d’ajouter du CPU.

Note d’alignement ingénierie (expérience communautaire et ops, pas benchmark de labo) : double piste de jetons et mauvaise cible loopback en conteneur restent en tête des échecs « premier déploiement » ; après ajout d’audits de variables d’environnement aux modèles de changement, le nombre moyen de tours de triage baisse souvent. Surtout, ces échecs sont faiblement corrélés au GHz ; plus de RAM seul ne répare pas un mauvais handshake.

Si le Gateway doit rester en ligne 24/7 sans lutter contre la veille d’un portable, placez « surface d’exécution dédiée stable » et « fenêtres de jumelage/mise à niveau » dans le même document SRE—aligné avec les pratiques entreprise de passerelles d’agents sur Mac distants.

Pourquoi « Gateway sur un portable perso » peine à tenir le rythme de jumelage production

Sur matériel personnel, le Gateway subit veille, bascules VPN et renouvellements de certificats d’entreprise, ce qui complique l’audit et la relecture de la machine à états de jumelage ; quand la rotation de jetons touche plusieurs CI humaines, les portables manquent aussi de nom d’hôte fixe et de frontière loopback stable, fragmentant les journaux.

Mettre le Gateway sur un Mac distant dédié redémarrable de façon prévisible, avec disque et journaux maîtrisés, sur le même réseau que les runners d’équipe, converge généralement plus vite que de migrer entre plusieurs machines perso. Les équipes qui ont besoin d’Apple Silicon en continu avec un modèle de secrets aligné sur la CI peuvent utiliser les nœuds multi-régions Mac mini M4 / M4 Pro et des durées de location flexibles chez MACCOME pour regrouper « triage de jumelage » et « exécution stable » sur une même facture et cadence de changement. Lisez d’abord la page tarifs publique, puis alignez l’exploitation sur la checkliste d’exploitation non assistée sur Mac distant.

Pilote : choisir un hôte distant dans la même région que le CI principal, n’y déployer que Gateway plus un smoke minimal, exécuter ce runbook en six étapes en revue bihebdomadaire, puis décider si le développement interactif migre vers la même topologie.