Skip to main content

​
openclaw update

Оновлюйте OpenClaw і перемикайтеся між каналами stable/extended-stable/beta/dev. Якщо встановлення виконано через npm/pnpm/bun (глобальне встановлення без метаданих git), оновлення відбуваються за процедурою менеджера пакетів, описаною в розділі Оновлення.

​
Використання

openclaw --update перетворюється на openclaw update (корисно для оболонок і скриптів запуску).

​
Параметри

Прапорця --verbose немає. Використовуйте --dry-run для попереднього перегляду запланованих дій, --json для машинозчитуваних результатів і openclaw update status --json лише для перевірки каналу/доступності. Докладність консолі Gateway (--verbose) і рівень журналювання у файл (logging.level: "debug"/"trace") налаштовуються незалежно; див. Журналювання Gateway.
У режимі Nix (OPENCLAW_NIX_MODE=1) виконання openclaw update, що вносять зміни, вимкнено. Натомість оновіть джерело Nix або вхідні дані flake для цього встановлення; для nix-openclaw скористайтеся орієнтованим насамперед на агента швидким початком. openclaw update status і openclaw update --dry-run залишаються доступними лише для читання.
Повернення до попередніх версій потребує підтвердження, оскільки старіші версії можуть порушити конфігурацію. Якщо встановлення вже перенесло сеанси до SQLite, відновіть архівні артефакти застарілих транскриптів перед запуском старішої версії з файловим сховищем. Див. Doctor: повернення до попередньої версії після міграції сеансів до SQLite.

​
update status

Показати активний канал оновлень, тег/гілку/SHA git (лише для робочих копій вихідного коду) та доступність оновлень.
Для пакетних встановлень extended-stable команда стану виконує такий самий вибір загальнодоступного селектора й перевірку точного пакета, що й звичайне оновлення. Вона може повідомити ahead of extended-stable, коли встановлена версія новіша. Помилки JSON містять registry.reason (selector_missing, selector_query_failed, exact_package_mismatch або unsupported_git_channel).

​
update repair

Повторно виконати завершальні дії оновлення, якщо основний пакет уже змінився, але подальші відновлювальні дії не завершилися належним чином. Це підтримуваний спосіб відновлення, коли openclaw update установив новий основний пакет, але синхронізація плагінів після оновлення ядра, метадані керованих плагінів npm, оновлення реєстру або відновлення засобом doctor не зійшлися до узгодженого стану.
update repair запускає openclaw doctor --fix, повторно завантажує відновлену конфігурацію та записи про встановлення, синхронізує відстежувані плагіни для активного каналу оновлень, оновлює керовані встановлення плагінів npm, відновлює відсутні налаштовані корисні дані плагінів, оновлює реєстр плагінів і записує узгоджені метадані записів про встановлення. Він не встановлює новий основний пакет і не перезапускає Gateway.

​
update wizard

Інтерактивна процедура вибору каналу оновлень і підтвердження перезапуску Gateway після цього (типово перезапускається). Якщо вибрати dev без робочої копії git, буде запропоновано створити її.

​
Принцип роботи

Явне перемикання каналів (--channel ...) також узгоджує спосіб встановлення:
  • dev -> забезпечує наявність робочої копії git (типово ~/openclaw або $OPENCLAW_HOME/openclaw, коли задано OPENCLAW_HOME; можна перевизначити за допомогою OPENCLAW_GIT_DIR), оновлює її та встановлює глобальний CLI із цієї робочої копії.
  • stable -> установлює з npm за допомогою latest.
  • extended-stable -> визначає загальнодоступний селектор npm extended-stable, перевіряє точний вибраний пакет і встановлює саме цю версію. Резервний перехід до іншого селектора не виконується; цей варіант відхиляється для робочих копій Git.
  • beta -> віддає перевагу dist-tag npm beta, переходячи до latest, коли beta відсутня або старіша за поточний стабільний випуск.

​
Передавання перезапуску

