> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Обновить

# `openclaw update`

Безопасно обновляйте OpenClaw и переключайтесь между каналами stable/beta/dev.

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

## Использование

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw update
openclaw update status
openclaw update repair
openclaw update wizard
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
```

## Параметры

* `--no-restart`: пропустить перезапуск службы Gateway после успешного обновления. Обновления через менеджер пакетов, которые перезапускают Gateway, перед успешным завершением команды проверяют, что перезапущенная служба сообщает ожидаемую обновленную версию.
* `--channel <stable|beta|dev>`: задать канал обновлений (git + npm; сохраняется в конфигурации).
* `--tag <dist-tag|version|spec>`: переопределить целевой пакет только для этого обновления. Для пакетных установок `main` сопоставляется с `github:openclaw/openclaw#main`; спецификации источников GitHub/git упаковываются во временный tarball перед промежуточной глобальной установкой npm.
* `--dry-run`: предварительно показать запланированные действия обновления (канал/тег/цель/поток перезапуска) без записи конфигурации, установки, синхронизации plugins или перезапуска.
* `--json`: вывести машиночитаемый JSON `UpdateRunResult`, включая
  `postUpdate.plugins.warnings`, когда поврежденные или незагружаемые управляемые plugins требуют
  исправления после успешного обновления ядра, сведения о резервном варианте plugins beta-канала,
  когда у Plugin нет beta-релиза, и `postUpdate.plugins.integrityDrifts`,
  когда при синхронизации Plugin после обновления обнаружено расхождение артефактов npm Plugin.
* `--timeout <seconds>`: тайм-аут для каждого шага (по умолчанию 1800 с).
* `--yes`: пропустить запросы подтверждения (например, подтверждение отката на более раннюю версию).
* `--acknowledge-clawhub-risk`: после просмотра предупреждений о доверии к сообществу ClawHub
  разрешить синхронизации Plugin после обновления продолжиться без интерактивного
  запроса. Без этого рискованные релизы Plugin сообщества ClawHub пропускаются и
  остаются без изменений, когда OpenClaw не может запросить подтверждение. Официальные пакеты ClawHub и
  встроенные источники Plugin OpenClaw обходят этот запрос доверия к релизу.

