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-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, не используют задержку/джиттер стабильного канала и не применяют частоту опроса бета-канала. Явные обновления на переднем плане, обычные обновления на переднем плане с сохранённым update.channel: "extended-stable", получение состояния по запросу и связанная с ними передача управления управляемому Gateway по-прежнему поддерживаются.

Если установлена локальная служба управляемого Gateway и включён перезапуск, обновления через менеджер пакетов и обновления Git checkout останавливают работающую службу перед заменой дерева пакета или изменением checkout/результатов сборки. Затем средство обновления обновляет метаданные службы, перезапускает её и проверяет перезапущенный Gateway, прежде чем сообщить Gateway: restarted and verified.. При обновлениях через менеджер пакетов дополнительно проверяется, что перезапущенный Gateway сообщает ожидаемую версию пакета; при обновлениях Git checkout после повторной сборки проверяются работоспособность Gateway и готовность службы.

В 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 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 требуется идентификатор модуля 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 checkout

Выбор канала

• stable: извлекает последний тег, не относящийся к бета-версии, затем выполняет сборку и doctor.
• beta: отдаёт предпочтение последнему тегу -beta, возвращаясь к последнему стабильному тегу, если бета-версия отсутствует или устарела.
• dev: извлекает main, затем получает изменения и выполняет rebase.
• extended-stable: не поддерживается для Git checkout; checkout не изменяется.

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

Подробности синхронизации плагинов

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

После успешного обновления ядра extended-stable проверка целостности и согласование плагинов после обновления ядра нацеливаются на подходящие официальные плагины npm с точной версией установленного ядра. Для намерения default/latest OpenClaw не запрашивает @extended-stable плагина и не возвращается к npm latest; версия пакета определяется по установленному ядру. Явно закреплённые версии, явно заданные теги, отличные от latest, сторонние пакеты и источники, отличные от npm, сохраняют существующее намерение.

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

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

• openclaw doctor (предлагает сначала запустить обновление для Git checkout)
• Каналы разработки
• Обновление
• Справочник CLI