Автоматичний оновлювач ядра Gateway (якщо його ввімкнено в конфігурації) запускає процедуру оновлення CLI поза обробником активного запиту Gateway. Оновлення через менеджер пакетів площини керування update.run і контрольовані оновлення робочих копій git використовують те саме передавання керованій службі замість заміни дерева пакетів або повторної збірки dist/ усередині активного процесу Gateway: Gateway запускає від’єднаний допоміжний процес і завершує роботу, а цей процес виконує openclaw update --yes --json поза деревом процесів Gateway. Якщо передавання недоступне, update.run повертає структуровану відповідь із безпечною командою оболонки для виконання вручну. Збережені вибори extended-stable отримують під час запуску підказки лише для читання та підказки про оновлення раз на 24 години, коли ввімкнено update.checkOnStart. Ці перевірки ніколи не застосовують оновлення, не запускають передавання керування, не перезапускають Gateway, не використовують затримку/джитер stable і не використовують частоту опитування beta. Явні оновлення на передньому плані, звичайні оновлення на передньому плані зі збереженим update.channel: "extended-stable", перевірка стану на вимогу та кероване ними передавання керування Gateway і надалі підтримуються. Коли встановлено локальну керовану службу Gateway і ввімкнено перезапуск, оновлення через менеджер пакетів і оновлення git-робочої копії зупиняють запущену службу перед заміною дерева пакета або зміною робочої копії чи результатів збірки. Потім засіб оновлення оновлює метадані служби, перезапускає її та перевіряє перезапущений Gateway, перш ніж повідомити Gateway: restarted and verified.. Оновлення через менеджер пакетів додатково перевіряють, що перезапущений Gateway повідомляє очікувану версію пакета; оновлення git-робочої копії перевіряють справність Gateway і готовність служби після повторної збірки. Оновлення через менеджер пакетів зазвичай і надалі використовують виконуваний файл Node, записаний у керованій службі. Якщо цей Node не може запустити цільовий випуск, але поточний Node CLI може, а належність служби до пакета, що оновлюється, підтверджено, оновлення з увімкненим перезапуском використовує поточний Node для завершення та переписує метадані служби для цього середовища виконання. --no-restart не може виправити метадані служби, тому така сама невідповідність середовища виконання зупиняє процес до зміни пакета. У macOS перевірка після оновлення також підтверджує, що LaunchAgent завантажено/запущено для активного профілю, а налаштований порт loopback справний. Якщо plist установлено, але launchd не контролює його, OpenClaw автоматично повторно ініціалізує LaunchAgent і знову виконує перевірки справності/версії/ готовності каналу (нова ініціалізація безпосередньо завантажує завдання RunAtLoad, тому відновлення не виконує негайно kickstart -k для щойно запущеного Gateway). Якщо Gateway усе одно не стає справним, команда завершується з ненульовим кодом і виводить шлях до журналу перезапуску, а також інструкції щодо перезапуску, перевстановлення та відкочування пакета. Якщо перезапуск неможливий, команда виводить Gateway: restart skipped (...) або Gateway: restart failed: ... із підказкою щодо ручного виконання openclaw gateway restart. З --no-restart заміна пакета або повторна git-збірка все одно виконується, але керована служба не зупиняється й не перезапускається, тому запущений Gateway продовжує використовувати старий код, доки його не буде перезапущено вручну.

​
Формат відповіді площини керування

Коли update.run виконується через площину керування Gateway для інсталяції через менеджер пакетів або контрольованої git-робочої копії, обробник повідомляє про початок передавання керування окремо від оновлення CLI, яке продовжується після завершення роботи Gateway:
  • ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" і handoff.status: "started": Gateway створив передавання керування керованою службою та запланував власний перезапуск, щоб відокремлений допоміжний процес міг виконати openclaw update --yes --json поза процесом активної служби.
  • ok: false, result.reason: "managed-service-handoff-unavailable" і handoff.status: "unavailable": OpenClaw не вдалося знайти межу контрольованої служби та сталу ідентичність служби для безпечного передавання керування (наприклад, передавання керування systemd потребує ідентичності юніта OPENCLAW_SYSTEMD_UNIT, а не лише наявних у середовищі маркерів процесу systemd). Відповідь містить handoff.command — команду оболонки, яку слід виконати поза Gateway.
  • ok: false, result.reason: "managed-service-handoff-failed": Gateway спробував створити передавання керування, але не зміг запустити відокремлений допоміжний процес.
