OPENCLAW_2026
GATEWAY_
SYSTEMD_
LAUNCHD_RUNBOOK.

1. Engpass-Analyse: Installation ja, Betrieb nein

(1) Demo-Shell mit Produktion verwechseln: Ein interaktives openclaw gateway beweist Binärdateien und Token, nicht die Restart-Politik. Ohne einen klaren Supervisor kehrt jeder Reboot oder OOM zur manuellen Arbeit zurück. (2) OS-Verträge: Auf Linux zählen journald, cgroup-Limits und unbeaufsichtigte Security-Updates; auf macOS Schlaf mit geschlossenem Deckel, App Nap und die Grenze zwischen LaunchDaemon und LaunchAgent. (3) Upgrades ohne Rollback: Schnelle OpenClaw-Releases plus Node-/Python-Drift desynchronisieren Gateway und Channel-Adapter; Logs sehen aus wie „WhatsApp tot“, obwohl das eigentliche Problem ein Versions-Mismatch ist.

Teams ohne schriftlichen Supervisor-Vertrag sammeln „Zombie-Gateways“: Ein alter Vordergrundprozess hält den Port, während systemd einen neuen startet – TLS flattert, Edge-Proxys liefern 502er. Hygiene: genau ein Owner-Prozess, explizite Bind-Adressen, Runbook-Zeile „Supervisor vor manuellem Debug stoppen“.

Zweite Fehlerklasse: doppelte Konfigurationsquellen (Server-openclaw.json vs. lokales onboard). Channels wirken grün, solange der letzte Schreiber zufällig richtig lag. Git mit Secret-Filter, immutable Deploy-Artefakte und Boot-Checksummen beenden das Roulette.

Observability-Schulden enden als emotionales Debugging: Dienste blind neu starten, API-Keys rotieren. Eine feste Leiter hält die mittlere Zeit bis zur Unschuld klein.

Auf Linux können unbeaufsichtigte Updates lange Jobs unterbrechen – Wartungsfenster oder transaktionale Updates nutzen. Auf macOS verändern App-Store-/Xcode-Updates Framework-Reihenfolgen; vor großen OS-Sprüngen Snapshots und Gateway-Rehearsal auf einem Klon.

Doppelstarts (manuell + Supervisor) erzeugen Portkollisionen. Produktion: genau ein Besitzer – vor Debug den Dienst stoppen, Port frei verifizieren.

2. Matrix systemd vs launchd

2b. Regel des einzelnen Supervisors

Entweder systemd/launchd besitzt das Gateway oder ein Mensch temporär – niemals beides gleichzeitig. Vordergrund-Debug ist erlaubt, aber Unit zuerst stoppen und Port-Freigabe dokumentieren. Diese eine Regel entfernt viele Heisenbugs in Multi-Channel-Setups.

Incident-Vorlage: Unit-Name, launchctl bootout-Label, freizugebender Port, Wartezeit bis „OK“. Mehrdeutige Sekunden kosten Stunden, wenn mehrere Responder parallel agieren.

3. Fünf Härtungsschritte

1. Wahrheitsquelle einfrieren: Versionsstring, Config-Pfad, Changelog-Zeile.
2. Baseline: openclaw status, openclaw gateway status, openclaw channels status --probe.
3. Supervisor schreiben: systemd mit EnvironmentFile und ulimits; plist mit WorkingDirectory und StdOut/Err.
4. Guardrails: Restart-Rate-Limit; Alarm bei >3 Crashes in 5 Minuten.
5. Rollback-Pack: vor Upgrade Tarball der Config + Checksumme des Binaries.

Schritt 2 ist nicht verhandelbar: Wenn Probes rot sind, ist launchd die falsche Schicht. Channels müssen manuell grün sein, bevor Automatisierung sie einpackt.

Schritt 3: Auf Linux User=/Group=, auf Mac dedizierten Service-Account, damit Skill-Verzeichnisse nicht zwischen Admin und Login-User flappen.

Schritt 4 verhindert Crash-Loops, die Provider-Quotas verbrennen und als „Model-Ausfall“ missverstanden werden.

Zwischen 3 und 4 Game-Day: Prozess killen, Supervisor muss ohne Mensch erholen; nach jedem Major-Upgrade wiederholen.

Ist doctor sauber, aber Antworten stocken, Policies prüfen: Mentions, Allowlists, Pairing, Rate-Limits. doctor prüft Umgebung, Probes prüfen Produktverhalten.

App-Logs mit Kernel-Zeit korrelieren: Auf dem Mac folgen auf Power-Assertions oder Wi-Fi-Roam oft stille Channel-Drops; auf Linux erklärt dmesg-OOM Kind-Prozesse besser als reine App-Stacks.

4. Planungszahlen (SRE-tauglich)

5. Entscheidung Linux vs Mac

Als Pre-Mortem nutzen: Wenn mehrere Zeilen gleichzeitig passen, Rollen pro Host splitten und dokumentieren, welcher Host das Token-Tresor besitzt.

