---
read_when:
    - Потрібно безпечно оновити локальну копію вихідного коду
    - Ви налагоджуєте виведення або параметри `openclaw update`
    - Вам потрібно розуміти скорочену поведінку `--update`
summary: Довідник CLI для `openclaw update` (відносно безпечне оновлення вихідного коду + автоматичний перезапуск Gateway)
title: Оновити
x-i18n:
    generated_at: "2026-07-16T17:40:32Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: b46696f6b9cba5c318f870bcb6c5ea8e0652940968da2ad85e86709fe4c11146
    source_path: cli/update.md
    workflow: 16
---

# `openclaw update`

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

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

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

```bash
openclaw update
openclaw update status
openclaw update repair
openclaw update wizard
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --acknowledge-clawhub-risk
openclaw update --json
openclaw --update
```

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

## Параметри

| Прапорець                                             | Опис                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-restart`                                   | Не перезапускати службу Gateway після успішного оновлення. Під час оновлень через менеджер пакетів із перезапуском команда завершується успішно лише після перевірки, що перезапущена служба повідомляє очікувану версію.                                                                                                                                                |
| `--channel <stable\|extended-stable\|beta\|dev>` | Задати канал оновлень і зберегти його після успішного оновлення ядра. Extended-stable доступний лише для пакетного встановлення.                                                                                                                                                                                                                                            |
| `--tag <dist-tag\|version\|spec>`                | Перевизначити цільовий пакет лише для цього оновлення. Не можна поєднувати з чинним каналом `extended-stable`, для якого обов’язковою є перевірена точна ціль. Для інших пакетних встановлень `main` зіставляється з `github:openclaw/openclaw#main`; специфікації джерел GitHub/git пакуються в тимчасовий tar-архів перед поетапним глобальним встановленням через npm. |
| `--dry-run`                                      | Переглянути заплановані дії (канал/тег/ціль/процедуру перезапуску) без запису конфігурації, встановлення, синхронізації плагінів або перезапуску.                                                                                                                                                                                                                |
| `--json`                                         | Вивести машинозчитуваний JSON `UpdateRunResult`. Містить `postUpdate.plugins.warnings`, коли керований плагін потребує відновлення, відомості про резервний вибір плагіна для beta-каналу та `postUpdate.plugins.integrityDrifts`, коли під час синхронізації після оновлення виявлено розбіжність артефактів плагіна npm.                                                                 |
| `--timeout <seconds>`                            | Час очікування для кожного кроку. Типове значення — `1800`.                                                                                                                                                                                                                                                                                                            |
| `--yes`                                          | Пропустити запити на підтвердження (наприклад, підтвердження повернення до попередньої версії).                                                                                                                                                                                                                                                                              |
| `--acknowledge-clawhub-risk`                     | Дозволити синхронізації плагінів після оновлення продовжуватися попри попередження щодо довіри до спільнотних пакетів ClawHub без інтерактивного запиту. Без цього ризиковані спільнотні випуски пропускаються й залишаються без змін, якщо OpenClaw не може показати запит. Офіційні пакети ClawHub і вбудовані джерела плагінів не потребують цього підтвердження.                                                     |

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

