Le Gateway semble sain dans le conteneur, mais derrière Nginx/Caddy vous voyez des 502, des handshakes WebSocket en échec ou des redirections infinies ? Cet article cible la couche reverse proxy en périphérie + terminaison TLS + upgrade WebSocket. Il complète le tri réseau Docker : là on parle de quels paquets voient quels pairs, ici de si la chaîne d'upgrade HTTP/1.1 et les chemins navigateur → Gateway sont corrects. Vous obtenez six pièges fréquents, deux tableaux topologie/symptômes, des extraits copiables, un runbook production en six étapes et trois métriques d'astreinte. Ensuite vous saurez s'il faut corriger les en-têtes Upgrade ou revenir à l'amont 127.0.0.1:18789.
proxy_pass sans HTTP/1.1 ni Upgrade : le navigateur WebSocket reçoit 400/502 en périphérie alors que les logs ressemblent à une panne Gateway./openclaw mais l'app émet encore des URL absolues depuis la racine, séparant assets statiques et chemins WS.proxy_read_timeout trop court : longues inférences ou rafales canal sont coupées silencieusement en périphérie, provoquant des tempêtes de reconnexion.Le tableau de topologie résume proxy même hôte, hôte séparé, sous-domaine et sous-chemin avant les en-têtes et la matrice de symptômes.
Reverse proxy sur le même hôte que le Gateway (Nginx/Caddy colocalisés) : le tri est le plus court, curl -v http://127.0.0.1:18789 valide l'amont localement. Un hôte proxy séparé ajoute des sauts : revérifier groupes de sécurité, DNS interne et SNI TLS. Les sous-domaines évitent souvent le retrait de chemin et les conflits Cookie Path ; les sous-chemins conviennent à un domaine d'entrée unique mais exigent un seul retrait de préfixe côté base OpenClaw et proxy, puis confirmation dans les outils que les URL WS visent toujours le wss:// attendu.
Dans les demandes de changement, joignez deux captures : URL finale dans la barre d'adresse et Request URL du handshake WebSocket dans l'onglet Network. Sans elles, la revue classe souvent à tort en timeout modèle ou OAuth canal. Avec un proxy HTTPS d'entreprise, séparez navigateur de bureau (injection PAC) et reverse proxy datacenter (souvent direct)—des symptômes divergents sont normaux.
HTTP/2 en périphérie avec amont HTTP/1.1 WebSocket reste courant en 2026 : vérifiez sur quel saut l'upgrade est autorisé. N'activez pas simultanément H2 forcé et réécritures WS personnalisées sans capture, sinon le tri devient de la divination.
| Topologie | Adapté à | Avantage ops | Pièges typiques |
|---|---|---|---|
| Même hôte + amont loopback | VPS unique / Mac distant toujours allumé | curl local pour tri ; TLS et processus partagent les journaux | Lier 0.0.0.0 élargit l'exposition—pare-feu obligatoire |
| Hôte proxy dédié | Plusieurs backends, bleu/vert, WAF devant | Edge découplé du calcul ; renouvellements centralisés | Routage interne, SNI, dérive des cibles de health-check |
| Sous-domaine | WS séparé du site principal | Sémantique de chemin claire ; règles CDN plus simples | Plusieurs certificats ; HSTS à revoir séparément |
| Sous-chemin | Domaine de marque unique | Charge cognitive faible pour l'utilisateur | Retrait de préfixe, boucles de redirection, racine d'assets fausse |
Dans tous les cas, la périphérie doit passer en HTTP/1.1, transmettre ou reconstruire Connection: upgrade et Upgrade: websocket, et fixer des timeouts de lecture au-dessus du percentile le plus lent du modèle. Le tableau sert de checklist de revue de code.
Souvent négligé : le buffering du proxy. proxy_buffering peut aider le débit des API classiques, mais le streaming ou les connexions longues ajoutent latence ou sensation de troncature ; avec canaux en flux ou comportement type SSE, chargez le staging avant de laisser le buffering par défaut.
| Contrôle | Points Nginx | Points Caddy |
|---|---|---|
| Version de protocole | proxy_http_version 1.1; | reverse_proxy en HTTP/1.1 par défaut ; surveiller les transports explicites |
| Chaîne Upgrade | Upgrade $http_upgrade; Connection "upgrade"; | Souvent automatique ; custom via header_up |
| Host et IP client | proxy_set_header Host $host;, X-Forwarded-* | header_up Host {host} ; faire confiance aux hops proxy |
| Connexions longues | proxy_read_timeout / send_timeout | transport http { read_timeout ... } (syntaxe selon version) |
| Gros corps | client_max_body_size | Directives de limite de corps (doc Caddy) |
# Extrait : reverse proxy vers Gateway local (port selon déploiement ; ex. 18789)
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
# Extrait : TLS automatique + amont WebSocket
openclaw.example.com {
reverse_proxy 127.0.0.1:18789 {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
}
}
Astuce : après modification, validez d'abord la sémantique de handshake en amont avec curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" http://127.0.0.1:18789/, puis testez le wss:// public ; sinon TLS et proxy se renvoient la balle.
Associez les symptômes à périphérie, amont ou configuration applicative avant de reconstruire les conteneurs. Si la table pointe vers le réseau conteneur, revenez au tri réseau Docker ; si les canaux sont connectés mais Slack/Telegram muets, voir dépannage des canaux.
Reproduction uniquement en prod alors que la préprod est propre : comparez la chaîne de certificats (même AC ?), la version des règles CDN/WAF, et si des branches map/if du proxy ciblent certains User-Agent. Beaucoup de 502 sont de faux positifs en périphérie, sans lien avec la version OpenClaw.
| Symptôme | Suspect prioritaire | Vérifier |
|---|---|---|
| 502 Bad Gateway | Amont non à l'écoute, pare-feu, mauvaise famille de socket | curl depuis le proxy ; error.log upstream timed out / refused |
| 413 Request Entity Too Large | client_max_body_size trop petit en périphérie | Augmenter et reload ; aligner limites CDN/WAF |
| WS pas en 101 | Upgrade manquant, chemin réécrit, redirection http→https casse le handshake | Statut dans Network ; ordre des locations et return 301 |
| Boucles de redirection | HTTPS forcé sans X-Forwarded-Proto | Assouplir temporairement HSTS en périphérie ; compléter les en-têtes forwarded |
| Alertes certificat / échecs partiels | Chaîne incomplète, mauvais SNI, certificats IP | openssl s_client -servername pour la chaîne ; NTP |
https://, sous-chemin ou non, WS partage-t-il l'hôte HTTP.18789).127.0.0.1:18789 ou VIP interne—hors latence publique pour distinguer lenteur edge vs Gateway.Avec des logs centralisés, croisez taux 5xx access proxy et taux d'erreurs applicatives Gateway : quand une seule courbe monte, la frontière de responsabilité est claire pour les post-mortems.
Les essais de proxy sur portable valident vite les extraits, mais veille, bascules VPN et uplinks domestiques instables transforment TLS et renouvellements en tâches manuelles ; difficile de contractualiser un SLO sur les 502. Placer reverse proxy + Gateway permanent sur des hôtes dédiés 24/7 (par ex. Mac cloud Apple Silicon loués ou VPS contrôlés) rend limites de débit, certificats et rétention de logs des changements standard. Sans entrée stable, lier OpenClaw à la CI et aux pipelines de signature reste peu auditable.
Les piles proxy maison suivent aussi les CVE OpenSSL, Nginx et OS ; les équipes qui attachent OpenClaw à la CI, à la signature et aux bots multi-canaux économisent souvent au total avec capacité dédiée prévisible et régions/durées de location claires plutôt qu'avec des expérimentations sur ligne résidentielle. Les Mac cloud MACCOME offrent plusieurs régions et des paliers de location nets comme machine propre derrière la terminaison TLS : ancrer d'abord répertoires et droits via le guide d'installation trois plateformes, puis héberger l'exécution de façon contractuelle avec les tarifs de location Mac mini et les pages région—Singapour, Tokyo, Séoul, Hong Kong, Virginie, Silicon Valley—tandis que l'edge ne porte que politique et observabilité.
Connexions, sessions et canaux : recherche par mot-clé dans le centre d'aide ; pour un tri visuel, combiner avec les articles bureau à distance et SSH/VNC.
Questions fréquentes
502 : proxy ou Docker en premier ?
curl de l'amont loopback depuis l'hôte proxy ; si échec, retour au tri Docker. Offres : tarifs location Mac mini.
Sous-chemin ou sous-domaine ?
Les sous-domaines évitent souvent les pièges de retrait ; les sous-chemins exigent des bases URL alignées. Installation : guide d'installation trois plateformes.
WebSocket tombe derrière un CDN ?
Désactiver le cache, allonger les timeouts d'inactivité, ou contourner le CDN sur un sous-domaine de contrôle. Canaux : dépannage Slack/Discord/Telegram.
Journaux et tickets : où ?
Les changements entreprise passent par les tickets du centre d'aide—évitez la moitié d'une config Nginx perdue dans le chat prod.