Faire tourner OpenClaw Gateway sur un petit VPS Linux derrière terminaison TLS est un schéma courant en 2026 : egress maîtrisé, cycle de vie systemd prévisible, une seule entrée HTTPS publique pour les bots. La surprise arrive quand un fournisseur exige que le callback webhook ne soit réussi que si le statut HTTP visible est 200 OK, alors que votre pile répond légitimement 202 Accepted pour accuser réception d’un travail mis en file. L’interface du vendeur affiche « livraison échouée », vos journaux Gateway montrent l’événement traité, et personne ne fait confiance à l’autre côté. Ce billet rassemble une chaîne de diagnostic reproductible, une matrice opérationnelle et des esquisses de bord Nginx (dont OpenResty) et Caddy pour arrêter de débattre la sémantique et livrer.
Chaîne de symptômes reproductible (curl d’abord, tableaux de bord ensuite)
Avant de toucher à la config, capturez exactement ce qu’Internet voit. Depuis un poste portable : curl -sS -D- -o /dev/null -X POST https://votre-hôte/gateway/webhook -H 'content-type: application/json' --data '{}' et vérifiez que la première ligne est HTTP/2 202 ou HTTP/1.1 202. S’il y a un proxy d’entreprise ou un CDN devant, répétez depuis l’intérieur du VPC et l’extérieur. Beaucoup d’échecs « aléatoires » sont simplement le worker de retry du fournisseur qui compare le code statut avec une égalité stricte. Quand vous séparez un second pipeline macOS des jobs Linux, les mêmes contraintes de statut réapparaissent sous d’autres masques : voir 2026 — sprint à court cycle : second pipeline macOS CI ou jobs sur agents Linux ? File d'attente, secrets, matrice et FAQ pour une matrice files / secrets utile lorsque les webhooks ne déclenchent « jamais » la bonne branche.
Matrice : où placer le contrat « 200 vs 202 » ?
Utilisez le tableau avant d’éditer la production. Préférez rapprocher le contrat de la logique métier quand c’est possible ; recourez au bord quand le fournisseur est figé et le calendrier ne l’est pas.
| Signal | Correctif privilégié | Compromis |
|---|---|---|
| La doc impose « doit renvoyer 200 » | Demander un réglage côté vendeur ; sinon normaliser au proxy uniquement pour ce chemin | La réécriture masque l’asynchronisme réel pour l’observateur externe |
| La Gateway peut accuser réception en synchrone | Renvoyer 200 avec un petit corps JSON après validation, mettre le travail en file en interne | Le handler doit rester rapide pour éviter les timeouts socket du fournisseur |
| Le load balancer marque les cibles unhealthy | Pointer les checks vers /healthz qui répond 200, jamais vers l’URL webhook |
Des routes séparées limitent les GET accidentels sur des POST |
| La supervision « clignote » quand les intégrations cassent | Séparer les moniteurs : POST synthétique signé vs simple battement GET | Plus de tableaux de bord, moins de faux positifs à 3 h du matin |
Esquisses au bord : Nginx (OpenResty) et Caddy
Nginx stock ne réécrit pas le statut amont sans phase supplémentaire (par ex. Lua dans OpenResty). Si vous exploitez déjà OpenResty, un header_filter_by_lua_block qui fixe ngx.status = 200 lorsque l’amont a renvoyé 202 est le patch le plus chirurgical. Avec Nginx « vanilla », les options tenables sont : isoler le fournisseur strict sur un sous-domaine dont l’amont renvoie déjà 200, ou placer un petit sidecar qui proxyfie et normalise les réponses.
# Dans location = /gateway/vendor-acme { ... } header_filter_by_lua_block { if ngx.status == 202 then ngx.status = 200 end }
Pour Caddy, les versions récentes exposent des branches reverse_proxy avec handle_response ; vérifiez votre mineure exacte, puis ajoutez une branche qui matche status 202 et réécrit la ligne de statut en 200 en conservant le corps déjà émis par la Gateway. Gardez TLS et compression identiques avant/après pour que les captures HAR restent comparables. Les topologies où un contrôleur léger sur VPS orchestre des agents distants posent les mêmes questions de chemins publics et de healthchecks : la check-list d’2026 — topologie hybride Jenkins : contrôleur sur VPS léger, agents Mac cloud en JNLP entrant, check-list d'un pool d'entreprise aide à éviter de mélanger sondes JNLP et callbacks HTTP sur le même hôte nominal sans le vouloir.
Sondes de santé qui cessent de se battre avec le chemin webhook
Un piège fréquent : pointer la sonde HTTP d’un load balancer cloud vers / ou pire vers l’URL webhook. Un GET sur une route réservée au POST peut renvoyer 405, que certains équilibreurs traitent comme panne dure et vident le trafic — puis les retries fournisseur s’empilent. Offrez aux sondes un fichier statique ennuyeux ou un petit JSON sur un autre chemin, le même certificat TLS, et journalisez les User-Agent des sondes à part pour prouver qu’aucun trafic synthétique ne recouvre les vrais callbacks.
Après tout changement, redémarrez en ordre : d’abord le reverse proxy, puis l’unité Gateway, et observez si les livraisons fournisseur en cours se reconnectent proprement. Croisez cinq minutes de journalctl -u votre.service -f avec les access logs du proxy dans le même fuseau pour éviter le classique « Grafana dit OK, Slack dit non » à cause d’un décalage d’horloge.
FAQ
HTTP 202 signifie-t-il que le bot a échoué ?
Non — en général cela veut dire « requête acceptée pour traitement ». Traitez 202 comme un reçu signé indiquant que le travail a rejoint une file. La question utile est de savoir si le SDK du fournisseur respecte la sémantique RFC.
Réécrire 202 en 200 est-il « mentir » aux auditeurs ?
Cela change le contrat externe. Documentez-le dans votre registre d’ADR, limitez-le au chemin le plus étroit, et gardez en interne des métriques de profondeur de file pour que l’observabilité reste honnête même si la ligne de statut est normalisée.
Et si TLS et le statut semblent tous deux incorrects ?
Réparez d’abord la chaîne de certificats : beaucoup de fournisseurs abandonnent avant d’analyser le JSON si TLS échoue, et l’équipe lit alors à tort une erreur de corps webhook.
Une fois le bord Linux stabilisé, livrez le natif Apple depuis le cloud
Ancrer OpenClaw Gateway sur un VPS sobre reste le bon endroit pour l’HTTPS toujours allumé et le fan-out des webhooks, mais la plupart des équipes ont encore besoin d’Apple Silicon pour Xcode, les simulateurs et les flux de signature qui n’ont rien à faire sur la même boîte bruyante en périphérie. Un Mac mini M4 cloud VPSSpark offre l’outil Unix natif, Homebrew et des conteneurs sans pilotes Windows exotiques, tandis que la mémoire unifiée d’Apple Silicon absorbe les pics Swift sans swap agressif.
macOS reste silencieux et prévisible pour les tâches sans affichage — une conso idle de l’ordre de ~4 W — et Gatekeeper plus SIP réduisent la surface malware par rapport à des hôtes de build Windows ad hoc, ce qui compte quand la même équipe tient à la fois le gateway Linux et les artefacts de release.
Si vous voulez le bord Linux pour les callbacks et un environnement Apple dédié pour les builds sans acheter du métal tout de suite, le Mac mini M4 cloud VPSSpark est un découpage « split plane » pragmatique — parcourir les forfaits maintenant pour garder des webhooks honnêtes pendant que vos binaires se compilent là où ils ont leur place.