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-тегу 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; рабочая копия не изменяется.

Этапы обновления

Сведения о синхронизации плагинов

На бета-канале отслеживаемые установки плагинов npm и ClawHub, использующие линию default/latest, сначала пытаются получить выпуск плагина @beta. Если у плагина нет бета-выпуска, OpenClaw возвращается к записанной спецификации default/latest и выводит предупреждение. Для плагинов npm OpenClaw также использует резервный вариант, если бета-пакет существует, но не проходит проверку установки. Эти предупреждения о переходе на резервный вариант не приводят к ошибке основного обновления. Точные версии и явно заданные теги никогда не перезаписываются.

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