OpenClaw gateway circuit breakers for flaky upstream tools: failure thresholds, half-open probes, metrics hooks, coordination with HTTP 429 Retry-After and token throttles, read-timeout diagnostics, health monitoring, and macOS rehearsal on cloud Mac mini

Les passerelles d'agent s'étendent vers des modèles, des magasins de vecteurs et des outils HTTP sur mesure ; lorsqu'un système en amont vacille, les tentatives naïves amplifient les pannes en multipliant le trafic vers une dépendance malade. Dans 2026, production Griffe Ouverte les piles associent un recul exponentiel avec disjoncteurs qui passent de fermé à ouvert après des budgets d'erreur limités, puis sondent prudemment dans les états semi-ouverts avant d'admettre à nouveau la pleine charge. Cet article définit les seuils pratiques, la cadence semi-ouverte, les métriques Prometheus que vous devez exporter, la manière dont les disjoncteurs se coordonnent avec 429 réponses portant Retry-After, comment ils complètent les budgets de jetons par locataire et comment les diagnostics de blocage du délai de lecture ainsi que les contrôles de santé synthétiques empêchent les opérateurs d'interpréter à tort un disjoncteur comme un trafic sain. Lire à côté fournisseur 429 Traitement de la nouvelle tentative-après, Accélérateurs de l'outil de budget symbolique, diagnostic de blocage du délai de lecture de la passerelle, et surveillance de l'état de la passerelle et temps de disponibilité Ainsi, les tentatives, les budgets, les délais d'attente et les sondes racontent une histoire cohérente.

Contexte tarifaire : répétition du comportement de la passerelle sur un site dédié Mac-mini depuis MacHTML près 16,9 $ par jour est moins cher qu'un incident lorsque des tempêtes semi-ouvertes endommagent à nouveau un amont déjà en train de se remettre d'une surcharge.

Pourquoi les tentatives sans disjoncteurs échouent aux opérations

Les nouvelles tentatives supposent des erreurs transitoires. Lorsqu'un système en amont connaît une défaillance prolongée (tempêtes de verrouillage de base de données, expiration de certificat ou perte de paquets régionaux), chaque nouvelle tentative ajoute de la charge exactement là où le système étouffe déjà. Les passerelles voient une diffusion amplifiée car un seul tour d'agent peut appeler six outils en parallèle ; si chaque outil réessaye trois fois à 200 ms intervalles, vous pouvez mettre en file d'attente 18 appels échoués par geste de l'utilisateur. Les disjoncteurs limitent ces dommages en convertissant les pannes répétées en erreurs locales rapides jusqu'à ce qu'une période de refroidissement s'écoule.

Les déploiements OpenClaw mélangent également des outils HTTP synchrones avec des appels de modèle de streaming. Les disjoncteurs doivent être définis par dépendance et non par processus : l'ouverture du disjoncteur pour une API de recherche CRM irrégulière ne devrait pas bloquer un outil de calcul sain qui partage le même pool de travailleurs, à moins qu'ils ne se disputent des sockets identiques. Clés de disjoncteur d'espace de noms avec identifiant du fournisseur, région et empreinte digitale des informations d'identification pour éviter tout couplage accidentel.

Cycles de vie fermés, ouverts et semi-ouverts

À l'état fermé, toutes les demandes transitent vers l'amont avec une instrumentation normale. Une fois que les échecs franchissent un seuil, le disjoncteur s'ouvre : les appels suivants échouent rapidement avec une erreur structurée que les agents peuvent interpréter comme une « dépendance indisponible », permettant aux planificateurs de niveau supérieur de changer de stratégie. Après une mise en veille configurée (souvent dérivée du temps de récupération historique de p95), le disjoncteur entre en demi-ouverture et admet un filet de sondes. Les sondes réussies ferment le circuit ; les échecs le rouvrent avec un multiplicateur d’intervalle plus long.

enum BreakerState { Closed, Open, HalfOpen }

