Namespace-Matrix · Auswahl des Netzwerkmodus · Reverse-Proxy-WebSocket · AllowOrigins · sechsstufiges Runbook
Betreiber hosten OpenClaw selbst auf einem VPS mit Composestoße oft auf eine Fata Morgana:docker compose psist grün, Gateway-Protokolle scrollen nochDie Openclaw-CLI auf dem Host oder in einem Sidecar-Container läuft ständig ab oder gibt 502 zurück. Die Grundursache liegt normalerweise darinwie Netzwerk-Namespaces mit Bind-Adressen kombiniert werden, nicht der Modell-API-Schlüssel. In diesem Artikel heißt esWer hat welches Problem?, verwendet adreischichtiger Symptombaumum die Prozessgesundheit von der tatsächlichen Erreichbarkeit zu trennen, vergleichtBridge, Host und Netzwerkmodus: Dienstin einer Matrix geht aSechsstufiges reproduzierbares Runbooküber veröffentlichte Ports, Loopback-Bindungen, Reverse-Proxy-WebSocket-Upgrades undallowedOrigins, und schließt mitüberprüfbare technische Fakten sowie eine Entscheidungsmatrix. Lesen Sie dieDocker Compose-Produktionsbasislinie, DieCheckliste für die Isolierung mehrerer Instanzen, und dieCheckliste zur Gateway-Härtung; Für stabile Knoten und vorhersehbaren Ausgang verwenden Sie dieBestellseite.
Ein KomponierenhealthcheckPrüft häufig den Loopback innerhalb des Containers oder die Prozessaktivität. Esbeweist sich nicht automatischdass DNS-Auflösung, iptables und User-Space-Proxys alle auf dem Pfad von einem CLI-Container zum Gateway-Dienstnamen zusammenarbeiten. Die folgenden fünf Muster kommen zusammen in Tickets vor; Wenn Sie sie trennen, wird Ihr Vorfallprotokoll sofort ausgedünnt.
Nur auf 127.0.0.1 abhören:Wenn das Gateway einen Loopback bindet, wird die Verbindung von Geschwisterdiensten auf derselben Bridge über den Dienstnamen verweigert. Es fühlt sich an wie zufällige Zeitüberschreitungen, obwohl nie etwas diesen Netzwerk-Namespace verlassen hat.
CLI auf dem Host mit einem Container-Hostnamen:Kopierenopenclaw-gateway:18789in ein Host-Shell-Profil führt zu einer sofortigen Fehlanpassung von Auflösung und Routing.
Reverse-Proxy leitet HTTP weiter, aber kein Upgrade:Browser oder CLIs, die WSS verwenden, sehen 400 oder stille Drops, während in den Anwendungsprotokollen weiterhin „Gateway bereit“ angezeigt wird.
AllowOrigins weichen von echten Ursprüngen ab:Durch das Mischen von Produktionsdomänen, internen Aliasen und Namen im MagicDNS-Stil werden Handshakes auf der App-Ebene abgelehnt, während Paketerfassungen gut aussehen.
network_mode: Dienst-Neustart-Rennen:Nach Änderungen der Neustartreihenfolge stoßen Downstreams immer noch auf alte Container-IPs oder veraltete Portzuordnungen, was zu zeitweiligem Erfolg führt.
Drucken Sie den nächsten Abschnitt als Rezensionshandout aus: Lassen Sie zu, dass sich pro Architekturänderung nur eine Matrixzelle ändert, und hängen Sie gepaarte Ausgaben für Curl innerhalb desselben Namespace gegenüber Curl aus dem äußeren Namespace an.
Fügen Sie eine Zeitdimension hinzu: Während fortlaufender Updates führt Compose kurzzeitig alte und neue Container zusammen aus. Wenn DNS-Caches und Client-Pools voneinander abweichen, sehen SieDie erste Anfrage war erfolgreich, dann folgten Minuten voller Fehler. Bevor Sie Zeitüberschreitungen auslösen, aktualisieren Sie die Auflösung auf dem Initiator und vergleichen Sie die Wiederverwendung der Verbindung mit dem aktuellen Endpunkt vondocker inspect. Wenn Sie auch User-Space- oder Unternehmens-Proxys verketten, melden Sie sich anTunnelziele CONNECTgetrennt vondirekte ZieleDaher wird eine 407 vom Proxy nicht fälschlicherweise als Fehler bei der Anwendungsauthentifizierung interpretiert.
Ein weiterer einfacher Fehler istMTU und Fragmentierungauf wolken- oder trägerübergreifenden Pfaden, was zu sporadischen Zeitüberschreitungen führt. Wenn große Nutzlasten fehlschlagen, während kleine Integritätsprüfungen grün bleiben, beschränken Sie die Erfassungen auf WebSocket-Framegrößen und TLS-Datensatzgrenzen, anstatt zunächst Anwendungsrouten neu zu schreiben.
Sobald diese Signale im Änderungsticket enthalten sind, richten Sie die Zeitstempel zwischen ihnen ausopenclaw logsund Edge-Zugriffsprotokolle. Die meisten Teams können verwirrende Netzwerke zusammenbrechen lassenein einzelnes Konfigurationsfeldinnerhalb von dreißig Minuten, was auch die Kontexttiefe ist, die ein minimales Repro-Paket bieten sollte, wenn Sie um externe Hilfe bitten.
Wenn Sie ein Modell auswählen, notieren Sie esWer initiiert die Verbindung, welcher Name wird zu welcher Adresse aufgelöst und welche NAT-Schichten liegen dazwischen. Ohne diesen Tisch pendelt das Team zwischen den Wechselnports, extra_hostsund Reverse-Proxy-Upstreams.
| Modell | Typisches Hörmuster | Andere Dienste in derselben Compose-Datei | Host-Prozesse |
|---|---|---|---|
| Standardbrücke mit veröffentlichten Ports | 0.0.0.0innerhalb des Containers oder explizite Veröffentlichungen | Verwenden Sie den Compose-Dienstnamen und den internen Port | Verwenden127.0.0.1:publishedoder eine Host-NIC-IP |
| Host-Netzwerke | Gibt den Host-Stack frei. Bindungen sind für den Host sichtbar | Andere Container, die außerhalb der Brücke bleibenkann nichtBehalten Sie den alten Dienstnamenpfad bei | Überprüfen Sie Portkollisionen und INPUT-Firewallketten neben Containern |
| Netzwerkmodus: Dienst: Gateway | Gibt die Gateway-Netze frei; Loopback-Semantik richten sich aus | Beiwagen können anrufen127.0.0.1:gateway-port | Der Host benötigt weiterhin veröffentlichte Ports oder einen Proxy; nichts wird automatisch vererbt |
Echte Erreichbarkeit bedeutet, dass derselbe Hostname, Port und dieselben TLS-Parameter darin wiederholt werdenDer Namespace des Initiatornetzwerksund konsistente Antworten zu erhalten, nicht ein einmaliges Abrollen von einem Laptop.
In der Reihenfolge werden die günstigsten Beobachtungen zuerst angezeigt; Stoppen und speichern Sie die Ausgabe, wenn ein Schritt fehlschlägt. Wenn die Feldnamen von Ihrer Installation abweichen, überprüfen Sie dieseCheckliste zur Fehlerbehebung bei der Installation und beim Arzt.
Beschriften Sie den Initiator:Beachten Sie, ob Befehle auf dem Host, in einem Gateway-Sidecar oder in einem eigenständigen CLI-Container ausgeführt werden. erfassenhostnameund ein kurzerip routeZusammenfassung.
HTTP-Sonde innerhalb der Netns:aus dem Initiator-Namespace den Ziel-Hostnamen und -Port GET oder HEAD, überprüfen Sie Statuscodes und Body-Präfixe und schließen Sie einen reinen DNS-Fehler aus.
WebSocket-Probe:Üben Sie den von Ihnen tatsächlich verwendeten Upgrade-Pfad aus, zeichnen Sie Edge- und Anwendungsantwort-Header auf und stimmen Sie Zeitstempel mit Protokollen ab.
Listen-Matrix im Gateway:wenn Zuhörer binden127.0.0.1Nur und dienstübergreifender Zugriff erforderlich ist, wechseln Sie zu0.0.0.0Oder übernehmen Sie ein gemeinsames Netz und aktualisieren Sie das Runbook entsprechend.
Reverse-Proxy-Vierfach:Upstream-Punkte an der Container-IP im Vergleich zum veröffentlichten Port bestätigen, überprüfenConnectionUndUpgradeWeiterleitung und stellen Sie sicher, dass Leerlaufzeitüberschreitungen keine langlebigen Sitzungen beschneiden.
Checkliste zur Herkunft:real aufzählenOriginZeichenfolgen oder Äquivalente für Browser, CLIs und CI; Jede fehlende Zeile ist ein Freigabeblocker.
docker compose ps
docker compose exec cli sh -lc 'getent hosts openclaw-gateway; curl -fsS -o /dev/null -w "%{http_code}\n" http://openclaw-gateway:18789/health || true'
curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/health || true
docker compose logs --no-color --tail=200 openclaw-gateway
Notiz:Ersetzen Sie Dienstnamen, Ports und Gesundheitspfade durch die Werte aus Ihrem Repository. Behalten Sie das Muster bei, dieselbe URL aus zwei Namespaces auszuführen.
Dieser Abschnitt listet aufFakten, die Sie in Konfigurationsdateien benennen können, keine Stimmung über Fehlverhalten von CDNs. Informationen zu Speichergrenzen und Protokollrotationssprache finden Sie unterErstellen Sie eine Produktionsbasislinie.
ports:Zuordnungen erstellen DNAT-Regeln auf dem Host; Ein Missverständnis der Reihenfolge zwischen lokalen Firewall-Richtlinien und Docker-Ketten führt zum Erfolg von Container zu Container, während der Host-Pfad fehlschlägt, oder umgekehrt.Warnung:Ändern Sie nicht gleichzeitig Reverse-Proxy-Upstreams, Gateway-Bindungen und CLI-Konfiguration ohne aufgezeichnete Baseline. Dreiecksveränderungen machen eine Halbierung unmöglich.
Schreiben Sie vor der Auswahl einen booleschen Wert, der angibt, ob die CLI die Loopback-Semantik mit dem Gateway teilen mussnetwork_mode: service:oder Gastgeber. Verwenden Sie die Matrix zur Designüberprüfung, nicht für Slogans.
| Zwang | Sichererer Standard | Schlüsselakzeptanzsignal | Hauptrisiko |
|---|---|---|---|
| CLI und Gateway in einer Compose-Datei | Bridge plus explizit0.0.0.0bindet | Die Auflösung des Dienstnamens entspricht dem Curl des internen Ports | Die Dokumentation von Firewalls und veröffentlichten Ports weicht von der Realität ab |
| Muss die Localhost-Semantik teilen | Beiwagen mitnetwork_mode: service:gateway | Durch den Sidecar-Neustart werden veraltete Verbindungspools nicht wiederbelebt | Upgrade-Bestellpaare mit Volume-Mount-Berechtigungen |
| Ein ausgereifter Host-Reverse-Proxy ist bereits vorhanden | Nur veröffentlichter Loopback plus TLS-Terminierung am Rand | Der Paket- oder Protokollnachweis zeigt ein konsistentes WS-Upgrade | allowedOriginsEs fehlen URL-Formen, die die CLI tatsächlich verwendet |
Wenn Sie sich auf Ad-hoc-Tunnelskripte oder handbearbeitete Hosts-Dateien verlassen, dauert die Wiederherstellung in den einzelnen Speicher länger. Wenn sich Upstream-Zertifikate oder interne DNS ändern, geht die Triage in All-Hands-Meetings über.
Häufiger Fallstrick:Zuerst 502 und rotierende Modellschlüssel sehen; Beenden Sie die HTTP- und WebSocket-Prüfungen aus Abschnitt drei, bevor Sie sich mit den Anmeldeinformationen befassen.
Das vorübergehende Öffnen von Ports ohne Checkliste erweist sich bei Audits selten als Standardverweigerungs- und explizite Zulassungshaltung. Wenn OpenClaw zusammen mit festem Egress, Hostnamen und gegenseitiger TLS-Richtlinie ausgeliefert werden muss,Ad-hoc-VPS-Netzwerkschichten verfügen oft über keine signierbaren Änderungsdatensätze. Für Teams, die iOS-Builds, Desktop-Übergabe und persistente Agents benötigendedizierte Maschinen mit vorhersehbaren Regionen und Netzwerkebenenund möchten weniger Schleifen beim Erraten von Host- und Container-Netzen,Die Cloud-Miete von VpsMesh Mac Mini ist in der Regel die bessere Lösung: Dedizierte Knoten vereinfachen die Beschreibung von Listenern und ACLs in derselben Sprache wieDas Team-Private-Network-Runbook; Die Preisgestaltung lebt davonPreisseiteund Konnektivitätsanleitungen zumHilfecenter.
Führen Sie darin HTTP-Probes ausdie gleichen Netze wie die CLI, validieren Sie dann das WebSocket-Upgrade und überprüfen Sie erst dann die CLI-Hostnamen erneut auf versehentliches Host-Loopback oder veraltete Aliase. Informationen zum Härten finden Sie in derCheckliste für die Produktionshärtung.
Verwenden Sie es, wenn Helfer den Gateway-Stack und die Loopback-Ansicht gemeinsam nutzen müssen. Dokumentieren Sie die Anordnung zum Neustart des gemeinsam genutzten Dienstes und überprüfen Sie die offiziellen Konnektivitätshinweise imHilfecenter.
Upstream-Zeitüberschreitungen, fehlende Upgrade-Header-Weiterleitung oderallowedOriginsLücken für die tatsächliche Client-Herkunft; Richten Sie Kanten- und Anwendungsprotokolle aus, bevor Sie Schlüssel drehen oder Routen modellieren. Informationen zu Plänen und Ausgangsanforderungen finden Sie imPreisseite.