Aktualizacje i kopie zapasowe OpenClaw: pinowanie wersji i plan powrotu

Co naprawdę robi openclaw update

Za jedną komendą stoją cztery czynności. openclaw update wykrywa typ instalacji — npm, pnpm, Bun albo git — pobiera nową wersję, uruchamia openclaw doctor i restartuje gateway. Restart pominiesz flagą --no-restart, jeśli akurat nie chcesz ciszy na kanałach.

Zanim cokolwiek się zmieni, zobacz plan: openclaw update --dry-run. Na maszynie, na której agent odbiera wiadomości od klientów, ten jeden krok zwraca się przy pierwszym zaskoczeniu. Restart gatewaya oznacza przerwę na wszystkich kanałach naraz.

Pod spodem dzieje się więcej, niż widać w wyjściu. Przy globalnej instalacji npm updater instaluje kandydata najpierw do tymczasowego prefiksu. Kandydat sprawdza wersję Node w kroku preinstall, dopiero potem OpenClaw weryfikuje zawartość spakowanego dist i podmienia czyste drzewo pakietu w prawdziwym prefiksie. Jeśli podmiana plików albo wymiana skrótów wykonywalnych się nie uda, stary pakiet wraca automatycznie.

Ręczne alternatywy istnieją: npm i -g openclaw@latest, pnpm add -g openclaw@latest, bun add -g openclaw@latest. Przy instalacji z zarządzaną usługą najpierw zatrzymaj gateway. Menedżery pakietów podmieniają pliki w miejscu, a działający gateway potrafi wtedy wczytać połowę starego, połowę nowego kodu.

openclaw update --dry-run
openclaw update
openclaw update status --json

Dlaczego pinowanie wersji bije latest

Tag latest mówi „daj mi cokolwiek, co jest teraz najnowsze”. openclaw update --tag <wersja> mówi „daj mi dokładnie tę”. Różnica nie jest kosmetyczna. Droga przez --tag wykrywa cofnięcie wersji i prosi o potwierdzenie, uruchamia zbieżność pluginów zarządzanych i sprawdzenia zgodności wobec zainstalowanego celu, odświeża metadane usługi, restartuje gateway i weryfikuje wersję, która faktycznie wstała. Bezpośrednia instalacja pakietem nie robi nic z tej listy.

Jest jeszcze skutek uboczny, który zaskakuje. CLI zapisuje kanał po udanej aktualizacji rdzenia, ale bezpośrednie npm install -g openclaw@extended-stable nie zaktualizuje klucza update.channel. Konfiguracja twierdzi wtedy co innego niż stan faktyczny, a auto-updater podejmuje decyzje właśnie na podstawie konfiguracji.

Kanały wydań są cztery i różnią się tym, kiedy aplikują. Stable aplikuje po wbudowanym opóźnieniu z deterministycznym rozrzutem, żeby rollout rozłożył się w czasie. Beta sprawdza w stałym interwale i aplikuje od razu. Extended-stable tylko podpowiada — przy starcie i co 24 godziny, gdy checkOnStart jest włączone — i nigdy niczego nie zastosuje sam. Dev to trwały ruchomy checkout gałęzi main z GitHuba, również bez automatycznego aplikowania.

Auto-updater jest domyślnie wyłączony. Włącza się go w ~/.openclaw/openclaw.json kluczami update.channel i update.auto.enabled. Na czas naprawy awarii zablokujesz go zmienną OPENCLAW_NO_AUTO_UPDATE=1 w środowisku gatewaya — to samo dotyczy sytuacji, w której świadomie cofasz wersję i nie chcesz, żeby updater natychmiast wciągnął nowszą z powrotem. Podpowiedzi startowe wyłącza osobno update.checkOnStart.

• stable — aplikuje po wbudowanym opóźnieniu z deterministycznym rozrzutem
• beta — sprawdza w stałym interwale i aplikuje natychmiast
• extended-stable — tylko podpowiada przy starcie i co 24 godziny, nigdy nie aplikuje
• dev — ruchomy checkout gałęzi main, bez automatycznego aplikowania

{
  update: {
    channel: "stable",
    auto: { enabled: true }
  }
}

Kopia przed aktualizacją: openclaw backup create --verify

