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 durchgeführt haben (globale Installation, keine Git-Metadaten), erfolgen Aktualisierungen über den unter Aktualisierung 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 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 der Datei (logging.level: "debug"/"trace") sind voneinander 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 der Status dieselbe öffentliche Auswahl und Prüfung des exakten Pakets wie die Aktualisierung im Vordergrund durch. Er 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, aber die Plugin-Synchronisierung nach der Kernaktualisierung, die Metadaten verwalteter npm-Plugins, die Registry-Aktualisierung 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-Nutzlasten, 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). Bei Auswahl von dev ohne Git- Checkout wird angeboten, einen zu erstellen.

Funktionsweise

Durch einen expliziten Kanalwechsel (--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; kann mit OPENCLAW_GIT_DIR überschrieben werden), 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, verifiziert das exakt ausgewählte Paket und installiert diese exakte Version. Es weicht nicht auf einen anderen Selektor aus und wird für Git-Checkouts abgelehnt.
• beta -> bevorzugt das npm-Dist-Tag beta und weicht auf latest aus, 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 aktiven Gateway-Anfrage-Handlers. Paketmanager-Aktualisierungen der Steuerungsebene update.run und beaufsichtigte Aktualisierungen von Git-Checkouts verwenden dieselbe Übergabe an den verwalteten Dienst, anstatt 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 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 Aktualisierungen im Vordergrund, einfache Aktualisierungen im Vordergrund 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 Aktualisierungen über den Paketmanager und Git-Checkout-Aktualisierungen den laufenden Dienst, bevor sie den Paketbaum ersetzen oder die Checkout-/Build-Ausgabe verändern. Das Aktualisierungsprogramm aktualisiert anschließend die Dienstmetadaten, startet den Dienst neu und überprüft das neu gestartete Gateway, bevor es Gateway: restarted and verified. meldet. Paketmanager-Aktualisierungen überprüfen zusätzlich, dass das neu gestartete Gateway die erwartete Paketversion meldet; Git-Checkout-Aktualisierungen überprüfen nach dem erneuten Build den Zustand des Gateways und die Dienstbereitschaft.

Paketmanager-Aktualisierungen verwenden normalerweise weiterhin die im verwalteten Dienst hinterlegte Node-Binärdatei. Wenn diese Node-Version das Ziel-Release nicht ausführen kann, die aktuelle CLI-Node-Version dies jedoch kann und nachgewiesen ist, dass der Dienst zu dem aktualisierten Paket gehört, verwendet eine Aktualisierung mit aktiviertem Neustart die aktuelle Node-Version für den Abschluss und schreibt die Dienstmetadaten auf diese Laufzeit um. --no-restart kann Dienstmetadaten nicht reparieren, daher wird dieselbe Laufzeitinkompatibilität vor der Paketänderung abgebrochen.

Unter macOS überprüft die Prüfung nach der Aktualisierung außerdem, ob der LaunchAgent für das aktive Profil geladen/ausgeführt wird und der konfigurierte Loopback-Port funktionsfähig ist. Wenn die plist installiert ist, aber nicht von launchd überwacht wird, führt OpenClaw automatisch ein erneutes Bootstrap des LaunchAgent durch und wiederholt die Zustands-/Versions-/ Kanalbereitschaftsprüfungen (ein frisches Bootstrap lädt den Auftrag RunAtLoad direkt, sodass die Wiederherstellung das neu gestartete Gateway nicht sofort kickstart -k). Wenn das Gateway weiterhin nicht funktionsfähig wird, wird der Befehl mit einem von null verschiedenen Status beendet und gibt den Pfad zum Neustartprotokoll sowie Anweisungen zum Neustart, zur Neuinstallation und zum Paket-Rollback aus.

Wenn der Neustart nicht ausgeführt werden kann, gibt der Befehl Gateway: restart skipped (...) oder Gateway: restart failed: ... mit einem manuellen Hinweis zu openclaw gateway restart aus. Mit --no-restart wird der Paketersatz oder der erneute Git-Build weiterhin ausgeführt, aber der verwaltete Dienst wird weder gestoppt noch neu gestartet, sodass das laufende Gateway den alten Code behält, bis Sie es manuell neu starten.

