2026_OPENCLAW
UPGRADE_
BREAKING_
DOCTOR_AUTH_V2.

1. Почему недостаточно бинарника

(1) Дрейф корня состояния: старые сборки опирались на ~/.moltbot или префиксы CLAWDBOT_*/MOLTBOT_*; текущие ожидают ~/.openclaw и канонические OPENCLAW_*. Обновить пакет без миграции данных — значит получить раздвоенную правду.

(2) Границы doctor --fix: типичные смещения он чинит, но не истёкшие токены каналов, не пути reverse-proxy и не кастомные монтирования skills — читайте diff до применения.

(3) Auth устройства v2: nonce-подпись поднимает планку клиентов; устаревшие CLI выглядят «подключёнными», но не попадают в workflow. launchd без той же среды, что интерактивная shell, усиливает эффект «локально работает, на сервере нет».

2. Матрица

3. Пять шагов

1. Снимок состояния, workspace, plist, версии.
2. doctor без --fix.
3. Пробный --fix на копии.
4. grep старых префиксов.
5. Дым каналов; откат по статье Gateway.

4. Пороги

5. Секреты и соответствие

Документируйте, какие секреты попадают в plist/units и кто имеет право чтения. Staging-Mac с теми же ключами до продакшена снижает риск тестовых персональных сообщений в боевых каналах.

5.1 Матрица удалённого launchd

6. FAQ

Трогает ли --fix workspace? Может переписать указатели — снимок обязателен.

Docker? Одна истина между хостом и контейнером; одновременное редактирование даёт гонки во время doctor --fix.

Откат на v1? Только изолированная лаборатория с датой закрытия; в проде поднимайте клиентов.

Снести ~/.moltbot сразу? После паритета секретов и валидных каналов; tarball хранить минимум один релиз.

Doctor зелёный, канал молчит? Смотрите логи доставки webhook и заголовки у SaaS — doctor не видит апстрим.

7. Кейс: Slack после двух миноров

В plist остался старый путь к бинарнику, токены жили только в .zshrc, заголовок Slack не совпал с новой подписью по умолчанию. Починка по одному слою давала флаки; обнуление diff окружения + re-pair стабилизировали.

Архив выводов doctor и diff plist на каждый апгрейд сокращает повторы с часов до минут и помогает аудиту.

К тикету прикладывайте shasum итогового openclaw; откат возвращает и версию пакета, и путь в plist. На мультипользовательской машине UserName демона должен совпадать с владельцем ключей.

Homebrew и npm global требуют одного победителя в PATH, иначе doctor чинит одно, launchd стартует другое.

Staging, зеркалирующий прод-plist, уменьшает повторные сообщения пользователям; фиксируйте, какие каналы в staging разрешены, чтобы не остались «призрачные» webhook’и.

Оценка воздействия на персональные данные должна отметить, расширяет ли апгрейд логи skills — база может сместиться без смены модели.

Ротацию секретов не синхронизируйте с крупными бампами OpenClaw и ротацией TLS в одну ночь — иначе кажется, что «сломался шлюз», хотя не хватает отпечатка.

После апгрейда проверьте лимиты дескрипторов: миноры иногда меняют одновременные webhook-соединения; рост EMFILE диагностируется быстрее с базовой линией.

Внутренние chatops-боты должны проходить ту же цепочку auth, что прод; отдельный «админ-бот» на старом билде скрывает проблемы v2 до демо.

При IaC рендерьте plist/unit из того же коммита, что digest образа и npm-lock; три разных SHA на тикете — сигнал ночного дрейфа.

Обучите поддержку отличать «процесс жив» от «workflow ест события» — healthcheck только процесса лжёт зелёным при застойной очереди.

Приостанавливайте бэкапы, которые замирают каталог состояния во время апгрейда, иначе получите полуторные архивы.

Ведите список запрещённых «горячих» shell-команд вне runbook — каждая недокументированная команда становится следующим инцидентом.

Для нескольких регионов повторяйте зонды одинаковыми скриптами при разном DNS, чтобы не спутать сеть с auth.

Сохраняйте скриншоты настроек Slack рядом с текстами doctor — UI SaaS тяжело diff’ить, пары до/после экономят часы.

8. Наблюдаемость в окне изменений

Коды выхода, успех зондов каналов, медиана cold-start skills, auth-ошибки/ч — все четыре плохи: корень/env; только auth: матрица клиентов.

Коррелируйте с user-agent, если логи позволяют; старый мобильный билд может доминировать в ошибках.

8.1 CI, staging и ловушка latest

CI с npm i -g openclaw@latest не доказывает безопасность флота: Node раннера, PATH shell, отсутствие digest в метаданных. Пиньте версию или digest, пишите абсолютный путь + shasum в артефакт, в тикете ссылайтесь на это, а не на слово latest.

Staging в том же Slack, что прод, требует раздельных ботов/каналов. Клонируйте plist, меняйте только секреты/порты, гоняйте полные смоуки. Лишний блок EnvironmentVariables только в staging — дрейф прода, мержите структуру назад.

Во время заморозки запретите двойное толкование OPENCLAW_CONFIG_ROOT; одна авторитетная поверхность, к тикету diff -u.

