Оновлення

Підтримуйте OpenClaw в актуальному стані.

Щодо заміни образів Docker, Podman і Kubernetes див. Оновлення образів контейнерів. Gateway виконує безпечні для запуску операції оновлення до перевірки готовності й завершує роботу, якщо змонтований стан потребує ручного виправлення.

Рекомендовано: openclaw update

Визначає тип інсталяції (npm, pnpm, Bun або git), отримує найновішу версію, запускає openclaw doctor і перезапускає Gateway.

openclaw update

Перемикання каналів або вибір певної версії:

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # попередній перегляд без застосування

openclaw update не має прапорця --verbose (інсталятор має). Для діагностики використовуйте --dry-run, щоб переглянути заплановані дії, --json для структурованих результатів або openclaw update status --json, щоб перевірити стан каналу й доступності.

--channel beta надає перевагу npm dist-tag beta, але повертається до stable/latest, якщо тег beta відсутній або його версія старіша за найновіший стабільний випуск. Натомість використовуйте --tag beta для одноразового оновлення пакета, закріпленого безпосередньо за npm dist-tag beta.

--channel extended-stable працює лише з пакетами, а інсталяція, як і раніше, виконується лише на передньому плані. OpenClaw зчитує загальнодоступний npm-селектор extended-stable, перевіряє точно вибраний пакет та інсталює саме цю версію. За відсутніх або неузгоджених даних реєстру операція безпечно завершується помилкою; повернення до latest ніколи не відбувається. Якщо вибрана версія старіша за інстальовану, звичайне підтвердження повернення до попередньої версії все одно застосовується. CLI зберігає канал після успішного оновлення ядра; прямий виклик npm install -g openclaw@extended-stable не оновлює update.channel. Після заміни ядра відповідні офіційні npm-плагіни з порожнім/типовим наміром або наміром latest переходять на ту саму точну версію ядра. Точні закріплення та явні теги, відмінні від latest, сторонні плагіни й джерела, відмінні від npm, залишаються без змін. Інсталяції з каталогу, створені поточними версіями OpenClaw, зберігають цей типовий намір. Старіші записи, які містять лише точну версію, залишаються закріпленими, оскільки OpenClaw не може безпечно відрізнити старе автоматичне закріплення від користувацького; один раз запустіть openclaw plugins update @openclaw/name у каналі extended-stable, щоб знову ввімкнути для цього плагіна відстеження точної версії ядра.

--channel dev надає постійно оновлюваний checkout GitHub main. Для одноразового оновлення пакета --tag main зіставляється зі специфікацією пакета github:openclaw/openclaw#main та інсталює його безпосередньо через цільовий менеджер пакетів (npm/pnpm/bun).

Для керованих плагінів відсутність beta-випуску є попередженням, а не помилкою: оновлення ядра все одно може завершитися успішно, а плагін повернеться до свого записаного типового/найновішого випуску.

Семантику каналів див. у розділі Канали випусків.

Перемикання між інсталяціями npm і git

Використовуйте канали, щоб змінити тип інсталяції. Засіб оновлення зберігає стан, конфігурацію, облікові дані та робочий простір у ~/.openclaw; змінюється лише інсталяція коду OpenClaw, яку використовують CLI та Gateway.

# інсталяція пакета npm -> редагований checkout gitopenclaw update --channel dev # checkout git -> інсталяція пакета npmopenclaw update --channel stable

Спочатку перегляньте перемикання режиму інсталяції:

openclaw update --channel dev --dry-runopenclaw update --channel stable --dry-run

dev забезпечує наявність checkout git, збирає його та інсталює глобальний CLI із цього checkout. Канали stable, extended-stable і beta використовують пакетні інсталяції. Канал extended-stable відхиляється для checkout git без його зміни чи перетворення. Якщо Gateway уже інстальовано, openclaw update оновлює метадані служби та перезапускає її, якщо не передано --no-restart.

Для пакетних інсталяцій із керованою службою Gateway openclaw update використовує корінь пакета, який застосовує ця служба. Якщо команда оболонки openclaw походить з іншої інсталяції, засіб оновлення виводить обидва корені та шлях Node керованої служби й перевіряє цю версію Node на відповідність вимозі engines.node цільового випуску, перш ніж замінювати пакет.

Альтернатива: повторний запуск інсталятора

