OpenClaw : callbacks et runners Mac cloud — validation, isolation, idempotence et audit

Points clés

Authentifier avant le travail coûteux : HMAC en temps constant (ou mTLS), fenêtre d’horloge courte, option nonce anti-rejeu — mieux vaut cela que « faire confiance au JSON ».
Isoler l’exécution : le gestionnaire HTTP ne fait qu’accepter ; il pousse des unités de travail opaques vers une file privée ; les runners tirent depuis le réseau interne, sans exécuter de shell à partir des champs du webhook.
L’idempotence est un contrat de données : event_id stable, magasin de déduplication, retries bornés avec jitter ; les doublons deviennent une métrique, pas une surprise dans les logs seuls.
Les champs d’audit sont volontairement ennuyeux : qui a invoqué quoi, sur quel bail de runner, avec quel digest d’artefact — mêmes colonnes des journaux HTTP aux sorties CI.

Poste de travail avec écrans de code et supervision d’automatisation — Illustration générique : une chaîne webhook → file → runner suppose des attaquants capables de rejouer des charges et des échecs partiels.

1. Validation entrante à faible confiance

Traitez chaque POST comme des octets non fiables jusqu’à preuve cryptographique. Vérifiez la signature sur le corps brut (avant toute transformation JSON), refusez les enveloppes sans horodatage, et gardez une fenêtre glissante courte pour le décalage Date ou X-OpenClaw-Timestamp. Répondez 401 pour signature invalide et 400 pour enveloppe mal formée afin de partitionner les alertes. Si TLS se termine sur un proxy, documentez où tourne le vérificateur pour éviter qu’on ne « corrige la latence » en contournant la vérification.

Limitez le débit par adresse IP et par identifiant de clé de signature : une clé compromise ne doit pas saturer la flotte. Ne logguez que des empreintes tronquées des secrets et du corps. Pour la propagation d’identité d’artefact dans la chaîne de build, le même rigueur que sur la frontière HTTP s’applique — voir CI iOS/macOS sur Mac cloud Apple Silicon : codesign, Notarization, stapler et frontières du trousseau — pipelines reproductibles et tableau de codes de rejet.

2. Isolation : passerelle → file → runner

Le worker HTTP doit rester minimal : valider, normaliser vers un schéma interne, écrire dans une file durable, répondre 202 avec un identifiant de corrélation. Les étapes lourdes — git fetch, résolveurs de dépendances, xcodebuild — appartiennent à des baux de runner éphémères dont la sortie réseau est bornée aux registres autorisés. Interdiction d’instancier des commandes shell à partir de champs fournis par le webhook.

Quand les rafales arrivent plus vite que le warm-up des machines, la planification de capacité rejoint les sujets déjà traités côté conteneurs sur Mac cloud — Docker de production sur Mac cloud Apple Silicon : images arm64/amd64, bind mounts et cache de build — guide de dépannage (limites des forfaits) rappelle les limites disque et I/O qui amplifient les files d’attente. Si vos runners passent par tunnel ou DNS scindé, validez MTU et chemins symétriques tôt : WireGuard et appairage passerelle pour le contrôle à distance transfrontalier : dépannage MTU, routage asymétrique, DNS en split et observation de la latence (région et dimensionnement Mac cloud) couvre les divergences entre « webhook reçu » et « job réellement exécuté ».

3. Idempotence, retries et messages toxiques

Supposez une livraison au moins une fois. Exigez un event_id (ou un hachage du corps canonique) et stockez l’issue dans une table de déduplication dont le TTL couvre l’horizon de retry. Côté client, backoff exponentiel avec jitter ; côté serveur, réponse identique aux doublons qu’au premier succès pour simplifier les réconciliateurs amont.

Définissez un nombre maximal de réceptions par message de file et un flux en lettres mortes avec l’enveloppe signée jointe : les post-mortems ont besoin des métadonnées, pas seulement du JSON interne. Comptabilisez duplicate_suppressed séparément de validation_failed pour garder les runbooks courts.

4. Observabilité et champs d’audit (mémo)

Portez les mêmes identifiants dans les journaux d’accès HTTP, les enregistrements de file et la sortie standard du runner. Colonnes utiles :

Champ	Où il vit	Intérêt audit
`trace_id` / `correlation_id`	Edge, appli, file, runner	Reconstruction bout à bout sans ne joindre que sur l’horodatage
`event_id` + `delivery_attempt`	Enveloppe webhook, DLQ	Preuve de suppression des doublons et de la politique de retry
`signing_key_id`	Vérificateur, journal d’audit	Rotation des clés et rayon d’explosion en cas de compromission
`runner_lease_id` / classe d’hôte	Ordonnanceur, métadonnées CI	Lie l’automatisation à la capacité louée
`git_ref` / digest d’artefact	Enregistrement de build	Réexécutabilité pour les revues sécurité
`policy_version`	Empreinte de config passerelle	Explique pourquoi une requête acceptée hier échoue aujourd’hui

Préférez une ligne JSON structurée par transition d’état (received, enqueued, leased, succeeded, failed_terminal). Évitez les données personnelles dans les champs dérivés du webhook ; mappez les acteurs vers des identifiants opaques côté IdP.

Métriques honnêtes sous retry

Style RED sur la surface HTTP : débit, ratio d’erreurs découpé 4xx / 5xx, latence jusqu’à la mise en file (pas la durée de build entière). Surveillez l’âge du message le plus ancien dans la file séparément du taux d’occupation CPU des runners pour distinguer « ingress sain mais capacité affamée » de « vérification qui fond le CPU ». Les suppressions de doublons et la profondeur de DLQ doivent être des jauges de première classe ; alertez sur une croissance soutenue plutôt que sur un pic isolé, car les rafales de retry sont normales après incident.

5. Conclusion

Les chaînes de callbacks échouent de façons banaires : dérive d’horloge, double livraison, runners qui démarrent sans la même vue DNS que la passerelle. Ancrez vérification, handlers « enqueue-only », idempotence et corrélation partagée avant d’optimiser les minutes de build : l’automatisation OpenClaw reste lisible pour la sécurité et pour vous à trois heures du matin.