func (b *Breaker) Allow(now time.Time) bool {
  switch b.state {
  case Open:
    if now.Sub(b.openedAt) < b.cooldown { return false }
    b.state = HalfOpen
    b.probeBudget = 1
    return true
  case HalfOpen:
    return b.probeBudget > 0
  default:
    return true
  }
}

Seuils de défaillance et fenêtres glissantes

Choisissez des seuils à partir du trafic observé, et non des valeurs par défaut copiées à partir des articles de blog. Un point de départ pragmatique pour les outils HTTP est une fenêtre glissante de 30 secondes avec au moins 20 tentatives enregistrées avant d’évaluer les ratios. Ouvrez le disjoncteur soit 5 échecs de transport consécutifs ou lorsque plus de 60 pour cent des appels échantillonnés renvoient 5xx dans la fenêtre. Les compteurs consécutifs détectent rapidement les pannes totales, tandis que les compteurs ratio détectent les dégradations élevées mais partielles.

Pour les itinéraires de modèle de streaming, classez soigneusement les échecs : une réinitialisation à mi-parcours après la livraison des jetons peut constituer un litige de facturation, et non un incident digne d'être résolu. Conservez des compteurs séparés pour les « en-têtes jamais arrivés » et pour « flux interrompu après 40 % d'achèvement ».

Sondes semi-ouvertes et plafonds de concurrence

L'entrouverte est la phase la plus risquée : trop de sondes recréent le troupeau tonitruant auquel vous avez tenté de vous échapper. Boucher les sondes 1 appel en vol tous les 250 ms par dépendance, instable jusqu'à 50 ms, et nécessitent deux succès consécutifs sur différents threads de travail avant de se fermer complètement. Si votre passerelle fonctionne 12 les travailleurs, sérialisent les sondes via un canal d'élection de leader ou une petite cellule Redis afin que chaque hôte ne lance pas de sondes indépendantes.

Crochets de métriques Prometheus et câblage SLO

Exporter au minimum : breaker_state comme une jauge étiquetée par dépendance, breaker_transitions_total comptoir avec étiquettes pour les états de et vers, breaker_rejections_total pour des échecs rapides lorsqu'il est ouvert, et breaker_probe_latency_ms histogramme avec des compartiments délimités entre 25 ms et 2s. Associez-les aux histogrammes de requêtes existants afin que les tableaux de bord indiquent si l'augmentation de la latence a précédé les transitions.

# HELP breaker_state 0=closed 1=half_open 2=open
breaker_state{dep="crm_search"} 2
breaker_rejections_total{dep="crm_search"} 184

Coordination avec HTTP 429 et Retry-After

Quand l'amont revient 429 avec Retry-After: 120, traitez cela comme un refroidissement faisant autorité : prolongez la minuterie d'ouverture d'au moins 120 secondes même si votre fenêtre locale aurait tenté de s'ouvrir à moitié plus tôt. Enregistrer une métrique dédiée breaker_retry_after_skips_total afin que les SRE puissent voir à quelle fréquence les limitations du fournisseur, et non les pannes binaires, les pannes prolongées. Cette coordination est détaillée dans le guide du fournisseur 429.

Budgets de jetons et limitations par outil

Les budgets de jetons limitent les dépenses des agents ; les disjoncteurs isolent la santé des dépendances. Ils doivent échanger des signaux : lorsqu'un disjoncteur s'ouvre pour le fournisseur modèle A, décrémenter le budget d'appels effectif pour les forfaits qui insistent sur le fournisseur A afin que l'orchestration soit transférée au fournisseur B sans brûler le quota visible par l'utilisateur sur les échecs garantis. Le article sur la limitation du budget symbolique montre comment câbler des compteurs sans doubler les flux partiels.

Lire les délais d'attente et bloquer les diagnostics

Les disjoncteurs ne doivent pas s'ouvrir uniquement parce qu'un outil légitime de longue durée a dépassé un délai de lecture serré. Différencier context deadline exceeded à partir d'une réinitialisation par un homologue. Accrochez les diagnostics dans le guide de délai de lecture vous aider à classer les outils lents par rapport aux sockets morts afin que les sondes semi-ouvertes utilisent des délais de lecture réalistes.