openclaw update zachowuje automatyczną kopię konfiguracji sprzed zmiany, ale nie tworzy punktu odtworzenia całego stanu. To dwie różne rzeczy i mylenie ich kosztuje najwięcej. Przed poważniejszą aktualizacją zrób kopię sam, a flagą --verify zwaliduj archiwum od razu po zapisie — o uszkodzonym pliku dowiesz się wtedy teraz, a nie w dniu awarii.

Do archiwum trafiają cztery rzeczy. Katalog stanu (zwykle ~/.openclaw), ścieżka aktywnego pliku konfiguracyjnego, katalog credentials, gdy leży poza katalogiem stanu, oraz katalogi workspace odnalezione w konfiguracji. Profile auth i stan runtime per-agent siedzą w SQLite pod agents/<agentId>/agent/openclaw-agent.sqlite, więc wchodzą razem z katalogiem stanu. Manifest zapisuje wersję OpenClaw i listę źródeł. To on później mówi, co gdzie odtworzyć.

Archiwum celowo pomija pliki, które zmieniają się w trakcie zapisu: .jsonl i .log pod sessions/, logs/ oraz cron/runs/, pliki kolejek dostarczeń, a w całym katalogu stanu .sock, .pid i .tmp. Ile plików wypadło, mówi pole skippedVolatileCount w wyjściu JSON. Skutek praktyczny jest taki, że zakończone transkrypty i logi nie są w kopii — jeśli ich potrzebujesz, archiwizuj je osobno.

Bazy SQLite w katalogu stanu są zrzucane przez online backup API i kompaktowane przez VACUUM, więc nie musisz zatrzymywać gatewaya na czas kopii. Pliki -wal i -shm nie są kopiowane. Uwaga na źródło pomyłki: bazy SQLite złapane przez backup workspace’u są kopiowane jak zwykłe pliki i ta gwarancja ich nie obejmuje.

Archiwum zawiera poświadczenia, profile auth i stan kanałów. Trzymaj je z uprawnieniami tylko dla właściciela, dokładnie tak jak żywy katalog stanu. chmod 700 na ~/.openclaw i chmod 600 na pliku konfiguracyjnym to minimum, które dotyczy również katalogu z kopiami.

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw backup verify ~/Backups/openclaw/<archiwum>.tar.gz

openclaw backup sqlite i flaga --agent

Gdy potrzebujesz przenośnego artefaktu z jednej bazy, a nie całego archiwum stanu, użyj openclaw backup sqlite. Tworzenie snapshotu przyjmuje dokładnie jedno źródło: --global dla wspólnego stanu OpenClaw albo --agent <id> dla bazy konkretnego agenta. To właśnie tu należy --agent, a nie do openclaw backup create. Pomyłka w tym miejscu kończy się komunikatem o nieznanej fladze i kwadransem szukania w dokumentacji.

Repozytorium wskazujesz flagą --repository <katalog>. W środku powstaje jeden katalog na snapshot, a w nim dokładnie dwa pliki: manifest.json i database.sqlite. Nic więcej.

Tworzenie snapshotu weryfikuje żywą bazę przed odczytem, używa online backup API, zamyka bazę, kompaktuje prywatną kopię przez VACUUM, weryfikuje wynik ponownie i publikuje gotowy katalog bez nadpisywania istniejących ścieżek. Snapshoty globalne usuwają przy okazji przejściowe wiersze kolejki dostarczeń, żeby usunięte ładunki nie zostały w wolnych stronach pliku.

Czego nie robić: nie kopiuj żywych plików .sqlite, -wal, -shm ani -journal jako kopii zapasowej. Kopiuje się wyłącznie zakończone katalogi snapshotów. Odtworzenie idzie przez openclaw backup sqlite restore <snapshot> --target <nowa-ścieżka> i zawsze pisze do świeżego pliku — komenda odmówi nadpisania istniejącego celu i nigdy nie podmieni żywej bazy w miejscu. Podstawienie odtworzonej bazy jest osobną, ręczną czynnością przy zatrzymanym gatewayu.

openclaw backup sqlite create --global --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite list --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqlite

Czego archiwum nie zrobi: nie ma odtwarzania w miejscu

