OpenClaw-Gateway 2026: Graceful Shutdown, Readiness-Sonden, begrenzte Drain-Fristen, Tool-Abschluss, Load-Balancer-Alignment, LaunchAgent-SIGTERM-Fenster und macOS-Proben auf Cloud-Mac-mini

Blue/Green-Deployments und wöchentliche Dependency-Updates bleiben nur dann „langweilig im positiven Sinne“, wenn Ihr OpenClaw-Gateway verschwinden kann, ohne halbfertige Tool-Aufrufe abzureißen. Im Jahr 2026 erwarten Betriebsteams einen Graceful-Shutdown-Pfad im cloud-nativen Stil: Readiness so umschalten, dass Load Balancer keinen neuen Traffic mehr schedulen, die Accept-Schleife beenden, laufende HTTP- und Streaming-Tool-Invocationen unter expliziten Fristen drainen und anschließend mit Exit-Code null beenden, während Metriken und Logs vollständig geschrieben sind. Dieser Artikel präzisiert Readiness versus Liveness, zeigt, wie Drain-Budgets lang laufende CRM-Exporte nicht verhungern lassen, wie der Shutdown mit Leistungsschaltern und Dead-Letter-Warteschlangen verzahnt wird, wie Read-Timeout-Diagnostik hilft, und wie Health-Monitoring den Draining-Zustand synthetischen Sonden gegenüber sichtbar machen sollte.

Preisanker: Die SIGTERM-Choreografie auf einem dedizierten Mac mini von MacHTML für rund 16,9 $ pro Tag nachzustellen ist günstiger als ein Deploy, bei dem launchd nach typischerweise 30 Sekunden zu SIGKILL eskaliert, während zwölf Tool-Calls noch Datenbanklocks halten.

Signale, launchd ExitTimeout und Betriebssystem-Defaults

Unter macOS sendet launchd beim launchctl bootout oder wenn ein Dependency-Upgrade den Job neu startet, SIGTERM an Ihr Gateway. Ohne erhöhtes ExitTimeout folgt nach einer plattformspezifischen Karenzzeit SIGKILL—häufig liegen Templates bei etwa 30 Sekunden, verifizieren Sie aber immer mit launchctl print gui/$UID/ihre.plist. Linux-Container haben andere Standardwerte; gemischte Flotten ohne Probe überraschen garantiert.

Ihr Gateway sollte Signalhandler installieren, die ein atomares Flag shutting_down setzen, idle Keep-Alive schließen und einen Drain-Timer thread-sicher starten. Schwerarbeit im Handler selbst vermeiden: Ereignis in die Hauptschleife legen, damit TLS-Zustand konsistent bleibt.

Dokumentieren Sie zwei Budgets: extern (was der Load Balancer glaubt) und intern (was der Worker-Pool braucht). Wenn intern > extern, verlängern Sie die Deregistrierungsverzögerung am Balancer oder verkürzen Sie Tool-Timeouts, bevor Sie Shutdown-Code ändern.

Operations-Teams sollten außerdem festhalten, welche Umgebungsvariablen Drain-Fristen zur Laufzeit überschreiben dürfen und welche nur nach Code-Review geändert werden. Ein häufiger Fehler in 2026 ist, Kubernetes-terminationGracePeriodSeconds mental auf macOS zu übertragen, ohne launchd-ExitTimeout anzugleichen; die Diskrepanz erklärt mysteriöse „fast saubere“ Deploys.

Readiness versus Liveness beim Drain

Liveness bleibt wahr, solange der Prozess noch Fortschritt erzielen kann; Readiness wird falsch, sobald Sie neue Arbeit ablehnen wollen. Vertauschen aus Bequemlichkeit erzeugt Kaskaden: Front-Ends schedulen weiter Sessions auf Hosts, die faktisch nur noch 503 liefern, weil Readiness nicht geflippt wurde—Retry-Verstärkung folgt.

Stellen Sie ein /readyz bereit, das bei Drain 503 mit JSON wie {"draining":true,"in_flight":14,"deadline_ms":12000} liefert, damit synthetische Monitore Kurven zeichnen. Kombinieren Sie das mit den Uptime-Leitlinien aus Gateway-Health-Monitoring.