curl -fsSL https://openclaw.ai/install.sh | bash

Додайте --no-onboard, щоб пропустити початкове налаштування. Щоб примусово вибрати певний тип інсталяції, передайте --install-method git --no-onboard або --install-method npm --no-onboard.

Якщо openclaw update завершується помилкою після етапу інсталяції пакета npm, повторно запустіть інсталятор. Він не викликає засіб оновлення, а безпосередньо виконує глобальну інсталяцію пакета та може відновити частково оновлену інсталяцію npm.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

Закріпіть відновлення за певною версією або dist-tag за допомогою --version:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

Альтернатива: ручне оновлення через npm, pnpm або bun

npm i -g openclaw@latest

Для контрольованих інсталяцій віддавайте перевагу openclaw update: він може узгодити заміну пакета з активною службою Gateway. Якщо контрольована інсталяція оновлюється вручну, спочатку зупиніть керований Gateway. Менеджери пакетів замінюють файли на місці, інакше активний Gateway може спробувати завантажити файли ядра або плагінів під час заміни. Після завершення роботи менеджера пакетів перезапустіть Gateway, щоб він підхопив нову інсталяцію.

Для загальносистемної інсталяції Linux, що належить root, якщо openclaw update завершується помилкою EACCES, виконайте відновлення за допомогою системного npm, залишаючи Gateway зупиненим на час ручної заміни. Використовуйте ті самі прапорці профілю й змінні середовища, які зазвичай використовуються для цього Gateway. Замініть /usr/bin/npm на системний npm, якому належить глобальний префікс root на вашому хості:

openclaw gateway stopsudo /usr/bin/npm i -g openclaw@latestopenclaw gateway install --forceopenclaw gateway restart

Потім перевірте:

openclaw --versioncurl -fsS http://127.0.0.1:18789/readyzopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

Коли openclaw update керує глобальною інсталяцією npm, він спочатку інсталює цільовий пакет у тимчасовий префікс npm. Пакет-кандидат перевіряє версію Node хоста під час preinstall; лише після цього OpenClaw перевіряє упакований перелік dist і замінює чистим деревом пакета вміст справжнього глобального префікса. Упакований запобіжник завершення не включається до очікуваного переліку й видаляється лише після успішного виконання preinstall, тому пропущені сценарії життєвого циклу також спричиняють помилку до заміни. У npm 12 і новіших версіях засіб оновлення дозволяє лише життєвий цикл пакета-кандидата OpenClaw; сценарії транзитивних залежностей залишаються заблокованими. Це запобігає накладанню нового пакета npm поверх застарілих файлів попереднього. Якщо команда інсталяції завершується помилкою, OpenClaw повторює спробу один раз із --omit=optional, що допомагає на хостах, де нативні необов’язкові залежності неможливо скомпілювати.

Керовані OpenClaw команди оновлення npm і плагінів також очищають для дочірнього процесу npm карантин ланцюга постачання min-release-age (або старіший ключ конфігурації before). Ця політика призначена для загального захисту, але явне оновлення OpenClaw означає «інсталювати вибраний випуск зараз».

pnpm add -g openclaw@latest

Якщо pnpm 11 інсталював OpenClaw 2026.7.1, один раз виконайте цю команду вручну. Цей випуск передує ізольованій структурі глобальних пакетів pnpm 11, тому його засіб оновлення може помилково прийняти іншу інсталяцію npm за активний CLI. Пізніші випуски зберігають належність pnpm і під час оновлень використовують корінь пакета заміни. Вони також використовують повідомлений менеджером-власником глобальний каталог бінарних файлів і зупиняються до внесення змін, якщо доступна команда pnpm повідомляє про інший глобальний корінь або основну версію, або якщо пакет, з якого здійснено виклик, є осиротілим чи не є єдиною активною інсталяцією OpenClaw у цьому розташуванні.

Якщо OpenClaw спільно використовує групу глобальної інсталяції pnpm 11 з іншим пакетом, автоматичний засіб оновлення зупиняється до зміни групи. Оновіть початкову групу, розділену комами, вручну, щоб зберегти її споріднені пакети та політику збирання незмінними.

bun add -g openclaw@latest

Розширені теми інсталяції npm

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

Автоматичне оновлення

Типово вимкнено. Увімкніть його в ~/.openclaw/openclaw.json:

{  update: {    channel: "stable",    auto: {      enabled: true,      stableDelayHours: 6,      stableJitterHours: 12,      betaCheckIntervalHours: 1,    },  },}

Gateway також записує до журналу підказку про оновлення під час запуску (вимкнення: update.checkOnStart: false). Збережені вибори extended-stable використовують цей шлях підказки лише для читання та наявний 24-годинний інтервал підказок, але ніколи не запускають автоматичну інсталяцію, передавання керування, перезапуск, затримку/випадковий зсув stable або опитування beta. Для повернення до попередньої версії чи відновлення після інциденту задайте OPENCLAW_NO_AUTO_UPDATE=1 у середовищі Gateway, щоб блокувати автоматичне застосування, навіть коли налаштовано update.auto.enabled. Підказки про оновлення під час запуску можуть і далі виконуватися, якщо update.checkOnStart також не вимкнено.

Оновлення через менеджер пакетів, запитані за допомогою активної площини керування Gateway (update.run), не замінюють дерево пакетів усередині активного процесу Gateway. У керованих інсталяціях служби Gateway запускає відокремлене передавання керування, завершує роботу та дозволяє звичайному шляху CLI openclaw update --yes --json зупинити службу, замінити пакет, оновити метадані служби, перезапустити її, перевірити версію й доступність Gateway та, коли можливо, відновити інстальований, але не завантажений LaunchAgent macOS. Якщо Gateway не може безпечно виконати таке передавання керування, update.run повідомляє безпечну команду оболонки замість запуску менеджера пакетів у поточному процесі.

Картка оновлення на бічній панелі Control UI показує Оновити Gateway, коли вона безпосередньо запускає цей процес update.run. Це стосується розміщеного у браузері Control UI, віддалених Gateway і локальних Gateway з ручним керуванням.

У підписаному застосунку для macOS локальний Gateway, яким керує застосунок, змінює цю картку на Оновити застосунок Mac + Gateway. Спочатку Sparkle оновлює застосунок; після повторного запуску застосунок виконує openclaw update --tag <app-version> --json, перезапускає свій Gateway і перевіряє його працездатність у вікні перебігу, подібному до налаштування. Вікно з’являється лише тоді, коли цей керований Gateway потребує оновлення, відновлення або встановлення; оновлення лише застосунку після повторного запуску відразу відкривають застосунок. Відомості про помилку залишаються видимими разом із діями Retry, Посібник з оновлення та Discord. Застосунок ніколи не використовує цей скоординований шлях для віддаленого Gateway або Gateway із зовнішнім керуванням, ніколи не понижує версію новішого Gateway і ніколи не перевизначає закріплений канал extended-stable.

Коли оновлення завершується успішно, застосунок ставить у чергу одноразову вітальну подію для останнього прямого сеансу верхнього рівня з реальною взаємодією користувача або каналу. Запуски Cron, Heartbeat і фонові оновлення сеансів не змінюють цей вибір. У віддаленому режимі застосунок оновлює лише середовище виконання локального Node на Mac і надсилає подію лише тоді, коли підключений віддалений Gateway має версію не старішу за версію застосунку.

Після оновлення

openclaw doctor

openclaw gateway restart

openclaw health

Відкочування

Відкочування має два рівні:

1. Повторно встановіть старіший код OpenClaw, зберігши поточний стан.
2. Відновлюйте стан до оновлення лише тоді, коли старіший код не може використовувати перенесену конфігурацію або базу даних.

Почніть із відкочування лише коду. Відновлення стану відкидає зміни, внесені після створення резервної копії.

Перед оновленням: створіть перевірену резервну копію

openclaw update зберігає автоматичну копію конфігурації до оновлення, але не створює повної точки відновлення стану. Перед значним оновленням створіть її явно:

mkdir -p ~/Backups/openclawopenclaw backup create --output ~/Backups/openclaw --verify

Маніфест архіву містить версію OpenClaw і вихідні шляхи, включені до резервної копії. Архів може містити облікові дані, профілі автентифікації та стан каналів, тому зберігайте його з дозволами лише для власника й таким самим захистом, як каталог поточного стану. Перелік включених і навмисно пропущених файлів наведено в розділі Резервне копіювання.

Щоб створити побайтову точку відновлення, яка містить мінливі артефакти, пропущені в переносному архіві, зупиніть Gateway і скористайтеся знімком файлової системи, тому або віртуальної машини, який надає ваша платформа.