To jest miejsce, w którym najwięcej osób zakłada za dużo. openclaw backup create umie tworzyć i weryfikować archiwa, ale nie umie aktywować całego archiwum w miejscu. Odtworzenie polega na rozpakowaniu do katalogu roboczego i użyciu mapowania źródeł z manifest.json przy zatrzymanym gatewayu. Ręcznie, plik po pliku, według manifestu.

Jeśli chcesz punktu odtworzenia co do bajta, razem z tym, co przenośne archiwum świadomie pomija, zatrzymaj gateway i zrób snapshot systemu plików, wolumenu albo maszyny wirtualnej po stronie swojej platformy. To jedyna droga do „wracam do stanu z wtorku z dziewiątej rano” bez składania go z części.

Jest jeszcze zachowanie, które ratuje przy uszkodzonej konfiguracji. openclaw backup omija normalne sprawdzenie configu, żeby dało się go użyć w trakcie naprawy. Odnajdywanie katalogów workspace wymaga jednak poprawnej konfiguracji, więc backup create przerwie od razu, gdy plik istnieje, ale jest niepoprawny, a backup workspace’u pozostaje włączony. Wtedy --no-include-workspace zostawia stan, config i katalog credentials, a --only-config zapisuje sam aktywny plik konfiguracyjny i działa nawet na zepsutym configu.

Podział na dwie lokalizacje jest tu praktyczny, nie teoretyczny. Workspace agenta — pamięć oraz pliki AGENTS.md, SOUL.md i USER.md — nadaje się do prywatnego repozytorium git, a historia zmian bywa cenniejsza niż samo archiwum, bo widać, kiedy agent zmienił zdanie na swój temat. Katalog ~/.openclaw do gita nie nadaje się nigdy: trzyma poświadczenia kanałów, sesje, tokeny i zaszyfrowane ładunki sekretów.

openclaw backup create --no-include-workspace
openclaw backup create --only-config
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Plan powrotu: najpierw kod, stan tylko gdy trzeba

Rollback ma dwie warstwy i kolejność nie jest dowolna. Najpierw przywracasz starszy kod OpenClaw, zostawiając bieżący stan. Dopiero gdy starszy kod nie potrafi odczytać zmigrowanej konfiguracji albo bazy, wracasz do stanu sprzed aktualizacji — a to kasuje wszystko, co wydarzyło się po zrobieniu kopii.

Przy instalacji pakietowej sekwencja jest trzyczęściowa: wypisz opublikowane wersje, przećwicz na sucho, wykonaj. openclaw update --tag jest tu wyraźnie lepsze od bezpośredniego wywołania menedżera pakietów, bo wykrywa cofnięcie, prosi o potwierdzenie i weryfikuje uruchomioną wersję. Jedna niespodzianka: jeśli zapisany kanał to extended-stable, dokładnych tagów nie da się z nim połączyć — użyj --channel stable --tag <wersja>.

Przy checkoucie źródłowym wracasz przez gita: git fetch --all --tags, git checkout --detach <tag-lub-commit>, pnpm install && pnpm build, openclaw gateway restart. Updater potrafi zresztą sam cofnąć checkout do poprzedniej gałęzi i konkretnego commita, gdy po starcie aktualizacji wywali się instalacja zależności, build, build interfejsu albo doctor.

Osobny przypadek to zejście poniżej migracji sesji do SQLite. Zanim uruchomisz starsze wydanie, przywróć zarchiwizowane transkrypty bieżącym CLI: openclaw gateway stop, potem openclaw doctor --session-sqlite restore. To nie kasuje danych z SQLite, ale sesje utworzone po migracji w starszym runtime po prostu nie będą widoczne.

Po każdym powrocie przelatujesz ten sam zestaw kontrolny: openclaw --version, openclaw health, openclaw plugins list --json, openclaw gateway status --deep --json, openclaw doctor --lint --json. Pięć komend, dwie minuty, koniec zgadywania.

npm view openclaw versions --json
openclaw update --tag <znana-dobra-wersja> --dry-run
openclaw update --tag <znana-dobra-wersja>
openclaw --version && openclaw health

Gateway padł po aktualizacji: dwie instalacje na jednej maszynie