Product- und Platform-Teams profitieren, wenn Dashboards Readiness-Flips und gleichzeitige in_flight-Peaks überlagern; so erkennen Sie, ob Marketing-Kampagnen oder Batch-Jobs Ihre Drain-Mathematik sprengen, bevor Kunden es tun.

Accept stoppen ohne TCP-Reset-Stürme

Das sofortige Schließen des Listening-Sockets kann laufende TLS-Handshakes mit RST beenden. Besser: Applikations-Gate, das 503 mit Retry-After: 5 antwortet, während bestehende Verbindungen ihren aktuellen Request fertig stellen. Bei HTTP/2 ist GOAWAY-Sequenzierung kritisch: maximale Streams auf null setzen, offene Streams auslaufen lassen, dann schließen.

Für WebSocket-Tool-Bridges senden Sie vor dem Socket-Close eine Anwendungsnachricht server_shutdown plus Client-Backoff-Hinweis, damit Agents nicht alle gleichzeitig das nächste Pod bombardieren.

Beobachten Sie bei Layer-7-Proxies, ob idle timeouts kürzer sind als Ihr Drain-Budget; ein Proxy, der Verbindungen früher knipst, erzeugt clientseitige Retries, die Ihr Drain eigentlich verhindern wollte.

Worker-Pools, Tool-Fristen und Streaming

Partitionieren Sie Drain-Budgets: z. B. 60 % Wandzeit für Standard-REST-Tools, 30 % für Long-Poll oder Streaming-Fan-out, 10 % für Admin-Hooks wie Metrik-Scrapes. Wenn ein Mandant Worker monopolisiert, erzwingen Sie mandantenweise Concurrency-Caps auch während des Drains.

Bei aktivem Modell-Streaming: keine neuen Turns akzeptieren, aber den aktuellen SSE-Chunk-Pump entweder bis Byte-Ende oder bis zu einer Unterfrist von z. B. 20 Sekunden laufen lassen—was früher eintritt. Teilabbrüche protokollieren Sie strukturiert als SHUTDOWN_TRUNCATED_STREAM, damit Produktteams Prompts justieren können.

Für Teams, die GPU-lokal oder remote anbinden, gilt: Kontext-Cancellation muss bis in Vendor-SDKs durchgereicht werden; sonst „wartet“ der Drain auf Hardware, die faktisch nicht mehr antwortet.

Load-Balancer-Hooks und Retry-After-Header

Nach Readiness-Flip mindestens eine Balancer-Health-Check-Periode warten—oft 5 Sekunden—bevor Accept gestoppt wird. In Multi-Region-Setups DNS-TTLs einplanen, die noch Stragglers auf alte Instanzen zeigen. Retry-After konsistent halten, damit SDK-Idempotenz und Backoff eine Geschichte erzählen.

Bei Layer-4-Pass-Through können bestehende TCP-Verbindungen auf Keep-Alive neue HTTP-Requests tragen. Tracken Sie Generationszähler pro Verbindung: nach Beginn des Shutdowns neue Requests auf alten Sockets mit Connection: close ablehnen, den aktiven Request auf dem Socket aber beenden.

Wenn Ihr Anbieter „connection draining“ nur auf der Datenpfad-Ebene aber nicht auf der Steuerungsebene unterstützt, dokumentieren Sie explizit, welche manuellen Schritte Operators vor einem Mac-mini-Neustart ausführen müssen.

Metriken, Logs und Post-Mortems

Emittieren Sie eine Gauge gateway_in_flight_total für Scraper während des Drains plus einen Counter gateway_shutdown_events_total{result} mit Labels clean, deadline_exceeded, forced_kill. Ein Histogramm gateway_shutdown_duration_seconds spannt vom Readiness-Flip bis Prozessende—so sehen SLO-Dashboards, ob Ihr 45-Sekunden-Budget realistisch bleibt.

Strukturierte Logs sollten konfigurierte Karenz (macOS-Äquivalent zu terminationGracePeriodSeconds), beobachteten in_flight-Peak und langsamstes Tool enthalten. Archivieren Sie diese Zeilen neben Deploy-Tickets für spätere Regressionen.