TCO immer mit Engineering-Stunden: Ein etwas teurerer Mac-Stundenpreis gewinnt oft gegen Cross-OS-Sync-Skripte.

MACGPU richtet sich an Teams, die Apple-natives Verhalten ohne CapEx und mit vorhersehbarem BOM wollen – Monitoring und Rollback-Disziplin vorausgesetzt.

Hybrid: Datenpfad explizit machen – wer hält langlebige WebSockets, wer signiert Apple-spezifische Payloads, wie TLS-Clientzertifikate erneuert werden.

Jede plist-/Unit-Änderung ins Changelog, auch eine Zeile – git blame rettet Regressionen Monate später.

6. FAQ

Fragen aus Produktionsbetrieb Anfang 2026, als Vorlage mit eigenen Pfaden zu nutzen.

Doctor grün, keine Antworten? Channels proben; Mention-Policies und Allowlists prüfen. Zwei User auf einem Mac? HOME trennen; keine geteilte beschreibbare Config. Nur nach Upgrade kaputt? Ports, Zombie-PIDs, überschriebene Env-Dateien.

Gateway in Docker auf dem Mac? Möglich, aber Credential-Volumes und IPC komplex; ohne Container-Standard native Supervision. IPv6-only-VPS? DNS und SANs alignen; AAAA-Fehlkonfiguration erzeugt halb-offene Tunnel. Zu viele Logs? Strukturiertes JSON an einen Collector; kein raw tail in Prod-Shells.

Failover testen? Staging-Hostname, Rollback zweimal üben bevor Prod-Tokens. Secrets in Git? sops/sealed secrets; nie Roh-Keys committen.

journald rotiert Beweise weg? Strukturierte Logs extern speichern. launchd loaded aber kein Prozess? Exit-Codes in log show. Gateway als root? Vermeiden; least privilege, CapabilityBoundingSet auf Linux.

7. Fallstudie: Schichtdiagnose rettet Schlaf

Incident-Zeitlinien wiederholen sich: Deckel zu oder Provider-Wartung → Gateway down → Stundenlang Modelle tweaken. Eine eingefrorene Fünf-Schritte-Leiter senkt MTTR; teure Fehler sind operativ, selten algorithmisch.

Dual-Source-Configs erzeugen Geistererfolge; GitOps mit Checksumme beim Boot macht Drift sofort sichtbar.

Apple-lastige Workflows profitieren, wenn das Gateway auf einem Remote-Mac liegt – Pfade und Sandbox entsprechen eher den Tutorials. TLS-Skalierung bleibt optional auf Linux am Edge, Topologie aber lieber simpel.

Langfristig gewinnen Teams mit Runbooks: Ports, Health-Commands, Rollback-Tarball-Pfade auf einer Seite – das zahlt jede Störung.

Sicherheit: Management-Ports nicht exponieren; TLS am kontrollierten Proxy; Credentials im Kanal-Upgrade-Takt rotieren.

Kapazität: Gateway-CPU selten der Pol; Netzwerk-Stalls und Rate-Limits schon. p95 der Channel-Probe-Latenz wöchentlich messen; Skill-Cache-Disk auf kleinen VPS im Blick.

Change-Management: plist/Unit wie Code reviewen; fehlende WorkingDirectory-Zeile bricht relative Skill-Pfade. Diff vor Reload, .bak mit Timestamp.

Vendor-Tickets: Gateway-Version, Probe-Output, redigierte Config-Snippets anhängen – Support schließt „kein Repro“ schneller.

People: wöchentlich rotierender On-Call, aber ein Gateway-Architekt für strukturelle Änderungen – sonst widersprüchliche Restart-Politiken.

8. Fazit: Linux für Ingress, Mac für Apple-Kleber

(1) Grenzen: Linux schwach bei Apple-only-Glue; Mac schwach beim billigsten rohen Egress. (2) Remote-Mac-Wert: einheitliche Supervision mit Creative-Stacks, weniger Cross-OS-Dateihops. (3) MACGPU: vorhersagbaren Apple-Silicon-Knoten mieten statt Schrank-Rechenzentrum – CTA zu Plänen und Hilfe.

Hybrid ok: Tokens auf Linux erzeugen, Apple-Workflows auf Mac – Grenze per rsync/Object-Storage automatisieren, nicht per Drag&Drop über flaky Tunnel.

Experimente: manuelle Checks → systemd/launchd → Alerting. Mittelschritt überspringen garantiert Mitternachts-Pages.

Budgetrealität: Engineering-Zeit dominiert TCO bei Kleinteams; gemieteter Remote-Mac mit Monitoring schlägt oft eine „kostenlose“ VPS-Nachtschicht. Umgekehrt: rein Linux-native Teams ohne Apple-APIs sollten Mac nicht erzwingen.

Training: Fünf-Minuten-Screenrecording der gesunden Probe-Sequenz neben dem Runbook speichern.

Langweilige Wochen feiern: die besten OpenClaw-Flotten sind ereignisarm – flache Graphen, grüne Probes, geprobte Upgrades.