2026 OpenClaw derrière Nginx ou Caddy : TLS, WebSocket et allowedOrigins en production

Trois modes de défaillance dès que le HTTPS devient la norme

Premièrement, l’écart d’origine brise les garde-fous du navigateur. L’équipe teste sur http://127.0.0.1:18789, où l’origine localhost semble interchangeable. Les utilisateurs de production chargent https://agents.exemple.com. Les appels fetch, les flux EventSource et les outils d’administration empaquetés comparent l’origine de la page aux entrées de allowedOrigins. Un schéma absent, une barre oblique finale en trop, ou un nom d’hôte de préproduction oublié produisent des réponses 403 qui ressemblent à des échecs d’authentification alors que les jetons n’atteignent même pas la logique passerelle.

Deuxièmement, les upgrades WebSocket disparaissent dans le proxy. Les tableaux de bord OpenClaw et certains ponts de canaux supposent une voie HTTP/1.1 avec upgrade. Les recettes génériques de reverse proxy copiées depuis des hébergeurs de fichiers statiques omettent proxy_set_header Upgrade $http_upgrade; et Connection "upgrade". Les symptômes incluent des sockets qui s’ouvrent, émettent une trame, puis se réinitialisent parce que l’intermédiaire a mal tamponné la poignée de main ou a basculé vers HTTP/2 sur le même port sans chemin d’upgrade en clair.

Troisièmement, la double terminaison TLS ou de mauvaises ancres de confiance coûtent des journées entières. Certaines équipes activent HTTPS dans Node tout en terminant déjà chez Nginx, ce qui mène à des boucles de chiffrement incompatibles ou à des chaînes de certificats rejetées par les navigateurs. D’autres fois, le TLS est relayé en passthrough sans routage conscient du SNI, et les défis ACME échouent sans message limpide. Il faut une histoire unique de terminaison : les clients publics parlent TLS au proxy, le proxy parle HTTP clair vers le loopback, sauf si vous déployez volontairement du mTLS dans un maillage privé.

Quatrièmement, les avertissements de contenu mixte apparaissent lorsque les pages marketing restent en HTTP pendant que l’interface d’administration redirige vers HTTPS, ce qui pousse le navigateur à bloquer des sous-ressources. Cinquièmement, les proxies d’entreprise retirent parfois l’en-tête Sec-WebSocket-Protocol exigé par certains clients ; il faut des captures ou curl -v via le nom public pour comparer au comportement loopback. Sixièmement, la limitation de débit en périphérie renvoie des 429 que l’exploitation confond avec le throttling OpenClaw. Septièmement, les pare-feux d’application web bloquent parfois des corps JSON qui ressemblent à des sondes SSRF alors qu’il s’agit d’appels légitimes compatibles OpenAI, comme le détaille le guide de durcissement. Huitièmement, les enregistrements AAAA IPv6 pointent vers une machine obsolète tandis que l’IPv4 fonctionne, produisant des pannes WebSocket intermittentes corrélées au choix DNS plutôt qu’à un bogue applicatif. Neuvièmement, les contrôles de santé du répartiteur de charge frappent le mauvais hôte virtuel et marquent les nœuds comme dégradés malgré un processus actif sur le port 18789. Dixièmement, l’agrégation des journaux masque entièrement la couche proxy : l’astreinte suppose que openclaw doctor ment alors que nginx a déjà renvoyé 502 avant que la requête n’atteigne Node.

Modèle de menace : pourquoi la production veut un reverse proxy devant OpenClaw

Exposer Node directement sur le port 443 convient aux démos en laboratoire. La production gagne un périmètre dédié qui gère le renouvellement ACME, l’agrafe OCSP, la politique de chiffrement TLS et les limites de taille de requête avant que des clients non fiables n’atteignent votre passerelle. Ce périmètre accueille aussi le scoring anti-bot, les blocages GeoIP et les journaux d’accès centralisés attendus par la conformité.

Nginx reste le choix par défaut lorsque l’équipe l’exploite déjà pour d’autres services. Vous obtenez des directives map fines, des pages d’erreur personnalisées et des zones de limitation de débit matures. Le coût opérationnel est plus élevé : renouvellement des certificats et discipline de rechargement de configuration incombent à la plateforme.

Caddy séduit lorsque vous voulez HTTPS automatique avec peu de cérémonie et des Caddyfiles lisibles. Les compromis incluent des valeurs par défaut différentes pour le passage des en-têtes : il faut toujours vérifier le comportement WebSocket plutôt que de supposer une résolution magique.

OpenClaw ne doit faire confiance qu’au loopback ou à une socket Unix lorsque c’est possible. Évitez d’écouter publiquement sur 0.0.0.0:18789 dans les images cloud sauf si votre modèle de menace l’exige explicitement. Associez cette posture à la séparation des jetons de compatibilité et des secrets de canal décrite dans l’article de durcissement, afin qu’une règle de bord compromise n’équivaille pas à une prise de contrôle complète de la messagerie.

Documentez quels sauts peuvent ajouter X-Forwarded-For. Si OpenClaw ou des greffons dérivent l’adresse IP client pour l’audit, les en-têtes falsifiés depuis Internet aléatoire doivent être ignorés. Seul l’IP immédiate du proxy de confiance devrait enrichir les métadonnées de transmission. Cela recoupe l’ordre de vérification des webhooks : authentifier avant d’analyser de gros corps, comme le souligne la guidance SSRF de production.

