openclaw update
Безопасно обновляйте OpenClaw и переключайтесь между каналами stable/beta/dev.
Если вы установили через npm/pnpm/bun (глобальная установка, без метаданных git),
обновления выполняются через поток менеджера пакетов, описанный в разделе Обновление.
Использование
Параметры
--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: вывести машиночитаемый JSONUpdateRunResult, включая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.
В режиме Nix (
OPENCLAW_NIX_MODE=1) изменяющие запуски openclaw update отключены. Вместо этого обновите источник Nix или вход flake для этой установки; для nix-openclaw используйте ориентированный на агента Краткий старт. openclaw update status и openclaw update --dry-run остаются доступными только для чтения.update status
Показать активный канал обновлений + тег/ветку/SHA git (для исходных checkout), а также доступность обновлений.
--json: вывести машиночитаемый JSON статуса.--timeout <seconds>: тайм-аут для проверок (по умолчанию 3 с).
update repair
Повторно запустить финализацию обновления после того, как основной пакет уже изменился, но последующие
работы по исправлению не завершились корректно. Это поддерживаемый путь восстановления, когда
openclaw update установил новый основной пакет, но синхронизация plugins после ядра,
метаданные управляемых npm plugins, обновление реестра или исправление doctor все еще должны
сойтись.
--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-tagbeta, но откатывается кlatest, когда beta отсутствует или старше текущего stable-релиза.
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: checkoutmain, затем fetch и rebase.
Шаги обновления
Предварительная сборка (только для разработки)
Запускает сборку TypeScript во временном рабочем дереве. Если tip не проходит сборку, откатывается назад до 10 коммитов, чтобы найти самый новый собираемый коммит. Установите
OPENCLAW_UPDATE_PREFLIGHT_LINT=1, чтобы также запускать lint во время этой предварительной проверки; lint выполняется в ограниченном последовательном режиме, потому что хосты пользовательских обновлений часто меньше CI-раннеров.Установить зависимости
Использует пакетный менеджер репозитория. Для checkout на pnpm обновлятор загружает
pnpm по требованию (сначала через corepack, затем с временным fallback npm install pnpm@11) вместо запуска npm run build внутри рабочего пространства pnpm.@beta.
Если у плагина нет beta-выпуска, OpenClaw возвращается к записанной
спецификации default/latest и сообщает об этом как о предупреждении. Для npm-плагинов
OpenClaw также выполняет fallback, когда beta-пакет существует, но не проходит
проверку установки. Эти предупреждения fallback для плагинов не приводят
к сбою обновления ядра. Точные версии и явные теги не переписываются.
Сбои синхронизации плагинов после обновления, которые ограничены управляемым плагином и которые путь синхронизации может обойти (например, недоступный 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.Сокращение --update
openclaw --update переписывается в openclaw update (полезно для shell и launcher-скриптов).
Связанные материалы
openclaw doctor(предлагает сначала запустить обновление в git checkout)- Каналы разработки
- Обновление
- Справочник CLI