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

Agent-Gateways verteilen Anfragen auf Modelle, Vektordatenbanken und maßgeschneiderte HTTP-Tools. Sobald irgendein stromaufwärts liegender Dienst instabil wird, vergrößern naive Wiederholungsversuche Ausfälle, weil der Traffic vervielfacht wird, der ohnehin an eine kranke Abhängigkeit geht. Im Jahr 2026 betreiben reife OpenClaw-Setups exponentielles Backoff neben Leistungsschaltern (Circuit Breakern), die innerhalb fester Fehlerbudgets von geschlossen auf geöffnet umspringen, danach vorsichtig halb-offene Zustände mit Proben durchlaufen, bevolle Last wieder zugelassen wird. Dieser Beitrag legt praktikable Schwellwerte, die Taktfrequenz in Halb-offen, zu exportierende Prometheus-Metriken, die Zusammenarbeit mit 429-Antworten und Retry-After sowie per-Mandant-Token-Budgets fest, und zeigt, wie Lese-Timeout-Diagnosen und synthetische Health-Checks verhindern, dass Betreuer einen offenen Leistungsschalter fälschlich für gesunden Traffic halten. Lesen Sie dazu Umgang mit 429 und Retry-After, Token-Budget- und Tool-Drosselung, Diagnose von Lese-Timeouts und Health-Monitoring, damit Retries, Budgets, Timeouts und Proben dieselbe Erzählstruktur teilen.

Preisrahmen: Ein dediziertes Mac mini-Mietlaufwerk bei MacHTML für rund 16,9 $ pro Tag ist in der Regel günstiger als ein Vorfall, in dem ein Halb-offen-Storm eine bereits überlastungsbedingt heilende Gegenstelle abermals stört.

Warum Retries ohne Leistungsschalter den Betrieb scheitern lassen

Retries setzen voraus, die Ursache sei kurzzeitig. Bleibt ein Stromaufwärtssystem in anhaltendem Fehlerzustand—Verriegelungsstürme, abgelaufene Zertifikate, regionaler Paketverlust—, erhöht jeder Retry genau dort die Last, wo sie ohnehin wimmelt. Gateways erfahren abgestufte Fan-Out-Peaks, weil ein einzelner Agententurn vielleicht sechs Werkzeuge parallel anstößt; hält jedes Werkzeug drei Wiederholungen in 200-ms-Intervallen, erzeugen Sie leicht 18 gescheiterte Anrufe pro Geste. Leistungsschalter begrenzen solchen Schaden, indem sie wiederholte Fehler schnell lokal in strukturierte Fehlermeldungen fassen, bevor die Abkühlzeit abläuft.

OpenClaw-Deployments mischen synchrone HTTP-Tools und Streaming-Modellrouten. Schalter müssen pro technischer Abhängigkeit benannt sein, nicht global pro Prozess: Wenn der CRM-Suche-Dienst wackelt, darf der Schalter dafür nicht ein gesundes Rechen-Tool sperren, sofern nicht dieselbe Socket-Schicht wirklich in Konflikt steht. Verwenden Sie Schlüssel mit Anbieter-ID, Region und Fingerabdruck des Credentials, damit unabhängige Pfade sich nicht fälschlich koppeln.

Lebenszyklen: geschlossen, geöffnet, halb-offen

Im geschlossenen Zustand passieren Anfragen mit normaler Instrumentierung komplett nach stromaufwärts. Überschreiten Fehlerschwelle und Fenster, öffnet sich der Leistungsschalter: Folgeaufrufe scheitern schnell mit klarer Semantik „Abhängigkeit nicht verfügbar"; Planner können Strategien umschwenken. Nach abgelaufener Ruhe—oft an historisches p95 der Erholung angebunden—wechselt der Schalter in halb-offen und lässt Tropfenfänger-Sonden laufen. Erfolgreiche Proben schließen den Stromkreis, Misserfolge verlängern offene Pausen mit wachsendem Faktor.

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
  }
}

Fehlerschwellen und gleitende Fenster

