Шлюз OpenClaw аутентифицирует RPC-клиентов общим секретом. На практике секрет приходит по трём каналам на macOS: дерево openclaw.json на диске, мастер приложения macOS, который может переписать конфиг, и блок окружения LaunchAgent, который подставляет переменные для headless-сессий. Когда любой слой расходится, операторы гоняются за призраками: openclaw status выглядит здоровым, а приложение показывает отключение. Статья даёт две матрицы, восемь шагов внедрения и последовательность HowTo, чтобы хост-шлюз Mac mini M4 перестал качаться между «починили» и «401 Unauthorized».
Начните с токен-аутентификации и дрейфа launchd, затем держите перезапуск шлюза вне сессий агента. Базовые установки: установка и развёртывание; автоматизация здоровья: doctor и диагностика. Вопросы аккаунта: помощь; добавление хостов через цены.
Симптомы, кричащие «раздвоенный токен», а не «плохая модель»
- Раздвоение: CLI успешен, а приложение в строке меню зациклено на настройке.
- 401 только после перезагрузки: у сессии loginwindow нет env, но токен в файле верен.
- 401 после обновления: приложение подняло minor и переписало JSON, а launchd всё ещё экспортирует старую переменную.
- Прерывистый успех: два процесса шлюза на мгновение гонятся с разными конфигами при reload.
Матрица A: откуда каждый клиент читает учётные данные
| Клиент | Основной источник | Типичный дрейф | Стабилизатор |
|---|---|---|---|
| CLI по SSH | Домашний каталог openclaw.json |
Другой $HOME у сервисного пользователя vs админ |
Всегда sudo к сервисному аккаунту перед правкой |
| Приложение macOS | Песочничные настройки + логика слияния JSON | Перезапись мастером после «нет шлюза» | Закреплять версии приложения с change control; открывать приложение только когда файл каноничен |
| Шлюз launchd | EnvironmentVariables plist + файл в рабочем каталоге | Устаревший экспорт OPENCLAW_GATEWAY_TOKEN |
Один скрипт-писатель, обновляющий оба атомарно |
| Агент автоматизации | Унаследованное окружение от родительского shell | Нет токена, когда песочница инструмента срезает env | Явные флаги пути конфига в манифесте инструмента |
Матрица B: риск выката vs смягчение
| Изменение | Радиус поражения | Смягчение |
|---|---|---|
| Ежемесячная ротация токена | Все чат-каналы, пока клиенты не перезагрузятся | Двойная запись старого+нового 15 минут с мониторингом доли 401 |
| Перенос пользователя шлюза | Абсолютные пути и метки plist | Пересоздать symlink; переустановить с паттернами --force из статьи recovery |
| Добавить хост второго региона | Операторы вставляют токен не на тот хост | Имена секретов на хост в vault; не переиспользовать макросы буфера обмена |
| Включить bind не на loopback | Более строгие требования auth | Сочетать с allowlist из лимитов шлюза |
Числовые ограждения
- Перекрытие ротации: держать старый токен валидным минимум 900 с после публикации нового на диск.
- Проверки равенства: автоматический diff env plist vs токен файла каждые 6 ч на прод-шлюзах.
- Бюджет инцидента: если доля 401 > 1 % RPC пять минут — автоматически заморозить обновления приложения.
Совет по GUI: когда запросы приватности macOS блокируют запись токена без присмотра, один раз используйте VNC, одобрите, затем вернитесь к обслуживанию только по SSH.
Восемь шагов внедрения
- Зафиксировать владение каноническим путём файла токена на каждом хосте.
- Убрать дублирующие экспорты из shell, которые борются с launchd.
- Скрипт атомарных обновлений JSON + plist в одной транзакции с путями бэкапа.
- Добавить проверки в стиле CI, падающие при различии хэшей между слоями.
- Документировать пины версий приложения рядом с semver шлюза в строке CMDB.
- Запускать doctor после каждого обновления до объявления «здоров».
- Обучить дежурных читать логи 401 сначала как дрейф конфига, вторым — как падение модели.
- Разделить прод и лаб на разные хосты Mac mini M4 NodeMac, если команды не согласны на одного писателя.
FAQ
Хранить токен в связке ключей лучше?
Может быть, если все потребители поддерживают это согласованно. Смешанные стеки обычно сначала синхронизируют файл+plist, потом мигрируют.
А ноутбуки участников команды?
Никогда не переиспользуйте прод-токены на ноутбуках. Короткоживущие dev-токены и отдельные хосты шлюза избегают случайного прод-RPC из кафе.
Наследует ли launchd мой профиль shell?
Нет. Поэтому токены «исчезают» после перезагрузки, пока вы не скопируете их в plist или файл, который читает шлюз.
Гигиена токенов любит скучное железо: выделенный Mac mini M4 у NodeMac даёт запас Apple Silicon для постоянно включённых шлюзов, поведение нативного macOS, как на ноутбуках разработчиков, и SSH плюс VNC, когда согласие GUI блокирует автоматизацию. С узлами в Гонконге, Японии, Корее, Сингапуре и США можно ставить шлюзы ближе к пользователям, держа секреты вне общих ноутбуков. Аренда вместо покупки дёшево изолирует «прод-шлюз» от «лаб-шлюза», чтобы ротации не превращались в политику. Начните с цен по регионам, когда делите хосты.