openclaw update

OpenClaw aktualisieren und zwischen den Kanälen Stable/Extended-Stable/Beta/Dev wechseln.

Wenn Sie die Installation über npm/pnpm/bun vorgenommen haben (globale Installation, keine Git-Metadaten), erfolgen Aktualisierungen über den unter Aktualisieren beschriebenen Paketmanager-Ablauf.

Verwendung

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update wird in openclaw update umgeschrieben (nützlich für Shells und Startskripte).

Optionen

Es gibt kein Flag --verbose. Verwenden Sie --dry-run, um die geplanten Aktionen anzuzeigen, --json für maschinenlesbare Ergebnisse und openclaw update status --json nur für Kanal und Verfügbarkeit. Die Ausführlichkeit der Gateway-Konsole (--verbose) und die Protokollierungsstufe für Dateien (logging.level: "debug"/"trace") sind unabhängige Einstellungen; siehe Gateway-Protokollierung.

update status

Zeigt den aktiven Aktualisierungskanal, Git-Tag/-Branch/-SHA (nur Quellcode-Checkouts) und die Verfügbarkeit von Aktualisierungen an.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Bei Extended-Stable-Paketinstallationen führt die Statusabfrage dieselbe öffentliche Auswahl und exakte Paketverifizierung wie die Aktualisierung im Vordergrund aus. Sie kann ahead of extended-stable melden, wenn die installierte Version neuer ist. JSON-Fehler enthalten registry.reason (selector_missing, selector_query_failed, exact_package_mismatch oder unsupported_git_channel).

update repair

Führt die Finalisierung der Aktualisierung erneut aus, nachdem das Kernpaket bereits geändert wurde, aber spätere Reparaturarbeiten nicht ordnungsgemäß abgeschlossen wurden. Dies ist der unterstützte Wiederherstellungspfad, wenn openclaw update das neue Kernpaket installiert hat, aber die anschließende Plugin-Synchronisierung, die Metadaten verwalteter npm-Plugins, die Aktualisierung der Registry oder die Doctor-Reparatur nicht konvergiert sind.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair führt openclaw doctor --fix aus, lädt die reparierte Konfiguration und die Installationsdatensätze neu, synchronisiert nachverfolgte Plugins für den aktiven Aktualisierungskanal, aktualisiert verwaltete npm-Plugin-Installationen, repariert fehlende konfigurierte Plugin-Nutzdaten, aktualisiert die Plugin-Registry und schreibt konvergierte Metadaten der Installationsdatensätze. Es installiert kein neues Kernpaket und startet das Gateway nicht neu.

update wizard

Interaktiver Ablauf zur Auswahl eines Aktualisierungskanals und zur Bestätigung, ob das Gateway anschließend neu gestartet werden soll (standardmäßig erfolgt ein Neustart). Wenn Sie dev ohne einen Git- Checkout auswählen, wird angeboten, einen solchen zu erstellen.

Funktionsweise

Beim expliziten Wechseln von Kanälen (--channel ...) wird auch die Installationsmethode entsprechend angepasst:

• dev -> stellt einen Git-Checkout sicher (standardmäßig ~/openclaw oder $OPENCLAW_HOME/openclaw, wenn OPENCLAW_HOME gesetzt ist; kann mit OPENCLAW_GIT_DIR überschrieben werden), aktualisiert ihn und installiert die globale CLI aus diesem Checkout.
• stable -> installiert über npm unter Verwendung von latest.
• extended-stable -> löst den öffentlichen npm-Selektor extended-stable auf, verifiziert das exakt ausgewählte Paket und installiert diese exakte Version. Es greift nicht auf einen anderen Selektor zurück und wird für Git-Checkouts abgelehnt.
• beta -> bevorzugt den npm-Dist-Tag beta und greift auf latest zurück, wenn Beta fehlt oder älter als die aktuelle Stable-Version ist.

Neustartübergabe

Die automatische Aktualisierungsfunktion des Gateway-Kerns startet, wenn sie über die Konfiguration aktiviert ist, den CLI- Aktualisierungspfad außerhalb des aktiven Gateway-Anfragehandlers. Paketmanager-Aktualisierungen über die Steuerungsebene update.run und überwachte Aktualisierungen von Git-Checkouts verwenden dieselbe Übergabe an den verwalteten Dienst, statt den Paketbaum zu ersetzen oder dist/ innerhalb des aktiven Gateway-Prozesses neu zu erstellen: Das Gateway startet einen abgekoppelten Hilfsprozess und wird beendet; dieser Hilfsprozess führt openclaw update --yes --json außerhalb des Gateway-Prozessbaums aus. Wenn die Übergabe nicht verfügbar ist, gibt update.run eine strukturierte Antwort mit dem sicheren Shell-Befehl zurück, der manuell ausgeführt werden kann.