Schwellen leiten Sie aus realem Verkehr ab, nicht aus beliebten Blog-Standardwerten. Pragmatisch für HTTP-Tools starten Sie mit einem 30-Sekunden-Fenster und mindestens 20 beobachteten Versuchen, ehe Anteile zählen. Öffnen Sie, sobald 5 hintereinander transportrelevante Fehler auftreten oder über 60 Prozent der im Fenster beprobten Anrufe 5xx liefern. Zähler für lange Ketten fangen totale Outages schnell, Anteilszähler fangen teilweisen Verfall.

Bei Streaming-Modellrouten trennen Sie Fälle: Ein Abbruch mitten im Strom nach ausgelieferten Token kann ein Abrechnungskonflikt sein, kein Kandidat fürs Oeffnen. Führen Sie getrennte Zähler „Header nie angekommen" versus „Strom bei 40 % Füllstand abgebrochen".

Halb-offene Sonden und Nebenläufigkeitsbegrenzung

Halb-offen ist die riskanteste Phase: zu viele Sonden erzeugen die stampfende Herde, der Sie entkommen wollten. Deckeln Sie Sonden auf 1 In-Flight-Call pro Abhängigkeit und 250 ms, Jitter bis 50 ms, und fordern Sie zwei unmittelbar folgende Erfolge auf getrennten Workern, bevor Sie voll schließen. Laufen 12 Worker, serialisieren Sie Sonden per Leader-Channel oder einer kleinen Redis-Zelle, damit nicht jeder Host parallel sticht.

Prometheus-Metriken und SLO-Anbindung

Exportieren Sie mindestens: breaker_state als Gauge je Abhängigkeit, breaker_transitions_total mit „von/nach"-Labels, breaker_rejections_total für schnelle Fehlschläge im offenen Zustand und breaker_probe_latency_ms mit Buckets zwischen 25 ms und 2 s. Koppeln Sie alles an vorhandene Request-Latenz-Histogramme, damit sichtbar bleibt, ob Latenz vor Umschaltungen stieg.

Beschriftungen nur mit niedriger Kardinalität: Anbieter, Region, Umgebung—niemals Benutzer-IDs. Wenn Sie Service-Level-Ziele mit Fehlerbudgets verknüpfen, tragen Sie die offene Mindestdauer in eine dedizierte Zeitreihe, damit Postmortems sehen, ob Wiederholungspolitik statt realem Ausfall die Downtime verlängert hat. Achten Sie auf gleichmäßige Scrape-Intervalle; springende Abfrageabstände verfälschen Umschaltzähler, besonders in Halb-offen, wo seltene zufällige Peaks schnell als Rückkehr fehlinterpretiert werden könnten.

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

Abstimmung mit HTTP 429 und Retry-After

Antwortet stromaufwärts 429 mit Retry-After: 120, so ist das bindende Abkühlen: verlängern Sie die offene Wartezeit mindestens um 120 Sekunden, selbst wenn Ihr lokalen Fenster früher halb-offen proben wollte. Zählen Sie dazu breaker_retry_after_skips_total, damit SRE sehen, wie oft Quote statt harter Fehler die Downtime stützt. Feinheiten: 429-Guide.

Token-Budgets und pro-Tool-Drosselung

Token-Budgets begrenzen Ausgaben, Leistungsschalter trennen Abhängigkeits-Sünden. Tauschen Sie Signale: Öffnet A als Modellanbieter, senken Sie die effektive Rufkontingente für Pfade, die ausschließlich A wollen, damit Orchestratoren zu B umschwenken, ohne sichtbares Volumen auf garantierte Niederlagen zu verheizen. Draht-Details stehen in Token- und Drossel-Artikel, inkl. korrekter Abrechnung bei abgebrochenen Teilstrom-Leverages.

Lese-Timeouts und Hänger

