openclaw update

Оновлюйте OpenClaw і перемикайтеся між каналами stable/extended-stable/beta/dev.

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

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

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 перетворюється на openclaw update (корисно для оболонок і скриптів запуску).

Параметри

Прапорця --verbose немає. Використовуйте --dry-run для попереднього перегляду запланованих дій, --json для машинозчитуваних результатів і openclaw update status --json лише для перевірки каналу/доступності. Докладність консолі Gateway (--verbose) і рівень журналювання у файл (logging.level: "debug"/"trace") налаштовуються незалежно; див. Журналювання Gateway.

update status

Показати активний канал оновлень, тег/гілку/SHA git (лише для робочих копій вихідного коду) та доступність оновлень.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Для пакетних встановлень 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 не зійшлися до узгодженого стану.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

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-робочих копій; робоча копія не змінюється.

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

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

У каналі beta відстежувані інсталяції плагінів npm і ClawHub, що використовують рядок default/latest, спочатку намагаються встановити випуск плагіна @beta. Якщо плагін не має beta-випуску, OpenClaw повертається до записаної специфікації default/latest і повідомляє попередження. Для плагінів npm OpenClaw також застосовує резервний варіант, якщо beta- пакет існує, але не проходить перевірку встановлення. Ці попередження про резервний варіант не спричиняють помилки оновлення ядра. Точні версії та явні теги ніколи не переписуються.

Після успішного оновлення ядра 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.

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

• openclaw doctor (пропонує спочатку запустити оновлення для git-робочих копій)
• Канали розробки
• Оновлення
• Довідник CLI