Antwortformat der Steuerungsebene

Wenn update.run über die Gateway-Steuerungsebene bei einer Paketmanager- Installation oder einem überwachten Git-Checkout ausgeführt wird, meldet der Handler die Initiierung 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 des verwalteten Dienstes erstellt und seinen eigenen Neustart geplant, damit das abgekoppelte Hilfsprogramm 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 (zum Beispiel erfordert eine systemd-Übergabe die Unit-Identität OPENCLAW_SYSTEMD_UNIT, nicht nur systemd-Prozessmarkierungen aus der Umgebung). Die Antwort enthält handoff.command, den Shell-Befehl, der außerhalb des Gateways ausgeführt werden soll.
• ok: false, result.reason: "managed-service-handoff-failed": Das Gateway hat versucht, die Übergabe zu erstellen, konnte das abgekoppelte Hilfsprogramm jedoch nicht starten.

Die Nutzlast sentinel 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 Ergebnis ok neu geschrieben hat. openclaw status und openclaw status --all zeigen eine Zeile Update restart, während dieser Sentinel aussteht oder fehlgeschlagen ist, und update.status aktualisiert und gibt den neuesten Sentinel zurück.

Git-Checkout-Ablauf

Kanalauswahl

• stable: Checkt den neuesten Nicht-Beta-Tag aus und führt anschließend Build und Doctor aus.
• beta: Bevorzugt den neuesten Tag -beta und greift auf den neuesten 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: Für Git-Checkouts nicht unterstützt; es erfolgt keine Änderung des Checkouts.

Aktualisierungsschritte

Details zur Plugin-Synchronisierung

Im Beta-Kanal versuchen nachverfolgte npm- und ClawHub-Plugin-Installationen, die der Standard-/Latest-Linie folgen, zunächst ein Plugin-Release @beta. Wenn das Plugin kein Beta-Release besitzt, greift OpenClaw auf die aufgezeichnete Standard-/Latest-Spezifikation zurück und meldet eine Warnung. Bei npm-Plugins greift OpenClaw auch zurück, wenn das Beta- Paket vorhanden ist, aber die Installationsvalidierung fehlschlägt. Diese Rückfallwarnungen führen nicht zum Fehlschlagen der Core-Aktualisierung. Exakte Versionen und explizite Tags werden niemals umgeschrieben.

Nach dem erfolgreichen Abschluss einer Extended-Stable-Core-Aktualisierung zielen die Integritäts- und Konvergenzprüfungen der Plugins nach der Core-Aktualisierung auf geeignete offizielle npm-Plugins mit exakt der installierten Core- Version. Bei Standard-/latest-Absicht fragt OpenClaw keine Plugin- @extended-stable ab und greift nicht auf npm-latest zurück; die Paketversion wird aus dem installierten Core abgeleitet. Explizite Versions-Pins, explizite Tags, die nicht latest sind, 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 ein temporäres npm-Präfix, lässt das Kandidatenpaket während preinstall die Node-Version des Hosts validieren und überprüft dort das paketierte Inventar dist. Eine paketierte Abschlussprüfung bleibt außerhalb dieses Inventars, bis preinstall erfolgreich ist, sodass Paketmanager, die Lebenszyklusskripte überspringen, ebenfalls vor der Aktivierung anhalten. Bei npm 12 und neuer genehmigt das Aktualisierungsprogramm nur den OpenClaw-Lebenszyklus des 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 mit dem Ziel übereinstimmt, aktualisiert der Befehl die globale Paketinstallation und führt anschließend die Plugin-Synchronisierung, eine Aktualisierung der Core-Befehlsvervollständigung und die Neustartarbeiten aus. Dadurch bleiben paketierte Sidecars und kanaleigene Plugin-Datensätze auf den installierten OpenClaw-Build abgestimmt, während vollständige Neuaufbauten der Plugin-Befehlsvervollständigung expliziten Ausführungen von openclaw completion --write-state vorbehalten bleiben.

Verwandte Themen

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