Manchmal reicht ein kleiner Routine-Job und eine harmlose Domain-Änderung, um einen ganzen Nachmittag zu verschlingen. Genau das ist mir mit meiner OpenClaw-Instanz passiert – Webinterface und Telegram-Bot waren plötzlich tot, und die Ursachenkette entpuppte sich als kleines Lehrstück in Sachen „ein Problem verdeckt das nächste“.
Der Ausgangspunkt
OpenClaw läuft bei mir nativ auf einer eigenen VM – kein Docker, sondern ein klassischer systemd-User-Service. Nachts um kurz nach zwei prüft ein automatischer „Hausmeister“-Timer, ob es Updates gibt, installiert sie und soll danach den Gateway-Service neu starten. Normalerweise unspektakulär. An diesem Tag aber: Webinterface tot, Bot antwortet nicht.
Der erste Reflex war, den Prozess zu suchen – kein Docker-Container, kein laufender Node-Prozess, nur ein Update-Timer, der brav „erfolgreich“ gemeldet hatte. Der Teufel steckte, wie so oft, im Detail des Update-Logs:
Restarting service...
Gateway: restart skipped (no installed service found).Das Update selbst lief durch, aber der eigentliche Dienst kam nie wieder hoch.
Fund Nummer 1: Ein Legacy-State blockiert den Start
Der manuelle Startversuch offenbarte den eigentlichen Blocker:
OpenClaw startup migrations did not complete cleanly; refusing to report the gateway ready.
Left legacy update-check state in place because shared SQLite state already differsEine alte JSON-Datei mit dem Update-Check-Status war nicht mehr kompatibel mit dem neuen SQLite-basierten State und OpenClaw weigerte sich – zu Recht vorsichtig – einfach drüberzubügeln. Die Datei enthielt nichts Kritisches (nur Zeitstempel und Versionsnummern der letzten Update-Prüfung), also wanderte sie kurzerhand aus dem Weg. Startversuch zwei.
Fund Nummer 2: Der Service selbst war museumsreif
openclaw doctor --fix – der eingebaute Reparatur-Assistent – brachte den nächsten Fund ans Licht: Der systemd-Service war noch von einer älteren OpenClaw-Version angelegt worden, während die CLI längst weiter war. Ein Update der Service-Konfiguration auf die aktuellen Defaults, und der Gateway lief tatsächlich stabil durch. Kurzer Moment der Erleichterung.
Ein Nebenschauplatz eröffnet sich
Beim Versuch, mir den Zugang zum Webinterface einzurichten, fiel mir auf: Ich hatte kürzlich die Domain für den Reverse Proxy von openclaw.example.tld auf openclaw-web.example.tld umgestellt. Klang nach einer Kleinigkeit. War es nicht.
Problem A – der Browser wird abgewiesen: Die Control-UI kannte nur die alte Origin und lehnte jede Verbindung von der neuen Domain kategorisch ab. Ein Eintrag in gateway.controlUi.allowedOrigins, fertig.
Problem B – die Verbindung bricht trotz gültigem Token ab: Kurios: Der WebSocket-Handshake gelang, der Token wurde akzeptiert – und trotzdem flog die Verbindung sofort wieder raus. Im Log stand ein unscheinbarer Hinweis: OpenClaw vertraute meinem Reverse Proxy nicht als solchem und behandelte die Verbindung dadurch nicht als „lokal“. Ein Eintrag in gateway.trustedProxies mit der IP des Proxy-Hosts löste das.
Problem C – immer noch derselbe Fehlercode: Auch danach brach die Verbindung an exakt derselben Stelle ab. Des Rätsels Lösung: OpenClaw führt für Clients ein Pairing-System, und der Browser über die neue Domain zählte als neues, nicht genehmigtes Gerät. Ein Blick in die Liste der ausstehenden Pairing-Anfragen, eine Freigabe – und endlich, endlich ging die Tür auf.
Die Lektion
Vier voneinander unabhängige Ursachen, die sich alle hinter derselben Symptomatik („geht einfach nicht“) versteckten:
- Ein liegengebliebener Legacy-State blockierte den Start
- Eine veraltete Service-Konfiguration
- Eine fehlende erlaubte Origin
- Ein nicht vertrauter Proxy
- Ein nicht freigegebenes Gerät
Jeder einzelne Punkt für sich wäre in fünf Minuten erledigt gewesen – wenn man gewusst hätte, wonach man sucht. Zusammen ergaben sie eine hübsche kleine Fehlersuche mit mehreren Sackgassen. Die Erkenntnis, die bleibt: Bei einer Domain-Änderung an einem Dienst mit eigenem Auth-Modell reicht es nicht, nur DNS und den Reverse Proxy anzupassen. Origin, Proxy-Trust und Device-Pairing wollen alle drei mitgenommen werden – sonst begrüßt einen am Ende ein Login-Formular, das zwar aussieht, als würde es funktionieren, aber beharrlich schweigt.
Webinterface und Telegram-Bot laufen jetzt wieder wie gewohnt. Und ich habe mir für die Zukunft eine kleine Checkliste angelegt, damit der nächste Domain-Umzug nicht wieder zur Nachmittagsfüllung wird.