Contrôles de santé par rapport aux jauges de disjoncteur

Les contrôles de santé synthétiques atteignent les points de terminaison Canary fixes ; les disjoncteurs observent les mélanges réels de trafic d’utilisateurs. Conservez les deux : une route de santé verte peut se trouver lorsque seuls de rares chemins de code atteignent un fragment cassé, tandis qu'un disjoncteur fermé peut refléter un pic transitoire même lorsque les canaris passent. Alignez les itinéraires d'alerte pour que les pages se déclenchent lorsque moniteurs de santé et les jauges des disjoncteurs sont en désaccord pendant plus de 3 minutes.

Matrice : disjoncteur contre régulateur contre file d'attente

Mécanisme	Objectif principal	Signaux utilisés	Effet visible par l'utilisateur
Disjoncteur	Protéger en amont	Ratio 5xx, erreurs consécutives	Échec rapide avec des conseils structurés pour les nouvelles tentatives
Accélérateur de jetons	Protéger le budget	Jetons par minute, niveau de locataire	Dégradation gracieuse vers des modèles moins chers
File d'attente des demandes	Des rafales douces	Profondeur de la file d'attente, âge	Latence accrue, pas d'erreurs graves

Modèles de répétition macOS LaunchAgent

Répétez les transitions de disjoncteur avec launchctl des minuteries qui rejouent les fichiers de trafic capturés à 10 RPS pour 5 minutes, puis injectez des scripts d'erreur qui renvoient des 503 synthétiques. Les piles réseau macOS diffèrent légèrement des conteneurs Linux en ce qui concerne les valeurs par défaut keepalive ; la validation sur un cloud Mac détecte les minuteries semi-ouvertes qui supposent les valeurs de délai d'expiration de l'utilisateur TCP Linux.

Liste de contrôle de déploiement numérotée

1. Instrumentez chacun en amont avec des clés de disjoncteur et des étiquettes de dépendance distinctes.
2. Câblez les jauges Prometheus et vérifiez que les cartes Grafana affichent des transitions d'état dans les 15 secondes.
3. Intégrez l'analyse Retry-After à partir du guide 429 avant d'activer les sondes automatiques semi-ouvertes.
4. Alignez les délais de lecture des sondes sur la latence de production P99 plus une marge de sécurité de 40 %.
5. Exécutez un test de chaos qui ouvre simultanément les disjoncteurs de deux dépendances pour valider l'isolement.
6. Documentez les codes d'erreur destinés aux agents afin que les planificateurs changent d'outil sans plantages visibles par l'utilisateur.
7. Planifiez une répétition hebdomadaire sur un Mac mini loué avec des LaunchAgents de type production.
8. Examinez les interactions de limitation des jetons pour éviter une pénurie de budget pendant le temps de recharge du disjoncteur.

FAQ

GraphQL et REST devraient-ils partager un seul disjoncteur ?

Divisez-les si les résolveurs touchent des fragments différents ; les disjoncteurs partagés masquent les pannes partielles.

Le semi-ouvert peut-il utiliser le même bassin que le trafic ?

Isolez les agents utilisateurs ou les en-têtes de la sonde afin que les filtres d'observabilité puissent les exclure des calculs SLO si nécessaire.

Qu’en est-il des outils WebSocket ?

Suivez les échecs au niveau des messages séparément ; l'ouverture au premier délai d'expiration du ping provoque un battement lorsque les utilisateurs Wi-Fi se déplacent.

L’exploitation de passerelles résilientes est autant un problème de répétition qu’un problème d’algorithme. UN Mac-mini loué à MacHTML pour environ 16,9 $ par jour offre aux opérateurs un environnement de type macOS pour valider l'injection de fautes pilotée par LaunchAgent, le timing de semi-ouverture et la surcharge de Prometheus avant que les modifications n'atteignent la production.