Wenn ein OpenClaw Gateway ausfällt, liegt die Ursache in der Praxis selten an „mystischen Plattformproblemen“. Meist sind es Portkonflikte, unvollständige Konfigurationen oder falsch verdrahtete Netzwerkpfade. Dieser Leitfaden liefert einen reproduzierbaren Ablauf für die häufigsten 90 % der Vorfälle.
Für produktive Setups sollten Sie Deployment, OpenHuman-Workload und Runner-Rolle sauber trennen: ../openclaw-fern-mac-usa-ost-west-m4/openclaw-fern-mac-usa-ost-west-m4.html, ../openhuman-memory-tree-cloud-mac-openclaw/openhuman-memory-tree-cloud-mac-openclaw.html, ../github-actions-ios-ci-langsam-mac-self-hosted-runner/github-actions-ios-ci-langsam-mac-self-hosted-runner.html. Das reduziert Ressourcenkollisionen und sporadische Gateway-Instabilität deutlich.
1. Fehlerbild zuerst klassifizieren
Ohne klare Symptomklasse wird Troubleshooting zufällig. Nutzen Sie die Matrix als ersten Schritt im On-Call-Runbook.
| Symptom | Typische Ursache | Erster Check |
|---|---|---|
| Gateway startet und beendet sich sofort | Port belegt, Konfigurationsfehler | Doctor ausführen, dann Listening-Sockets prüfen |
| Lokal erreichbar, extern nicht | Firewall/Security Group blockiert | Bind-Adresse gegen offene Ports abgleichen |
| Intermittierende 502/Timeouts | Upstream-Latenz, strenge Healthchecks | Timeline aus Health- und Upstream-Logs bilden |
| TLS-Handshake-Fehler | Zertifikatskette unvollständig, SNI-Mismatch | openssl-Handshake gezielt testen |
2. Fünf-Minuten-Triage mit Doctor
Starten Sie mit den offiziellen Checks aus Gateway Troubleshooting und Gateway Doctor.
openclaw gateway doctor --verbose # Verify: config path, bind address, upstream checks, TLS hints
ps aux | rg "openclaw|gateway" lsof -nP -iTCP -sTCP:LISTEN | rg ":(3000|8080|8443)" netstat -an | rg "LISTEN|3000|8080|8443"
| Doctor-Ausgabe | Bedeutung | Aktion |
|---|---|---|
| config file not found | Falscher Pfad oder fehlendes Volume-Mount | Konfigurationspfad korrigieren, Dienst neu starten |
| bind failed | Portkonflikt oder fehlende Rechte | Port freigeben oder Portnummer anpassen |
| upstream unhealthy | Backend ist nicht bereit | Upstream stabilisieren, Retry-Policy prüfen |
| tls chain invalid | Zertifikatskette inkonsistent | fullchain erneuern und erneut testen |
3. Portkonflikte systematisch beseitigen
Auf gemeinsam genutzten Hosts laufen Gateway, Runner und Hilfsdienste oft parallel. Genau dort entstehen Kollisionen durch doppelte Default-Ports.
PORT=8080 lsof -nP -iTCP:$PORT -sTCP:LISTEN sudo kill -15 <PID> sleep 2 lsof -nP -iTCP:$PORT -sTCP:LISTEN || echo "port released"
| Komponente | Empfohlener Port | Hinweis |
|---|---|---|
| OpenClaw Gateway | 8080 oder 8443 | In Produktion fest zuweisen |
| Admin UI / lokale Kontrolle | 3000 | Nur auf localhost binden |
| Runner Callback | 9090+ | Nicht auf Gateway-Port legen |
| Lokale Dev-Services | 5173 / 3001 | Von Produktionsports trennen |
Für APAC-Teams lohnt ein eigenes Region-Profil für Hongkong statt Copy/Paste aus US-Regeln: ../japan-vs-hong-kong-remote-mac-m4-ci/japan-vs-hong-kong-remote-mac-m4-ci.html.
4. Doctor richtig lesen: welche Warnungen sind kritisch?
Ein „warning“ ist nicht automatisch harmlos. Einige Hinweise sind typische Vorboten späterer Ausfälle unter Last.
| Check | Kritikalität | Empfehlung |
|---|---|---|
| Clock skew > 3s | Hoch | NTP korrigieren, sonst Token-Validierung instabil |
| DNS fallback active | Hoch | Resolver festlegen, DNS-Latenz reduzieren |
| Retry budget low | Mittel-Hoch | Timeouts und Retry-Limits anpassen |
| Deprecated key used | Mittel | In nächstem Change Window migrieren |
mkdir -p ./diag
openclaw gateway doctor --format json > ./diag/doctor-$(date +%F-%H%M).json
jq '.checks[] | {name,status,message}' ./diag/doctor-*.json
5. Logs und Healthchecks zeitlich korrelieren
Einzelne Fehlzeilen helfen wenig. Wirksam ist ein 15-Minuten-Korridor mit gemeinsamer Zeitachse aus Access-Log, Error-Log und Upstream-Log.
| Signal | Alert-Schwelle | Nächster Schritt |
|---|---|---|
| p95 Upstream-Latenz | > 1.5s | Connection-Pool und Backend-Kapazität prüfen |
| 5xx-Rate | > 1% | Nach Statuscode clustern (502/503/504) |
| Healthcheck-Flapping | > 3/10 min | Probe-Intervalle und Timeout justieren |
| TLS handshake errors | Steigend | SNI, Chain und Ablaufdatum verifizieren |
6. Netzwerk und TLS ohne Blindflug prüfen
„Intern ok, extern kaputt“ deutet oft auf zusätzliche Schichten wie WAF, Load Balancer oder CDN hin. Testen Sie hop-by-hop, nicht alles auf einmal.
curl -Iv https://gateway.example.com/health openssl s_client -connect gateway.example.com:443 -servername gateway.example.com dig +short gateway.example.com traceroute gateway.example.com
Netzwerkdetails und Patterns finden Sie in der Doku: Gateway Networking.
7. Deployment-Muster passend zur Last wählen
Viele Stabilitätsprobleme sind in Wahrheit Topologieprobleme. Definieren Sie das Zielmuster, bevor Sie an Einzelparametern drehen.
| Muster | Geeignet für | Risiko |
|---|---|---|
| Single Host | PoC und geringe Last | Ressourcenkonflikte steigen schnell |
| Gateway + Runner getrennt | Regelmäßige CI-Last | Mehr Monitoring und Routingaufwand |
| Dual-Region Gateway | Verteilte Nutzerbasis | Konfig-Sync und Token-Strategie komplexer |
| Gateway getrennt von OpenHuman | Parallele Agent-/Memory-Workloads | Mehr Kosten, dafür höhere Robustheit |
Für Budget- und Kapazitätsplanung: ../../../mac-mini-preise.html.
8. Fazit: 90 % der Ausfälle sind prozessierbar
OpenClaw-Gateway-Stabilität entsteht nicht durch Ad-hoc-Fixes, sondern durch Reihenfolge und Disziplin: Triage, Port-Hygiene, Doctor-Interpretation, Log-Korrelation und Netzwerkvalidierung. Mit diesem Ablauf lassen sich die meisten Störungen im ersten Durchgang isolieren.
Pflegen Sie das Runbook versionsgeführt und gleichen Sie Konfigurationsänderungen mit der offiziellen Referenz ab: Gateway Configuration.
Q1: Doctor ist grün, warum trotzdem Timeouts?
Doctor prüft Basiskonfiguration; Last- und Kapazitätsprobleme im Upstream bleiben möglich.
Q2: Darf Gateway mit Runner auf einen Host?
Ja, aber nur mit klaren Portgrenzen, CPU/RAM-Limits und Lastfenstern.
Q3: Macht ein anderer Port den Dienst automatisch sicherer?
Nein. Entscheidend sind TLS, ACL, Secret-Handling und Least Privilege.
Q4: Warum hilft ein Neustart nur kurz?
Weil die Ursache (z. B. DNS oder Portkollision) unverändert bleibt.
Q5: Eine Konfiguration für alle Regionen?
Baseline ja, aber regionale Overrides für DNS, Firewall und Upstream sind sinnvoll.
Q6: Wo beginne ich bei TLS-Fehlern?
Mit Zertifikatsablauf, fullchain und SNI-Hostname.
Q7: Wann lohnt Blue/Green?
Wenn Updates ohne Downtime notwendig sind und Restart-Fenster teuer werden.
Q8: Wie lange Diagnosedaten speichern?
Mindestens 14 bis 30 Tage für saubere Vorher/Nachher-Vergleiche.
Planen Sie Stabilität und Kosten gemeinsam: Deployment unter ../openclaw-fern-mac-usa-ost-west-m4/openclaw-fern-mac-usa-ost-west-m4.html, Workload-Trennung mit ../openhuman-memory-tree-cloud-mac-openclaw/openhuman-memory-tree-cloud-mac-openclaw.html und ../github-actions-ios-ci-langsam-mac-self-hosted-runner/github-actions-ios-ci-langsam-mac-self-hosted-runner.html, regionale Optionen über ../japan-vs-hong-kong-remote-mac-m4-ci/japan-vs-hong-kong-remote-mac-m4-ci.html plus Preisabgleich via ../../../mac-mini-preise.html.