1. Décomposition douloureuse : curl du mauvais espace de noms vous ment
(1) Confusion de bouclage WS : ws://127.0.0.1:18789 est correct sur l'hôte lorsque le port est publié, mais à l'intérieur de un autre conteneur il boucle sur lui-même. Si la passerelle écoute le nom du service openclaw-gateway, le code 127.0.0.1 codé en dur ne l'atteint jamais. (2) L'appariement vs le jeton : pairing required est un problème de session d'autorisation ; token mismatch est une incompatibilité secrète ; les mélanger crée des modifications aléatoires. (3) L'environnement remplace les fichiers : une seule ligne OPENCLAW_GATEWAY_TOKEN dans Compose peut remplacer le gateway.auth.token monté, produisant "J'ai modifié JSON mais rien n'a bougé". (4) Double pile Mac distant : launchd plus compose partageant la même déclaration de port ou le même répertoire d'état génère des échecs silencieux intermittents.
2. Matrice de symptômes : triage du transport avant l'authentification avant les canaux
| Signal | Hypothèse | Première action |
|---|---|---|
1006 / réinitialisation |
Mauvais hôte ou conflit de port | À partir du même espace de noms réseau que la CLI, exécutez nc -vz host port |
1008 pairing required |
Appairage incomplet | Ouvrir l'interface utilisateur de contrôle, émettre le code d'appariement, exécuter la commande de paire CLI |
token mismatch |
Doubles sources de vérité | Imprimer l'environnement à l'intérieur du conteneur CLI ; réconcilier avec le volume JSON |
| Succès instable | Deux instances en course sur l'état | docker ps plus table de volume ; réduire à une seule passerelle |
3. Runbook en cinq étapes : du ping à une sonde de canaux réussie
- Geler les espaces de noms : documentez si la CLI s'exécute sur l'hôte, le side-car ou le coureur CI ; dessinez une flèche du client à l'auditeur.
- Base de passerelle explicite : définissez
OPENCLAW_GATEWAY_URL(ou votre équivalent documenté) suropenclaw-gateway:18789ou sur le port hôte publié - ne supposez jamais 127.0.0.1 dans les espaces de noms. - Porte d'appairage : terminez l'appairage avant de tester les canaux professionnels ; conserver deux modèles de ticket pour "non apparié" ou "mauvais jeton".
- Source de vérité à jeton unique: Choisissez le fichier env ou comme canonique ; faites correspondre l'autre ou supprimez-le.
- Acceptez avec la sonde de canaux : exécutez une sonde réussie à partir du même environnement et joignez les journaux et l'extrait de composition à la demande de modification.
4. Lorsque network_mode : "service:openclaw-gateway" est justifié
Utilisez-le lorsque la CLI doit partager l'espace de noms du réseau de la passerelle pour éviter un DNS fragile sous le pont par défaut. Le coût prête à confusion avec la sémantique de localhost : schématisez-le. Alternative : conservez CLI sur l'hôte et pointez WS vers le port hôte publié, en alignant la terminaison TLS sur le proxy inverse.
5. Seuils citables (remplacez par vos mesures)
Numéros de qualité discussion :
- Si le succès de la connexion TCP à partir de l'espace de noms CLI tombe en dessous de 97 % sur 100 sondes, arrêtez le travail des fonctionnalités et corrigez d'abord le DNS, les noms de service ou les ports publiés.
- Si vous voyez plus de trois
token mismatchévénements à l'intérieur d'une seule fenêtre d'appariement, supposez deux sources jusqu'à preuve du contraire. - Si l'attente de verrouillage sur un répertoire d'état partagé dépasse 2,5 s à p95 sur un Mac distant, divisez les volumes ou déplacez la CLI dans un side-car dédié.
6. Lecture des journaux openclaw en trois couches
Filtrer d'abord les lignes de transport, puis l'authentification et l'appariement, puis les lignes spécifiques au canal. Joignez trois captures d'écran au ticket au lieu d'un simple récit. Lorsqu'il est lu avec l'article officiel install.sh, traitez l'ordre d'installation et l'alignement du réseau comme deux portes d'acceptation distinctes.
| Couche | Question | Exemple de réussite |
|---|---|---|
| Transport L1 | La prise de contact WS a-t-elle réussi ? | Pas d'explication 1006/1008 |
| Authentification L2 | Le jeton et l'appairage sont-ils cohérents ? | Aucune boucle non autorisée après l'appairage |
| Canaux L3 | Le canal est-il en ligne ? | channels probe renvoie un état interprétable |
7. Mac distant : launchd vs Docker pour les ports et les volumes
Document qui possède le port 18789, si l'état est un montage lié ou un volume nommé, et quelle unité s'arrête en premier lors des mises à niveau. Associez-le au guide SSH vs VNC pour séparer les modifications VNC interactives des rouleaux de composition sans surveillance.
8. FAQ
Extra_hosts va-t-il tout réparer ? Parfois, mais si la cause première est des sources à double jeton, extra_hosts ne fait que remanier les modes de défaillance.
Lier la passerelle à 0.0.0.0 ? Lisez d'abord l'article sur la surface d'attaque ; l'exposition publique n'est pas la réponse par défaut.
Conflit avec le flux install.sh ? Non : install.sh établit l'ordre de base ; cet article se concentre sur la mise en réseau Docker et l'alignement de l'authentification.
9. Étude de cas : les journaux indiquent écouter, CLI toujours 1008
Un mode d'échec fréquent en 2026 est l'écoute de la passerelle dans le conteneur A tandis que les développeurs exécutent la CLI dans le conteneur B avec ws://127.0.0.1. C'est évident sur le papier mais coûteux dans les configurations multi-repo. Placez la phrase "espace de noms qui exécute openclaw" en haut du README et ajoutez un CI smoke qui exécute la sonde à partir du conteneur d'exécution.
Une deuxième classe est oubliée OPENCLAW_GATEWAY_TOKEN lignes dans les fichiers de remplacement. Choisissez une discipline d'environnement ou de fichier et ajoutez un élément de liste de contrôle PR pour les différences d'environnement de jeton.
Une troisième classe atteint les Mac distants lorsque Time Machine ou un logiciel de synchronisation met en miroir les répertoires d'état, créant ainsi des secondes passerelles fantômes. Marquez les répertoires d’état comme non synchronisés ou consolidez-les sur un nœud distant dédié.
Associez l'article sur la migration pour séparer les exercices de « migration de machine » des exercices de « composition de reconstruction » ; les mélanger brouille les histoires de restauration.
Docker est une livraison reproductible sous des contraintes plus fortes, et non une simplicité automatique. Joignez des extraits de composition, d'impression d'environnement, de sortie nc et de journal à trois couches avant de revendiquer la préparation à la production.
10. n8n et entrée webhook
Lorsque n8n rappelle dans votre pile, le propriétaire de l'entrée HTTP doit correspondre au propriétaire du jeton WS. Divisez les enquêtes HTTP 502 des tickets WS 1008 en utilisant des titres distincts.
11. Discipline de mise à niveau : une seule passerelle d'abord
Lors des dernières versions, réduisez-vous à une seule passerelle et une seule CLI avant de réactiver HA. Les volumes à moitié mis à niveau produisent des schémas à moitié cohérents ; joindre la sortie du médecin à l'enregistrement de modification.
12. Clôture : Docker prouve la répétabilité, le Mac distant porte le SLO
(1) Limites : Sans documenter les espaces de noms CLI, le dépannage de Docker devient exponentiel ; les sources à double jeton rendent les modifications de configuration aléatoires.
(2) Pourquoi les pools Mac distants sont utiles : les hôtes dédiés épinglent les versions, les volumes et les contrôles de santé loin des ordinateurs portables des développeurs.
(3) Ajustement MACGPU : si vous souhaitez un essai à faible friction de passerelles Mac distantes alignées au lieu de serveurs d'ordinateurs portables, MACGPU propose des nœuds louables et des points d'entrée d'aide publique ; le CTA ci-dessous renvoie à des plans sans connexion.
(4) Porte finale : ne prétendez pas être prêt à la production sans un channels probe réussi ainsi qu'une preuve d'alignement de composition/env/jeton.
13. Liens pour installer la matrice et install.sh
Si install.sh n'est pas encore vert, lisez d'abord cet article. S'il est vert mais que Docker échoue, redémarrez à partir de la matrice L1 ici. La matrice à trois piles permet de décider si la CLI appartient à l'hôte ou à un side-car.
14. Observabilité : annotez le rayon d'explosion par projet de composition
Lorsque plusieurs projets de composition partagent un hôte, indiquez quel projet possède le port 18789 et lequel possède l'entrée du webhook. Les personnes de garde devraient ouvrir une seule page avec cette carte au lieu de consulter l'historique de Slack.
15. Note de sécurité : jeton dans les fichiers env vs secrets
Les variables d'environnement apparaissent dans les listes de processus et les vidages sur incident. Si votre modèle de menace l'interdit, préférez les fichiers secrets avec les autorisations de volume correctes et supprimez les doublons d'environnement. Alignez-vous avec le guide de surface d'attaque Gateway pour les adresses de liaison et les proxys inverses.
16. Parité CI : reproduire l'espace de noms défaillant dans GitHub Actions
De nombreuses équipes ne reproduisent les problèmes d'OpenClaw que sur les ordinateurs portables. Ajoutez un travail qui crée le même projet de composition et exécute docker compose run --rm openclaw-cli openclaw channels probe afin que les régressions dans les URL WS soient interceptées avant la fusion. Mettez en cache les images de manière judicieuse, mais actualisez toujours les balises lorsque les correctifs de sécurité arrivent. Si vos exécuteurs CI ne peuvent pas résoudre les noms de service Docker, documentez explicitement cette limitation au lieu de revenir silencieusement à 127.0.0.1, ce qui masque le mode d'échec de production.
17. Proxy inverses et en-têtes de mise à niveau WebSocket
Lorsque TLS se termine sur nginx ou Caddy, vérifiez les en-têtes de mise à niveau, les délais d'inactivité et les paramètres de mise en mémoire tampon. Un proxy qui met en mémoire tampon les trames WebSocket peut ressembler à une fermeture aléatoire 1006 sous charge. Capturez les journaux d'accès au proxy aux côtés des journaux OpenClaw et corrélez les horodatages. Si vous mettez fin à TLS sur l'hôte alors que Gateway reste en HTTP simple dans Docker, conservez ce diagramme dans le référentiel afin que les nouvelles recrues ne réintroduisent pas le double cryptage ou un schéma erroné dans OPENCLAW_GATEWAY_URL.
18. Modèle de transfert de Runbook pour les astreintes
Collez les éléments suivants dans votre modèle d'incident : composez le nom du projet, les balises d'image, l'URL WS vue de l'espace de noms défaillant, la sortie de env grep pour les variables OPENCLAW_, la sortie du chemin de volume pour gateway.auth.token, le résultat de nc et les vingt dernières lignes de journaux de passerelle filtrées par niveau. Lorsque la législation ou l'approvisionnement bloque les GPU cloud, un pool Mac distant documenté reste un moyen pragmatique d'ajouter une capacité Apple Silicon stable pour les agents toujours actifs sans achats de capitaux.
19. L'asymétrie de version entre les images CLI et Gateway
Le fractionnement de la CLI et de la passerelle entre différentes balises d'image est valide, mais uniquement lorsque vos notes de version prennent explicitement en charge cette matrice. Si la CLI ajoute un champ de prise de contact que la construction de la passerelle ne comprend pas, vous verrez des déconnexions opaques qui ressemblent à des bogues réseau. Épinglez les deux images sur le même train de diffusion lors d'incidents, puis divisez-les en deux. Enregistrez les résumés dans votre document d'incident, pas seulement les balises flottantes. Pour les flottes de Mac distantes, automatisez une vérification hebdomadaire afin que la dérive ne s'accumule pas silencieusement pendant que les ingénieurs se concentrent sur le travail sur les fonctionnalités.
20. La dette de documentation est une dette opérationnelle
Chaque heure passée à redécouvrir la sémantique 127.0.0.1 est une heure non consacrée à l'amélioration des invites ou des outils. Investissez une fois dans une topologie d'une page et associez-la à partir du README, des runbooks et de l'intégration. Lorsque les dirigeants demandent si OpenClaw est prêt pour la production, remettez-leur le journal de sonde et le résumé de composition, et non une assurance verbale. La location de Mac à distance ne supprime pas le besoin de bons documents, mais elle vous donne un endroit stable pour héberger la pile canonique qui correspond à ce que la production exécute réellement.
21. Invites d'examen post-incident
Après avoir clôturé un incident de passerelle, répondez à cinq questions par écrit : quel espace de noms a initié la CLI, quel fichier ou variable d'environnement a finalement détenu le jeton, si le couplage a été tenté avant les modifications du jeton, si un proxy était présent sur le chemin et quel résumé de composition était actif pendant la panne. L'absence d'une réponse signifie généralement que l'incident se répétera sous une chaîne de symptômes différente le trimestre prochain.
Enfin, traitez les mises à niveau mineures de macOS sur les hôtes distants comme des problèmes semver pour votre pile : réexécutez les vérifications de sonde et de nc après chaque fenêtre de mise à niveau avant de déclarer à nouveau la flotte saine.