Плейбук 2026: восстановление LaunchAgent шлюза OpenClaw на macOS после обновлений

Шлюз OpenClaw на macOS должен переживать перезагрузки через launchd, но быстрые обновления канала 2026.x иногда оставляют тихий сбой: бинарник обновился, LaunchAgent не перезагрузился, и все мосты сообщений перестают отвечать. Этот плейбук сопоставляет симптомы с исправлениями, сравнивает тактики восстановления в матрице и перечисляет девять воспроизводимых шагов по SSH на NodeMac Mac mini M4 без угадывания путей.

Сочетайте с операционным runbook OpenClaw по расположению логов и политике обновлений и с первичной установкой macOS, если собираете с нуля.

Признаки дрейфа LaunchAgent — не просто «ИИ лежит»

• Процесса нет, диалога о падении нет: в ps нет воркера шлюза при простаивающем CPU — типичный выгруженный агент.
• HTTP 401 от всех провайдеров после reboot: ключи в dotenv есть, но демон унаследовал пустое окружение, потому что plist не содержал нужных переменных.
• Ручной запуск CLI работает, автозапуск нет: операторы успешно стартуют шлюз в терминале; после выхода сервис останавливается, потому что LaunchAgent указывает на устаревший рабочий каталог или имя entry из старой структуры.

Матрица вариантов восстановления

Переменные окружения: где они должны жить у демонов

Интерактивные оболочки читают .zshrc; LaunchAgents — нет. Если ключи провайдера только в файле, который plist не подхватывает, шлюз поднимается без аутентификации и сыплет непонятными 401.

1. Перечислить обязательные ключи (API-токены, опциональные proxy URL) в фрагменте runbook для вставки после ротации.
2. Дублировать в EnvironmentVariables plist или использовать поддерживаемую обёртку с явной загрузкой dotenv при старте — одна стратегия на машину, не обе наполовину.
3. Тест перезагрузки: планировать ежеквартально; ловить пропущенные переменные в течение 24 часов после смены учётных данных.
4. Ограничить права plist пользователем сервиса; world-readable plist утекают секреты.
5. Задокументировать активный домен (gui/$(id -u) vs фон), чтобы дежурный не выгрузил неверный job.

Почему обновления ломают автозапуск при исправном бинарнике

Обновления пакета могут сразу сдвинуть три хрупких точки: путь к исполняемому файлу в ProgramArguments, рабочий каталог для относительных конфигов и ожидаемую мажорную версию Node в бандле шлюза. Достаточно одного рассогласования: launchd считает job «настроенным», хотя он сразу выходит — галочки в UI, который так и не устоял.

Относитесь к каждому апгрейду как к мини-миграции: снимок plist, контрольные суммы entry-скрипта шлюза, предыдущий tarball хранить минимум семь дней. На облачных Mac вы платите за аптайм независимо от ответов бота; дисциплина в календаре изменений окупается при первом пятничном деплое, который рвёт клиентскую автоматизацию.

• Дросселировать автообновления на прод-шлюзах; canary в staging берёт свежую сборку первой.
• Согласовать мажорные Node с документацией вендора — неверные мажоры часто дают загадочные ошибки резолва модулей в первой строке лога.
• Централизовать ротацию секретов, чтобы правки plist делались раз на флот, а не на каждую панику.

Девять шагов runbook (SSH на Mac mini M4)

1. Подтвердить связь тем же SSH-пользователем, что и LaunchAgent; несовпадение прав часто объясняет «вручную ок, при загрузке нет».
2. Сохранить вывод launchctl print gui/$(id -u) к заметкам инцидента для diff.
3. Найти plist в ~/Library/LaunchAgents/; проверить существование путей ProgramArguments.
4. Запустить kickstart с -k; подождать 30 секунд и проверить listening-порты.
5. Если всё ещё down — аккуратно unload/load plist; искать дубликаты в /Library/LaunchDaemons, если экспериментировали.
6. Свести переменные окружения; добавить недостающие ключи, снова загрузить.
7. Тейлить логи шлюза две минуты на crash-loop — откат, если один и тот же стек повторяется больше трёх раз.
8. Интеграционный смоук (тестовое сообщение по каналу с минимальным риском) до объявления «зелёный».
9. Обновить внутренние доки точными командами; флоты в HK, JP, KR, SG и US делят одну каноническую страницу восстановления.

Логи, health-check и эскалация

После перезапуска проверяйте не только «процесс жив», а осмысленные строки лога: успешные рукопожатия с провайдерами, стабильные WebSocket, отсутствие повторяющихся stack trace. Добавьте простой HTTP health-check (если шлюз его поддерживает) в то же мониторинговое ядро, что и остальной прод, чтобы отличать «launchd считает job здоровым» от реально отвечающих мостов.

Для распределённых команд централизованную агрегацию логов (rsyslog, агент и т. п.) включайте только после threat model и согласования по данным — API-ключи не должны попадать в общий индекс в открытом виде. На машинах NodeMac оставайтесь близко к хосту по SSH и при необходимости VNC; дополняйте короткими еженедельными «diff plist» после каждого обновления вендора, чтобы видеть дрейф до тикета клиента.

Цепочка эскалации: сначала kickstart, затем reload plist, затем переустановка CLI, затем откат — зафиксируйте порядок, чтобы ночная смена не экспериментировала. Если подряд падают два релиза, зафиксируйте прод-версию и откройте тикет вендору с приложенной plist и отредактированными логами.

Постмортем и контроль изменений

После каждого инцидента фиксируйте в тикет-системе хеш plist, версию шлюза и сработавшие команды launchctl. Привязывайте изменения к формальному запросу, чтобы пятничные эксперименты не попадали на прод без согласования. На выделенных машинах NodeMac группируйте политики по хосту и применяйте ту же модель SSH-доступа, что в справочном центре.

Чеклист до обвинения провайдера моделей

FAQ

Почему OpenClaw пропадает из строки меню после обновления?

Процесс шлюза мог завершиться, а launchd так и не перезагрузил plist LaunchAgent, либо plist всё ещё указывает на старый путь к программе после смены структуры пакета. Исправление: проверить plist, перезагрузить агент и убедиться, что переменные окружения переживают перезагрузку.

Безопасно ли запускать kickstart на продакшен-шлюзе?

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

Нужны всегда включённые шлюзы без присмотра за ноутбуками? Сравните тарифы NodeMac на выделенные Mac mini M4 с SSH/VNC в регионах ваших пользователей и используйте этот плейбук как стандартный чеклист после обновлений.

Железо Mac mini M4 делает восстановление демонов скучным в хорошем смысле: запас производительности Apple Silicon позволяет уместить шлюз, локальные хелперы и лёгкую автоматизацию без свопа, unified memory снижает OOM при всплесках логов. NodeMac поставляет выделенные физические машины — не общие VM — с SSH и VNC в Гонконге, Японии, Корее, Сингапуре и США, чтобы операторы выполняли этот плейбук удалённо сразу после выхода обновления. Аренда снижает CapEx, пока вы настраиваете политики LaunchAgent, и сочетается с справкой платформы по гигиене доступа на флоте.