Корисне навантаження sentinel записується до завершення роботи Gateway, а CLI передавання керування оновлює той самий маркер перезапуску після завершення перевірок справності перезапущеної керованої служби. Під час передавання керування маркер може містити stats.reason: "restart-health-pending" без продовження в разі успіху; перезапущений Gateway опитує його та запускає продовження лише після того, як CLI перевірить справність служби й перепише маркер з остаточним результатом ok. openclaw status і openclaw status --all показують рядок Update restart, доки цей маркер очікує на обробку або містить помилку, а update.status оновлює та повертає найновіший маркер.

​
Процес для git-робочої копії

​
Вибір каналу

  • stable: перейти на найновіший тег, що не є beta, а потім виконати збірку й doctor.
  • beta: віддавати перевагу найновішому тегу -beta, повертаючись до найновішого тегу stable, коли beta відсутня або старіша.
  • dev: перейти на main, а потім отримати зміни та виконати rebase.
  • extended-stable: не підтримується для git-робочих копій; робоча копія не змінюється.

​
Етапи оновлення

1

Перевірка чистоти робочого дерева

Вимагає відсутності незбережених у комітах змін.
2

Перемикання каналу

Перемикає на вибраний канал (тег або гілку).
3

Отримання змін із джерела

Лише для dev.
4

Попередня збірка (лише для dev)

Запускає збірку TypeScript у тимчасовому робочому дереві. Якщо верхівка гілки не проходить збірку, повертається до 10 комітів назад, щоб знайти найновіший коміт, який можна зібрати. Установіть OPENCLAW_UPDATE_PREFLIGHT_LINT=1, щоб також запускати lint під час цієї попередньої перевірки; lint виконується в обмеженому послідовному режимі, оскільки хости користувацьких оновлень часто мають менше ресурсів, ніж виконавці CI.
5

Rebase

Виконує rebase на вибраний коміт (лише для dev).
6

Установлення залежностей

Використовує менеджер пакетів репозиторію. Для робочих копій pnpm засіб оновлення за потреби ініціалізує pnpm (спочатку через corepack, а потім із тимчасовим резервним варіантом npm install pnpm@11) замість запуску npm run build у робочому просторі pnpm. Якщо ініціалізація pnpm усе одно завершується помилкою, засіб оновлення зупиняється завчасно з помилкою, специфічною для менеджера пакетів, замість спроби виконати npm run build у робочій копії.
7

Збірка інтерфейсу керування

Збирає Gateway та інтерфейс керування.
8

Запуск doctor

openclaw doctor виконується як остаточна перевірка безпечного оновлення.
9

Синхронізація плагінів

Синхронізує плагіни з активним каналом. Dev використовує вбудовані плагіни; stable і beta використовують npm. Оновлює відстежувані інсталяції плагінів.

​
Відомості про синхронізацію плагінів