Gespeicherte Extended-Stable-Auswahlen erhalten beim Start schreibgeschützte Hinweise sowie alle 24 Stunden Aktualisierungshinweise, wenn update.checkOnStart aktiviert ist. Diese Prüfungen wenden niemals eine Aktualisierung an, starten keine Übergabe, starten den Gateway nicht neu, verwenden weder die Verzögerung bzw. den Jitter von Stable noch den Abfragezyklus von Beta. Explizite Aktualisierungen im Vordergrund, einfache Aktualisierungen im Vordergrund mit gespeichertem update.channel: "extended-stable", Statusabfragen bei Bedarf und die zugehörige Übergabe des verwalteten Gateway werden weiterhin unterstützt.

Wenn ein lokaler verwalteter Gateway-Dienst installiert und der Neustart aktiviert ist, beenden Aktualisierungen über den Paketmanager und aus Git-Checkouts den laufenden Dienst, bevor sie den Paketbaum ersetzen oder die Checkout-/Build-Ausgabe verändern. Anschließend aktualisiert das Aktualisierungsprogramm die Dienstmetadaten, startet den Dienst neu und überprüft den neu gestarteten Gateway, bevor es Gateway: restarted and verified. meldet. Aktualisierungen über den Paketmanager überprüfen zusätzlich, ob der neu gestartete Gateway die erwartete Paketversion meldet; Aktualisierungen aus Git-Checkouts überprüfen nach dem erneuten Build die Funktionsfähigkeit des Gateway und die Dienstbereitschaft.

Unter macOS überprüft die Prüfung nach der Aktualisierung außerdem, ob der LaunchAgent für das aktive Profil geladen/aktiv ist und der konfigurierte Loopback-Port ordnungsgemäß funktioniert. Wenn die plist installiert ist, aber nicht von launchd überwacht wird, bootstrapt OpenClaw den LaunchAgent automatisch neu und führt die Prüfungen auf Funktionsfähigkeit, Version und Kanalbereitschaft erneut aus (ein neuer Bootstrap lädt den RunAtLoad-Job direkt, sodass die Wiederherstellung den neu gestarteten Gateway nicht sofort mit kickstart -k neu startet). Wenn der Gateway weiterhin nicht funktionsfähig wird, wird der Befehl mit einem von null verschiedenen Status beendet und gibt den Pfad zum Neustartprotokoll sowie Anweisungen für Neustart, Neuinstallation und Paket-Rollback aus.

Wenn der Neustart nicht ausgeführt werden kann, gibt der Befehl Gateway: restart skipped (...) oder Gateway: restart failed: ... mit einem Hinweis auf den manuellen Befehl openclaw gateway restart aus. Mit --no-restart wird der Paketaustausch oder der erneute Git-Build weiterhin ausgeführt, der verwaltete Dienst wird jedoch weder beendet noch neu gestartet, sodass der laufende Gateway den alten Code weiterverwendet, bis Sie ihn manuell neu starten.

Form der Control-Plane-Antwort

Wenn update.run bei einer Paketmanager-Installation oder einem überwachten Git-Checkout über die Control Plane des Gateway ausgeführt wird, meldet der Handler die Einleitung der Übergabe getrennt von der CLI-Aktualisierung, die nach dem Beenden des Gateway fortgesetzt wird:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" und handoff.status: "started": Der Gateway hat die Übergabe des verwalteten Dienstes erstellt und seinen eigenen Neustart geplant, damit der abgekoppelte Helfer openclaw update --yes --json außerhalb des laufenden Dienstprozesses ausführen kann.
• ok: false, result.reason: "managed-service-handoff-unavailable" und handoff.status: "unavailable": OpenClaw konnte keine überwachende Dienstgrenze und dauerhafte Dienstidentität für eine sichere Übergabe finden (beispielsweise erfordert die systemd-Übergabe die Unit-Identität OPENCLAW_SYSTEMD_UNIT, nicht nur Umgebungsmerkmale eines systemd-Prozesses). Die Antwort enthält handoff.command, den Shell-Befehl, der außerhalb des Gateway ausgeführt werden soll.
• ok: false, result.reason: "managed-service-handoff-failed": Der Gateway hat versucht, die Übergabe zu erstellen, konnte den abgekoppelten Helfer jedoch nicht starten.

