Коротко

  • Вся механика — одна команда: openclaw update. Она сама определяет, как у тебя стоит OpenClaw (npm или git), тянет новую версию, прогоняет openclaw doctor и рестартит gateway.
  • Главных граблей три: не сделал --dry-run до; не сверил openclaw --version, doctor и health после; не записал версию для отката, пока всё работало.
  • Остальная статья — про то, чего в доках не пишут: почему «команда завершилась успешно» ничего не гарантирует и когда обновляться не надо вовсе.

По запросу «how to update openclaw» выдача одинаковая: вот команда, вот флаги, вот npm, docker и git. Всё правда, всё работает. Чего в них нет, так это взгляда человека, который обновлял это на боевых серверах и получал по рукам. Я держу OpenClaw в проде и усвоил дорогой ценой: обновиться — это не просто набрать команду и забыть, это решение, за которым может тянуться долгая дорога назад, к тому, что работало вчера. Где ставишь, что ломается, почему пинишь, как откатываешься, когда не трогаешь. Вот об этом и статья.

Быстрый путь: посмотреть, обновить, проверить

Порядок у меня всегда один: превью, бэкап, апдейт, проверка руками.

Сначала превью, без применения:

openclaw update --dry-run

Показывает текущий канал, целевую версию, запланированные действия и предупредит, если понадобится подтверждение даунгрейда. Ничего не меняет. Дешёвая страховка от «а я думал, у меня stable».

Сразу оговорка про диагностику: --verbose у openclaw update не работает. Хочешь деталей — --dry-run и --json.

Потом бэкап:

openclaw backup create

Снапшот state, конфига и workspace. Нужно в конкретное место — есть --output <dir>; хочется сперва глянуть состав — --dry-run --json. В блогах к этой команде любят дописывать флаг --verify: в первоисточнике его нет, не закладывайся.

Само обновление:

openclaw update

Внутри оно аккуратнее голого npm: ставит новую версию во временный npm-prefix, сверяет состав dist и только после этого атомарно подменяет всё дерево пакета, не наслаивая новое на старое. Споткнулось — будет один ретрай с --omit=optional.

После — проверка, руками:

openclaw --version
openclaw doctor
openclaw health

--version подтверждает, что новая версия реально встала (ниже объясню, почему я в это на слово не верю). doctor мигрирует конфиг и чинит state. health показывает, жив ли gateway. Если что-то мутное, openclaw channels status --probe даст живой статус транспортов по аккаунтам, включая 401 по авторизации, а openclaw gateway status --deep --json — глубокий срез состояния gateway.

Обновляешься руками через пакетный менеджер? npm i -g openclaw@latest (или pnpm add -g, bun add -g) — путь законный, но на supervised-установке порядок жёсткий: сначала openclaw gateway stop, потом пакетный менеджер, потом openclaw gateway restart. Иначе живой gateway читает наполовину подменённое дерево пакета. Ровно поэтому я предпочитаю openclaw update: он сам разруливает подмену под работающим gateway.

Апдейт упал посреди npm-фазы? Не разгребай руками — перезапусти инсталлер, он добьёт наполовину обновлённую установку:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

Каналы: stable, beta, dev — и почему авто-апдейт у меня выключен

Каналов три, и выбор между ними — это почти вся твоя политика обновлений.

  • stable — npm dist-tag latest. Для большинства; на проде у меня только он.
  • beta — dist-tag beta. Если беты нет или она старше latest, канал сам откатится на latest.
  • dev — движущийся main из git. Доки прямым текстом: «Do not use it for production gateways». Незаконченное и ломающее приезжает сюда первым, для того канал и существует.

Переключение — openclaw update --channel stable|beta|dev, и учти: выбор персистится в update.channel. По виду разовый флаг, по факту — смена политики.

Тонкость, на которой спотыкаются: --channel beta и --tag beta ведут себя по-разному. Канал умный: нет беты — возьмёт latest. --tag beta бьёт строго в сырой dist-tag beta и действует один прогон.

Что настроено сейчас и есть ли апдейт, покажет openclaw update status --json.

Теперь авто-апдейтер. По умолчанию он выключен, и на проде я оставляю ровно так. Включается через update.auto.enabled в ~/.openclaw/openclaw.json, причём каналы ведут себя по-разному: stable выжидает stableDelayHours и раскатывается с джиттером, beta проверяется ежечасно и применяется сразу, dev автоматом не применяется вовсе. Перечитай это «применяется сразу»: включить авто-апдейт на beta — отдать чужому релизу право перезапустить твой рантайм ночью. На стенде — пожалуйста. На проде обновляюсь сам, в момент, который выбрал сам.