Скрипты здоровья, вызывающие openclaw, обновляйте вместе с поколением CLI иначе ложные critical и шторм рестартов.

Откат тренируйте теми же артефактами: снимок, старый digest, зонды — без вывода doctor откат неполон.

CM иногда рендерит шаблоны для login и демона с минутным сдвигом — комментируйте ревизию в plist для связи с Git.

Сканеры секретов должны видеть и shell, и plist; ключи мигрируют тихо во время «лечения» дрейфа.

При Zero Trust проверьте, что интерактив и демон видят один контекст сертификата устройства, иначе v2 падает выборочно.

Пакетные джобы со старыми субкомандами депрекейтите так же, как публичные API.

Храните версию Node агента, делавшего глобальные npm-установки — влияет на нативные модули и пути.

После заморозки убедитесь, что дашборды ссылаются на актуальные label launchd.

Несколько шлюзов: нумеруйте каталоги состояния, не symlink’айте между ними — doctor «лечит» не то дерево.

Аварийный доступ в прод уведомляет второго инженера; хотфикс без свидетеля плохо воспроизводится в постмортеме.

Гипервизоры добавляют источники времени; сверяйте NTP, если nonce чувствительны ко времени.

Антивирус в реальном времени на каталоге состояния может замедлить doctor — фиксируйте исключения с security.

Держите зеркало release notes, если апстрим недоступен — иначе решения «на усталой интуиции».

Парное ревью plist: микроскопические XML-ошибки дают макроскопический отказ auth.

Запишите, какие правила firewall для webhook открывались — пригодится аудиту.

9. Windows/Linux: больше слоёв

Без замороженного контракта состояния сервис-менеджеры множат сбои. Удалённые Apple Silicon Mac ближе к примерам launchd — MACGPU сдаёт узлы в аренду с низким трением, CTA без логина.

WSL, snap, distro-специфичные пути Node: один OPENCLAW_* может понадобиться трижды, пока согласуются демон, CLI и skill.

После v2 короткие бури переподключений грузят маленькие CPU VPS — ступенчатый выкат клиентов или временно больший хост.

Ревьюеры просят ls -le до/после, если doctor --fix мог расширить ACL.

10. Цепочки установки и Docker-прод

npm global, Compose, pnpm source имеют разные корни данных. Digest образа — часть контракта; bump npm на хосте не двигает CLI внутри контейнера.

Bind ~/.openclaw плюс правки на хосте — сериализуйте писателей или staging-копию, иначе гонки на fix.

CI, шеллящая openclaw, пинит AMI вместе с минором сервера — иначе «прод зелёный, nightly красный».

Карта апгрейда: путь бинарника, label plist, корень данных, список каналов — первое вложение в инцидент.

Проверяйте, что внутренний артефакт-зеркало всё ещё смотрит в тот же upstream — тихая смена зеркала меняет хэши без semver.

Документируйте, кто подписывает какие бинарники при сосуществовании brew и npm — цепочка поставки важнее строки версии.

Долгие WebSocket-сессии могли пережить апгрейд, подписывая v1, пока новые события ждут v2 — форсируйте контролируемый reconnect после major.

Библиотека анонимизированных webhook-payload’ев для регрессий без спама пользователям.

11. Неделя ноль после зелёного doctor

День 0: второй tarball doctor после реального трафика, diff. День 1: зонды из контекста демона и админа. День 2: самый медленный skill холодный + ретраи. День 3: кластеризация auth по билдам, при необходимости окно принудительного обновления. День 4: восстановление совпадает с текущим label plist. День 5: короткий ретро, строка на карте.

Ступенчатый выкат с хотя бы одним суточным циклом между стадиями; маркетинговые фризы и отпуска on-call важнее даты публикации npm.

Ротируйте исполнителей чеклиста, версионируйте его рядом с инфракодом; личные alias портят смоуки.

При редких таймаутах меряйте DNS/TLS отдельно от процесса шлюза.

Трёхпунктовые заметки в вики на релиз дешевле знаний в личке.

Следите за размером каталога состояния — неожиданный рост намекает на debug-логи или отсутствие уборки.

Не забывайте мобильные клиенты — отдельный шаблон дыма.

Для FinOps показывайте сэкономленные часы инцидентов, а не только баннер версии.

Раз в квартал тренируйте намеренно неудачный откат без паники.

Фиксируйте, какие алерты временно приглушались — иначе глушение вечное.

Совмещайте ротацию сертификатов reverse-proxy и бампы, когда возможно, чтобы не тянуть две ночи подряд.

Указывайте часовой пояс логов в тикете для глобальных команд.

Креатив и платформа должны со-подписать определение полос, иначе дедлайны рендера съедают окна embeddings, а интерактивная полоса страдает тихо.

Ежемесячно пересматривайте digest модели и версию прокси даже без релиза приложения.

«Тихие» обновления Homebrew/npm без тикета — именно то, что ловит еженедельный чеклист.

Несколько DNS-провайдеров: фиксируйте TTL и даты ротации.

Короткие постмортемы с квартальным владельцем лучше PDF на 20 страниц.

