1. Schmerzzerlegung: Locken aus dem falschen Namespace belügt Sie
(1) WS-Loopback-Verwirrung: ws://127.0.0.1:18789 ist auf dem Host korrekt, wenn der Port veröffentlicht wird, aber innerhalb eines einem anderen Container führt es eine Schleife zu sich selbst durch. Wenn das Gateway den Dienstnamen openclaw-gateway abhört, erreicht ihn die fest codierte Nummer 127.0.0.1 nie. (2) Pairing vs. Token: pairing required ist ein Autorisierungssitzungsproblem; token mismatch ist eine geheime Nichtübereinstimmung; Durch das Mischen entstehen zufällige Bearbeitungen. (3) Umgebung überschreibt Dateien: Eine einzelne OPENCLAW_GATEWAY_TOKEN-Zeile in Compose kann gemountetes gateway.auth.token überschreiben, was zu „Ich habe JSON geändert, aber nichts verschoben“ führt. (4) Remote-Mac-Dual-Stacks: launchd plus compose, das dieselbe Portdeklaration oder dasselbe Statusverzeichnis verwendet, führt zu zeitweise stillen Fehlern.
2. Symptommatrix: Triage-Transport vor Authentifizierung vor Kanälen
| Signal | Hypothese | Erste Aktion |
|---|---|---|
1006 / Zurücksetzen |
Falscher Host- oder Portkonflikt | Führen Sie im dem gleichen Netzwerk-Namespace wie die CLI, run nc -vz host port |
1008 pairing required |
Pairing aus unvollständig | Steuerungs-UI öffnen, Paarungscode ausgeben, CLI-Paarbefehl ausführen |
token mismatch |
Duale Quellen der Wahrheit | Env im CLI-Container drucken; mit Volume-JSON abgleichen |
| Flockiger Erfolg | Zwei Instanzen laufen im Status | docker ps plus Volume-Tabelle; auf ein Gateway verkleinern |
3. Runbook in fünf Schritten: vom Ping bis zu einer erfolgreichen Kanalprüfung
- Namespaces einfrieren: Dokumentieren Sie, ob CLI auf Host, Sidecar oder CI-Runner ausgeführt wird; Zeichnen Sie einen Pfeil vom Client zum Listener.
- Explizite Gateway-Basis: Setzen Sie
OPENCLAW_GATEWAY_URL(oder Ihr dokumentiertes Äquivalent) aufopenclaw-gateway:18789oder den veröffentlichten Host-Port – gehen Sie niemals 127.0.0.1 über Namespaces hinweg an. - Pairing-Gate: Beenden Sie das Pairing, bevor Sie Geschäftskanäle testen. Behalten Sie zwei Ticketvorlagen für „ungepaartes“ vs. „falsches Token“.
- Einzelne Token-Quelle der Wahrheit: Env-Datei oder als kanonisch auswählen; Machen Sie die andere Übereinstimmung oder entfernen Sie sie.
- Mit Kanalprobe akzeptieren: Führen Sie eine erfolgreiche Probe aus derselben Umgebung aus und hängen Sie Protokolle an und verfassen Sie ein Snippet zur Änderungsanforderung.
4. Wenn network_mode: „service:openclaw-gateway“ gerechtfertigt ist
Verwenden Sie es, wenn die CLI den Gateway-Netzwerk-Namespace gemeinsam nutzen muss, um sprödes DNS unter der Standardbrücke zu vermeiden. Die Kosten verwirren die Localhost-Semantik – stellen Sie sie grafisch dar. Alternative: Behalten Sie die CLI auf dem Host bei und verweisen Sie WS auf den veröffentlichten Host-Port, wobei Sie die TLS-Beendigung am Reverse-Proxy ausrichten.
5. Zitierbare Schwellenwerte (durch Ihre Messungen ersetzen)
Diskussionswürdige Zahlen:
- Wenn der TCP-Verbindungserfolg aus dem CLI-Namespace unter 97 % über 100 Tests fällt, stoppen Sie die Funktionsarbeit und reparieren Sie zuerst DNS, Dienstnamen oder veröffentlichte Ports.
- Wenn Sie mehr sehen Als drei
token mismatchEreignisse innerhalb eines einzelnen Paarungsfensters gehen Sie von zwei Quellen aus, bis das Gegenteil bewiesen ist. - Wenn die Sperrwartezeit für ein freigegebenes Statusverzeichnis 2,5 s bei p95 auf einem Remote-Mac überschreitet, teilen Sie Volumes auf oder verschieben Sie die CLI in ein dediziertes Beiwagen.
6. Lesen von Openclaw-Protokollen in drei Schichten
Filtern Sie zuerst Transportleitungen, dann Authentifizierung und Paarung und dann kanalspezifische Leitungen. Fügen Sie dem Ticket drei Screenshots statt nur eine Beschreibung bei. Wenn Sie es zusammen mit dem offiziellen install.sh-Artikel lesen, behandeln Sie die Installationsreihenfolge und die Netzwerkausrichtung als zwei separate Akzeptanztore.
| Schicht | Frage | Pass-Beispiel |
|---|---|---|
| L1-Transport | War der WS-Handshake erfolgreich? | Kein ungeklärtes 1006/1008 |
| L2 auth | Sind Token und Paarung konsistent? | Keine unautorisierte Schleife nach der Paarung |
| L3-Kanäle | Ist der Kanal online? | channels probegibt einen interpretierbaren Zustand zurück |
7. Remote-Mac: launchd vs. Docker für Ports und Volumes
Dokumentieren Sie, wer Port 18789 besitzt, ob der Status ein Bind-Mount oder ein benanntes Volume ist und welche Einheit bei Upgrades zuerst stoppt. Kombinieren Sie es mit dem SSH vs. VNC-Leitfaden, um interaktive VNC-Bearbeitungen von unbeaufsichtigten Erstellungsrollen zu trennen.
8. FAQ
Wird extra_hosts alles reparieren? Manchmal, aber wenn die Ursache in zwei Token-Quellen liegt, mischt extra_hosts nur die Fehlermodi neu.
Gateway an 0.0.0.0 binden? Lesen Sie zuerst den Artikel zur Angriffsfläche; Öffentliche Offenlegung ist nicht die Standardantwort.
Konflikt mit install.sh-Ablauf? Nein – install.sh legt die Grundreihenfolge fest; Dieser Artikel konzentriert sich auf Docker-Netzwerke und Authentifizierungsausrichtung.
9. Fallstudie: In den Protokollen heißt es: Abhören, CLI immer noch 1008
Ein häufiger Fehlermodus im Jahr 2026 ist das Gateway-Abhören in Container A, während Entwickler CLI in Container B mit ws://127.0.0.1 ausführen. Auf dem Papier ist es offensichtlich, in Multi-Repo-Setups jedoch teuer. Fügen Sie den Satz „Namespace, der openclaw ausführt“ oben in die README-Datei ein und fügen Sie einen CI-Smoke hinzu, der die Sonde aus dem Runner-Container ausführt.
Eine zweite Klasse ist vergessen OPENCLAW_GATEWAY_TOKEN Zeilen in Override-Dateien. Wählen Sie Env-or-File-Disziplin und fügen Sie einen PR-Checklistenpunkt für Token-Env-Diffs hinzu.
Eine dritte Klasse trifft Remote-Macs, wenn Time Machine oder Synchronisierungssoftware Statusverzeichnisse spiegeln und so Phantom-Second-Gateways erzeugen. Markieren Sie Statusverzeichnisse als nicht synchronisiert oder konsolidieren Sie sie auf einem dedizierten Remote-Knoten.
Kombinieren Sie den Migrationsartikel, um die Übungen zur „Maschinenmigration“ von den Übungen zum „Zusammenstellen und Neuaufbau“ zu trennen. Das Mischen bringt Rollback-Storys durcheinander.
Docker ist eine wiederholbare Bereitstellung unter stärkeren Einschränkungen, keine automatische Einfachheit. Hängen Sie Compose, Env-Drucke, NC-Ausgabe und dreischichtige Protokollausschnitte an, bevor Sie die Produktionsbereitschaft beanspruchen.
10. n8n und Webhook-Ingress
Wenn n8n Ihren Stack zurückruft, muss der HTTP-Ingress-Besitzer mit dem WS-Token-Besitzer übereinstimmen. Teilen Sie HTTP 502-Untersuchungen von WS 1008-Tickets mithilfe unterschiedlicher Titel auf.
11. Upgrade-Disziplin: zuerst ein einzelnes Gateway
Verkleinern Sie sich bei aktuellen Releases auf ein Gateway und eine CLI, bevor Sie HA erneut aktivieren. Halb aktualisierte Volumes erzeugen halbkonsistente Schemata; Hängen Sie die Arztausgabe an den Änderungsdatensatz an.
12. Abschluss: Docker beweist Wiederholbarkeit, Remote-Mac trägt das SLO
(1) Einschränkungen: Ohne Dokumentation von CLI-Namespaces wird die Fehlerbehebung durch Docker exponentiell; Dual-Token-Quellen sorgen dafür, dass sich Konfigurationsänderungen zufällig anfühlen.
(2) Warum Remote-Mac-Pools helfen: Dedizierte Hosts erstellen Versionen, Volumes und Integritätsprüfungen fern von Entwickler-Laptops.
(3) MACGPU-Passform: Wenn Sie eine reibungslose Testversion abgestimmter Remote-Mac-Gateways anstelle von Laptop-Servern wünschen, bietet MACGPU mietbare Knoten und öffentlichen Hilfeeintrag Punkte; Der CTA unten enthält Links zu Plänen ohne Anmeldung.
(4) Endgültiges Tor: Beanspruchen Sie nicht die Produktionsbereitschaft ohne einen erfolgreichen channels probe plus Compose-/Env-/Token-Alignment-Nachweis.
13. Links zur Installationsmatrix und zu install.sh
Wenn install.sh noch nicht grün ist, lesen Sie zuerst diesen Artikel. Wenn grün, Docker jedoch fehlschlägt, starten Sie hier von der L1-Matrix aus neu. Die Drei-Stack-Matrix hilft bei der Entscheidung, ob CLI zum Host oder in einen Sidecar gehört.
14. Beobachtbarkeit: Kommentieren Sie den Explosionsradius pro Compose-Projekt
Wenn sich mehrere Compose-Projekte einen Host teilen, kennzeichnen Sie, welches Projekt Port 18789 besitzt und welches Webhook-Ingress besitzt. On-Call sollte eine einzelne Seite mit dieser Karte öffnen, anstatt den Slack-Verlauf zu durchsuchen.
15. Sicherheitshinweis: Token in env vs. geheime Dateien
Umgebungsvariablen erscheinen in Prozesslisten und Absturzdumps. Wenn Ihr Bedrohungsmodell dies verbietet, bevorzugen Sie geheime Dateien mit den richtigen Volume-Berechtigungen und entfernen Sie Umgebungsduplikate. Befolgen Sie den Leitfaden zur Gateway-Angriffsoberfläche für Bindungsadressen und Reverse-Proxys.
16. CI-Parität: Reproduzieren Sie den fehlerhaften Namespace in GitHub Actions
Viele Teams reproduzieren OpenClaw-Probleme nur auf Laptops. Fügen Sie einen Job hinzu, der dasselbe Compose-Projekt erstellt und docker compose run --rm openclaw-cli openclaw channels probe ausführt, damit Regressionen in WS-URLs vor der Zusammenführung abgefangen werden. Zwischenspeichern Sie Bilder sinnvoll, aktualisieren Sie aber dennoch die Tags, wenn Sicherheitspatches verfügbar sind. Wenn Ihre CI-Runner Docker-Dienstnamen nicht auflösen können, dokumentieren Sie diese Einschränkung explizit, anstatt stillschweigend auf 127.0.0.1 zurückzugreifen, was den Produktionsfehlermodus verbirgt.
17. Reverse-Proxys und WebSocket-Upgrade-Header
Wenn TLS bei Nginx oder Caddy endet, überprüfen Sie Upgrade-Header, Leerlauf-Timeouts und Puffereinstellungen. Ein Proxy, der WebSocket-Frames puffert, kann unter Last so aussehen, als würde er zufällig 1006 geschlossen. Erfassen Sie Proxy-Zugriffsprotokolle neben OpenClaw-Protokollen und korrelieren Sie Zeitstempel. Wenn Sie TLS auf dem Host beenden, während Gateway in Docker reines HTTP bleibt, behalten Sie dieses Diagramm im Repo, damit neue Mitarbeiter nicht erneut eine doppelte Verschlüsselung oder ein falsches Schema in OPENCLAW_GATEWAY_URL einführen.
18. Runbook-Übergabevorlage für Bereitschaftsdienst
Fügen Sie Folgendes in Ihre Vorfallvorlage ein: Verfassen Sie den Projektnamen, die Image-Tags, die WS-URL aus Sicht des fehlerhaften Namespace, die Ausgabe von „env grep“ für OPENCLAW_-Variablen, die Ausgabe des Volume-Pfads für „gateway.auth.token“, das Ergebnis von „nc“ und die letzten zwanzig Zeilen der Gateway-Protokolle, gefiltert nach Ebene. Wenn rechtliche oder behördliche Bestimmungen Cloud-GPUs blockieren, bleibt ein dokumentierter Remote-Mac-Pool eine pragmatische Möglichkeit, stabile Apple Silicon-Kapazität für ständig verfügbare Agenten ohne Kapitalanschaffungen hinzuzufügen.
19. Versionsunterschied zwischen CLI- und Gateway-Images
Die Aufteilung von CLI und Gateway auf verschiedene Image-Tags ist zulässig, jedoch nur, wenn Ihre Versionshinweise diese Matrix explizit unterstützen. Wenn die CLI ein Handshake-Feld hinzufügt, das der Gateway-Build nicht versteht, werden Sie undurchsichtige Verbindungsabbrüche sehen, die Netzwerkfehlern ähneln. Befestigen Sie beide Bilder bei Vorfällen an derselben Freigabeschiene und halbieren Sie sie dann. Erfassen Sie die Zusammenfassungen in Ihrem Vorfalldokument, nicht nur schwebende Tags. Automatisieren Sie für Remote-Mac-Flotten eine wöchentliche Digest-Prüfung, damit sich die Abweichung nicht stillschweigend ansammelt, während sich die Ingenieure auf die Funktionsarbeit konzentrieren.
20. Dokumentationsschulden sind Betriebsschulden
Jede Stunde, die Sie mit der Neuentdeckung der 127.0.0.1-Semantik verbringen, ist eine Stunde, die Sie nicht mit der Verbesserung von Eingabeaufforderungen oder Tools verbringen. Investieren Sie einmal in eine One-Page-Topologie und verlinken Sie sie aus README, Runbooks und Onboarding. Wenn Führungskräfte fragen, ob OpenClaw produktionsbereit ist, geben Sie ihnen das Prüfprotokoll und den Compose Digest, keine mündliche Zusicherung. Die Remote-Mac-Vermietung macht gute Dokumente nicht überflüssig, bietet Ihnen aber einen stabilen Ort zum Hosten des kanonischen Stacks, der der tatsächlich ausgeführten Produktion entspricht.
21. Eingabeaufforderungen zur Überprüfung nach dem Vorfall
Beantworten Sie nach dem Schließen eines Gateway-Vorfalls fünf Fragen schriftlich: Welcher Namespace hat die CLI initiiert, welche Datei oder Umgebungsvariable enthielt letztendlich das Token, ob vor der Token-Bearbeitung ein Pairing versucht wurde, ob sich ein Proxy auf dem Pfad befand und welcher Compose-Digest während des Ausfalls aktiv war. Das Fehlen einer Antwort bedeutet in der Regel, dass sich der Vorfall im nächsten Quartal unter einer anderen Symptomzeichenfolge wiederholt.
Behandeln Sie abschließend kleinere macOS-Upgrades auf Remote-Hosts als geringfügige Beeinträchtigungen für Ihren Stack: Führen Sie nach jedem Upgrade-Fenster erneut Probe- und NC-Prüfungen durch, bevor Sie die Flotte wieder für fehlerfrei erklären.