2026 : Webhooks OpenClaw via reverse proxy Nginx sur un Mac cloud Apple Silicon loué

Les SaaS qui déclenchent vos flux OpenClaw—webhooks CRM, suivi de tickets ou exécuteurs de jobs internes—ont besoin d'un point de terminaison HTTPS stable. Lier la passerelle à 127.0.0.1:18789 est la valeur sûre documentée dans le guide d'installation et déploiement, mais la boucle locale n'aide pas les appelants externes. Ce playbook 2026 montre comment placer Nginx sur un Mac mini M4 loué à Hong Kong, au Japon, en Corée, à Singapour ou aux États-Unis, terminer le TLS sur :443 et reverse-proxy vers la passerelle avec les bons en-têtes d'upgrade WebSocket. Vous obtiendrez un tableau comparatif des schémas d'entrée, une checklist de directives, un runbook en sept étapes et une FAQ alignée sur le JSON-LD. Pour les incidents multi-couches, croisez avec l'accès mesh Tailscale, les clés API dans launchd et le dépannage passerelle.

Pourquoi les webhooks imposent presque toujours un reverse proxy

Trois réalités d'ingénierie convergent sur les Mac cloud :

• Cycle de vie TLS — les webhooks publics attendent le port 443 avec des certificats valides renouvelés tous les 60 à 90 jours. Laisser OpenClaw parler TLS directement couple l'automatisation des certificats aux montées de version du runtime agent.
• Fidélité des en-têtes — les services amont envoient X-Forwarded-For, X-Request-Id et parfois des en-têtes HMAC personnalisés. Les supprimer casse la piste d'audit sauf si nginx les relaie à l'identique.
• Éventail WebSocket — la passerelle upgrade des connexions longues ; sans plomberie Upgrade, symptôme classique : « ça marche sur le LAN, 502 en prod ».
• Isolation opérationnelle — recharger nginx coûte moins cher que de redémarrer tout l'arbre OpenClaw lorsque vous affinez les suites TLS ou ajoutez des listes blanches IP pour les plages fournisseurs.

Topologie d'entrée : choisissez la ligne qui colle à votre modèle de menace

Schéma	Qui se connecte	Avantages	Inconvénients
Nginx public → 127.0.0.1:18789	Webhooks Internet	DNS + ACME simples ; les fournisseurs vous joignent sans VPN	Exige des règles WAF/IP disciplinées ; les scanners tapent :443 en continu.
Tailscale uniquement	Employés sur le tailnet	Pas de surface d'attaque publique ; ACL dans Tailscale	Les SaaS tiers ne rejoignent pas votre mesh sans canaux latéraux.
Hybride	Fournisseurs publics + mesh admin	Sépare plan de contrôle et plan de données	Deux piles TLS à surveiller ; documentez quel hôte mappe quel chemin.
Tunnel SSH depuis bastion	Intégrations héritées	Zéro port entrant sur le Mac	Ne scale pas aux pics de webhooks ; fragile lors des tempêtes de reconnexion.

Checklist des directives Nginx (amont HTTP/1.1)

Avant de coller une config de 200 lignes depuis un gist, vérifiez que votre bloc server {} contient :

Directive / réglage	Rôle	Piège typique
proxy_pass http://127.0.0.1:18789;	Envoyer le trafic déchiffré vers OpenClaw	Proxy par erreur vers localhost résolu d'abord en IPv6—épinglez explicitement la boucle IPv4.
proxy_set_header Host $host;	Conserver le nom d'hôte issu du SNI	Un Host codé en dur casse le routage multi-tenant quand vous ajoutez des hôtes de staging.
client_max_body_size	Autoriser des charges fournisseur > 1 Mo	La valeur par défaut 1m provoque des 413 opaques ressemblant à des bugs OpenClaw.
proxy_read_timeout	Allers-retours modèle longs	Trop bas → 504 alors que la passerelle stream encore des jetons.
limit_req_zone	Limiter les scanners bruyants	Oublier d'exempter les health checks et vous faites flapper vos propres moniteurs.

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