Відкотіть установлення пакета

Перегляньте опубліковані версії, потім попередньо перегляньте та встановіть перевірену версію:

npm view openclaw versions --jsonopenclaw update --tag <known-good-version> --dry-runopenclaw update --tag <known-good-version>

openclaw update --tag є кращим варіантом, ніж безпосереднє встановлення через менеджер пакетів. Він виявляє пониження версії, запитує підтвердження, виконує узгодження керованих Plugin і перевірки сумісності зі встановленою цільовою версією, оновлює метадані служби, перезапускає Gateway і перевіряє запущену версію. Якщо збережений канал — extended-stable, використовуйте --channel stable --tag <known-good-version>, оскільки точні одноразові теги не можна поєднувати із селектором extended-stable.

Під час оновлення пакетів кандидат готується та перевіряється перед активацією. Якщо не вдається замінити файли у файловій системі або командну обгортку, OpenClaw автоматично відновлює старий пакет. Після успішної заміни подальша помилка перевірки працездатності Gateway повідомляє попередню версію та надає інструкції з ручного відкочування замість повторної автоматичної заміни пакета.

Якщо шлях оновлення через CLI недоступний, використовуйте той самий менеджер пакетів і ту саму область установлення, яким належить поточний Gateway:

openclaw gateway stopnpm i -g openclaw@<known-good-version>openclaw gateway install --forceopenclaw gateway restart

Замініть npm на pnpm або bun, якщо встановленням керує відповідний менеджер. Під час відновлення після інциденту не допускайте, щоб увімкнений засіб автоматичного оновлення негайно застосував новіший випуск: установіть OPENCLAW_NO_AUTO_UPDATE=1 у середовищі Gateway.

Відкотіть стан робочої копії вихідного коду

Використайте чисту робочу копію та виберіть перевірений тег або коміт:

git fetch --all --tagsgit checkout --detach <known-good-tag-or-commit>pnpm install && pnpm buildopenclaw gateway restart

Щоб повернутися до останньої версії: git checkout main && git pull.

Засіб оновлення автоматично повертає робочу копію git до попередньої гілки та SHA, якщо після початку оновлення git не вдається встановити залежності, виконати збірку, зібрати UI або запустити doctor. Ручне перемикання робочої копії все одно потрібне, якщо ви навмисно вибираєте старіший коміт.

Пониження версії через межу міграції сеансів до SQLite

Перед запуском старішого випуску OpenClaw із файловим сховищем скористайтеся поточним CLI, щоб відновити архівні артефакти застарілих розшифрувань сеансів:

openclaw gateway stopopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

Це не видаляє дані SQLite. Сеанси, створені після міграції до SQLite, існують лише в SQLite і не відображатимуться у старішому середовищі виконання. Див. Пониження версії після міграції сеансів до SQLite.

Відновлюйте стан лише за потреби

Якщо старіший код не може прочитати новішу конфігурацію або схему бази даних, зупиніть Gateway і відновіть перевірений знімок файлової системи, тому або віртуальної машини, створений до оновлення. Перед відновленням окремо збережіть поточний стан, оскільки ця операція видаляє зміни, внесені після створення знімка.

Широкі архіви openclaw backup create підтримують створення та перевірку, але не активацію цілого архіву на місці. Розпакуйте широкий архів у проміжний каталог і використайте його зіставлення джерела з архівом manifest.json для автономного відновлення. openclaw backup sqlite restore так само записує перевірену базу даних до нової цілі; активація цієї цілі залишається явною автономною дією оператора.

Перевірте відкочування

openclaw --versionopenclaw healthopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

Якщо виникли труднощі

• Знову запустіть openclaw doctor і уважно прочитайте вивід.
• Для openclaw update --channel dev у робочих копіях вихідного коду засіб оновлення автоматично готує pnpm, коли це потрібно. Якщо ви бачите помилку підготовки pnpm/corepack, установіть pnpm вручну (або повторно ввімкніть corepack) і знову запустіть оновлення.
• Перегляньте: Усунення несправностей
• Запитайте в Discord: https://discord.gg/clawd

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

• Огляд установлення: усі способи встановлення.
• Doctor: перевірки працездатності після оновлень.
• Міграція: посібники з міграції між основними версіями.