<Note>
У режимі Nix (`OPENCLAW_NIX_MODE=1`) виконання `openclaw update`, що вносять зміни, вимкнено. Натомість оновіть джерело Nix або вхідні дані flake для цього встановлення; для nix-openclaw скористайтеся орієнтованим насамперед на агента [швидким початком](https://github.com/openclaw/nix-openclaw#quick-start). `openclaw update status` і `openclaw update --dry-run` залишаються доступними лише для читання.
</Note>

<Warning>
Повернення до попередніх версій потребує підтвердження, оскільки старіші версії можуть порушити конфігурацію.
Якщо встановлення вже перенесло сеанси до SQLite, відновіть архівні артефакти застарілих
транскриптів перед запуском старішої версії з файловим сховищем. Див.
[Doctor: повернення до попередньої версії після міграції сеансів до SQLite](/uk/cli/doctor#downgrading-after-session-sqlite-migration).
</Warning>

## `update status`

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

```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```

| Прапорець                  | Типове значення | Опис                         |
| --------------------- | ------- | ----------------------------------- |
| `--json`              | `false` | Вивести машинозчитуваний JSON стану. |
| `--timeout <seconds>` | `3`     | Час очікування для перевірок.                 |

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

```bash
openclaw update repair
openclaw update repair --channel beta
openclaw update repair --acknowledge-clawhub-risk
openclaw update repair --json
```

| Прапорець                                             | Опис                                                                                                                                                                                                                                                         |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--channel <stable\|extended-stable\|beta\|dev>` | Зберегти канал оновлення ядра перед відновленням. Для extended-stable придатні офіційні плагіни npm, що дотримуються порожнього/типового наміру або наміру `latest`, орієнтуються на точну встановлену версію ядра. Відновлення extended-stable відхиляється в робочих копіях Git без зміни конфігурації. |
| `--json`                                         | Вивести машинозчитуваний JSON завершальних дій.                                                                                                                                                                                                                           |
| `--timeout <seconds>`                            | Час очікування для кроків відновлення. Типове значення — `1800`.                                                                                                                                                                                                                           |
| `--yes`                                          | Пропустити запити на підтвердження.                                                                                                                                                                                                                                          |
| `--acknowledge-clawhub-risk`                     | Така сама поведінка, як у `openclaw update`.                                                                                                                                                                                                                              |
| `--no-restart`                                   | Приймається для узгодженості; відновлення ніколи не перезапускає Gateway.                                                                                                                                                                                                             |

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

## `update wizard`

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

| Прапорець                  | Типове значення | Опис                   |
| --------------------- | ------- | ----------------------------- |
| `--timeout <seconds>` | `1800`  | Час очікування для кожного кроку оновлення. |

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

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

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

<Steps>
  <Step title="Перевірка чистоти робочого дерева">
    Вимагає відсутності незбережених у комітах змін.
  </Step>
  <Step title="Перемикання каналу">
    Перемикає на вибраний канал (тег або гілку).
  </Step>
  <Step title="Отримання змін із джерела">
    Лише для dev.
  </Step>
  <Step title="Попередня збірка (лише для dev)">
    Запускає збірку TypeScript у тимчасовому робочому дереві. Якщо верхівка гілки не проходить збірку, повертається до 10 комітів назад, щоб знайти найновіший коміт, який можна зібрати. Установіть `OPENCLAW_UPDATE_PREFLIGHT_LINT=1`, щоб також запускати lint під час цієї попередньої перевірки; lint виконується в обмеженому послідовному режимі, оскільки хости користувацьких оновлень часто мають менше ресурсів, ніж виконавці CI.
  </Step>
  <Step title="Rebase">
    Виконує rebase на вибраний коміт (лише для dev).
  </Step>
  <Step title="Установлення залежностей">
    Використовує менеджер пакетів репозиторію. Для робочих копій pnpm засіб оновлення за потреби ініціалізує `pnpm` (спочатку через `corepack`, а потім із тимчасовим резервним варіантом `npm install pnpm@11`) замість запуску `npm run build` у робочому просторі pnpm. Якщо ініціалізація pnpm усе одно завершується помилкою, засіб оновлення зупиняється завчасно з помилкою, специфічною для менеджера пакетів, замість спроби виконати `npm run build` у робочій копії.
  </Step>
  <Step title="Збірка інтерфейсу керування">
    Збирає Gateway та інтерфейс керування.
  </Step>
  <Step title="Запуск doctor">
    `openclaw doctor` виконується як остаточна перевірка безпечного оновлення.
  </Step>
  <Step title="Синхронізація плагінів">
    Синхронізує плагіни з активним каналом. Dev використовує вбудовані плагіни; stable і beta використовують npm. Оновлює відстежувані інсталяції плагінів.
  </Step>
</Steps>

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

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

<Warning>
Якщо оновлення плагіна npm із точно зафіксованою версією визначає артефакт, цілісність якого відрізняється від збереженого запису встановлення, `openclaw update` скасовує оновлення цього артефакту плагіна замість його встановлення. Перевстановлюйте або явно оновлюйте плагін лише після перевірки надійності нового артефакту.
</Warning>

<Note>
Помилки синхронізації плагінів після оновлення, які стосуються керованого плагіна та які шлях синхронізації може обійти (наприклад, недоступний реєстр 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, а перевірки справності служби визначають, чи можна повідомити про завершення оновлення.
</Note>

Після успішного оновлення ядра 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-робочих копій)
- [Канали розробки](/uk/install/development-channels)
- [Оновлення](/uk/install/updating)
- [Довідник CLI](/uk/cli)