Gdy usługa gatewaya nieoczekiwanie zatrzymuje się po aktualizacji, sprawdź, czy nie masz na maszynie dwóch instalacji OpenClaw. OpenClaw stempluje zapisy konfiguracji kluczem meta.lastTouchedVersion. Starszy plik wykonywalny może czytać config zapisany przez nowszą wersję, ale odmówi czynności zmieniających: startu, zatrzymania, restartu i odinstalowania usługi, wymuszonej reinstalacji, startu gatewaya w trybie usługi oraz czyszczenia portu przez gateway --force.

Diagnoza jest krótka: which openclaw, openclaw --version, openclaw gateway status --deep oraz openclaw config get meta.lastTouchedVersion. Jeśli numery się rozjeżdżają, napraw PATH tak, żeby openclaw wskazywał na nowszą instalację, albo zainstaluj usługę z tej nowszej przez openclaw gateway install --force i openclaw gateway restart.

Druga rodzina objawów po aktualizacji to kanały, które zniknęły, i wywołania modelu wracające z 401. W logach szukaj wpisu „plugin load failed: dependency tree corrupted; run openclaw doctor --fix” — konfiguracja kanału jest na miejscu, ale rejestracja pluginu nie doszła do skutku. Przy 401 po ponownym uwierzytelnieniu openclaw doctor --fix sprawdza nieaktualne cienie OAuth per-agent i usuwa stare kopie, żeby wszyscy agenci rozwiązywali bieżący wspólny profil.

W openclaw status i openclaw status --all sprawdź linię „Update restart”. Zawieszone albo nieudane przekazania podają w niej następną komendę do uruchomienia. Nie trzeba jej wymyślać.

which openclaw
openclaw --version
openclaw config get meta.lastTouchedVersion
openclaw gateway install --force
openclaw gateway restart

Przeprowadzka agenta na inny serwer

Migracja to przeniesienie całego katalogu stanu, nie samego openclaw.json. Na starej maszynie zatrzymujesz gateway i pakujesz ~/.openclaw, na nowej instalujesz CLI, przenosisz archiwum przez scp, rsync -a albo dysk, rozpakowujesz w katalogu domowym i uruchamiasz openclaw doctor, openclaw gateway restart oraz openclaw status.

Kryteria udanej przeprowadzki dokumentacja podaje wprost, więc odhacz je po kolei: gateway działa, kanały pozostają połączone bez ponownego parowania, dashboard pokazuje istniejące sesje, pliki workspace są na miejscu.

Migrację psują za każdym razem te same cztery rzeczy.

Jeśli Telegram albo Discord korzysta z domyślnego zapasu w zmiennych środowiskowych, sprawdź po przeniesieniu, czy plik .env w katalogu stanu zawiera TELEGRAM_BOT_TOKEN i DISCORD_BOT_TOKEN — bez wypisywania samych wartości. openclaw doctor ostrzega zresztą sam, gdy włączone domyślne konto Telegrama lub Discorda nie ma skonfigurowanego tokenu, a zmienna nie jest dla niego dostępna.

Osobne profile, na przykład ~/.openclaw-work, archiwizuje się oddzielnie — nie wjadą razem z domyślnym katalogiem stanu. A jeśli cała ta procedura brzmi jak coś, czego wolisz nie robić w sobotę, alternatywą jest hosting zarządzany: ClawLabs uruchamia agenta w chmurze EU na Hetznerze, a aktualizacje i kopie zostają po stronie dostawcy.

• Skopiowanie samego openclaw.json — profile auth modeli leżą w agents/<agentId>/agent/auth-profiles.json, a stan kanałów w credentials/
• Rozjazd profilu albo katalogu stanu — gdy stary gateway chodził z --profile lub OPENCLAW_STATE_DIR, a nowy nie, kanały wyglądają na wylogowane, a sesje na puste
• Właścicielstwo plików po kopiowaniu jako root albo między użytkownikami — gateway nie odczyta wtedy poświadczeń
• Tryb zdalny — jeśli interfejs celuje w zdalny gateway, to on jest właścicielem sesji i workspace’u; przenosi się jego host, nie laptopa

openclaw gateway stop
cd ~ && tar -czf openclaw-state.tgz .openclaw
# po transferze, na nowej maszynie:
cd ~ && tar -xzf openclaw-state.tgz
openclaw doctor
openclaw gateway restart
openclaw status