2026 — Tutoriel OpenClaw Webhooks et Hooks sur passerelle Mac physique distante : authentification par jeton, chemins reverse proxy et déclenchement CI — runbook reproductible (dépannage 401/404 + FAQ)
Les équipes plateforme qui déclenchent OpenClaw depuis GitHub, des ponts chat ou des bus internes voient souvent la CI au vert pendant que les webhooks de production échouent avec des 401/404 peu parlants. Ce guide s’adresse aux opérateurs qui veulent un runbook 2026 prêt à coller : aligner jetons Bearer et en-têtes transmis, faire correspondre les préfixes nginx/Caddy aux routes réellement enregistrées par OpenClaw, et câbler GitHub Actions pour rejouer le même contrat que votre bord — avec matrice de symptômes, sept étapes de vérification, seuils réutilisables et FAQ.
1. Pourquoi les webhooks échouent discrètement sur un Mac distant
Les Mac physiques distants sont d’excellentes cibles webhook — sockets Unix réels, cycles de vie launchd prévisibles, faible gigue vers une CI régionale — mais l’échec est rarement « OpenClaw est tombé ». C’est une dérive de contrat : l’URL invoquée par votre SaaS, le chemin réécrit par le proxy et l’ensemble d’en-têtes lus par le vérifieur sont trois documents qui divergent.
- Filtrage d’en-têtes : Les reverse proxies retirent souvent
Authorizationou des en-têtesX-*personnalisés sans les transmettre explicitement. La CI semble authentifiée ; l’amont ne voit jamais le jeton. - Double préfixe : Vous montez OpenClaw derrière
/agents/openclawalors que le handler a enregistré/hooks/...sans préfixe — des 404 qui disparaissent quand vous curl localhost sans le bord. - Dispersion des secrets : Jetons pivotés dans GitHub Secrets mais pas dans le vérifieur macOS (ou l’inverse) produisent des 401 intermittents corrélés au shard de pipeline. Associez ce runbook à une histoire de processus passerelle stable dans 2026 — OpenClaw Gateway 7×24 : déconnexions et dépannage du démon — install-daemon, launchd et openclaw health (parcours reproductible).
2. Matrice décisionnelle jeton & chemins
Servez-vous du tableau ci-dessous en revue de conception et après chaque upgrade proxy ou OpenClaw. Toute entrée de la colonne « Fragile » doit avoir un propriétaire nommé et un modèle de ticket de retour arrière.
| Dimension | Schéma fragile | Cible production |
|---|---|---|
| Transport du jeton | Chaîne de requête ?token= dans les journaux d’accès |
Authorization: Bearer ou en-tête de signature HMAC relayé de bout en bout |
| Mappage des chemins | location / générique sans règles strip/rewrite explicites |
Triplet documenté : chemin public → règle proxy → table de routes OpenClaw |
| Bord TLS | Webhook HTTP en clair « parce que VPN » | TLS sur Caddy/nginx ; mTLS optionnel pour bus internes |
| Déclencheur CI | curl ad hoc sur le laptop d’un mainteneur |
Workflow versionné postant la même enveloppe JSON que la production |
| Observabilité | Seulement les journaux OpenClaw — pas de log d’accès proxy | Corréler request_id bord ↔ appli avec rétention ≥ 60 s minimum |
Si vous amorcez encore le binaire passerelle et les canaux, suivez d’abord l’ordre d’installation multi-plateforme — Guide d'installation complet OpenClaw 2026 : Mac / Windows / Linux — puis revenez ici pour durcir l’entrée.
3. Runbook reproductible en sept étapes
Exécutez sur le Mac distant avec SSH admin. Gardez une transcription : les incidents webhook se gagnent sur des chemins et en-têtes au millimètre.
- Geler le contrat : Notez méthode, URL publique complète, schéma JSON et en-têtes requis (casse incluse). Collez le même bloc dans votre wiki interne et l’en-tête de commentaire du workflow GitHub.
- Prouver l’amont en local : Depuis le Mac,
curl -fsS -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:<port>/<chemin-documenté>avec un corps minimal. Attendez un HTTP 2xx avant de toucher au DNS. - Aligner le proxy : Dans nginx ou Caddy, terminez le TLS et mappez le chemin public vers le chemin amont enregistré par OpenClaw. Si vous utilisez
strip_prefixourewrite, journalisez$request_uriet l’URI amont pour un appel réussi et un appel en échec. - Transmettre les en-têtes d’auth : Passez explicitement
Authorizationet les en-têtes de signature fournisseur. Les réglages proxy « sûrs » par défaut les omettent souvent — première cause de 401 mystérieux. - Câbler GitHub Actions : Ajoutez un job sur
workflow_dispatchet sur tags de release, lisant les secretsOPENCLAW_WEBHOOK_URLetOPENCLAW_WEBHOOK_TOKEN, et échouant si le statut HTTP n’est pas 2xx. Faites correspondre la forme du JSON à la production. - Exercices 401/404 : Envoyez une requête au mauvais jeton (401 attendu) et une avec un segment de chemin en trop (404 attendu). Capturez les deux dans les journaux proxy et appli pour valider vos règles d’alerte.
- Paquet de retour arrière : Snapshot du fichier unit proxy, chemin des certificats et blocs
locationprécédents avant changement ; répétez une restauration en moins de quinze minutes chaque trimestre.
4. Seuils réutilisables
- SLO webhook synthétique : POST de bout en bout CI → 2xx en p95 2,5 s lorsque le Mac est sans charge interactive ; pagez si trois sondes consécutives échouent sur 5 minutes.
- Fenêtre de rotation : Après rotation de jeton, terminez mise à jour vérifieur + secret CI dans une fenêtre de 30 minutes unique ; rejouez le job synthétique avant de clôturer le ticket.
- Budget corrélation journaux : Conservez les identifiants de requête bord ↔ appli au moins 7 jours — suffisant pour déboguer un week-end de release sans snapshot disque complet.
- Discipline IPv6 : Si le DNS publie des AAAA, testez Actions depuis un runner compatible IPv6 ou épinglez IPv4 explicitement ; les vhosts divergents par famille sont une source récurrente de « ça marche sur mon curl » en 404.
5. FAQ
Pourquoi obtiens-je un HTTP 401 sur l’URL webhook alors que curl depuis le Mac fonctionne ?
Votre curl localhost inclut le bearer ; le chemin via load balancer peut supprimer Authorization ou réécrire vers un vhost aux identifiants différents. Diff les journaux d’accès proxy pour la présence d’en-tête (hachée) et confirmez qu’OpenClaw voit les mêmes noms d’en-tête que le vérifieur attend.
Pourquoi GitHub Actions renvoie 404 alors qu’un curl manuel vers le même hôte réussit ?
Incohérence de chemin et de famille DNS : Actions peut appeler /api/hooks/openclaw alors que le bord ne déclare que /hooks/openclaw, ou IPv6 tombe sur un server par défaut. Journalisez $request_uri à la terminaison TLS et comparez octet pour octet à votre curl qui marche.
Le jeton doit-il vivre uniquement dans GitHub Secrets ou aussi sur le Mac ?
La CI garde l’identifiant émetteur dans les secrets ; le Mac stocke le vérifieur via Trousseau, environnement launchd ou fichier root en 0600. Ne commitez aucune copie ; faites tourner les deux bouts dans la même fenêtre de maintenance.
À quelle fréquence rejouer un webhook synthétique après une mise à jour macOS ou OpenClaw ?
Dans les trente minutes suivant tout upgrade passerelle, proxy ou OS, lancez la sonde CI et un curl manuel via l’URL publique. Les tables d’enregistrement des hooks et imports dynamiques peuvent bouger sur un semver mineur — traitez les upgrades comme des migrations de schéma.
6. Pourquoi un Mac mini convient à ce bord d’automatisation
Les webhooks et workers de hooks demandent la même chose que tout démon de bord : une pile POSIX réelle, une supervision launchd prévisible et des outils TLS alignés sur vos runbooks. macOS fournit cela sans WSL ni surprises réseau conteneur — Homebrew, curl, Caddy ou nginx se comportent comme vos scripts le supposent.
Les Mac mini Apple Silicon ajoutent environ 4 W au repos et un refroidissement silencieux, ce qui compte lorsque la passerelle doit absorber le trafic CI 24/7. Gatekeeper, SIP et FileVault s’empilent proprement avec une conception webhook « TLS d’abord », sans sacrifier la vélocité d’automatisation pour un poste de bureau poreux.
Si vous voulez ce schéma d’entrée sur du matériel que vous contrôlez réellement — pas une VM imbriquée capricieuse — le Mac mini M4 reste l’un des meilleurs compromis prix/stabilité pour maîtriser la pile webhook complète. Découvrez les nœuds ZoneMac pour exécuter les hooks OpenClaw sur Apple Silicon dédié avec les mêmes commandes que vous avez validées ci-dessus.
Exécutez vos webhooks sur un Mac mini dédié
Nœuds macOS physiques pour passerelles OpenClaw, builds signés et hooks adjacents à la CI — la même pile TLS et launchd que ce runbook cible.