CLI commands
Aktualizacja
openclaw update
Zaktualizuj OpenClaw i przełączaj się między kanałami stable/extended-stable/beta/dev.
Jeśli instalację przeprowadzono za pomocą npm/pnpm/bun (instalacja globalna, bez metadanych git), aktualizacje odbywają się zgodnie z przepływem menedżera pakietów opisanym w sekcji Aktualizowanie.
Użycie
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 --updateopenclaw --update jest przekształcane w openclaw update (przydatne w powłokach i
skryptach uruchamiających).
Opcje
| Flaga | Opis |
|---|---|
--no-restart |
Pomija ponowne uruchomienie usługi Gateway po pomyślnej aktualizacji. Aktualizacje za pośrednictwem menedżera pakietów, które ponownie uruchamiają usługę, przed pomyślnym zakończeniem polecenia sprawdzają, czy ponownie uruchomiona usługa zgłasza oczekiwaną wersję. |
--channel <stable|extended-stable|beta|dev> |
Ustawia kanał aktualizacji i zachowuje go po pomyślnej aktualizacji rdzenia. Kanał extended-stable jest dostępny tylko dla pakietów. |
--tag <dist-tag|version|spec> |
Zastępuje docelowy pakiet tylko dla tej aktualizacji. Nie można go połączyć z aktywnym kanałem extended-stable, dla którego wymagany jest zweryfikowany, dokładny cel. W przypadku innych instalacji pakietów main jest mapowane na github:openclaw/openclaw#main; specyfikacje źródeł GitHub/git są pakowane do tymczasowego archiwum tar przed etapową globalną instalacją npm. |
--dry-run |
Wyświetla podgląd zaplanowanych działań (przepływu kanału/tagu/celu/ponownego uruchomienia) bez zapisywania konfiguracji, instalowania, synchronizowania pluginów ani ponownego uruchamiania. |
--json |
Wyświetla nadający się do przetwarzania maszynowego kod JSON UpdateRunResult. Obejmuje postUpdate.plugins.warnings, gdy zarządzany plugin wymaga naprawy, szczegóły mechanizmu rezerwowego pluginu kanału beta oraz postUpdate.plugins.integrityDrifts, gdy podczas synchronizacji po aktualizacji zostanie wykryta rozbieżność artefaktu pluginu npm. |
--timeout <seconds> |
Limit czasu dla poszczególnych kroków. Domyślnie 1800. |
--yes |
Pomija monity o potwierdzenie (na przykład potwierdzenie obniżenia wersji). |
--acknowledge-clawhub-risk |
Zezwala synchronizacji pluginów po aktualizacji na kontynuowanie mimo ostrzeżeń dotyczących zaufania do społecznościowych pakietów ClawHub bez interaktywnego monitu. Bez tej opcji ryzykowne wydania społecznościowe są pomijane i pozostają niezmienione, gdy OpenClaw nie może wyświetlić monitu. Oficjalne pakiety ClawHub i dołączone źródła pluginów pomijają ten monit. |
Flaga --verbose nie istnieje. Aby wyświetlić podgląd zaplanowanych działań, należy użyć --dry-run,
aby uzyskać wyniki nadające się do przetwarzania maszynowego — --json, a aby sprawdzić
wyłącznie kanał/dostępność — openclaw update status --json. Szczegółowość konsoli Gateway (--verbose) i
poziom rejestrowania w pliku (logging.level: "debug"/"trace") są niezależnymi ustawieniami; zobacz
Rejestrowanie zdarzeń Gateway.
update status
Wyświetla aktywny kanał aktualizacji, tag/gałąź/SHA git (tylko w kopiach roboczych źródeł) oraz dostępność aktualizacji.
openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10| Flaga | Domyślnie | Opis |
|---|---|---|
--json |
false |
Wyświetla nadający się do przetwarzania maszynowego kod JSON ze stanem. |
--timeout <seconds> |
3 |
Limit czasu sprawdzania. |
W przypadku instalacji pakietów extended-stable sprawdzanie stanu wykonuje ten sam publiczny wybór
i weryfikację dokładnego pakietu co aktualizacja pierwszoplanowa. Może zgłosić
ahead of extended-stable, gdy zainstalowana wersja jest nowsza. Błędy JSON
obejmują registry.reason (selector_missing, selector_query_failed,
exact_package_mismatch lub unsupported_git_channel).
update repair
Ponownie uruchamia finalizację aktualizacji, gdy pakiet rdzenia został już zmieniony, ale późniejsze
prace naprawcze nie zakończyły się prawidłowo. Jest to obsługiwana ścieżka odzyskiwania, gdy
openclaw update zainstalowało nowy pakiet rdzenia, ale synchronizacja pluginów po aktualizacji rdzenia,
metadane zarządzanych pluginów npm, odświeżenie rejestru lub naprawa przez Doctor nie
osiągnęły spójnego stanu.
openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json| Flaga | Opis |
|---|---|
--channel <stable|extended-stable|beta|dev> |
Zachowuje kanał aktualizacji rdzenia przed naprawą. W przypadku extended-stable kwalifikujące się oficjalne pluginy npm zgodne z intencją bare/default lub latest są kierowane na dokładną zainstalowaną wersję rdzenia. Naprawa extended-stable jest odrzucana w kopiach roboczych Git bez zmiany konfiguracji. |
--json |
Wyświetla nadający się do przetwarzania maszynowego kod JSON finalizacji. |
--timeout <seconds> |
Limit czasu kroków naprawy. Domyślnie 1800. |
--yes |
Pomija monity o potwierdzenie. |
--acknowledge-clawhub-risk |
Działa tak samo jak w przypadku openclaw update. |
--no-restart |
Akceptowana dla zachowania zgodności; naprawa nigdy nie uruchamia ponownie Gateway. |
update repair uruchamia openclaw doctor --fix, ponownie wczytuje naprawioną konfigurację i
rekordy instalacji, synchronizuje śledzone pluginy dla aktywnego kanału aktualizacji, aktualizuje
zarządzane instalacje pluginów npm, naprawia brakujące dane skonfigurowanych pluginów,
odświeża rejestr pluginów i zapisuje metadane rekordów instalacji w spójnym stanie.
Nie instaluje nowego pakietu rdzenia ani nie uruchamia ponownie Gateway.
update wizard
Interaktywny przepływ umożliwiający wybranie kanału aktualizacji i potwierdzenie, czy następnie
ponownie uruchomić Gateway (domyślnie jest ponownie uruchamiany). Wybranie dev bez kopii
roboczej git powoduje wyświetlenie propozycji jej utworzenia.
| Flaga | Domyślnie | Opis |
|---|---|---|
--timeout <seconds> |
1800 |
Limit czasu dla każdego kroku aktualizacji. |
Sposób działania
Jawne przełączanie kanałów (--channel ...) zapewnia również zgodność
metody instalacji:
dev-> zapewnia kopię roboczą git (domyślnie~/openclawlub$OPENCLAW_HOME/openclaw, gdy ustawionoOPENCLAW_HOME; można zastąpić za pomocąOPENCLAW_GIT_DIR), aktualizuje ją i instaluje globalny CLI z tej kopii roboczej.stable-> instaluje z npm przy użyciulatest.extended-stable-> rozwiązuje publiczny selektor npmextended-stable, weryfikuje dokładny wybrany pakiet i instaluje dokładnie tę wersję. Nie korzysta z innego selektora jako rozwiązania rezerwowego i jest odrzucany w kopiach roboczych Git.beta-> preferuje tag dystrybucyjny npmbeta, a gdy wersja beta jest niedostępna lub starsza od bieżącego wydania stabilnego, korzysta zlatest.
Przekazanie ponownego uruchomienia
Automatyczny aktualizator rdzenia Gateway (gdy jest włączony w konfiguracji) uruchamia ścieżkę
aktualizacji CLI poza aktywną procedurą obsługi żądań Gateway. Aktualizacje menedżera pakietów
update.run w płaszczyźnie sterowania oraz nadzorowane aktualizacje kopii roboczych git używają
tego samego przekazania do zarządzanej usługi zamiast zastępowania drzewa pakietów lub
ponownego kompilowania dist/ wewnątrz aktywnego procesu Gateway: Gateway uruchamia
odłączony proces pomocniczy i kończy działanie, a ten proces pomocniczy uruchamia openclaw update --yes --json
spoza drzewa procesów Gateway. Jeśli przekazanie jest niedostępne,
update.run zwraca ustrukturyzowaną odpowiedź z bezpiecznym poleceniem powłoki do ręcznego
uruchomienia.
Zapisane wybory kanału extended-stable otrzymują wskazówki tylko do odczytu podczas uruchamiania i co 24 godziny,
gdy włączono update.checkOnStart. Te kontrole nigdy nie stosują aktualizacji,
nie rozpoczynają przekazania, nie uruchamiają ponownie Gateway, nie używają opóźnienia/losowego rozrzutu kanału stable ani
częstotliwości odpytywania kanału beta. Nadal obsługiwane są jawne aktualizacje pierwszoplanowe, aktualizacje pierwszoplanowe bez argumentów z
zapisanym update.channel: "extended-stable", stan na żądanie oraz powiązane z nimi zarządzane
przekazanie Gateway.
Gdy zainstalowano lokalną zarządzaną usługę Gateway i włączono ponowne uruchamianie,
aktualizacje za pomocą menedżera pakietów i aktualizacje kopii roboczej Git zatrzymują działającą usługę przed
zastąpieniem drzewa pakietu lub zmodyfikowaniem kopii roboczej/wyniku kompilacji. Aktualizator
następnie odświeża metadane usługi, uruchamia ją ponownie i weryfikuje
ponownie uruchomiony Gateway przed zgłoszeniem Gateway: restarted and verified..
Aktualizacje za pomocą menedżera pakietów dodatkowo sprawdzają, czy ponownie uruchomiony Gateway zgłasza
oczekiwaną wersję pakietu; aktualizacje kopii roboczej Git sprawdzają po ponownej kompilacji kondycję Gateway i
gotowość usługi.
Aktualizacje za pomocą menedżera pakietów zwykle nadal używają pliku wykonywalnego Node zapisanego w
zarządzanej usłudze. Jeśli ten Node nie może uruchomić docelowego wydania, ale bieżący
Node CLI może to zrobić, a usługa z pewnością należy do aktualizowanego pakietu,
aktualizacja z włączonym ponownym uruchamianiem używa bieżącego Node do finalizacji i przepisuje
metadane usługi na to środowisko uruchomieniowe. --no-restart nie może naprawić metadanych
usługi, dlatego taka sama niezgodność środowiska uruchomieniowego powoduje zatrzymanie przed modyfikacją pakietu.
W systemie macOS kontrola po aktualizacji sprawdza również, czy LaunchAgent jest
załadowany/uruchomiony dla aktywnego profilu i czy skonfigurowany port pętli zwrotnej jest
sprawny. Jeśli plik plist jest zainstalowany, ale launchd go nie nadzoruje, OpenClaw
automatycznie ponownie inicjuje LaunchAgent i powtarza kontrole kondycji/wersji/
gotowości kanału (świeża inicjalizacja ładuje zadanie RunAtLoad bezpośrednio,
więc odzyskiwanie nie powoduje natychmiastowego kickstart -k nowo uruchomionego Gateway). Jeśli
Gateway nadal nie osiągnie prawidłowego stanu, polecenie kończy się kodem różnym od zera i
wyświetla ścieżkę dziennika ponownego uruchamiania oraz instrukcje ponownego uruchomienia, ponownej instalacji i wycofania
pakietu.
Jeśli nie można wykonać ponownego uruchomienia, polecenie wyświetla Gateway: restart skipped (...) lub
Gateway: restart failed: ... ze wskazówką dotyczącą ręcznego openclaw gateway restart.
Przy --no-restart zastąpienie pakietu lub ponowna kompilacja Git nadal jest wykonywana, ale
zarządzana usługa nie jest zatrzymywana ani ponownie uruchamiana, więc działający Gateway zachowuje stary
kod do czasu ręcznego ponownego uruchomienia.
Struktura odpowiedzi płaszczyzny sterowania
Gdy update.run działa przez płaszczyznę sterowania Gateway w instalacji za pomocą menedżera pakietów
lub nadzorowanej kopii roboczej Git, procedura obsługi zgłasza rozpoczęcie przekazania
oddzielnie od aktualizacji CLI kontynuowanej po zakończeniu działania Gateway:
ok: true,result.status: "skipped",result.reason: "managed-service-handoff-started"orazhandoff.status: "started": Gateway utworzył przekazanie zarządzanej usługi i zaplanował własne ponowne uruchomienie, aby odłączony proces pomocniczy mógł uruchomićopenclaw update --yes --jsonpoza aktywnym procesem usługi.ok: false,result.reason: "managed-service-handoff-unavailable"orazhandoff.status: "unavailable": OpenClaw nie mógł znaleźć granicy nadzorowanej usługi i trwałej tożsamości usługi potrzebnych do bezpiecznego przekazania (na przykład przekazanie systemd wymaga tożsamości jednostkiOPENCLAW_SYSTEMD_UNIT, a nie tylko kontekstowych znaczników procesu systemd). Odpowiedź zawierahandoff.command, czyli polecenie powłoki do uruchomienia spoza Gateway.ok: false,result.reason: "managed-service-handoff-failed": Gateway próbował utworzyć przekazanie, ale nie mógł uruchomić odłączonego procesu pomocniczego.
Ładunek sentinel jest zapisywany przed zakończeniem działania Gateway, a przekazanie
CLI aktualizuje ten sam znacznik ponownego uruchomienia po zakończeniu kontroli kondycji
zarządzanej usługi po ponownym uruchomieniu. Podczas przekazania znacznik może zawierać
stats.reason: "restart-health-pending" bez kontynuacji powodzenia;
ponownie uruchomiony Gateway odpytuje go i uruchamia kontynuację dopiero po zweryfikowaniu przez CLI
kondycji usługi oraz ponownym zapisaniu znacznika z końcowym wynikiem ok.
openclaw status i openclaw status --all pokazują wiersz Update restart,
gdy ten znacznik oczekuje lub wskazuje niepowodzenie, a update.status odświeża i
zwraca najnowszy znacznik.
Przepływ kopii roboczej Git
Wybór kanału
stable: przełącza kopię roboczą na najnowszy znacznik inny niż beta, a następnie wykonuje kompilację i doctor.beta: preferuje najnowszy znacznik-beta, przechodząc na najnowszy znacznik stable, gdy kanał beta jest niedostępny lub starszy.dev: przełącza kopię roboczą namain, a następnie pobiera zmiany i wykonuje rebase.extended-stable: nieobsługiwane w przypadku kopii roboczych Git; kopia robocza nie jest modyfikowana.
Kroki aktualizacji
Sprawdzenie czystości drzewa roboczego
Wymaga braku niezacommitowanych zmian.
Zmiana kanału
Przełącza na wybrany kanał (znacznik lub gałąź).
Pobranie zmian z repozytorium nadrzędnego
Tylko kanał dev.
Wstępna kompilacja (tylko kanał dev)
Uruchamia kompilację TypeScript w tymczasowym drzewie roboczym. Jeśli najnowszy commit nie przejdzie kompilacji, cofa się o maksymalnie 10 commitów, aby znaleźć najnowszy commit możliwy do skompilowania. Ustaw OPENCLAW_UPDATE_PREFLIGHT_LINT=1, aby podczas tej kontroli wstępnej uruchomić również lint; lint działa w ograniczonym trybie szeregowym, ponieważ hosty aktualizacji użytkowników często mają mniej zasobów niż maszyny wykonawcze CI.
Rebase
Wykonuje rebase na wybrany commit (tylko kanał dev).
Instalacja zależności
Używa menedżera pakietów repozytorium. W przypadku kopii roboczych pnpm aktualizator inicjuje pnpm na żądanie (najpierw przez corepack, a następnie przez tymczasowy mechanizm awaryjny npm install pnpm@11), zamiast uruchamiać npm run build wewnątrz przestrzeni roboczej pnpm. Jeśli inicjalizacja pnpm nadal się nie powiedzie, aktualizator zatrzymuje się wcześniej z błędem właściwym dla menedżera pakietów, zamiast próbować użyć npm run build w kopii roboczej.
Kompilacja interfejsu sterowania
Kompiluje Gateway i interfejs sterowania.
Uruchomienie doctor
openclaw doctor działa jako końcowa kontrola bezpiecznej aktualizacji.
Synchronizacja pluginów
Synchronizuje pluginy z aktywnym kanałem. Kanał dev używa dołączonych pluginów; kanały stable i beta używają npm. Aktualizuje śledzone instalacje pluginów.
Szczegóły synchronizacji pluginów
Na kanale beta śledzone instalacje pluginów npm i ClawHub, które korzystają z
domyślnej/najnowszej linii, najpierw próbują użyć wydania pluginu @beta. Jeśli plugin nie ma
wydania beta, OpenClaw wraca do zapisanej specyfikacji domyślnej/najnowszej i
zgłasza ostrzeżenie. W przypadku pluginów npm OpenClaw używa mechanizmu awaryjnego również wtedy, gdy pakiet
beta istnieje, ale nie przechodzi walidacji instalacji. Te ostrzeżenia mechanizmu awaryjnego nie
powodują niepowodzenia aktualizacji rdzenia. Dokładne wersje i jawne znaczniki nigdy nie są przepisywane.
Po pomyślnym zakończeniu aktualizacji rdzenia extended-stable sprawdzanie integralności i
konwergencja pluginów po aktualizacji rdzenia obejmują kwalifikujące się oficjalne pluginy npm w dokładnie tej samej wersji co zainstalowany
rdzeń. W przypadku intencji domyślnej/latest OpenClaw nie odpytuje
@extended-stable pluginu ani nie wraca do latest npm; wyznacza wersję pakietu
na podstawie zainstalowanego rdzenia. Jawne przypięcia wersji, jawne znaczniki inne niż latest,
pakiety innych firm oraz źródła inne niż npm zachowują dotychczasową intencję.
W przypadku instalacji za pomocą menedżera pakietów openclaw update rozwiązuje docelową wersję
pakietu przed wywołaniem menedżera pakietów. Globalne instalacje npm korzystają z instalacji etapowej:
OpenClaw instaluje nowy pakiet w tymczasowym prefiksie npm,
pozwala pakietowi kandydującemu zweryfikować wersję Node hosta podczas preinstall
i sprawdza tam spis pakietu dist. Spakowane zabezpieczenie ukończenia
pozostaje poza tym spisem do czasu pomyślnego zakończenia preinstall, dzięki czemu menedżery pakietów,
które pomijają skrypty cyklu życia, również zatrzymują się przed aktywacją. W npm 12 i nowszych
aktualizator zatwierdza wyłącznie cykl życia kandydującego pakietu OpenClaw; skrypty
zależności przechodnich pozostają zablokowane. Następnie OpenClaw zamienia czyste drzewo pakietu
w rzeczywistym globalnym prefiksie. Jeśli weryfikacja się nie powiedzie, doctor po aktualizacji, synchronizacja
pluginów i ponowne uruchomienie nie są wykonywane z podejrzanego drzewa. Nawet gdy
zainstalowana wersja już odpowiada docelowej, polecenie odświeża
globalną instalację pakietu, a następnie uruchamia synchronizację pluginów, odświeżenie uzupełnień
poleceń rdzenia i ponowne uruchomienie. Dzięki temu spakowane procesy pomocnicze i należące do kanału
rekordy pluginów pozostają zgodne z zainstalowaną kompilacją OpenClaw, natomiast pełne
przebudowywanie uzupełnień poleceń pluginów pozostaje zadaniem jawnych
uruchomień openclaw completion --write-state.
Powiązane
openclaw doctor(oferuje najpierw uruchomienie aktualizacji w kopiach roboczych Git)- Kanały deweloperskie
- Aktualizowanie
- Dokumentacja CLI