У `openclaw update` нет флага `--verbose`. Используйте `--dry-run`, чтобы предварительно просмотреть
запланированные действия канала/тега/установки/перезапуска, `--json` для машиночитаемых
результатов и `openclaw update status --json`, когда вам нужны только сведения о канале и
доступности. Если вы отлаживаете журналы Gateway вокруг обновления,
подробность вывода в консоль и уровень файлового журнала настраиваются отдельно: Gateway `--verbose` влияет на
вывод терминала/WebSocket, а файловые журналы требуют `logging.level: "debug"` или
`"trace"` в конфигурации. См. [Журналирование Gateway](/ru/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>
  Откаты на более ранние версии требуют подтверждения, потому что старые версии могут нарушить конфигурацию.
</Warning>

## `update status`

Показать активный канал обновлений + тег/ветку/SHA git (для исходных checkout), а также доступность обновлений.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```

Параметры:

* `--json`: вывести машиночитаемый JSON статуса.
* `--timeout <seconds>`: тайм-аут для проверок (по умолчанию 3 с).

## `update repair`

Повторно запустить финализацию обновления после того, как основной пакет уже изменился, но последующие
работы по исправлению не завершились корректно. Это поддерживаемый путь восстановления, когда
`openclaw update` установил новый основной пакет, но синхронизация plugins после ядра,
метаданные управляемых npm plugins, обновление реестра или исправление doctor все еще должны
сойтись.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw update repair
openclaw update repair --channel beta
openclaw update repair --acknowledge-clawhub-risk
openclaw update repair --json
```

Параметры:

* `--channel <stable|beta|dev>`: сохранить канал обновлений перед исправлением и
  выполнить сведение Plugin для этого канала.
* `--json`: вывести машиночитаемый JSON финализации.
* `--timeout <seconds>`: тайм-аут для шагов исправления (по умолчанию `1800`).
* `--yes`: пропустить запросы подтверждения.
* `--acknowledge-clawhub-risk`: после просмотра предупреждений о доверии к сообществу ClawHub
  разрешить сведению Plugin во время исправления продолжиться без
  интерактивного запроса. Официальные пакеты ClawHub и встроенные источники Plugin
  OpenClaw обходят этот запрос доверия к релизу.
* `--no-restart`: принимается для согласованности с командой update; repair никогда не перезапускает
  Gateway.

`openclaw update repair` запускает `openclaw doctor --fix`, перезагружает исправленные
конфигурацию и записи установок, синхронизирует отслеживаемые plugins для активного канала обновлений,
обновляет установки управляемых npm plugins, исправляет отсутствующие настроенные полезные нагрузки Plugin,
обновляет реестр Plugin и записывает сведенные метаданные записей установок.
Она не устанавливает новый основной пакет и не перезапускает Gateway.

## `update wizard`

Интерактивный поток для выбора канала обновлений и подтверждения, нужно ли перезапустить Gateway
после обновления (по умолчанию выполняется перезапуск). Если выбрать `dev` без git checkout, он
предложит создать его.

Параметры:

* `--timeout <seconds>`: тайм-аут для каждого шага обновления (по умолчанию `1800`)

## Что делает

Когда вы явно переключаете каналы (`--channel ...`), OpenClaw также поддерживает
согласованность способа установки:

* `dev` → гарантирует наличие git checkout (по умолчанию: `~/openclaw` или `$OPENCLAW_HOME/openclaw`, когда
  задан `OPENCLAW_HOME`; переопределяется через `OPENCLAW_GIT_DIR`),
  обновляет его и устанавливает глобальный CLI из этого checkout.
* `stable` → устанавливает из npm с использованием `latest`.
* `beta` → предпочитает npm dist-tag `beta`, но откатывается к `latest`, когда beta
  отсутствует или старше текущего stable-релиза.

Автообновитель ядра Gateway (когда включен через конфигурацию) запускает путь обновления CLI
вне активного обработчика запросов Gateway. Обновления через менеджер пакетов `update.run`
плоскости управления и контролируемые обновления git checkout также используют
передачу управляемой службе вместо замены дерева пакета или пересборки
`dist/` внутри активного процесса Gateway. Gateway запускает отсоединенный вспомогательный процесс,
завершается, а вспомогательный процесс выполняет обычный путь CLI `openclaw update --yes --json`
за пределами дерева процессов Gateway. Если такая передача недоступна,
`update.run` возвращает структурированный ответ с безопасной shell-командой для ручного запуска.

Для установок через менеджер пакетов `openclaw update` определяет целевую версию пакета
до вызова менеджера пакетов. Глобальные установки npm используют промежуточную
установку: OpenClaw устанавливает новый пакет во временный префикс npm, проверяет
там инвентарь упакованного `dist`, затем заменяет этим чистым деревом пакета
реальный глобальный префикс. Если проверка не проходит, post-update doctor, синхронизация Plugin и
перезапуск не выполняются из подозрительного дерева. Даже когда установленная версия
уже совпадает с целевой, команда обновляет глобальную установку пакета,
затем выполняет синхронизацию Plugin, обновление завершений основных команд и перезапуск. Это
поддерживает согласованность упакованных sidecar-компонентов и принадлежащих каналу записей Plugin с
установленной сборкой OpenClaw, оставляя полные пересборки завершений команд Plugin для
явных запусков `openclaw completion --write-state`.

Когда установлена локальная управляемая служба Gateway и перезапуск включен,
обновления через менеджер пакетов и git checkout останавливают запущенную службу перед
заменой дерева пакета или изменением checkout/выходных данных сборки. Затем updater
обновляет метаданные службы из обновленной установки, перезапускает
службу и проверяет перезапущенный Gateway перед сообщением
`Gateway: restarted and verified.`. Обновления через менеджер пакетов дополнительно проверяют,
что перезапущенный Gateway сообщает ожидаемую версию пакета; обновления git checkout
проверяют работоспособность Gateway и готовность службы после пересборки. На macOS
проверка после обновления также проверяет, что LaunchAgent загружен/запущен для активного
профиля и настроенный порт loopback работоспособен. Если plist установлен,
но launchd не supervises его, OpenClaw автоматически повторно bootstrap-ит LaunchAgent,
затем повторно запускает проверки работоспособности/версии/готовности канала. Свежий
bootstrap загружает задание RunAtLoad напрямую, поэтому восстановление обновления не
выполняет немедленно `kickstart -k` для только что запущенного Gateway. Если Gateway все еще
не становится работоспособным, команда завершается с ненулевым кодом и печатает путь к журналу перезапуска
плюс явные инструкции по перезапуску, переустановке и откату пакета. Если перезапуск
не может выполниться, команда печатает `Gateway: restart skipped (...)` или
`Gateway: restart failed: ...` с подсказкой ручного `openclaw gateway restart`.
С `--no-restart` замена пакета или пересборка git все равно выполняется, но
управляемая служба не останавливается и не перезапускается, поэтому запущенный Gateway может сохранять старый
код, пока вы не перезапустите его вручную.

### Форма ответа плоскости управления

Когда `update.run` вызывается через плоскость управления Gateway в
установке через менеджер пакетов или контролируемом git checkout, обработчик сообщает
о запуске передачи отдельно от обновления 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 требует идентичность unit OpenClaw
  (`OPENCLAW_SYSTEMD_UNIT`), а не только окружающие маркеры процесса systemd. Ответ
  включает `handoff.command`, shell-команду для запуска вне
  Gateway.
* `ok: false`, `result.reason: "managed-service-handoff-failed"` означает, что
  Gateway попытался создать передачу, но не смог запустить отсоединенный вспомогательный процесс.

Полезная нагрузка `sentinel` все еще записывается до завершения Gateway, а передача CLI
обновляет тот же sentinel перезапуска после завершения проверок работоспособности
перезапуска управляемой службы. Во время передачи sentinel может содержать
`stats.reason: "restart-health-pending"` без продолжения успеха; перезапущенный
Gateway продолжает опрашивать его и запускает продолжение только после того, как CLI
проверит работоспособность службы и перезапишет sentinel с итоговым результатом `ok`.
`openclaw status` и `openclaw status --all` показывают строку `Update restart`,
пока этот sentinel ожидает или завершился ошибкой, а `update.status` обновляет и
возвращает последний sentinel.

## Поток git checkout

### Выбор канала

* `stable`: checkout последнего не-beta тега, затем сборка и doctor.
* `beta`: предпочитает последний тег `-beta`, но откатывается к последнему stable-тегу, когда beta отсутствует или старше.
* `dev`: checkout `main`, затем fetch и rebase.

### Шаги обновления

<Steps>
  <Step title="Проверить чистое рабочее дерево">
    Требует отсутствия незафиксированных изменений.
  </Step>

  <Step title="Переключить канал">
    Переключает на выбранный канал (тег или ветку).
  </Step>

  <Step title="Получить upstream">
    Только для разработки.
  </Step>

  <Step title="Предварительная сборка (только для разработки)">
    Запускает сборку TypeScript во временном рабочем дереве. Если tip не проходит сборку, откатывается назад до 10 коммитов, чтобы найти самый новый собираемый коммит. Установите `OPENCLAW_UPDATE_PREFLIGHT_LINT=1`, чтобы также запускать lint во время этой предварительной проверки; lint выполняется в ограниченном последовательном режиме, потому что хосты пользовательских обновлений часто меньше CI-раннеров.
  </Step>

  <Step title="Выполнить rebase">
    Выполняет rebase на выбранный коммит (только для разработки).
  </Step>

  <Step title="Установить зависимости">
    Использует пакетный менеджер репозитория. Для checkout на pnpm обновлятор загружает `pnpm` по требованию (сначала через `corepack`, затем с временным fallback `npm install pnpm@11`) вместо запуска `npm run build` внутри рабочего пространства pnpm.
  </Step>

  <Step title="Собрать Control UI">
    Собирает Gateway и Control UI.
  </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 также выполняет fallback, когда beta-пакет существует, но не проходит
проверку установки. Эти предупреждения fallback для плагинов не приводят
к сбою обновления ядра. Точные версии и явные теги не переписываются.

<Warning>
  Если обновление npm-плагина с точной закрепленной версией разрешается в артефакт, целостность которого отличается от сохраненной записи установки, `openclaw update` прерывает обновление этого артефакта плагина вместо его установки. Переустанавливайте или обновляйте плагин явно только после проверки, что вы доверяете новому артефакту.
</Warning>

<Note>
  Сбои синхронизации плагинов после обновления, которые ограничены управляемым плагином и которые путь синхронизации может обойти (например, недоступный npm registry для несущественного плагина), сообщаются как предупреждения после успешного обновления ядра. JSON-результат сохраняет верхнеуровневый `status: "ok"` и сообщает `postUpdate.plugins.status: "warning"` с рекомендациями `openclaw update repair` и `openclaw plugins inspect <id> --runtime --json`. Неожиданные исключения обновлятора или синхронизации по-прежнему приводят к сбою результата обновления. Исправьте ошибку установки или обновления плагина, затем повторно запустите `openclaw update repair`.

  После шага синхронизации для каждого плагина `openclaw update` запускает обязательный проход **post-core convergence** перед перезапуском Gateway: он восстанавливает отсутствующие настроенные payload плагинов, проверяет каждую *активную* отслеживаемую запись установки на диске и статически проверяет, что ее `package.json` можно разобрать (и что любой явно объявленный `main` существует). Сбои этого прохода — и недопустимый снимок конфигурации OpenClaw — возвращают `postUpdate.plugins.status: "error"` и переключают верхнеуровневый `status` обновления в `"error"`, поэтому `openclaw update` завершается с ненулевым кодом, а Gateway *не* перезапускается с непроверенным набором плагинов. Ошибка включает структурированные строки `postUpdate.plugins.warnings[].guidance`, указывающие на `openclaw update repair` и `openclaw plugins inspect <id> --runtime --json` для последующих действий. Отключенные записи плагинов и записи, которые не являются связанными с доверенным источником официальными целями синхронизации, здесь пропускаются, повторяя политику `skipDisabledPlugins`, используемую проверкой отсутствующих payload, поэтому устаревшая запись отключенного плагина не может заблокировать в остальном корректное обновление.

  Когда обновленный Gateway запускается, загрузка плагинов выполняется только в режиме проверки: startup не
  запускает пакетные менеджеры и не изменяет деревья зависимостей. Перезапуски package-manager `update.run`
  передаются пути managed-service в CLI, поэтому замена пакета происходит
  вне старого процесса Gateway, а проверки работоспособности сервиса решают, можно ли
  сообщить об успешном завершении обновления.

  Если bootstrap pnpm все равно завершается сбоем, обновлятор останавливается заранее с ошибкой, специфичной для пакетного менеджера, вместо попытки выполнить `npm run build` внутри checkout.
</Note>

## Сокращение `--update`

`openclaw --update` переписывается в `openclaw update` (полезно для shell и launcher-скриптов).

## Связанные материалы

* `openclaw doctor` (предлагает сначала запустить обновление в git checkout)
* [Каналы разработки](/ru/install/development-channels)
* [Обновление](/ru/install/updating)
* [Справочник CLI](/ru/cli)