Если инцидент «сам прошёл», запишите, что изменилось в окружении: браузер, MDM, ночной бэкап.

Сравнивайте постмортемы команд: одинаковые симптомы на разных ноутбуках часто указывают на общий корпоративный прокси.

Для удалённых узлов добавляйте температуру стойки и окна обслуживания ЦОД.

Не смешивайте в одном тикете смену модели и смену сетевого маршрута.

Ссылки на именованные CSV вместо безымянного archive.zip ускоряют поиск.

Онбординг: разбор реального постмортема в первую неделю.

Без задачи в бэклоге с датой ретро бессмысленно.

Раз в полгода перечитывайте старые постмортемы — паттерны повторяются, пока полосы не записаны.

Публично благодарите за честный разбор без охоты на виноватых — иначе следующий инцидент уйдёт в личку.

В шаблон добавьте «что не измеряли» — быстрее показывает дыры наблюдаемости.

Несколько арендованных Mac: ежемесячно сравнивайте лестницы нагрузки между узлами.

Конец квартала увеличивает фоновые задачи на рабочих станциях и может сдвинуть p99 без изменений ML-стека — отметьте в календаре.

Короткая пометка в тикете, кто запускал смоук (человек или CI), спасает от ложных выводов, если окружения отличаются тонкими alias в shell.

Фиксируйте точный часовой пояс машины, писавшей лог — ночные окна бэкапов по UTC и по локальному времени выглядят по-разному на графиках.

Если команда смешивает data science (эмбеддинги) и продукт (чат) на одном API без правил приоритета, побеждает самый громкий отдел, измеряемый чужими p99.

Мягкий rate limit на прокси предотвращает тройные демо, бьющие по очереди одновременно: лестница даёт цифры, политика — предохранитель.

При миграции с x86-облаков не копируйте слепо размеры батчей — иная память, иные узкие места.

Архивируйте «хорошие» и «плохие» недели с CSV и скриншотами Activity Monitor — онбординг быстрее длинного PDF.

Пропуск мини-лестницы из-за «ничего не менялось» игнорирует тихие обновления, которые двигают p99 задолго до релиза.

Строка в ежемесячном дайджесте платформы держит тему задержек на виду без бюрократии десятистраничных отчётов.

Шаблон постмортема из десяти строк с владельцем на квартал лучше презентации, которую никто не откроет.

Если инцидент закончился сам, запишите, что ещё изменилось: патч браузера, политика MDM, включившийся ночной sync-клиент.

Сравнение постмортемов между командами выявляет общий корпоративный прокси вместо «поломки модели».

Для удалённых стоек добавляйте события обслуживания и температуру — объясняет редкие провалы, не воспроизводимые на ноутбуке.

Не смешивайте в одном изменении сетевой маршрут и версию OpenClaw — откат превращается в лотерею.

Именованные ссылки на CSV в тикете ускоряют поиск лучше вложения archive.zip без названия.

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

Без задачи в бэклоге с датой ретро остаётся шумом — всегда назначайте владельца и срок.

Полугодичное перечитывание старых постмортемов ловит повторяющиеся паттерны, пока полосы не закреплены письменно.

Публичная благодарность за честный разбор снижает уход инцидентов в личные сообщения, где метрики пропадают.

Поле «что не измеряли» в шаблоне полезнее списка успехов — оно показывает пробелы культуры наблюдаемости.

Если арендуете несколько удалённых Mac, сравнивайте их лестницы ежемесячно — дрейф конфигурации между узлами незаметен до перекоса нагрузки.

Wi-Fi точка доступа или новый радиоканал иногда меняет буферизацию сильнее, чем смена модели — перезапустите хотя бы одну ступень лестницы после сетевых работ.

Гибрид «днём ноутбук, ночью удалёнка» требует дисциплины очередей; без оркестратора два тяжёлых стрима снова лягут на локальный Mac.

Синхронизируйте календарь моделей и патчей ОС; независимые выкладки создают невоспроизводимые регрессии, и тогда единственный источник правды — история CSV.

Официально зафиксируйте поддерживаемые длины контекста; иначе каждая маркетинговая демо становится скрытым SLA, который оплачивают очереди.

Мини-лестница из двух ступеней раз в две недели — дешёвый датчик смещения p99 между крупными релизами.

Даже одна строка в дайджесте о результате мини-лестницы держит культуру измерений живой без тяжёлой бюрократии отчётности и снижает риск забыть про тихие обновления окружения.

12. Вывод

Удалённые Apple Silicon Mac чаще совпадают с launchd-примерами. MACGPU — аренда узлов для 24/7 репетиций апгрейдов — CTA без логина. Апгрейды без снимков и логов doctor остаются по-настоящему незавершёнными.

Когда дисциплина на месте, следующие миноры становятся заметно дешевле из-за артефактов и порогов, а не из-за «магии релизов».

Фиксируйте каждый успех как повторяемый шаблон во внутренней библиотеке знаний, а не только как чат-праздник без последствий.

Это сильно сокращает онбординг и заметно снижает зависимость от героев прошлого инцидента — гораздо устойчивее любого разового драматического подвига без структурированного обучения.