Teams, die OpenClaw mit Docker Compose betreiben, scheitern selten daran, dass Images nicht gezogen werden können. Sie scheitern daran, dass Gateway-Logs gesund wirken, Browser oder die CLI aber Verbindung verweigert, fehlgeschlagene WebSocket-Handshakes oder Token-Fehler melden—häufig wegen Listenadressen (Bind), Port-Publishing und ob die CLI den Netzwerk-Namespace des Gateways teilt, nicht wegen des Modell-API-Schlüssels. Dieser Artikel liefert sechs On-Call-Symptomklassen, zwei Matrizen für „läuft nicht“ vs. „läuft, aber nicht routbar“, eine Bind-/Firewall-/Publish-Zuordnung, kopierbare Diagnosen, ein Sechs-Schritte-Runbook und drei Log-KPIs. Ergänzend zum Docker-Produktions-Runbook, Doctor-Triage nach der Installation und Kubernetes-Probe-Leitfaden: Produktion beantwortet wie man ausrollt; dies beantwortet warum Container einander oder den Host nicht so sehen, wie Sie es erwarten.
Die Steuerungsebene verbindet Gateway WebSocket/HTTP mit CLI / Control UI sowie mehreren Containern, eigenen Bridges und network_mode: service:.... Ohne geschichtete Triage rotieren Teams durch .openclaw-Dateien, ohne zu prüfen, ob der Listener aus dem CLI-Namespace erreichbar ist.
127.0.0.1 im Container; der Host erreicht es über veröffentlichte Ports, doch ein anderer Service derselben Compose-Datei nimmt einen anderen Pfad.gateway:18789 per Bridge-DNS auf, während das Gateway nur Loopback für den geteilten Service-Stack freigibt—klassisch „funktioniert einmal, bricht nach Neustart“.curl auf dem Host klappt zeitweise, In-Container-Probes scheitern nach einem Rolling-Upgrade mit alten NAT-Regeln.::1 oder fehlerhafte AAAA-Records auf schlanken Images.Erfassen Sie dies auf demselben Change-Ticket wie Volumes, Image-Digests und Health Checks aus der Produktion: Erreichbarkeit versus Versionskorrektheit.
Pflegen Sie eine einseitige Netzwerktopologie im Compose-Repository: welche Services in welchem Netz liegen, wer Ports veröffentlicht und wie Entwickler-Laptops versus CI den Stack prüfen. DNS auf benutzerdefinierten Netzen unterscheidet sich von der Standard-Bridge; wenn Dienstnamen scheitern, getent hosts oder nslookup im Container ausführen, bevor Sie OpenClaw beschuldigen.
Zuerst immer offizielles doctor und gateway status ausführen (siehe Artikel nach der Installation). Tokens nicht rotieren, bevor klar ist, dass ein Listener existiert.
| Signal | Wahrscheinliche Klasse | Erste Maßnahme | Anti-Pattern |
|---|---|---|---|
| Kein Gateway-Container oder CrashLoop | Nicht aktiv | docker logs, OOM, Probes beenden Pods | Endloses pull ohne Ressourcenprüfung |
Läuft, aber kein ss-Listener im Inneren | Konfiguration/Bind-Fehler | OPENCLAW_GATEWAY_BIND und Compose-Befehl mit Doku abgleichen | Nur Host-/etc/hosts bearbeiten |
Listener ok, CLI-wget scheitert | Routing über Namespaces | network_mode: "service:openclaw-gateway" erwägen | Blindes 0.0.0.0 ohne Bedrohungsmodell |
| Host-Browser scheitert, Container ok | Publish / Proxy | ports:, VPN, PAC-Dateien prüfen | TLS willkürlich abschalten |
An offizielle gateway.bind-Werte wie loopback, lan, tailnet und auto ausrichten; in Compose muss zudem klar sein, wer Ports veröffentlicht.
| Ziel | Bind / Umgebungsintention | Compose-Hinweise | Sicherheit |
|---|---|---|---|
| Nur lokales Notebook | Loopback zuerst; Host trifft veröffentlichten Port | 127.0.0.1:18789:18789 | Nicht annehmen, dass andere Compose-Services Loopback-Erreichbarkeit erben |
| CLI eng an Gateway gekoppelt | Netzwerk-Stack teilen | network_mode: "service:openclaw-gateway" | Gemeinsamer Portraum—doppelte Binds vermeiden |
| LAN-Debugging | lan oder gleichwertig | 0.0.0.0 vs. konkrete NIC explizit binden | Mit Firewall-Regeln vorgelagert abstimmen |
| Tunnel / Reverse Proxy | Gateway-Loopback; TLS am Rand | Netze trennen; WebSocket-Durchleitung prüfen | Keine nackten Admin-Ports im öffentlichen Internet |
# 1) Host: ist der Port wirklich veröffentlicht? docker compose ps curl -sv --max-time 2 http://127.0.0.1:18789/ || true # 2) Im Gateway-Container docker compose exec openclaw-gateway sh -lc 'ss -lntp 2>/dev/null || netstat -lntp' # 3) Von der CLI aus (Dienste umbenennen) docker compose exec openclaw-cli sh -lc 'wget -qO- --timeout=2 http://openclaw-gateway:18789/ || echo FAIL' # 4) Effektives Compose inspizieren docker compose config | sed -n '1,200p'
Hinweis: In der Community wird „CLI erreicht Gateway nicht“ häufig mit Compose-Dateien in Verbindung gebracht, die die CLI nie in den Gateway-Netzwerk-Namespace legen. Den Befehlsblock auf einem Test-Stack verifizieren, bevor in die Produktion gemerged wird.
Wenn Installationspfade unklar sind, mit dem Drei-Plattformen-Installationsleitfaden starten.
Upgrade-Header und Pfad-Rewrites prüfen, bevor Gateway-TLS-Knöpfe gedreht werden.Kompatibel mit HTTP-Probes aus dem Kubernetes-Health-Check-Artikel, wenn derselbe Stack in eine Orchestrierung übergeht.
ss, Prozessname, Compose-Service—jede Abweichung braucht ein Ticket.docker port versus iptables-NAT nach Rollouts—veraltete Ketten sind 2026 noch relevant.Gateway-Logs bei Handshake-Fehlern separat von Upstream 429/5xx taggen; wenn Letzteres dominiert, zum Provider-Failover-Leitfaden wechseln.
Wenn HTTP-Probes Loopback ansprechen, Nutzerverkehr aber über eine andere Schnittstelle eintrifft, können alle Probes grün und alle Nutzer rot sein; Probe-URLs mit der Bind-Politik aus Tabelle 2 abstimmen, bevor ein Release beschuldigt wird.
Docker-Desktop-Schlaf, VPN-Umschaltungen und lokale Proxies ändern, wie localhost aufgelöst wird. Produktionsnahe Automatisierung braucht wiederholbare Listen-Politiken, auditierte Compose-Revisionen und stabile Host-Grenzen. Ad-hoc-Notebooks liefern selten Multi-Region-Egress mit Bare-Metal-Isolation, was mit Always-on-Gateway-Erwartungen kollidiert.
Für Teams, die eine erreichbare, bereitzuschaltende Steuerungsebene brauchen, schlägt Hosting des Gateways auf professionellen Cloud-Macs oft fragile Privathardware. MACCOME stellt Mac Mini M4 / M4 Pro Bare-Metal-Knoten in Singapur, Japan, Korea, Hongkong, US-Ost und US-West bereit. Nach der Netzwerk-Triage SSH vs. VNC mit dem Hilfe-Center kombinieren, anschließend Mietpreise und Regionsseiten finalisieren.
Auf einem dedizierten Test-Host pilotieren, Logs archivieren, dann ins gemeinsame Compose-Repository promoten—tribales network_mode-Wissen vermeiden.
Jedes temporäre 0.0.0.0-Bind braucht dokumentiertes Rollback und Expositions-Review; Triage zielt darauf ab, wer die Steuerungsebene sehen soll, mit Namespace-Design in Einklang zu bringen, nicht die Listenfläche zu maximieren.
FAQ
Worin unterscheidet sich dies vom Docker-Produktions-Runbook?
Produktion behandelt Images, Volumes und Rollouts; dies behandelt Erreichbarkeit. Hilfe-Center zusammen mit dem Produktions-Runbook nutzen.
Gilt dieselbe Matrix unter WSL2?
Gleiche Reihenfolge, andere Localhost-Weiterleitung—den WSL2-Triage-Artikel darauf legen.
Wo lese ich zu Regionen und Mietkonditionen?
Wenn das Gateway auf einen Cloud-Mac wandert, mit dem Multi-Region-Leitfaden und den Mietpreisen abstimmen, bevor SSH-Egress festgezurrt wird.