Lorsque vous opérez plusieurs environnements, clonez les fragments proxy par nom d’hôte plutôt que de partager un bloc serveur wildcard qui sert par mégarde un certificat de préproduction au nom de production. Conservez des tableaux allowedOrigins spécifiques à l’environnement dans des magasins de secrets distincts pour éviter une coquille qui ouvre aux navigateurs de préproduction l’accès aux passerelles de production.

Alignez enfin l’observabilité : émettez des journaux structurés côté proxy et côté OpenClaw avec un identifiant de requête partagé lorsque c’est faisable. Cet identifiant rend évident qu’un délai d’attente s’est produit entre client et nginx ou entre nginx et Node.

Les bonnes pratiques industrielles sur le cycle de vie TLS — par exemple le NIST Special Publication 800-52 Rev. 2 pour les profils fédéraux — servent de référence à de nombreuses équipes privées lors du choix des suites de chiffrement et des fenêtres de rotation des certificats. Vous n’avez pas à copier chaque contrôle, mais documenter le profil suivi accélère les questionnaires sécurité et les passations d’astreinte.

Délais, tampons et repères d’observabilité

Réglez proxy_read_timeout et proxy_send_timeout à au moins 3600 secondes sur les routes qui portent des WebSockets interactifs ou du long polling depuis les clients assistant. Les valeurs par défaut adaptées aux API REST terminent des sessions pourtant saines. Pour les points de terminaison compat HTTP seuls, vous pouvez garder soixante à cent vingt secondes pour échouer vite sur des amonts bloqués.

Les limites de taille de corps doivent refléter les charges webhook ou média maximales acceptées. Si le guide de durcissement plafonne les récupérations média sortantes à vingt mégaoctets, alignez les limites entrantes pour qu’un attaquant ne puisse pas poster des gigaoctets qui épuisent le disque avant qu’OpenClaw ne rejette la requête.

Journalisez hebdomadairement la version de protocole TLS et la suite de chiffres en périphérie pour repérer les clients coincés sur des algorithmes dépréciés. Croisez ces métriques avec les journaux passerelle OpenClaw filtrés par famille de routes, comme le préconise l’article de production, afin que les revues sécurité voient les deux couches.

Exécutez des contrôles synthétiques toutes les cinq minutes : connexion TCP vers 443, poignée TLS complète, requête HTTP GET vers /health, et un upgrade WebSocket avec jeton de test prépartagé. Alerte lorsque une étape s’écarte de la latence de base de plus de trois écarts types.

Plan de capacité : attendez-vous à au moins deux connexions WebSocket concurrentes par opérateur actif aux heures ouvrées, plus le trafic de pointe lorsque l’intégration continue frappe les points de terminaison compat OpenAI. Traduisez cela en connexions worker et en limites de descripteurs de fichiers sur l’hôte proxy.

Documentez le retour arrière : conservez le fichier nginx ou Caddy précédent sous un chemin daté pour qu’un échec de nginx -t ne laisse pas l’équipe éditer la production sans point de restauration connu.

Publiez un schéma d’une page montrant DNS, répartiteur, proxy, OpenClaw loopback et chemins API sortants afin que les auditeurs voient d’un coup d’œil la frontière de confiance complète.

Complétez ces repères par une veille sur les notes de version OpenClaw : une modification subtile des chemins d’administration ou des en-têtes attendus peut rendre obsolète un fragment proxy qui fonctionnait hier. Intégrez la vérification de ces fragments à votre pipeline de déploiement, au même titre que les migrations de base ou les rotations de secrets.

Enfin, formez l’astreinte à lire les deux journaux en parallèle : la tentation de « tout attribuer à l’applicatif » disparaît lorsque la ligne proxy montre clairement un refus TLS ou une limite de corps dépassée avant toute logique Node.

FAQ, renvois croisés et quand le Mac distant hébergé simplifie la pile

Synthèse : terminez TLS au reverse proxy, relaissez explicitement les upgrades WebSocket, alignez allowedOrigins sur les origines réelles des navigateurs, et diagnostiquez par couches de la périphérie au loopback puis aux canaux.

Limite : vous opérez toujours certificats, configurations proxy et montées de version passerelle. Les équipes qui souhaitent des chaînes d’outils natives Apple colocalisées avec un ingress stable pour artefacts SFTP et passerelles longue durée louent souvent un Mac distant géré plutôt que de posséder chaque saut réseau.

SFTPMAC propose une capacité Mac distant avec connectivité suivie par des opérateurs, pour que vos ingénieurs se concentrent sur les flux OpenClaw plutôt que sur les tickets de colocation. Les mêmes machines qui reçoivent les téléversements d’intégration continue via SFTP peuvent héberger des passerelles avec des liaisons montantes prévisibles lorsque votre architecture exige un couplage serré entre sorties de build et automatisation.

Les flottes autogérées accumulent un temps caché : traquer les échecs ACME pendant les congés, réconcilier les diffs nginx entre régions, et prouver la fiabilité WebSocket aux clients entreprise. Lorsque ces coûts dépassent le prix d’un hébergement dédié, déplacer l’empreinte passerelle vers un fournisseur qui surveille alimentation, refroidissement et BGP amont devient un compromis rationnel.

Revisitez cette architecture chaque trimestre : les plages IP cloud publiques, les politiques d’inspection TLS en entreprise et les notes de version OpenClaw évoluent. Des fiches d’architecture décisionnelles légères empêchent le prochain arrivant de réduire vos timeouts proxy lors d’un nettoyage bienveillant.

Pour les studios et agences tech, l’intérêt du Mac distant hébergé réside aussi dans l’homogénéité : même matériel, même stack réseau, moins de surprises lorsque le créatif suivant branche une passerelle expérimentale derrière le même modèle proxy que la production cliente.