Leistungsschalter sollen sich nicht bloß wegen langer, aber seriöser Tools schließen. Unterscheiden Sie context deadline exceeded klar von Peer-Resets. Die Anleitungen in Lese-Timeout-Diagnose trennen langsame Tool-Läufe von toten Sockets, damit Halb-offen-Lese-Limits an produktive P99 ranrücken.

Health-Checks versus Schalteranzeigen

Synthese-Health zielt auf fixe Canaries, Schalter blicken auf wirklichen Nutzverkehr. Beides behalten: Grün lügt, wenn bloß seltene Pfade an einen kranken Shard stoßen, während ein harter Leistungsschalter trotz grüner Probes vorübergehend zuckt. Alarmieren Sie, falls Gesundheitsmonitore und Schalterindikatoren länger als 3 Minuten auseinanderlaufen.

Abgleich: Leistungsschalter, Drossel, Warteschlange

Mechanik	Hauptziel	Signale	Sichtbarer Effekt
Leistungsschalter	Stromaufwärtsschutz	5xx-Quote, Kettenfehler	Schnelles, strukturiertes Scheitern mit Retry-Hinweis
Token-Drossel	Budget bewahren	Token pro Minute, Tarifstufe	Stufenweiser Rückzug auf günstigere Modelle
Anforderungsschlange	Spitzen weichzeichnen	Schlagentiefe, Alter	Mehr Latenz, kein harter Fehler

macOS LaunchAgent-Übungen

Proben Sie mit launchctl, die Traffic-Aufnahmen in 10 RPS fünf Minuten wiederspielt und fehlerhaft 503 injiziert. Beachten Sie leicht anderes Keepalive-Standardverhalten gegenüber Linux-Containern; Miet-Cloud-Mac deckt ab, ob Halb-offen-Timer fälschlich Linux-Timeouts voraussetzten.

Einführung: nummerierte Checkliste

1. Jede stromaufwärtsspezifische Abhängigkeit bekommt eigene Schlüssel und Labels in Prometheus.
2. Prometheus-Messfühler anbinden und in Grafana Sicht, dass Umschaltungen innerhalb von 15 s sichtbar sind.
3. Retry-After-Parser laut 429-Guide, bevor automatische halb-offene Sonden scharf.
4. Leseschattenfristen in Proben koppeln: produktive P99 plus 40 % Puffer.
5. Chaostest, der zwei getrennte Abhängigkeiten zugleich offnet, belegt räumliche Trennung.
6. Geplanter Werkzeugwechsel: dokumentieren Sie sichtbare Fehlercodes, damit Planner reagieren.
7. Ein Miet-Mac-mit-LaunchAgent pro Woche verankern.
8. Token-Interplay prüfen, damit während Kühlpausen nicht Budget gequält wird.

Häufige Fragen

GraphQL und REST: ein Schalter?

Teilen Sie, wenn unterschiedliche Shards; gemeinsam verbirgt halbe Ausfälle.

Dürfen halb-offene Sonden im gleichen Pool fahren?

Kennzeichen reservieren, damit SLO-Filter Sonden bei Bedarf ausweisen.

WebSocket-basierte Tools?

Fehler auf Nachrichten-Ebene zählen, nicht sofort offnen beim ersten schlechten Ping, sonst wackelt alles, sobald Client-WLANs springen.

Robuste Gateways sind Sache von Algorithmen und von Generalprobe: Ein Mac mini via MacHTML (ca. 16,9 $/Tag) liefert eine macosnahe Bühne für fehlerkünstliche Szenen, saubere Halb-offen-Timings und reale Scrape-Last, bevor Produktion winkt.

Betriebsprozesse profitieren, wenn On-Call-Handbücher exakt benennen, wann manuell ein Schalter bewusst offen gehalten werden darf (z. B. während Wartung an der stromaufwärtsspezifischen API) und wie lange Staging die neuen Schwellwerte laufen muss, bevor sie produktiv werden. Ein Absatz in der Runbook-Checkliste erspart nächtliche Notrufe, weil jeder versteht, dass schnelle Fehlschläge in dieser Phase Vorsicht, kein neues Kundendebakel darstellen.