--- read_when: - Вы хотите безопасно обновить локальную копию исходного кода - Вы отлаживаете вывод или параметры `openclaw update` - Вам нужно понимать поведение сокращённой записи `--update` summary: Справочник CLI для `openclaw update` (относительно безопасное обновление исходного кода + автоматический перезапуск Gateway) title: Обновить x-i18n: generated_at: "2026-07-16T16:15:44Z" 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), обновление выполняется через процесс пакетного менеджера, описанный в разделе [Обновление](/ru/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 ` | Задать канал обновлений и сохранить его после успешного обновления ядра. Extended-stable доступен только для пакетных установок. | | `--tag ` | Переопределить целевой пакет только для этого обновления. Этот параметр нельзя сочетать с действующим каналом `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 ` | Время ожидания для каждого шага. По умолчанию — `1800`. | | `--yes` | Пропустить запросы подтверждения (например, подтверждение перехода на более раннюю версию). | | `--acknowledge-clawhub-risk` | Разрешить синхронизации плагинов после обновления продолжаться при предупреждениях о доверии к сообществу ClawHub без интерактивного запроса. Без этого параметра рискованные выпуски сообщества пропускаются и остаются без изменений, если OpenClaw не может запросить подтверждение. Официальные пакеты ClawHub и источники встроенных плагинов обходят этот запрос. | Флага `--verbose` нет. Для предварительного просмотра запланированных действий используйте `--dry-run`, для машиночитаемых результатов — `--json`, а для получения только сведений о канале и доступности — `openclaw update status --json`. Подробность вывода Gateway в консоль (`--verbose`) и уровень журналирования в файл (`logging.level: "debug"`/`"trace"`) настраиваются независимо; см. [Журналирование Gateway](/ru/gateway/logging). В режиме 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` остаются доступными только для чтения. Переход на более раннюю версию требует подтверждения, поскольку старые версии могут нарушить работу конфигурации. Если установка уже перенесла сеансы в SQLite, восстановите архивные устаревшие артефакты транскриптов перед запуском старой версии с файловым хранилищем. См. [Doctor: переход на более раннюю версию после миграции сеансов в SQLite](/ru/cli/doctor#downgrading-after-session-sqlite-migration). ## `update status` Показать активный канал обновлений, тег/ветку/SHA git (только для рабочих копий исходного кода) и доступность обновлений. ```bash openclaw update status openclaw update status --json openclaw update status --timeout 10 ``` | Флаг | По умолчанию | Описание | | --------------------- | ------- | ----------------------------------- | | `--json` | `false` | Вывести машиночитаемый JSON состояния. | | `--timeout ` | `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 ` | Сохранить канал обновлений ядра перед восстановлением. Для extended-stable подходящие официальные npm-плагины, следующие пустому/стандартному намерению или намерению `latest`, нацеливаются на точную установленную версию ядра. Восстановление extended-stable отклоняется в рабочих копиях Git без изменения конфигурации. | | `--json` | Вывести машиночитаемый JSON завершения. | | `--timeout ` | Время ожидания шагов восстановления. По умолчанию — `1800`. | | `--yes` | Пропустить запросы подтверждения. | | `--acknowledge-clawhub-risk` | Такое же поведение, как у `openclaw update`. | | `--no-restart` | Принимается для единообразия; восстановление никогда не перезапускает Gateway. | `update repair` запускает `openclaw doctor --fix`, повторно загружает восстановленную конфигурацию и записи об установке, синхронизирует отслеживаемые плагины для активного канала обновлений, обновляет установки управляемых npm-плагинов, восстанавливает отсутствующие данные настроенных плагинов, обновляет реестр плагинов и записывает метаданные согласованных записей об установке. Он не устанавливает новый основной пакет и не перезапускает Gateway. ## `update wizard` Интерактивный процесс выбора канала обновлений и подтверждения необходимости последующего перезапуска Gateway (по умолчанию перезапуск выполняется). При выборе `dev` без рабочей копии git предлагается создать её. | Флаг | По умолчанию | Описание | | --------------------- | ------- | ----------------------------- | | `--timeout ` | `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-тегу 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, не используют задержку/джиттер стабильного канала и не используют частоту опроса бета-канала. По-прежнему поддерживаются явные обновления в интерактивном режиме, обновления в интерактивном режиме без аргументов с сохранённым `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`: перейти на последний тег, не относящийся к бета-версии, затем выполнить сборку и doctor. - `beta`: предпочитать последний тег `-beta`, а если бета-версия отсутствует или старее — использовать последний стабильный тег. - `dev`: перейти на `main`, затем получить изменения и выполнить rebase. - `extended-stable`: не поддерживается для рабочих копий Git; рабочая копия не изменяется. ### Этапы обновления Требуется отсутствие незакоммиченных изменений. Переключает на выбранный канал (тег или ветвь). Только для dev. Запускает сборку TypeScript во временном рабочем дереве. Если вершина не проходит сборку, перебирает до 10 предыдущих коммитов, чтобы найти самый новый коммит, который можно собрать. Задайте `OPENCLAW_UPDATE_PREFLIGHT_LINT=1`, чтобы при этой предварительной проверке также запускался линтер; линтер работает в ограниченном последовательном режиме, поскольку пользовательские хосты обновления часто имеют меньше ресурсов, чем исполнители CI. Выполняет rebase на выбранный коммит (только для dev). Использует менеджер пакетов репозитория. Для рабочих копий pnpm средство обновления при необходимости загружает `pnpm` (сначала через `corepack`, затем через временный резервный вариант `npm install pnpm@11`) вместо запуска `npm run build` внутри рабочего пространства pnpm. Если загрузка pnpm всё равно завершается ошибкой, средство обновления останавливается на раннем этапе с ошибкой, относящейся к менеджеру пакетов, вместо попытки выполнить `npm run build` в рабочей копии. Собирает Gateway и интерфейс управления. `openclaw doctor` выполняется как заключительная проверка безопасного обновления. Синхронизирует плагины с активным каналом. Dev использует встроенные плагины; stable и beta используют npm. Обновляет отслеживаемые установки плагинов. ### Сведения о синхронизации плагинов На бета-канале отслеживаемые установки плагинов npm и ClawHub, использующие линию default/latest, сначала пытаются получить выпуск плагина `@beta`. Если у плагина нет бета-выпуска, OpenClaw возвращается к записанной спецификации default/latest и выводит предупреждение. Для плагинов npm OpenClaw также использует резервный вариант, если бета-пакет существует, но не проходит проверку установки. Эти предупреждения о переходе на резервный вариант не приводят к ошибке основного обновления. Точные версии и явно заданные теги никогда не перезаписываются. Если обновление плагина npm с точно закреплённой версией разрешается в артефакт, целостность которого отличается от сохранённой записи установки, `openclaw update` прерывает обновление этого артефакта плагина, не устанавливая его. Переустанавливайте или обновляйте плагин явно только после проверки того, что вы доверяете новому артефакту. Ошибки синхронизации плагинов после обновления, которые относятся к управляемому плагину и которые процесс синхронизации может обойти (например, недоступный реестр npm для необязательного плагина), выводятся как предупреждения после успешного завершения основного обновления. В результате JSON сохраняется верхнеуровневое значение обновления `status: "ok"`, а также выводится `postUpdate.plugins.status: "warning"` с рекомендациями `openclaw update repair` и `openclaw plugins inspect --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 --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`. ## См. также - `openclaw doctor` (предлагает сначала выполнить обновление в рабочих копиях Git) - [Каналы разработки](/ru/install/development-channels) - [Обновление](/ru/install/updating) - [Справочник CLI](/ru/cli)