Рядом два рычага. update.checkOnStart: false глушит подсказку об апдейте на старте. OPENCLAW_NO_AUTO_UPDATE=1 в окружении gateway блокирует авто-применения, даже если update.auto.enabled включён. Пригождается, когда ты откатился и разбираешь инцидент, а автоапдейтер норовит вернуть всё как было.

Почему я не гонюсь за latest

Незапиненный openclaw@latest — это лотерея. Рано или поздно прилетает версия с регрессией и роняет то, что вчера работало. Проверено на себе: свежие установки у меня падали ровно до тех пор, пока я не запинил версию.

С тех пор у каждого обновления есть причина, и список причин короткий: закрыть уязвимость; получить фичу, которая мне реально нужна; перейти на версию, которую я уже проверил вне прода. «Вышло новое» в списке нет. Свежесть сама по себе ничего не гарантирует: вместе со свежими фиксами первым приезжает и свежий брак. Безопасник читает «мы всегда на latest» однозначно: «чужие свежие CVE у нас тоже сразу».

Отсюда и валидация. Новую версию я сначала гоняю на небоевом стенде и только потом везу в прод. Нет стенда — хотя бы --dry-run, чтобы видеть, что именно поедет, до того как оно поехало.

Что реально ломается при апдейте

Список из практики, всё собрано на моём проде.

Конфиг «не применился». Поправил конфиг, обновился, а gateway живёт по-старому: правку подхватывает рестарт сервиса, и надо проверять, что новая конфигурация реально доехала. Симптом коварный: всё «работает», просто по вчерашним правилам.

Отвалился сосед. Когда на машине не один агент (у меня рядом с OpenClaw живёт Hermes), апдейт одного цепляет другого: обновил первого — лёг второй. После апдейта проверяй не только того, кого обновлял.

Разъехались токены. После рестартов авторизация между управляющим слоем и gateway может рассинхрониться, и выглядит это как поломка на ровном месте. openclaw channels status --probe показывает такие вещи, 401 в том числе.

`EACCES` на глобальной установке. Классика npm: глобальной директорией владеет root. Лечение по шагам: openclaw gateway stop, установка через sudo npm i -g, затем openclaw gateway install --force и рестарт.

Старый Node. Новая версия может твой Node уже не поддерживать. Совместимость проверяй до апдейта, а не когда уже упало.

Ручной npm поверх живого gateway. Уже писал выше, повторю, потому что на эти грабли наступают регулярно: на supervised-установке npm i -g без остановки gateway оставляет процесс на наполовину подменённом дереве пакета.

И главный урок, дороже остальных: «апдейт прошёл» и «система работает на новой версии» — два разных утверждения. Обновление форвардное. Новая сборка может не увидеть или не понять состояние, оставшееся от старой, причём молча. Апстрим сам описывает этот класс проблем: в логах один из бинарей openclaw старше версии, которая последней писала openclaw.json, — рецепт там же, openclaw doctor --fix. Отсюда привычка: после каждого апдейта --version, doctor, health, и неважно, насколько зелёным был вывод команды.

Пин и откат: дисциплина, а не флаг

Главное, что надо знать про пин в OpenClaw: постоянной фиксации версии здесь нет. openclaw update --tag <version> поставит ровно указанную версию, но лишь на один прогон. Следующий openclaw update спокойно уйдёт по настроенному каналу и уведёт тебя на latest. Вдобавок --tag работает только на npm-установках, git его игнорирует.

Про даунгрейд отдельно: если целевая версия старше текущей, OpenClaw запросит подтверждение. В скриптах оно гасится флагом --yes, а --dry-run заранее скажет, понадобится ли оно вообще.

Настоящий пин поэтому — дисциплина из четырёх пунктов:

  • авто-апдейт выключен;
  • openclaw update не запускается «на всякий случай» — только осознанно, после dry-run;
  • заведомо рабочая версия записана заранее: номер, к которому откатываешься, надо знать до апдейта, а не выяснять в панике, когда прод лежит;
  • перед апдейтом снят свежий openclaw backup create.

Сам откат скучный — и хорошо, что скучный:

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