У каналі beta відстежувані інсталяції плагінів npm і ClawHub, що використовують рядок default/latest, спочатку намагаються встановити випуск плагіна @beta. Якщо плагін не має beta-випуску, OpenClaw повертається до записаної специфікації default/latest і повідомляє попередження. Для плагінів npm OpenClaw також застосовує резервний варіант, якщо beta- пакет існує, але не проходить перевірку встановлення. Ці попередження про резервний варіант не спричиняють помилки оновлення ядра. Точні версії та явні теги ніколи не переписуються.
Якщо оновлення плагіна npm із точно зафіксованою версією визначає артефакт, цілісність якого відрізняється від збереженого запису встановлення, openclaw update скасовує оновлення цього артефакту плагіна замість його встановлення. Перевстановлюйте або явно оновлюйте плагін лише після перевірки надійності нового артефакту.
Помилки синхронізації плагінів після оновлення, які стосуються керованого плагіна та які шлях синхронізації може обійти (наприклад, недоступний реєстр npm для несуттєвого плагіна), повідомляються як попередження після успішного оновлення ядра. Результат JSON зберігає верхньорівневий стан оновлення status: "ok" і повідомляє postUpdate.plugins.status: "warning" із рекомендаціями openclaw update repair і openclaw plugins inspect <id> --runtime --json. Неочікувані винятки засобу оновлення або синхронізації все одно спричиняють помилку результату оновлення. Виправте помилку встановлення або оновлення плагіна, а потім повторно запустіть openclaw update repair. Коли невдале оновлення робить керований плагін непридатним до використання, OpenClaw вимикає його запис середовища виконання та скидає активні слоти, не змінюючи визначену оператором політику plugins.allow або plugins.deny.Після етапу синхронізації кожного плагіна openclaw update виконує обов’язковий прохід узгодження після оновлення ядра перед перезапуском Gateway: відновлює відсутні налаштовані корисні навантаження плагінів, перевіряє на диску кожен активний відстежуваний запис встановлення та статично перевіряє, що його package.json можна проаналізувати (і що будь-який явно оголошений main існує). Помилки цього проходу та недійсний знімок конфігурації повертають postUpdate.plugins.status: "error" і змінюють верхньорівневий стан оновлення status на "error", тому openclaw update завершується з ненульовим кодом, а Gateway не перезапускається з неперевіреним набором плагінів. Помилка містить структуровані рядки postUpdate.plugins.warnings[].guidance, що вказують на openclaw update repair і openclaw plugins inspect <id> --runtime --json. Вимкнені записи плагінів і записи, які не є офіційними цілями синхронізації, пов’язаними з надійним джерелом, тут пропускаються (відповідно до політики skipDisabledPlugins, яку використовує перевірка відсутніх корисних навантажень), тому застарілий запис вимкненого плагіна не може заблокувати в іншому разі коректне оновлення.Після запуску оновленого Gateway завантаження плагінів виконується лише в режимі перевірки: під час запуску менеджери пакетів не запускаються, а дерева залежностей не змінюються. Перезапуски update.run через менеджер пакетів передаються керованому CLI шляху служби, тому заміна пакета відбувається поза старим процесом Gateway, а перевірки справності служби визначають, чи можна повідомити про завершення оновлення.
Після успішного оновлення ядра extended-stable перевірка цілісності плагінів після оновлення ядра та узгодження спрямовані на придатні офіційні плагіни npm із точною встановленою версією ядра. Для наміру default/latest OpenClaw не опитує @extended-stable плагіна й не повертається до latest npm; версія пакета визначається зі встановленого ядра. Явно зафіксовані версії, явні теги, відмінні від latest, сторонні пакети та джерела, відмінні від npm, зберігають наявний намір. Для інсталяцій через менеджер пакетів openclaw update визначає цільову версію пакета перед викликом менеджера пакетів. Глобальні інсталяції npm використовують поетапне встановлення: OpenClaw установлює новий пакет у тимчасовий префікс npm, дозволяє пакету-кандидату перевірити версію Node хоста під час preinstall і перевіряє там упакований перелік dist. Упакований запобіжник завершення залишається поза цим переліком, доки preinstall не завершиться успішно, тому менеджери пакетів, які пропускають сценарії життєвого циклу, також зупиняються до активації. У npm 12 і новіших версіях засіб оновлення дозволяє лише життєвий цикл пакета-кандидата OpenClaw; сценарії транзитивних залежностей залишаються заблокованими. Потім OpenClaw переміщує чисте дерево пакета до справжнього глобального префікса. Якщо перевірка завершується помилкою, doctor після оновлення, синхронізація плагінів і перезапуск не виконуються з підозрілого дерева. Навіть коли встановлена версія вже відповідає цільовій, команда оновлює глобальну інсталяцію пакета, а потім виконує синхронізацію плагінів, оновлення автодоповнення команд ядра та перезапуск. Це підтримує відповідність упакованих допоміжних компонентів і записів плагінів, керованих каналом, установленій збірці OpenClaw, водночас залишаючи повне перегенерування автодоповнення команд плагінів для явних запусків openclaw completion --write-state.

​
Пов’язані матеріали