openclaw update

Aktualisieren Sie OpenClaw und wechseln Sie zwischen den Kanälen stable/extended-stable/beta/dev.

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 Launcher-Skripte).

Optionen

Es gibt kein Flag --verbose. Verwenden Sie --dry-run für eine Vorschau der geplanten Aktionen, --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, das Git-Tag, den Branch und den SHA (nur bei Quellcode-Checkouts) sowie die Verfügbarkeit von Aktualisierungen an.

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

Bei Extended-stable-Paketinstallationen verwendet die Statusprüfung denselben öffentlichen Selektor und dieselbe Prüfung des exakten Pakets wie eine Aktualisierung im Vordergrund. 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 den Abschluss der Aktualisierung erneut aus, nachdem das Kernpaket bereits geändert wurde, spätere Reparaturarbeiten jedoch nicht ordnungsgemäß abgeschlossen wurden. Dies ist der unterstützte Wiederherstellungspfad, wenn openclaw update das neue Kernpaket installiert hat, die anschließende Plugin-Synchronisierung, die Metadaten verwalteter npm-Plugins, die Aktualisierung der Registry oder die Doctor-Reparatur jedoch 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 dev ohne Git- Checkout ausgewählt wird, wird angeboten, einen zu erstellen.

Funktionsweise

Beim expliziten Wechseln des Kanals (--channel ...) wird auch die Installationsmethode entsprechend angepasst:

• dev -> stellt einen Git-Checkout sicher (standardmäßig ~/openclaw oder $OPENCLAW_HOME/openclaw, wenn OPENCLAW_HOME festgelegt ist; Überschreibung mit OPENCLAW_GIT_DIR), aktualisiert ihn und installiert die globale CLI aus diesem Checkout.
• stable -> installiert aus npm unter Verwendung von latest.
• extended-stable -> löst den öffentlichen npm-Selektor extended-stable auf, überprüft das exakt ausgewählte Paket und installiert genau diese Version. Es erfolgt kein Fallback auf einen anderen Selektor, und die Option wird bei Git-Checkouts abgelehnt.
• beta -> bevorzugt das npm-Dist-Tag beta und greift auf latest zurück, wenn die Beta-Version fehlt oder älter als die aktuelle stabile Version ist.

Neustartübergabe

Der automatische Aktualisierer des Gateway-Kerns (wenn über die Konfiguration aktiviert) startet den CLI- Aktualisierungspfad außerhalb des Anfrage-Handlers des laufenden Gateways. Paketmanager-Aktualisierungen der Steuerungsebene update.run und überwachte Aktualisierungen von Git-Checkouts verwenden dieselbe Übergabe an den verwalteten Dienst, anstatt den Paketbaum zu ersetzen oder dist/ innerhalb des laufenden Gateway-Prozesses neu zu erstellen: Das Gateway startet einen abgetrennten 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 schreibgeschützte Start- und 24-stündige Aktualisierungshinweise, wenn update.checkOnStart aktiviert ist. Diese Prüfungen wenden niemals eine Aktualisierung an, starten keine Übergabe, starten das Gateway nicht neu, verwenden weder Stable-Verzögerung/-Jitter noch den Beta-Abfragezyklus. Explizite Vordergrundaktualisierungen, einfache Vordergrundaktualisierungen mit gespeichertem update.channel: "extended-stable", Statusabfragen bei Bedarf und deren verwaltete Gateway-Übergabe werden weiterhin unterstützt.

Wenn ein lokaler verwalteter Gateway-Dienst installiert und der Neustart aktiviert ist, stoppen Paketmanager- und Git-Checkout-Aktualisierungen den laufenden Dienst, bevor der Paketbaum ersetzt oder die Checkout-/Build-Ausgabe geändert wird. Das Aktualisierungsprogramm aktualisiert anschließend die Dienstmetadaten, startet den Dienst neu und überprüft das neu gestartete Gateway, bevor Gateway: restarted and verified. gemeldet wird. Paketmanager-Aktualisierungen überprüfen zusätzlich, ob das neu gestartete Gateway die erwartete Paketversion meldet; Git-Checkout-Aktualisierungen überprüfen nach dem erneuten Build den Gateway-Zustand und die Dienstbereitschaft.

