2026 OpenClaw unter Linux systemd nach Upgrade: HOME-Drift, leer wirkende Gateway-Konfiguration, doctor Runbook

Nach Distribution-Upgrades oder größeren Paketbewegungen können systemd --user-Dienste weiterhin Ports binden und grün wirken, während sie unter anderem HOME oder anderen XDG-Basispfaden nach openclaw.json suchen als Ihre interaktive SSH-Sitzung. Behandeln Sie dies zuerst als Umgebungsdrift mit anschließendem dokumentiertem Merge auf JSON-Ebene, bevor Sie Modell-Anbieter oder Netzwerk als Ursache disqualifizieren. Dieses Notizbuch adressiert Bare-Metal oder virtuelle Maschinen mit persistenten Nutzerunits, nicht reine Container-Installationen ohne relevante ~/.config/systemd/user-Ebene.

1. Dreischichtiges Symptombild: Prozess aktiv, Schnittstellenantwort merkwürdig, Oberfläche wirkt wie Gerüst

Prozessschicht: systemctl --user meldet aktiv, aber der Gateway-Prozess liest eine Minimalvariante von openclaw.json, weil die Unit nicht dieselben Umgebungsvariablen erhält wie Ihre Shell. Der Dienst startet sauber neu, jedoch aus einem falschen Stammbaum für Konfigurationsdateien.

Schnittstellenschicht: openclaw gateway status kann Build- oder Pfadhinweise zeigen, die mit dem vom Nutzer verwendeten CLI-Paket nicht übereinstimmen; konsultieren Sie vor dem Löschen von Verzeichnissen die Hinweise zu Versionssplitting unter Split-Brain-Leitfaden oder vergleichbare interne Reihen zur SemVer-Analyse.

Oberflächen- und Sessionschicht: Dashboards laden statischen Inhalt und WebSocket-Verbindungen stürzen später ab oder bleiben leer bezüglich Anmeldekontext, wenn Credential-Speicher und Kanalzuordnung zu einer anderen Pfadwahl gehören. Die wartungsrechtlich empfohlene Leiter beginnt erst mit Zuverlässigkeitsbelegen zur Erreichbarkeit auf Protokoll- und Health-Ebene, nicht mit bloßem Neuladen im Browser.

1. Sichern Sie unmittelbar nach kontrolliertem Neustart mindestens die ersten zweihundert Journalzeilen der Gateway-Unit und durchsuchen Sie nach ENOENT-, HOME- sowie expliziten Konfigurationspfad-Tokens im Klartextlog.
2. Halten Sie drei Umgebungssätze vergleichbar: interaktive Anmeldung, nicht-anmeldende su-Aufrufe mit unterschiedlichen Nutzerkonten und Ausgaben von systemctl --user show … für die konkrete Dienstfragmentdatei.
3. Packen Sie alte sowie neu entdeckte Konfigurationsbäume konsequent vor jedem strukturellen JSON-Merge oder vor gateway install --force, damit spätere Incident-Reviews absolute Integrität prüfen können.

Ein laut ss -lntp angezeigtes lauschendes TCP-Socket belegt höchstens, dass irgendeine Instanz Ports gebunden hat, nicht jedoch, dass sie dieselbe openclaw.json nutzt wie Ihre manuelle Bearbeitung unter dem persönlichen Heimatverzeichnis. In gemischten Bereitstellungen passiert häufig, dass das CLI mittels erhöhter Privilegien installiert wurde, operative Änderungen aber als normaler Bereitstellungscode oder sogar zweites technisches Konto vorgenommen werden; dann existieren zwei parallele HOME-Räume, und der Daemon bedient Zugriffe ohne je Ihre echte Kanalliste geladen zu haben.

Die Festlegung durch XDG-Verzeichnisvariablen entscheidet mit, ob Voreinstellungen auf ~/.config/openclaw, ~/.local/state oder ältere Fallback-Pfade unter ~/.openclaw konsolidiert werden; Minor-Upstreams haben gelegentlich Suchreihen neu geordnet. Fehlen XDG_CONFIG_HOME und XDG_STATE_HOME nur in Servicekontext, entsteht genau diese Diskrepanz ohne expliziten Dateifehler im Editor. Dokumentieren Sie daher beim Ticket immer absolut aufgelöste Pfade ohne Tilde-Verkürzung, damit keine zweite Bearbeiterin dieselbe Kurznotation versehentlich im falschen Kontext expandiert.

