Оставить старые переменные env?

После 3.22 не рекомендуется; мигрировать на префиксы OPENCLAW_*.

2026 OpenClaw Upgrade Playbook: 3.22 → v2026.3.24 на Mac cloud

В OpenClaw вышли 3.22 (каналы, интеграции в духе ClawHub, более строгая работа с учётными данными) и v2026.3.24 (шире слой совместимости с OpenAI) почти одновременно в начале 2026 года, вместе с переходом на имена окружения OPENCLAW_*, жёсткой проверкой SecretRef, нативной обработкой PDF и потоковыми настройками каналов по умолчанию. Материал для команд, у которых шлюз под launchd или cron на Mac cloud: почему слепое обновление пакета ломает прод, матрица контроля и более пяти воспроизводимых шагов для снимка, обновления, doctor, дымовых тестов и отката — со ссылками на первый деплой, усиление и разбор ошибок.

1. Три типа сбоев: почему одного npm update мало

Быстрые сценарии из туториала рассчитаны на одноразовые машины. Продовые шлюзы с мостами Slack или Discord и конкретными формами деплоя ведут себя иначе:

Нет снимка: без архива конфигурации, plist и env-файлов нельзя доказать, что предыдущая версия запускалась — откат превращается в угадайку, хуже на общих аккаунтах Mac cloud.
Дрейф префиксов: 3.22 ожидает OPENCLAW_*; старые переменные в стиле ClawdBot/MoltBot могут не читаться. launchd подставляет только то, что в EnvironmentVariables; «тихие» частичные конфиги похожи на ошибки auth или таймауты.
SecretRef fail-fast и новые умолчания: отсутствующие секреты могут намеренно останавливать старт. PDF и каналы требуют настроек провайдера; без doctor проблемы всплывают только под нагрузкой.

На общем аккаунте Mac cloud эти сбои сложнее бисектить: у разных операторов в интерактивной оболочке разный export, а launchd всё ещё подмешивает старые ключи. Перед обновлением сохраните вывод launchctl print для job, путь к plist на диске и редуцированный дамп эффективного окружения (секреты в тикеты не класть — только имена ключей). Скрипты-сайдкары для IM-мостов обновляйте в том же окне изменений, чтобы пути логов и файлы токенов совпали с новой раскладкой CLI.

2. Матрица отличий релизов

Точные ключи сверяйте с установленной CLI и upstream release notes; таблица отражает типичные операционные отличия.

Область	Акценты 3.22	Акценты v2026.3.24	Действие ops
Пространство имён env	Предпочитать `OPENCLAW_*`, убрать legacy-префиксы	Строже валидация неизвестных ключей	Grep plist, профилей, CI-секретов; мигрировать до reload
Секреты	Покрытие SecretRef + fail-fast	Общие рекомендации с compat-маршрутами шлюза	В staging намеренно сломать SecretRef и убедиться в блокировке
PDF	Нативный путь с лимитами байт/страниц	Маршрутизация моделей взаимодействует с compat-слоем	Регрессия на маленьком PDF; зафиксировать лимиты
Каналы	Потоковые умолчания Telegram	—	Следить за 429/backoff; логи под режим деплоя
Совместимость OpenAI	—	`/v1/models`, `/v1/embeddings` для сторонних клиентов	Дымовой `curl` на loopback; без сырого выхода в интернет

Кросс-платформенным командам полезен мультиплатформенный деплой — порядок обновлений как на Linux; отличается только супервизия.

3. Шаги: снимок, стоп, обновление, миграция, doctor, дым, launchd

Выполняйте по порядку; не перезагружайте launchd, пока doctor и дым не проходят в foreground под тем же пользователем сервиса.

Снимок: архив каталога конфигурации, plist launchd, env-файлов; зафиксировать openclaw --version и ревизии lockfile. С Git — тег коммита; без — хотя бы SHA256 plist и бинарника CLI.
Стоп: openclaw gateway stop; lsof -i :18789 по гайду по порту; остановить IM-сайдкары при необходимости.
Обновление через поддерживаемый канал (pnpm/npm global или закреплённая установка в проекте) — без смеси root/user.
Миграция env: заменить legacy-префиксы на OPENCLAW_* в plist EnvironmentVariables и shell-профилях.
Doctor: без ERROR; WARN — по политике.
Дым: короткий PDF; негативный SecretRef, затем восстановление; опционально curl к /v1/models на loopback с bearer.
launchd: launchctl unload/load; смотреть логи 15 минут; держать tarball старой plist для отката в один шаг.

Для PDF возьмите двухстраничный файл в пределах лимитов байт/страниц; зафиксируйте время и RSS в Мониторинге системы для сравнения до/после. Для SecretRef намеренно укажите staging-ключ на несуществующий путь в vault и проверьте ненулевой код выхода — затем верните валидную ссылку и повторите doctor до чистоты.

curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  "http://127.0.0.1:18789/v1/models" | head -c 400

# Пример: перезагрузка job launchd после правки plist (метка и пути — примеры)
launchctl unload ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
launchctl print gui/$(id -u)/com.example.openclaw.gateway | head -n 40

Замечание: привязывайте шлюз только к loopback или аутентифицированному обратному прокси — см. усиление в проде.

4. Технические заметки для цитирования

Node 22+ по-прежнему обязателен; обновления ОС или toolchain могут сменить алиасы nvm. SecretRef fail-fast сделан намеренно — тихая работа с подставными учётными данными опаснее явного сбоя при деплое. Лимиты PDF защищают RAM и биллинг: рост pdfMaxBytesMb без корректировки параллелизма может загнать узел Mac cloud в swap при пересекающихся сессиях.

Клиенты могут кэшировать /v1/models; после обновлений сбрасывайте кэш, чтобы сторонние инструменты не держали устаревшие ID моделей. На Apple Silicon следите за давлением на память при одновременном PDF и стриминговых каналах; unified memory помогает, но не бесконечна. ThrottleInterval у launchd может скрывать быстрые циклы падений — смотрите launchctl print, если конфигурация «не подхватывается», и системные логи на throttling вроде кода 78.

5. От хаотичных обновлений к аудируемому Mac cloud

Шлюз только на ноутбуке разработчика или только в Docker на «голом» Linux без совпадающих путей томов и секретов часто «работает», пока не понадобятся воспроизводимые обновления: ноутбуки засыпают, Docker Desktop меняет сеть, bind mount уезжают от прода. Нет стабильного контракта launchd, пути SecretRef трудно держать идентичными, регрессии IM или PDF усложняются из‑за отличий GPU и энергопрофиля от сервера 24/7.

Выделенный аккаунт Mac cloud с версионируемой plist, скриптами doctor/дыма и неизменяемыми снимками превращает обновления OpenClaw в тикеты изменений. Аренда узлов VPSMAC M4 Mac cloud под роль шлюза сохраняет нативные пути Apple, стабильный egress и изоляцию от рабочих станций — обновления затрагивают ограниченную сервисную поверхность, а аудит безопасности видит, какой бинарник, plist и набор env были live.

6. FAQ

Шлюз тихо завершается после обновления?

Проверьте статус launchd, ThrottleInterval, вывод doctor и конфликты порта.

Оставить старые переменные окружения?

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

Публиковать OpenAI-совместимые эндпоинты наружу?

Нет — только loopback, SSH-туннель или аутентифицированный прокси.