Die sentinel-Nutzlast wird geschrieben, bevor der Gateway beendet wird, und die CLI-Übergabe aktualisiert denselben Neustart-Sentinel, nachdem die Funktionsprüfungen nach dem Neustart des verwalteten Dienstes abgeschlossen sind. Während der Übergabe kann der Sentinel stats.reason: "restart-health-pending" ohne erfolgreiche Fortsetzung enthalten; der neu gestartete Gateway fragt ihn regelmäßig ab und löst die Fortsetzung erst aus, nachdem die CLI die Funktionsfähigkeit des Dienstes überprüft und den Sentinel mit dem endgültigen ok-Ergebnis neu geschrieben hat. openclaw status und openclaw status --all zeigen eine Zeile Update restart, solange dieser Sentinel aussteht oder fehlgeschlagen ist, und update.status aktualisiert den Sentinel und gibt seinen neuesten Stand zurück.

Ablauf für Git-Checkouts

Kanalauswahl

• stable: Checkt das neueste Tag ohne Beta-Kennzeichnung aus und führt anschließend Build und Doctor aus.
• beta: Bevorzugt das neueste -beta-Tag und greift auf das neueste Stable-Tag zurück, wenn Beta fehlt oder älter ist.
• dev: Checkt main aus und führt anschließend Fetch und Rebase aus.
• extended-stable: Wird für Git-Checkouts nicht unterstützt; der Checkout wird nicht verändert.

Aktualisierungsschritte

Details zur Plugin-Synchronisierung

Im Beta-Kanal versuchen nachverfolgte npm- und ClawHub-Plugin-Installationen, die der Standard-/Latest-Linie folgen, zuerst eine Plugin-Version mit @beta. Wenn für das Plugin keine Beta-Version vorhanden ist, greift OpenClaw auf die aufgezeichnete Standard-/Latest-Spezifikation zurück und meldet eine Warnung. Bei npm-Plugins greift OpenClaw auch dann zurück, wenn das Beta-Paket vorhanden ist, aber die Installationsvalidierung fehlschlägt. Diese Fallback-Warnungen führen nicht dazu, dass die Kernaktualisierung fehlschlägt. Exakte Versionen und explizite Tags werden niemals umgeschrieben.

Nach erfolgreichem Abschluss einer Extended-Stable-Kernaktualisierung richten sich die Plugin-Integritätsprüfung und -Konvergenz nach der Kernaktualisierung für geeignete offizielle npm-Plugins nach der exakt installierten Kernversion. Bei Standard-/latest-Absicht fragt OpenClaw weder Plugin-@extended-stable ab noch greift es auf npm-latest zurück; stattdessen leitet es die Paketversion aus dem installierten Kern ab. Explizite Versions-Pins, explizite Tags außer latest, Drittanbieterpakete und Quellen außerhalb von npm behalten ihre bestehende Absicht bei.

Bei Paketmanager-Installationen löst openclaw update die Zielpaketversion auf, bevor der Paketmanager aufgerufen wird. Globale npm-Installationen verwenden eine gestufte Installation: OpenClaw installiert das neue Paket in ein temporäres npm-Präfix, überprüft dort den paketierten dist-Bestand und tauscht anschließend diesen sauberen Paketbaum in das tatsächliche globale Präfix ein. Wenn die Überprüfung fehlschlägt, werden Doctor nach der Aktualisierung, Plugin-Synchronisierung und Neustartarbeiten nicht aus dem verdächtigen Baum ausgeführt. Selbst wenn die installierte Version bereits dem Ziel entspricht, aktualisiert der Befehl die globale Paketinstallation und führt anschließend die Plugin-Synchronisierung, eine Aktualisierung der Vervollständigungen für Kernbefehle und die Neustartarbeiten aus. Dadurch bleiben paketierte Sidecars und kanaleigene Plugin-Datensätze mit dem installierten OpenClaw-Build synchron, während vollständige Neuaufbauten der Vervollständigungen für Plugin-Befehle expliziten Ausführungen von openclaw completion --write-state vorbehalten bleiben.

Verwandte Themen

• openclaw doctor (bietet bei Git-Checkouts an, zuerst die Aktualisierung auszuführen)
• Entwicklungskanäle
• Aktualisieren
• CLI-Referenz