Skip to main content

​
openclaw update

Обновление OpenClaw и переключение между каналами stable/extended-stable/beta/dev. Если установка выполнена через npm/pnpm/bun (глобальная установка без метаданных git), обновление выполняется через процесс пакетного менеджера, описанный в разделе Обновление.

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

openclaw --update преобразуется в openclaw update (это удобно для оболочек и скриптов запуска).

​
Параметры

Флага --verbose нет. Для предварительного просмотра запланированных действий используйте --dry-run, для машиночитаемых результатов — --json, а для получения только сведений о канале и доступности — openclaw update status --json. Подробность вывода Gateway в консоль (--verbose) и уровень журналирования в файл (logging.level: "debug"/"trace") настраиваются независимо; см. Журналирование Gateway.
В режиме Nix (OPENCLAW_NIX_MODE=1) изменяющие состояние запуски openclaw update отключены. Вместо этого обновите источник Nix или входные данные flake для этой установки; для nix-openclaw используйте ориентированное на агента краткое руководство. openclaw update status и openclaw update --dry-run остаются доступными только для чтения.
Переход на более раннюю версию требует подтверждения, поскольку старые версии могут нарушить работу конфигурации. Если установка уже перенесла сеансы в SQLite, восстановите архивные устаревшие артефакты транскриптов перед запуском старой версии с файловым хранилищем. См. Doctor: переход на более раннюю версию после миграции сеансов в SQLite.

​
update status

Показать активный канал обновлений, тег/ветку/SHA git (только для рабочих копий исходного кода) и доступность обновлений.
Для пакетных установок 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 не сошлись к согласованному состоянию.
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; рабочая копия не изменяется.

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

1

Проверить чистоту рабочего дерева

Требуется отсутствие незакоммиченных изменений.
2

Переключить канал

Переключает на выбранный канал (тег или ветвь).
3

Получить изменения из вышестоящего репозитория

Только для dev.
4

Предварительная сборка (только для dev)

Запускает сборку TypeScript во временном рабочем дереве. Если вершина не проходит сборку, перебирает до 10 предыдущих коммитов, чтобы найти самый новый коммит, который можно собрать. Задайте OPENCLAW_UPDATE_PREFLIGHT_LINT=1, чтобы при этой предварительной проверке также запускался линтер; линтер работает в ограниченном последовательном режиме, поскольку пользовательские хосты обновления часто имеют меньше ресурсов, чем исполнители CI.
5

Выполнить rebase

Выполняет rebase на выбранный коммит (только для dev).
6

Установить зависимости

Использует менеджер пакетов репозитория. Для рабочих копий pnpm средство обновления при необходимости загружает pnpm (сначала через corepack, затем через временный резервный вариант npm install pnpm@11) вместо запуска npm run build внутри рабочего пространства pnpm. Если загрузка pnpm всё равно завершается ошибкой, средство обновления останавливается на раннем этапе с ошибкой, относящейся к менеджеру пакетов, вместо попытки выполнить npm run build в рабочей копии.
7

Собрать интерфейс управления

Собирает Gateway и интерфейс управления.
8

Запустить doctor

openclaw doctor выполняется как заключительная проверка безопасного обновления.
9

Синхронизировать плагины

Синхронизирует плагины с активным каналом. 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 <id> --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 <id> --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.

​
См. также