Paketmanager-Aktualisierungen verwenden normalerweise weiterhin die im verwalteten Dienst aufgezeichnete Node-Binärdatei. Wenn dieses Node die Zielversion nicht ausführen kann, das aktuelle CLI-Node dies jedoch kann und der Dienst nachweislich zu dem aktualisierten Paket gehört, verwendet eine Aktualisierung mit aktiviertem Neustart das aktuelle Node für den Abschluss und schreibt die Dienstmetadaten für diese Laufzeit neu. --no-restart kann Dienstmetadaten nicht reparieren, daher führt dieselbe Laufzeitabweichung vor der Paketänderung zum Abbruch.

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, bootstrappt OpenClaw den LaunchAgent automatisch neu und führt die Zustands-/Versions-/ Kanalbereitschaftsprüfungen erneut aus (ein frischer Bootstrap lädt den RunAtLoad-Job direkt, sodass die Wiederherstellung das neu gestartete Gateway nicht sofort kickstart -k). Wenn das Gateway weiterhin keinen ordnungsgemäßen Zustand erreicht, wird der Befehl mit einem von null abweichenden 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 zur manuellen Ausführung von openclaw gateway restart aus. Mit --no-restart werden der Paketaustausch oder der erneute Git-Build weiterhin ausgeführt, der verwaltete Dienst wird jedoch weder gestoppt noch neu gestartet, sodass das laufende Gateway den alten Code weiterverwendet, bis Sie es manuell neu starten.

Form der Control-Plane-Antwort

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

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" und handoff.status: "started": Das Gateway hat die Übergabe an den verwalteten Dienst erstellt und seinen eigenen Neustart geplant, damit der getrennte 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 Identität der OPENCLAW_SYSTEMD_UNIT-Unit, nicht nur vorhandene systemd-Prozessmarker). Die Antwort enthält handoff.command, den Shell-Befehl, der außerhalb des Gateways auszuführen ist.
• ok: false, result.reason: "managed-service-handoff-failed": Das Gateway hat versucht, die Übergabe zu erstellen, konnte den getrennten Helfer jedoch nicht starten.

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

Git-Checkout-Ablauf

Kanalauswahl

• stable: Checkt das neueste Nicht-Beta-Tag 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 geändert.

Aktualisierungsschritte

Details zur Plugin-Synchronisierung

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

Nach erfolgreicher Extended-Stable-Kernaktualisierung zielen die Plugin-Integritäts- und Konvergenzprüfungen nach der Kernaktualisierung auf geeignete offizielle npm-Plugins mit exakt der installierten Kernversion. Bei Default-/latest-Absicht fragt OpenClaw weder Plugin-@extended-stable ab noch greift es auf npm-latest zurück; die Paketversion wird aus dem installierten Kern abgeleitet. Explizite Versionsanheftungen, explizite Nicht-latest-Tags, Drittanbieterpakete und Nicht-npm-Quellen 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 einem temporären npm-Präfix, lässt das Kandidatenpaket während preinstall die Node-Version des Hosts validieren und überprüft dort das paketierte dist-Inventar. Ein paketierter Abschlusswächter bleibt außerhalb dieses Inventars, bis preinstall erfolgreich abgeschlossen ist, sodass Paketmanager, die Lebenszyklusskripte überspringen, ebenfalls vor der Aktivierung anhalten. Unter npm 12 und neuer genehmigt das Aktualisierungsprogramm ausschließlich den Lebenszyklus des OpenClaw-Kandidaten; Skripte transitiver Abhängigkeiten bleiben blockiert. OpenClaw tauscht anschließend den 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ändigung für Kernbefehle und Neustartarbeiten aus. Dadurch bleiben paketierte Sidecars und kanaleigene Plugin-Datensätze mit dem installierten OpenClaw-Build abgestimmt, während vollständige Vervollständigungs-Neubuilds 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
• Aktualisierung
• CLI-Referenz