Gateway wirkt im Container gesund, hinter Nginx/Caddy gibt es 502, fehlgeschlagene WebSocket-Handshakes oder Endlosschleifen bei Redirects? Dieser Artikel fokussiert die Schicht Edge-Reverse-Proxy + TLS-Terminierung + WebSocket-Upgrade. Er ergänzt Docker-Netzwerk-Triage: dort geht es um wer welche Pakete sieht, hier um ob die HTTP/1.1-Upgrade-Kette und Pfade vom Browser zum Gateway stimmen. Du erhältst sechs typische Fallen, zwei Topologie-/Symptomtabellen, kopierbare Snippets, ein Sechs-Schritte-Produktions-Runbook und drei harte Metriken für den Dienst. Danach erkennst du, ob Upgrade-Header oder der Upstream 127.0.0.1:18789 dran sind.
proxy_pass ohne HTTP/1.1 und Upgrade: WebSocket-Anfragen liefern 400/502 am Edge, Logs wirken wie ein Gateway-Ausfall./openclaw, die App generiert aber absolute URLs vom Root—statische Assets und WS-Pfade auseinander.proxy_read_timeout zu kurz: lange Inferenz oder Channel-Bursts werden am Edge still gekappt, Reconnect-Stürme treffen den Upstream.Die Topologietabelle fasst Same-Host-Proxy, separaten Proxy-Host, Subdomain und Subpfad zusammen, danach folgen Header-Checks und die Symptommatrix.
Reverse Proxy auf demselben Host wie Gateway (Nginx/Caddy colocated) hält die Triage kurz: curl -v http://127.0.0.1:18789 prüft den Upstream lokal. Ein separater Proxy-Host addiert Hops—Security-Groups, internes DNS und TLS SNI erneut verifizieren. Subdomains vermeiden meist Stripping- und Cookie-Path-Theater; Subpfade passen zu einer einzigen Marken-Domain, erfordern aber nur einmaliges Präfix-Stripping auf OpenClaw-Basis-URL und Proxy, plus Devtools-Nachweis, dass WS-URLs weiterhin den erwarteten wss://-Pfad treffen.
Change-Requests sollten zwei Screenshots enthalten: finale Browser-URL und Request-URL des WebSocket-Handshakes im Network-Tab. Ohne sie werden Reviews oft als Modell-Timeout oder Channel-OAuth fehlklassifiziert. Bei Unternehmens-HTTPS-Proxys unterscheide Büro-Browser (PAC) vom Datacenter-Proxy (meist direkt)—unterschiedliche Symptome sind normal.
HTTP/2 am Edge mit HTTP/1.1-WebSocket-Upstreams ist 2026 noch Standard: prüfe, welcher Hop das Upgrade erlaubt. Ohne PCAP gleichzeitig erzwungenes H2 und eigene WS-Rewrites aktiv lassen verwandelt Triage in Rätselraten.
| Topologie | Passend für | Betriebsvorteil | Typische Fallen |
|---|---|---|---|
| Same Host + Loopback-Upstream | Einzel-VPS / dauerhaft erreichbarer Remote-Mac | Lokales curl, TLS und Prozess teilen Log-Volumes | Bind an 0.0.0.0 vergrößert Angriffsfläche—Firewall nötig |
| Dedizierter Proxy-Host | Viele Backends, Blue/Green, WAF davor | Edge entkoppelt von Compute; zentrale Zertifikatserneuerung | Interne Routen, SNI, Health-Check-Ziele driftieren |
| Subdomain | WS getrennt von der Hauptsite | Klare Pfadsemantik; einfachere CDN-Regeln | Mehrere Zertifikate; eigenes HSTS-Review |
| Subpfad | Eine Marken-Einstiegsdomain | Geringere Merklast für Nutzer | Präfix-Stripping, Redirect-Schleifen, falsche Asset-Roots |
Der Edge muss auf HTTP/1.1 upgraden, Connection: upgrade und Upgrade: websocket durchreichen oder neu aufbauen und Lese-Timeouts über dem langsamsten Modell-Perzentil setzen. Die Tabelle dient als Review-Checkliste.
Leicht übersehen: Proxy-Buffering. proxy_buffering kann APIs beschleunigen, aber Streaming oder Langzeitverbindungen erzeugen Latenz oder Kappungsgefühl; bei Streaming-Kanälen oder SSE-ähnlichem Verhalten Staging unter Last testen, bevor Standard-Buffering bleibt.
Wenn Sie TLS am Edge mit Zertifikaten eines Drittanbieters oder über ein CDN beenden, prüfen Sie zusätzlich Auftragsverarbeitung, Logaufbewahrung und datenschutzrechtliche Datenflüsse im Sinne der DSGVO.
| Prüfpunkt | Nginx | Caddy |
|---|---|---|
| Protokollversion | proxy_http_version 1.1; | reverse_proxy standardmäßig HTTP/1.1; explizite Transports beachten |
| Upgrade-Kette | Upgrade $http_upgrade; Connection "upgrade"; | meist automatisch; Custom via header_up |
| Host und Client-IP | proxy_set_header Host $host;, X-Forwarded-* | header_up Host {host}; Proxy-Hops vertrauenswürdig setzen |
| Langzeitverbindungen | proxy_read_timeout / send_timeout | transport http { read_timeout ... } (Syntax je Release) |
| Große Bodies | client_max_body_size | Body-Limit-Direktiven (Caddy-Doku) |
# Snippet: Reverse-Proxy zum lokalen Gateway (Port je Deployment; Beispiel 18789)
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
# Snippet: automatisches TLS + WebSocket-Upstream
openclaw.example.com {
reverse_proxy 127.0.0.1:18789 {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
}
}
Hinweis: Nach Änderungen zuerst am Upstream mit curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" http://127.0.0.1:18789/ die Handshake-Semantik prüfen, danach öffentliches wss:// testen—sonst schieben TLS- und Proxy-Schicht gegenseitig Schuld.
Symptome Edge vs. Upstream vs. App zuordnen, bevor Container neu gebaut werden. Zeigt die Tabelle Container-Netzwerk, zurück zu Docker-Netzwerk-Triage; Channel online, aber Slack/Telegram schweigt—Channel-Troubleshooting.
Nur Produktion, Staging sauber: diff auf gleiche CA-Kette, CDN/WAF-Regelversionen und ob Proxy-map/if nach User-Agent verzweigt. Viele 502 sind Edge-Fehlalarme, nicht die OpenClaw-Version.
| Symptom | Zuerst prüfen | Verifizieren |
|---|---|---|
| 502 Bad Gateway | Upstream lauscht nicht, Firewall, falsche Socket-Familie | Vom Proxy curl zum Upstream; error.log upstream timed out / refused |
| 413 Request Entity Too Large | Zu kleines client_max_body_size am Edge | Erhöhen und reload; CDN/WAF-Limits angleichen |
| WS nicht 101 | Fehlendes Upgrade, Pfadrewrite, http→https bricht Handshake | Handshake-Status im Browser; location-Reihenfolge und return 301 |
| Redirect-Schleifen | HTTPS-Zwang ohne X-Forwarded-Proto | Testweise Edge-HSTS lockern; Forwarded-Header ergänzen |
| Zert-Warnungen / partielle Client-Fehler | Unvollständige Kette, falsches SNI, IP-Zertifikate | openssl s_client -servername zur Kette; NTP |
https://-Basis, Subpfad ja/nein, teilt WS den HTTP-Host.18789).127.0.0.1:18789 oder internem VIP—ohne öffentliche Latenz, um Edge- vs. Gateway-Langsamkeit zu trennen.Mit zentralen Logs Proxy-Access-5xx-Rate und Gateway-Applikationsfehlerrate doppelt achsen—wenn nur eine Seite springt, ist Verantwortung klar und Postmortems datenbasiert.
Laptop-Proxys validieren Snippets schnell, aber Sleep, VPN-Wechsel und instabile Heim-Uplinks machen TLS und Erneuerungen Handarbeit; 502-SLOs lassen sich nicht vertraglich schärfen. Reverse Proxy + dauerhaftes Gateway auf dedizierten 24/7-Hosts (z. B. gemietete Apple-Silicon-Cloud-Macs oder verwaltete VPS) verwandeln Rate-Limits, Zertifikate und Log-Retention in Standard-Changes. Stabiler Eingang ist Voraussetzung, damit OpenClaw mit CI und Signaturpipelines auditierbar bleibt.
Eigene Proxy-Stacks verfolgen OpenSSL-, Nginx- und OS-CVEs; Teams, die OpenClaw langfristig mit CI, Signatur und Multi-Channel-Bots koppeln, sparen oft Gesamtkosten mit vorhersehbar dedizierter Rechenleistung und klaren Regionen/Mietlaufzeiten gegenüber Heim-Experimenten. MACCOME Cloud-Macs bieten mehrere Regionen und klare Mietstufen als saubere Dauer-Maschine hinter TLS-Terminierung: Verzeichnis- und Rechtegrenzen aus Installationsleitfaden für drei Plattformen umsetzen, Ausführung vertragssicher platzieren mit Mac-mini-Mietpreisen und Regionsseiten—Singapur, Tokio, Seoul, Hongkong, Virginia, Silicon Valley—während der Edge nur Policy und Observability trägt.
Verbindungs-, Session- und Channel-Themen über Hilfe-Center per Stichwort finden; für visuelle Triage Remote-Desktop- und SSH/VNC-Artikel kombinieren.
FAQ
502—zuerst Proxy oder Docker?
Vom Proxy-Host Loopback-Upstream curlen; wenn nicht erreichbar, Docker-Netzwerk-Triage. Tarife: Mac-mini-Mietpreise.
Subpfad oder Subdomain?
Subdomains vermeiden Stripping-Probleme; Subpfade brauchen identische Basis-URLs. Installation über Drei-Plattformen-Installationsleitfaden versionssynchron halten.
WebSocket bricht hinter CDN ab?
Caching aus, Idle-Timeouts verlängern oder CDN für Steuer-Subdomain umgehen. Channel-Themen: Slack/Discord/Telegram-Troubleshooting.
Logs und Tickets—wohin?
Enterprise-Änderungen über Hilfe-Center-Tickets, halbe Nginx-Configs nicht im Produktionschat verlieren.