Map d'upgrade WebSocket et pourquoi l'ordre compte

La passerelle OpenClaw négocie des WebSockets pour les canaux de streaming. Nginx doit annoncer HTTP/1.1 vers l'amont et transmettre le jeton Upgrade du client. Le motif minimal :

proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;

Runbook en sept étapes sur un Mac cloud loué neuf

1. Prouver la passerelle en local — openclaw gateway status et curl -v http://127.0.0.1:18789/health (le chemin peut varier selon la version).
2. Installer nginx — Homebrew sur macOS : brew install nginx ; conservez la config sous /opt/homebrew/etc/nginx sur Apple Silicon.
3. Émettre le matériel TLS — client ACME de votre choix ; fixez les hooks de renouvellement dans launchd pour qu'ils tournent 15 minutes avant le pic, pas pendant.
4. Rédiger le bloc server — server_name séparés prod/staging ; ne réutilisez jamais le même port amont sans préfixes de chemin.
5. Recharger nginx — sudo nginx -t && sudo nginx -s reload ; capturez stderr dans les journaux CI.
6. Contrôle synthétique externe — depuis un point hors tailnet, curl -v https://hooks.example.com/openclaw avec un corps de test signé.
7. Documenter le rollback — lien symbolique vers la version précédente de la config ; épinglez openclaw gateway dans les notes upgrade/rollback.

Durcissement : listes blanches IP, Request-IDs et ordre launchd

Les nœuds MacXCode résident dans des préfixes de colocation connus—les éditeurs bloquent parfois des ASN entiers quand un voisin bruyant dérape. Si votre fournisseur propose des IP de sortie statiques, attachez-les aux paires allow/deny nginx et journalisez les refus dans /var/log/nginx/openclaw-denied.log pour corréler avec les logs OpenClaw structurés.

launchd doit démarrer nginx après que la session utilisateur propriétaire d'OpenClaw a fini son bootstrap, ou via un petit script d'attente jusqu'à ce que le TCP 18789 accepte—des bugs d'ordre font marquer l'amont comme down au cold boot.

FAQ : Nginx + OpenClaw sur instances macOS cloud

Question	Réponse
Puis-je réutiliser le même nom d'hôte pour le trafic SSH admin ?	Mieux vaut séparer—hooks. vs ssh.—pour simplifier l'histoire pare-feu ; voir l'aide pour la base SSH.
Ai-je encore besoin de Tailscale ?	Optionnel mais recommandé pour l'admin break-glass ; combinez avec le playbook mesh ci-dessus.
Où louer un Mac mini M4 près de mes appelants webhook ?	Comparez les régions sur les tarifs ; choisissez SG pour les callbacks SaaS APAC ou US quand les fournisseurs terminent sur US-East.

Pourquoi le Mac mini M4 bare metal gagne encore pour les agents proches du bord

Les charges OpenClaw mélangent du CPU en rafales (streaming de jetons), une utilisation NIC régulière (webhooks + appels modèle) et des I/O fichiers sensibles sous ~/.openclaw. La mémoire unifiée d'Apple Silicon garde les tampons des workers nginx et les processus passerelle Node/Swift colocalisés sans la sursouscription DRAM bruyante des petites VM cloud. La flotte bare metal MacXCode couvrant Hong Kong, le Japon, la Corée, Singapour et les États-Unis vous permet de placer le terminateur TLS physiquement proche de la majorité de vos appelants webhook tout en administrant la machine en SSH ou VNC lorsque vous devez ajuster des plists launchd interactivement.

En bref : traitez nginx comme la surface contractuelle publique et OpenClaw comme l'implémentation privée. Versionnez les deux configs, testez les reloads en staging, et gardez l'observabilité au niveau des passerelles API de production. Quand vous êtes prêt à dupliquer le motif dans une autre région, partez des tarifs et validez la connectivité avec les listes de l'aide.