Alarmieren Sie, wenn clean über sieben Tage unter 99 % fällt, während Deploy-Frequenz steigt—oft sind Tool-Timeouts gewachsen oder ein Vendor ignoriert Cancellation.

Finanz- und Compliance-Stakeholder fragen gelegentlich nach Beweisen, dass keine halben Transaktionen offen blieben; Ihre Drain-Metriken sind die quantitative Antwort und ersetzen nicht die juristische Prüfung, erleichtern sie aber.

Canary-Gewichte während Rolling-Restarts

Rolling-Restarts vervielfachen Shutdown-Häufigkeit. Stündliche Instanz-Neustarts plus aggressive Canary-Verschiebungen verhindern oft den Erreichen eines stationären Zustands. Begrenzen Sie gleichzeitig drainende Instanzen auf höchstens 20 % der Flotte, sofern synthetischer Traffic Kopfroom belegt.

Automatisieren Sie Rollbacks, wenn Fehlerbudgets während des Drains brennen: überschreiten Fünf-Minuten-5xx-Raten 1 %, während eine Instanz draining meldet, schnappen Sie zur letzten guten Gewichtstabelle zurück und pagern Sie den Deploy-Owner.

Canary-Tools, die nur HTTP-Status betrachten, übersehen oft halboffene Tool-Calls; kombinieren Sie daher Geschäfts-KPIs mit reinen Verfügbarkeitsmetriken.

Abstimmung mit Leistungsschaltern

Während des Drains wollen Sie weniger Probes, nicht mehr. Koordinieren Sie mit Leistungsschalter-Einstellungen: Half-Open-Intervalle verlängern oder Breaker für bereits kranke Dependencies offen halten, damit keine Worker in sinnlose Upstream-Calls während kostbarer Sekunden laufen.

DLQ-Produzenten und idempotentes Enqueue

Rennen Shutdown und Fehlerhandler, die in die DLQ schreiben, muss Enqueue idempotent oder deduplizierend sein; sondern erzeugt ein Retry nach TCP-Fehlern ohne Idempotenz doppelte Einträge. Lesen Sie DLQ-Design für Felder im Envelope, die Prozessende überleben.

Matrix: Hard-Stop versus Graceful Drain

Szenario	Hard SIGKILL	Graceful Drain
Laufende DB-Transaktion	Risiko partieller Commits	Warten oder expliziter Rollback-Hook
Streaming-Modell-Tokens	Mitten im Satz abgeschnitten	Begrenztes Warten + strukturiertes Truncation-Flag
Deploy-Latenz	kürzer	typisch +5–45 s
Operator-Vertrauen	gering	hoch, wenn Metriken Drains belegen

Nummerierte Rollout-Checkliste

1. /readyz-Drain-JSON ins Dashboard bringen.
2. ExitTimeout an interne Drain-Mathematik plus 10 s Sicherheitsmarge koppeln.
3. Integrationstest: SIGTERM mit mindestens 50 synthetischen Tool-Calls.
4. HTTP/2-GOAWAY-Reihenfolge unter Last mit h2load prüfen.
5. Postmortem-Vorlage um CSV-Zeitleiste des Drains erweitern.

FAQ

Sollte systemd KillMode OpenClaw beeinflussen?

In gemischten Flotten Unterschiede dokumentieren: mixed versus control-group ändert, welche Kinder Signale erhalten.

Dürfen wir endlos drainen?

Nein—unbegrenzter Drain verbirgt hängende Worker. Nutzen Sie Hang-Diagnostik, um langsame Calls zu klassifizieren.

Spielen Windows-Dev-Laptops eine Rolle?

Nur wenn Sie Windows-Gateways ausliefern; für MacBook-lastige Designpartner bleibt macOS-Rehearsal trotzdem relevant.

Graceful Shutdown ist der Ort, an dem Zuverlässigkeitskultur auf messbare Sekunden trifft. Ein von MacHTML gemieteter Mac mini für rund 16,9 $/Tag liefert natives macOS-Signalverhalten, Apple-Silicon-Headroom für Soak-Tests und SSH/VNC, um launchd-Zeitlinien zu beobachten, bevor Kundenverkehr betroffen ist.