Verschwinden registrierte Erweiterungen plötzlich in der grafischen Liste, Filesystem-Dateien jedoch nicht, liegt die Vermutung nahe auf eine zusätzliche openclaw-Instanz aus Cron, aus Root-Parallelunits oder Deploy-Skripten. Kombinieren Sie systemctl --user list-units 'openclaw*' mit pgrep -af openclaw, um keine Debug-Session gegen den falschen Hauptprozess-ID zu verschwenden.

Unmittelbare Paketbereinigungen oder rekursive Löschaktionen in angenommen falschen Skeleton-Verzeichnischen sind riskant; sie vernichten häufig zuvor automatisch migrierten Metazeilen und meta.lastTouchedVersion-Hinweise.

2. Von systemd-Inspect bis OpenClaw-Doktor: die offizielle Reihenfolge respektieren

Die Reihenfolge Status prüfen, Gateway-Management-Schnittstelle befragen, Journal mit Unit-Filtern lesen und schließlich openclaw doctor entspricht einem Schutz vor parallelem Raten auf mehreren Ebenen. Wer Modell-Anbieter zuerst wechselt, obwohl HOME-Drift aktiv ist, erhält neue Fehlermodi ohne kausale Zuordnung.

Ein systemd --user-Dienst erbt keine interaktiven Profile aus ~/.bashrc oder Zsh-.zprofile. PAM-Exporte grafischer Sessions, eingeschränkte SSH-AcceptEnv-Listen und systemd-intern gesetzte Leereinträge können sich addieren. Wenn HOME fehlt, wählen Laufzeitumgebungen oft schreibbare Standardverzeichnisse unterhalb installierter Paketbäume; dadurch erscheint eine frische scheinbare Konfiguration, während Ihre produktive Datei unangetastet im SSH-Heimatordner liegt.

Die maßgebliche Autorität bleibt systemctl --user show UNIT -p Environment -p WorkingDirectory -p FragmentPath -p User, nicht der visuelle Eindruck einer Konsole. Vergleichen Sie Ausgaben mit printenv HOME XDG_CONFIG_HOME XDG_STATE_HOME aus Login-Shell, aus nicht-login Shell und mit beliebigen CI-Läufern, die dieselbe Maschine präpariert haben. Weicht nur eine Zeile ab, korrigieren Sie gezielt per Drop-In-Fragment statt stumpfem Kopieren gesamter Datenbäume.

WorkingDirectory bestimmt relative Auflösung innerhalb von ExecStart; verweisen ältere Units noch auf entfernte Checkouts oder globales node_modules-Layout vor npm-Verschiebung, laden Standard-Plug-ins, während Ihre Aktivitätenliste leer wirkt. Protokollieren Sie nach jedem Neustart den absolut vom Gateway angezeigten Konfigurationsstamm mittels Gateway-Statusbefehlen, sodass spätere Auditorinnen den Tarball gegen Laufzeitwahrheit abgleichen.

Headless-Rechner ohne loginctl enable-linger für den proprietären Dienstnutzer terminieren häufig den User-Manager beim letzten Sitzungsende; symptomatisch wirkt dann intermittierende Leere nach SSH-Neuverbindungen. Kombinieren Sie Linger-Verifikation mit journalctl --user -u UNIT -b, um Restarts paketbezogen oder durch manuelle Daemon-Reloads zu korrelieren statt Uhrenmutation zu raten.

Divergiert die SemVer-Zuordnung zwischen CLI und Daemon, priorisieren Sie zuerst die Split-Brain-Anleitung; HOME-Korrektur allein lässt halb migrierte Kanalregistrationen bestehen, wenn Versionsmetadaten widersprechen.

Geheimnisse sollten strukturell zuletzt verschoben werden: ein Teilkonfigurationsmix, der zuerst OAuth-Caches oder Tokens anfasst, kann Chat-Anbieter sperren, während die UI noch halb rendert. Halten Sie zwei Tarballs—vor Merge und nach erfolgreichem Doctor-Lauf—mit UTC-Zeitstempel und Kurzhostname im Dateinamen.

Für Flotten empfiehlt sich, Golden-Images vor Minor-Sprüngen mit geänderter Suchlogik einzufrieren; versionieren Sie Drop-In-SHA256 und Paketversionszeile im selben Change-Record. Gezwungene Installationen via gateway install --force gehören in ein kommuniziertes Wartungsfenster mit versioniertem Rollback der Unit-Fragmente, nicht in improvisierte Freitagabend-Sitzungen.

Reine Docker- oder Compose-Stacks beziehen Umgebung aus Orchestrator-Definitionen, nicht aus Nutzer-Drop-Ins. Vermischen Sie bare-metal user units und Compose auf einem Host, kennzeichnen Sie Tickets klar, damit Linux-spezifische Korrekturhinweise nicht fälschlich auf Container mit HOME=/root projiziert werden.