Какая версия сейчас опубликована в npm, смотрится через npm view openclaw version. На source-установке откат — это git checkout <sha>, потом pnpm install && pnpm build и рестарт gateway.

Когда обновляться не надо

Раздела «когда не обновляться» я в выдаче не встречал, а он важнее половины флагов.

Стабильная прод-система с узкой задачей — худший кандидат на «давай накатим свежее». Апдейт добавляет риск регрессии, а взамен не даёт ничего, что тебе нужно. Не закрывает уязвимость, не даёт нужной фичи и ты её не гонял на стенде — не трогай.

dev на проде — нет. Это даже не моё мнение, это первоисточник: движущийся main, незаконченное и ломающее.

И не делай из частоты обновлений метрику гигиены. Гнаться за свежайшим — значит первым катить себе чужие свежие баги и CVE, не успевая их проверить. Гигиена выглядит иначе: обновление по делу, откат наготове, проверка после.

Если возиться самому не хочется

Пин, прогон перед раскаткой, откат под рукой — всё это ручная работа, и она не кончается: у апстрима всегда найдётся следующий релиз. Её можно отдать. Cain держит OpenClaw и Hermes на выделенном под тебя сервере, один клиент на сервер, и версии там зафиксированы. Новую сперва гоняем через свою матрицу обновлений. Только потом раскатываем. Вслепую latest мы не тянем: катим только то, что сами запинили и проверили, поэтому фиксы безопасности доезжают до тебя без чужой регрессии в довесок. Запросы при этом уходят напрямую тому провайдеру модели, которому ты и так платишь, а не через чьё-то общее облако. Вариант не единственный: всё то же самое делается руками по шагам выше.

Частые вопросы

Как узнать версию OpenClaw? openclaw --version — что стоит у тебя. npm view openclaw version — что опубликовано в npm. openclaw update status --json — текущий канал и доступность апдейта. После обновления первая команда обязательна: «апдейт прошёл» ещё не значит, что рантайм поднялся на новой версии.

`openclaw update` не работает, после апдейта всё отвалилось. Что делать? По порядку: openclaw doctor --fix (миграция конфига, починка state), openclaw gateway restart, openclaw health. Мало — смотри openclaw channels status --probe (живой статус транспортов и авторизации, 401 видно сразу) и openclaw gateway status --deep --json. Апдейт упал посреди npm-фазы — перезапусти инсталлер: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm, он добьёт наполовину обновлённую установку. EACCES на глобальном npm: openclaw gateway stop, sudo npm i -g, openclaw gateway install --force, рестарт.

Как откатить OpenClaw на предыдущую версию (downgrade)? На npm-установке: npm i -g openclaw@<version>, затем openclaw doctor и openclaw gateway restart. На source: git checkout <sha>, pnpm install && pnpm build, рестарт gateway. Даунгрейд через openclaw update --tag запросит подтверждение (пропускается --yes). На время разбора запусти gateway с OPENCLAW_NO_AUTO_UPDATE=1 в окружении, чтобы авто-апдейтер не утащил тебя обратно наверх.

Включать ли авто-апдейт OpenClaw? На проде я не включаю, и по умолчанию он выключен; дефолт разумный. Особенно осторожно с beta: проверка ежечасно, применение сразу, то есть чужой релиз перезапускает твой gateway в момент, который выбирал не ты. stable с задержкой stableDelayHours мягче, но сути не меняет. Обновляйся сам: dry-run, бэкап, апдейт, проверка.

Какой канал выбрать: stable, beta или dev? stable — рабочий вариант для прода и для большинства вообще. beta — щупать новое раньше остальных; канал сам откатится на latest, если беты нет или она старше. dev — движущийся main, в доках прямой запрет ставить его на прод-gateway.

Можно ли попросить агента обновить самого себя? Можно, но не рекомендуется — так пишут сами доки, и я согласен. Апдейт рестартит gateway, то есть роняет активную сессию агента; вдобавок может понадобиться чистый git-checkout и интерактивное подтверждение. Надёжнее из шелла, руками оператора. Если всё же автоматизируешь: openclaw update --yes --no-restart, затем отдельным шагом openclaw gateway restart.

Илья Прудников держит приватные инстансы OpenClaw и Hermes. Это заметки оператора про обновления в проде, а не документация проекта; точные команды, флаги и дефолты сверяй по свежим докам OpenClaw.