openclaw update
OpenClaw sicher aktualisieren und zwischen Stable-/Beta-/Dev-Kanälen wechseln.
Wenn Sie über npm/pnpm/bun installiert haben (globale Installation, keine Git-Metadaten), erfolgen Updates über den Paketmanager-Ablauf unter Aktualisieren.
Verwendung
Optionen
--no-restart: überspringt den Neustart des Gateway-Dienstes nach einem erfolgreichen Update. Paketmanager-Updates, die das Gateway neu starten, prüfen vor erfolgreichem Abschluss des Befehls, dass der neu gestartete Dienst die erwartete aktualisierte Version meldet.--channel <stable|beta|dev>: legt den Update-Kanal fest (Git + npm; wird in der Konfiguration gespeichert).--tag <dist-tag|version|spec>: überschreibt das Paketziel nur für dieses Update. Bei Paketinstallationen wirdmainaufgithub:openclaw/openclaw#mainabgebildet; GitHub-/Git-Quellspezifikationen werden vor der gestuften globalen npm-Installation in einen temporären Tarball gepackt.--dry-run: zeigt die geplanten Update-Aktionen (Kanal/Tag/Ziel/Neustartablauf) an, ohne Konfiguration zu schreiben, zu installieren, Plugins zu synchronisieren oder neu zu starten.--json: gibt maschinenlesbaresUpdateRunResult-JSON aus, einschließlichpostUpdate.plugins.warnings, wenn beschädigte oder nicht ladbare verwaltete Plugins nach erfolgreichem Core-Update repariert werden müssen, Details zum Plugin-Fallback im Beta-Kanal, wenn ein Plugin keine Beta-Veröffentlichung hat, undpostUpdate.plugins.integrityDrifts, wenn während der Plugin-Synchronisierung nach dem Update Abweichungen bei npm-Plugin-Artefakten erkannt werden.--timeout <seconds>: Timeout pro Schritt (Standard ist 1800s).--yes: überspringt Bestätigungsabfragen (zum Beispiel Downgrade-Bestätigung).--acknowledge-clawhub-risk: nach Prüfung der Vertrauenswarnungen für Community-ClawHub kann die Plugin-Synchronisierung nach dem Update ohne interaktive Abfrage fortgesetzt werden. Ohne diese Option werden riskante Community-ClawHub-Plugin-Veröffentlichungen übersprungen und unverändert gelassen, wenn OpenClaw nicht nachfragen kann. Offizielle ClawHub-Pakete und gebündelte OpenClaw-Plugin-Quellen umgehen diese Release-Vertrauensabfrage.
openclaw update hat kein --verbose-Flag. Verwenden Sie --dry-run, um die geplanten
Kanal-/Tag-/Installations-/Neustartaktionen vorab anzuzeigen, --json für maschinenlesbare
Ergebnisse und openclaw update status --json, wenn Sie nur Kanal- und
Verfügbarkeitsdetails benötigen. Wenn Sie Gateway-Logs rund um ein Update debuggen,
sind Konsolenausführlichkeit und Datei-Log-Level getrennt: Gateway --verbose wirkt sich
auf Terminal-/WebSocket-Ausgaben aus, während Datei-Logs logging.level: "debug" oder
"trace" in der Konfiguration erfordern. Siehe Gateway-Logging.
Im Nix-Modus (
OPENCLAW_NIX_MODE=1) sind verändernde openclaw update-Läufe deaktiviert. Aktualisieren Sie stattdessen die Nix-Quelle oder den Flake-Input für diese Installation; verwenden Sie für nix-openclaw den agent-first Schnellstart. openclaw update status und openclaw update --dry-run bleiben schreibgeschützt.update status
Zeigt den aktiven Update-Kanal + Git-Tag/-Branch/-SHA (für Quell-Checkouts) sowie die Update-Verfügbarkeit an.
--json: gibt maschinenlesbares Status-JSON aus.--timeout <seconds>: Timeout für Prüfungen (Standard ist 3s).
update repair
Führt die Update-Finalisierung erneut aus, nachdem das Core-Paket bereits geändert wurde, spätere
Reparaturarbeiten aber nicht sauber abgeschlossen wurden. Dies ist der unterstützte Wiederherstellungspfad, wenn
openclaw update das neue Core-Paket installiert hat, aber Plugin-Synchronisierung nach dem Core-Update,
verwaltete npm-Plugin-Metadaten, Registry-Aktualisierung oder Doctor-Reparatur noch
konvergieren müssen.
--channel <stable|beta|dev>: speichert den Update-Kanal vor der Reparatur und führt die Plugin-Konvergenz gegen diesen Kanal aus.--json: gibt maschinenlesbares Finalisierungs-JSON aus.--timeout <seconds>: Timeout für Reparaturschritte (Standard1800).--yes: überspringt Bestätigungsabfragen.--acknowledge-clawhub-risk: nach Prüfung der Vertrauenswarnungen für Community-ClawHub kann die Plugin-Konvergenz während der Reparatur ohne interaktive Abfrage fortgesetzt werden. Offizielle ClawHub-Pakete und gebündelte OpenClaw-Plugin-Quellen umgehen diese Release-Vertrauensabfrage.--no-restart: wird aus Gründen der Parität mit dem Update-Befehl akzeptiert; Repair startet das Gateway nie neu.
openclaw update repair führt openclaw doctor --fix aus, lädt die reparierte
Konfiguration und Installationsdatensätze neu, synchronisiert verfolgte Plugins für den aktiven Update-Kanal,
aktualisiert verwaltete npm-Plugin-Installationen, repariert fehlende konfigurierte Plugin-Payloads,
aktualisiert die Plugin-Registry und schreibt die konvergierten Installationsdatensatz-Metadaten.
Es installiert kein neues Core-Paket und startet das Gateway nicht neu.
update wizard
Interaktiver Ablauf zur Auswahl eines Update-Kanals und Bestätigung, ob das Gateway nach dem Update
neu gestartet werden soll (Standard ist Neustart). Wenn Sie dev ohne Git-Checkout auswählen, wird
angeboten, einen zu erstellen.
Optionen:
--timeout <seconds>: Timeout für jeden Update-Schritt (Standard1800)
Was es tut
Wenn Sie Kanäle explizit wechseln (--channel ...), hält OpenClaw auch die
Installationsmethode synchron:
dev→ stellt einen Git-Checkout sicher (Standard:~/openclawoder$OPENCLAW_HOME/openclaw, wennOPENCLAW_HOMEgesetzt ist; überschreiben mitOPENCLAW_GIT_DIR), aktualisiert ihn und installiert die globale CLI aus diesem Checkout.stable→ installiert aus npm mitlatest.beta→ bevorzugt das npm-dist-tagbeta, fällt aber auflatestzurück, wenn Beta fehlt oder älter als die aktuelle Stable-Veröffentlichung ist.
update.run-
Paketmanager-Updates und überwachte Git-Checkout-Updates verwenden ebenfalls eine
Managed-Service-Übergabe, statt den Paketbaum zu ersetzen oder dist/ im laufenden
Gateway-Prozess neu zu bauen. Das Gateway startet einen getrennten Helfer,
beendet sich, und der Helfer führt den normalen CLI-Pfad openclaw update --yes --json
außerhalb des Gateway-Prozessbaums aus. Wenn diese Übergabe nicht verfügbar ist,
gibt update.run eine strukturierte Antwort mit dem sicheren Shell-Befehl zurück, der
manuell auszuführen ist.
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, prüft
dort das gepackte dist-Inventar und tauscht dann diesen sauberen Paketbaum in das
echte globale Präfix ein. Wenn die Prüfung fehlschlägt, werden Doctor nach dem Update,
Plugin-Synchronisierung und Neustartarbeiten nicht aus dem verdächtigen Baum ausgeführt.
Auch wenn die installierte Version bereits dem Ziel entspricht, aktualisiert der Befehl
die globale Paketinstallation, führt dann Plugin-Synchronisierung, eine Aktualisierung der
Core-Befehlsvervollständigung und Neustartarbeiten aus. Dadurch bleiben gepackte Sidecars und
kanaleigene Plugin-Datensätze mit dem installierten OpenClaw-Build synchron, während vollständige
Neuaufbauten der Plugin-Befehlsvervollständigung expliziten openclaw completion --write-state-Läufen
überlassen bleiben.
Wenn ein lokaler verwalteter Gateway-Dienst installiert und Neustart aktiviert ist,
stoppen Paketmanager- und Git-Checkout-Updates den laufenden Dienst, bevor
der Paketbaum ersetzt oder Checkout-/Build-Ausgaben verändert werden. Der Updater
aktualisiert dann die Dienstmetadaten aus der aktualisierten Installation, startet den
Dienst neu und prüft das neu gestartete Gateway, bevor
Gateway: restarted and verified. gemeldet wird. Paketmanager-Updates prüfen zusätzlich,
dass das neu gestartete Gateway die erwartete Paketversion meldet; Git-Checkout-Updates
prüfen Gateway-Zustand und Dienstbereitschaft nach dem Neuaufbau. Unter macOS prüft die
Prüfung nach dem Update außerdem, dass der LaunchAgent für das aktive
Profil geladen/ausgeführt wird und der konfigurierte loopback-Port gesund ist. Wenn die plist installiert ist,
launchd sie aber nicht überwacht, bootstrapt OpenClaw den LaunchAgent
automatisch erneut und führt dann die Health-/Versions-/Kanal-Bereitschaftsprüfungen erneut aus. Ein frischer
Bootstrap lädt den RunAtLoad-Job direkt, sodass die Update-Wiederherstellung das neu gestartete Gateway
nicht sofort mit kickstart -k anstößt. Wenn das Gateway weiterhin nicht
gesund wird, endet der Befehl mit einem Nicht-Null-Code und gibt den Neustart-Logpfad
sowie explizite Anweisungen zu 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 manuelles openclaw gateway restart aus.
Mit --no-restart wird der Paketaustausch oder Git-Neuaufbau weiterhin ausgeführt, aber der
verwaltete Dienst wird nicht gestoppt oder neu gestartet, sodass das laufende Gateway alten
Code behalten kann, bis Sie es manuell neu starten.
Antwortformat der Control Plane
Wennupdate.run über die Gateway-Control-Plane bei einer
Paketmanager-Installation oder einem überwachten Git-Checkout aufgerufen wird, meldet der Handler die
Initiierung der Übergabe getrennt vom CLI-Update, das nach dem Beenden des
Gateways fortgesetzt wird:
ok: true,result.status: "skipped",result.reason: "managed-service-handoff-started"undhandoff.status: "started"bedeuten, dass das Gateway die Managed-Service- Übergabe erstellt und seinen eigenen Neustart geplant hat, damit der getrennte Helferopenclaw update --yes --jsonaußerhalb des laufenden Dienstprozesses ausführen kann.ok: false,result.reason: "managed-service-handoff-unavailable"undhandoff.status: "unavailable"bedeuten, dass OpenClaw keine überwachende Dienstgrenze und dauerhafte Dienstidentität für eine sichere Übergabe finden konnte. Zum Beispiel erfordert die systemd-Übergabe die OpenClaw-Unit-Identität (OPENCLAW_SYSTEMD_UNIT), nicht nur umgebende systemd-Prozessmarker. Die Antwort enthälthandoff.command, den Shell-Befehl, der außerhalb des Gateways auszuführen ist.ok: false,result.reason: "managed-service-handoff-failed"bedeutet, dass das Gateway versucht hat, die Übergabe zu erstellen, den getrennten Helfer aber nicht starten konnte.
sentinel-Payload wird weiterhin geschrieben, bevor das Gateway beendet wird, und die CLI-
Übergabe aktualisiert denselben Neustart-Sentinel, nachdem die Health-Checks des
Managed-Service-Neustarts abgeschlossen sind. Während der Übergabe kann der Sentinel
stats.reason: "restart-health-pending" ohne Erfolgsfortsetzung tragen; das
neu gestartete Gateway pollt ihn weiter und löst die Fortsetzung erst aus, nachdem die CLI
die Dienstgesundheit verifiziert und den Sentinel mit dem finalen ok-
Ergebnis 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: den neuesten Nicht-Beta-Tag auschecken, dann bauen und Doctor ausführen.beta: den neuesten-beta-Tag bevorzugen, aber auf den neuesten Stable-Tag zurückfallen, wenn Beta fehlt oder älter ist.dev:mainauschecken, dann fetchen und rebasen.
Update-Schritte
Preflight-Build (nur Entwicklung)
Führt den TypeScript-Build in einer temporären Worktree aus. Wenn die aktuelle Spitze fehlschlägt, geht der Prozess bis zu 10 Commits zurück, um den neuesten buildbaren Commit zu finden. Setzen Sie
OPENCLAW_UPDATE_PREFLIGHT_LINT=1, um während dieses Preflight auch Lint auszuführen; Lint läuft im eingeschränkten seriellen Modus, weil Hosts für Benutzer-Updates oft kleiner sind als CI-Runner.Abhängigkeiten installieren
Verwendet den Paketmanager des Repos. Bei pnpm-Checkouts bootstrapt der Updater
pnpm bei Bedarf (zuerst über corepack, dann als temporärer Fallback mit npm install pnpm@11), statt npm run build innerhalb eines pnpm-Workspace auszuführen.@beta-Version. Wenn das Plugin keine
Beta-Version hat, fällt OpenClaw auf die aufgezeichnete Standard-/Latest-Spezifikation zurück und meldet
dies als Warnung. Bei npm-Plugins fällt OpenClaw auch dann zurück, wenn das Beta-
Paket existiert, aber die Installationsvalidierung fehlschlägt. Diese Plugin-Fallback-Warnungen lassen
das Core-Update nicht fehlschlagen. Exakte Versionen und explizite Tags werden nicht
umgeschrieben.
Plugin-Synchronisierungsfehler nach dem Update, die auf ein verwaltetes Plugin begrenzt sind und die der Synchronisierungspfad umgehen kann (z. B. eine nicht erreichbare npm-Registry für ein nicht essenzielles Plugin), werden als Warnungen gemeldet, nachdem das Core-Update erfolgreich war. Das JSON-Ergebnis behält für das Update auf oberster Ebene
status: "ok" bei und meldet postUpdate.plugins.status: "warning" mit Hinweisen zu openclaw update repair und openclaw plugins inspect <id> --runtime --json. Unerwartete Updater- oder Synchronisierungsausnahmen lassen das Update-Ergebnis weiterhin fehlschlagen. Beheben Sie den Plugin-Installations- oder Update-Fehler und führen Sie dann openclaw update repair erneut aus.Nach dem Synchronisierungsschritt pro Plugin führt openclaw update einen obligatorischen Post-Core-Konvergenz-Durchlauf aus, bevor der Gateway neu gestartet wird: Er repariert fehlende konfigurierte Plugin-Payloads, validiert jeden aktiven nachverfolgten Installationsdatensatz auf der Festplatte und verifiziert statisch, dass dessen package.json parsebar ist (und dass ein explizit deklariertes main existiert). Fehler aus diesem Durchlauf — und ein ungültiger OpenClaw-Konfigurations-Snapshot — geben postUpdate.plugins.status: "error" zurück und setzen den Update-status auf oberster Ebene auf "error", sodass openclaw update mit einem Nicht-Null-Code beendet wird und der Gateway nicht mit einem unverifizierten Plugin-Set neu gestartet wird. Der Fehler enthält strukturierte postUpdate.plugins.warnings[].guidance-Zeilen, die für die Nachverfolgung auf openclaw update repair und openclaw plugins inspect <id> --runtime --json verweisen. Deaktivierte Plugin-Einträge und Datensätze, die keine mit vertrauenswürdiger Quelle verknüpften offiziellen Synchronisierungsziele sind, werden hier übersprungen. Das entspricht der skipDisabledPlugins-Policy, die von der Prüfung auf fehlende Payloads verwendet wird, sodass ein veralteter deaktivierter Plugin-Datensatz ein ansonsten gültiges Update nicht blockieren kann.Wenn der aktualisierte Gateway startet, ist das Laden von Plugins nur verifizierend: Der Start führt keine
Paketmanager aus und verändert keine Abhängigkeitsbäume. Package-manager-update.run-
Neustarts werden an den von der CLI verwalteten Dienstpfad übergeben, sodass der Paketaustausch
außerhalb des alten Gateway-Prozesses erfolgt und die Dienst-Health-Checks entscheiden, ob das
Update als abgeschlossen gemeldet werden kann.Wenn der pnpm-Bootstrap weiterhin fehlschlägt, stoppt der Updater frühzeitig mit einem paketmanager-spezifischen Fehler, statt npm run build im Checkout zu versuchen.Kurzform --update
openclaw --update wird zu openclaw update umgeschrieben (nützlich für Shells und Launcher-Skripte).
Verwandt
openclaw doctor(bietet an, auf Git-Checkouts zuerst Update auszuführen)- Entwicklungskanäle
- Aktualisierung
- CLI-Referenz