macOS-Betriebskräfte sollten die launchd-Gateway-Notizen parallel lesen: Symptome ähneln sich, Werkzeuge heißen launchctl statt loginctl. Halten Sie Plattformgrenzen in Runbooks sichtbar, damit innerhalb von Minuten die richtige Schiene gewählt wird.

Budgetieren Sie nach jedem Merge explizit circa fünfzehn Minuten für Kanalsondierungen und je einen synthetischen Nachrichtentest pro Anbieter. Ohne diese Schicht tauchen stille Regressionen trotz null-exit doctor in Produktion auf. Scheitern Sondierungen, erfassen Sie HTTP-Status und WebSocket-Schließcodes vor Hersteller-Tickets, damit Dritte Ihren exakten Pfad reproduzieren.

Langfristig zahlt sich aus, Unit-Fragmente im Konfigurationsmanagement zu versionieren und Hash-Summen im Ticket zu spiegeln; so erkennen Sie unautorisierte lokale Bearbeitungen früh.

OpenClaws Konfigurationsmerger sollten Sie als semi-strukturierte Daten behandeln: Validieren Sie nach jedem kopierten Block mit demselben JSON- oder Schemawerkzeug wie in CI. Zusätzlich lohnt es, Credential-Pfade gegen reale UNIX-Berechtigungen zu testen—der Dienst läuft typischerweise als Nicht-root und darf keine Dateien öffnen, die nur Deploy-Root gehören.

Wenn Proxys oder systemd-EnvironmentFile=--Direktiven mehrere Quellen übereinander legen, kann die Reihenfolge entscheiden, welcher Wert gewinnt. Dokumentieren Sie die effektive Kette im Ticket, nicht nur eine einzelne Datei als mutmaßliche Wahrheit.

3. Entscheidungsmatrix: nur neu starten, Merge oder erzwungene Neuinstallation

Nutzen Sie die folgende Tabelle innerhalb planbarer Wartungsfenster; für Flotten frieren Sie Basis-Image-Hash und Paketlock ein. Wechseln Sie die gewählte Zeile, sobald Journal-Rauschen direkt nach daemon-reload signifikant ansteigt, denn syntaktisch korrekte Drop-Ins können dennoch falsche Pfade exportieren.

Kanarische Hosts sollten jede Rollout-Welle eröffnen; zeigt der erste Knoten erneut einen Skeleton-Pfad, stoppen Sie die Verteilung und hängen die Drei-Wege-Umgebungsdiffs an den Vorfall statt identische Unit-Dateien flächendeckend zu verteilen.

Risikolabel sind relativ: selbst gering eingestufte Drop-In-Änderungen können Automatisierung brechen, wenn daemon-reload vergessen wird. Koppeln Sie Reload, kontrollierten Restart und bereitliegenden Rollback-Tarball. Hochriskante erzwungene Installationen verlangen zweite technische Review der generierten Fragmente.

4. Siebenstufiger Merge für Konfigurationsbäume

systemctl --user show openclaw-gateway.service -p Environment -p WorkingDirectory -p FragmentPath
echo "$HOME" "$XDG_CONFIG_HOME" "$XDG_STATE_HOME"
tar czf ~/openclaw-premerge-$(date +%Y%m%d%H%M).tgz ~/.openclaw ~/.config/openclaw 2>/dev/null

1. Frieren Sie parallele Bearbeitung ein: stoppen Sie CI-Jobs und bitten Sie Menschen, während des Merges keine weiteren globalen npm i -g- oder Editorzyklen auf derselben JSON-Struktur auszuführen.
2. Exportieren Sie Umgebungsdumps für Root, Login-Shell und die Nutzerunit in drei Textdateien, damit spätere Vergleiche ohne erneutes Abtippen unter Zeitdruck möglich bleiben.
3. Vertrauen Sie Pfadhinweisen aus openclaw gateway status bezüglich des tatsächlich adoptierten Konfigurationsstamms gegenüber intuitiv präferierten Pfaden.
4. Verschieben Sie zuerst Kanaldefinitionen, danach Plug-In-Blöcke, erst zuletzt Credential-Abschnitte; validieren Sie jeden Block mittels Parser und minimalem Smoke-Test vor Token-Bewegung.
5. Führen Sie openclaw doctor aus, erfassen Standardausgabe und Fehlerstrom, wiederholen Sie anschließend openclaw gateway status, damit Tickets Vorher-Nachher-Paare zeigen.
6. Überprüfen Sie bei Headless-Hosting loginctl show-user "$USER" -p Linger, wenn SSH-Sitzungen flüchtig sind und der User-Manager sonst zerfallen kann.
7. Schreiben Sie SemVer-Zeilen, Drop-In-SHA256, Tarballpfad zur Rückstellung und Restart-Zeitstempel strukturiert in Ihr Incident- oder Change-Werkzeug, damit nächste Schicht ohne Neuauflage der Rekonstruktion startet.

5. Druckbare Checkliste mit erwarteten Schwellen

Übernehmen Sie folgende Reihen Zahlenfelder gegen interne SLA; verschärfen Sie sie bei normativ regulierten Arbeitslasten entsprechend.

Archivieren Sie mindestens sieben Kalendertage relevante Journalauszüge auch nach erfolgreichem Merge, damit Spike-Muster beim nächsten Upgrade vergleichbar bleiben. Speichern Sie Tarball-Prüfsummen neben Hashwerten von Unitfragmenten gemeinsam, damit Integrität später trotz Ticketsystemmigration nachweisbar ist.

Für kritische Produktionsknoten sollten zusätzliche Betriebsfenster dokumentiert sein, innerhalb derer keine parallelen Sicherheitspatche ohne Koordination den Node neu starten. Sonst verschwimmen Ursachenlinien zwischen ungeplantem Kernel-Neustart und Ihrem bewussten Gateway-Recycle.

Harmonisieren Sie Uhrzeiten zwischen Journal und zentralisierten Logsystemen bereits vor dem Incident; Zeitversatz verfälscht sonst Reihenfolge von Paketinstallation und systemd-Restart sichtbar.

6. Abgrenzung: Split-Brain, Container und macOS

Die Split-Brain-Dokumentation behandelt SemVer-Angleich, Metadaten wie meta.lastTouchedVersion und vertiefte Statusausgaben, wenn CLI und Daemon weiterhin widersprechen trotz korrigierter HOME-Werte. Nutzen Sie sie, wenn doctor Versionsabweichungen meldet, obwohl Pfade nun stimmen.

Compose- oder Kubernetes-gestützte Deployments mappen Variablen wie OPENCLAW_GATEWAY_TOKEN Container-intern; kopieren Sie Linux-Drop-In-Zeilen nicht wortwörtlich, sondern übersetzen Sie sie in deklarative Umgebungsblöcke und halten Sie Geheimnisse außerhalb von Git.

macOS-launchd-Artikel adressieren Plist-Reload und Node-Pfadverschiebungen; Symptome ähneln Linux-Drift, Korrektur aber zielt auf launchctl und Eigentümerschaft statt loginctl-Linger.

Linux-seitig bleiben User=, WorkingDirectory=, optionale EnvironmentFile=, Linger und Journal-Korrelation mit Paketupgrades die tragenden Säulen. Trennen Sie diese Themen in Tickets, damit Leserinnen die passende Anleitung innerhalb weniger Minuten identifizieren.

7. Häufige Fragen

F Darf ich das Gerüstverzeichnis löschen und alte Dateien rüberschieben? A Stoppen Sie zuerst den Dienst, snapshotten Sie, vermeiden Sie Schreibzugriffe bei laufendem Gateway. Bevorzugen Sie validierte Blockmerges statt blindem Löschen.

F Was passiert, wenn Root und normaler Benutzer je einen Gateway starten? A Port- und Konfigurationskonflikte sind vorhersehbar. Wählen Sie eine Identität, setzen Sie User= explizit, deaktivieren Sie die streunende Unit.

F Wöchentliche Minor-Upgrades in Produktion? A Nur mit automatisierten Snapshots und Kanarien; sonst übersteigen Drift-Vorfälle Ihre Merge-Kapazität.

8. Schlusswort und wann ein gehosteter Fern-Mac entlastet

Vom grünen Prozessindikator zur fachlich korrekten Konfiguration führt der Pfad über Abgleich von HOME und XDG-Variablen mit der systemd-gezeigten Wahrheit sowie anschließende RPC-Health-Belege über die offizielle Reihenfolge statt stumpfer Neustartschleifen.

Selbstgehostetes Linux bleibt anspruchsvoll bezüglich versionierter Drop-Ins, Golden-Images und Merge-Hygiene; schnelle Upstream-Zyklen machen stillen Drift wahrscheinlich, wenn Disziplin nachlässt.

Benötigen Sie lang laufende Gateways mit konsistenter Apple-Silicon-Basisplanung, weniger wöchentlicher Merge-Reibung und klar dokumentierten Änderungsfenstern, vergleichen Sie Ihren Linux-Stack mit den SFTPMAC Angeboten für gehostete Fern-Macs samt Begleit-Runbooks, damit Betriebsdauer in Agenten-Features statt in wiederholtes Aufspüren divergierender Heimatpfade investiert wird.