OPENCLAW_GATEWAY_TOKEN как SecretRef, doctor и config validate, матрица listen и отказы при «голом» нелокальном bind.
Связанные публичные материалы: усиление безопасности шлюза, ворота validate в CI, неинтерактивный onboard и env.
Почему только loopback ломает сценарии удалённого Mac
На выделенном или пуловом удалённом Mac шлюз часто вызывают агенты CI, скрипты на соседней подсети или обратный прокси на том же хосте. Дефолт в духе «слушать только localhost» упрощает локальную разработку, но в продакшен-контуре он превращается в источник ложных предположений: curl из интерактивной оболочки работает, а job без port-forward падает.
- Расхождение PATH. В интерактиве стоят nvm или Homebrew shims, у
launchd— урезанный PATH и другой набор переменных: токен вы экспортировали в сессии, но демон его не унаследовал. - Широкий bind без политики. Включение listen на LAN-интерфейсе без обязательного bearer и файрвола противоречит разделам security в актуальной документации OpenClaw; процесс может завершиться на старте как защитный отказ.
- Связка с прокси-pull. Тот же Mac тянет npm, PyPI или контейнерные слои через корпоративный прокси: мёртвый шлюз блокирует и вебхуки, и предварительные хуки установки; ранняя проверка токена экономит минуты параллельных job.
Матрица: область listen и требования к токену
| Паттерн listen | Типичное применение | Токен и сеть |
|---|---|---|
127.0.0.1 только |
Локальные прогоны doctor, sidecar reverse-proxy на том же Mac | Часто всё равно задавайте OPENCLAW_GATEWAY_TOKEN, если клиенты и инструменты бьют в HTTP API шлюза по документации. |
| Интерфейс VPN или site-local | Агенты CI в одном tailnet без публикации в интернет | Сочетайте bearer с ACL на уровне tailnet и ротацией токена при изменении членства. |
| LAN IP не loopback | Вебхуки из соседней сборочной подсети | Обязательны непустой токен, ограничение источников и согласование формулировок с официальным разделом security для вашей минорной версии. |
Минимально воспроизводимые шаги
Шаг 1. Установите Node.js 22.14 LTS или Node 24 той же политикой, что закреплена у OpenClaw в релиз-нотах. Первая строка каждого job — node -v, чтобы дрейф образов был виден в логах.
Шаг 2. Поставьте CLI: официальный install-скрипт (curl) из раздела установки на docs.openclaw.ai или закреплённый диапазон npm install -g openclaw@^…, одобренный security. Сразу выполните command -v openclaw и openclaw --version. Если на чистом раннере всплывает bootstrap Homebrew, один раз соберите verbose-трассу и зашейте brew в golden-образ по материалу onboard без диалога.
node -v npm install -g "openclaw@^2026.3.0" command -v openclaw openclaw --version
Шаг 3. Задайте уникальные OPENCLAW_HOME и OPENCLAW_CONFIG_HOME на каждый job или инстанс демона, chmod 700 на дерево конфигурации.
Шаг 4. Пробросьте секрет так же, как SecretRef в Kubernetes превращается в переменные процесса: в GitHub Actions — блок env:, в Azure DevOps — секретные переменные, в macOS — EnvironmentVariables в plist launchd. Стандартизируйте имя OPENCLAW_GATEWAY_TOKEN для входящего HTTP к API шлюза. Не копируйте значение в комментарии PR и markdown-сводки.
Шаг 5. Меняйте listen на не-loopback только после чтения официальных подразделов про gateway listen, TLS и exposure. Если TLS терминирует nginx или Caddy, разумно держать процесс OpenClaw на loopback и проксировать уже аутентифицированный поток. После атомарного изменения plist выполните цикл unload и load один раз.
Шаг 6. Запустите openclaw doctor, затем openclaw config validate с явным путём к JSON; объедините потоки в один артефакт CI по образцу ворот validate. Проверьте health/status через curl с заголовком Authorization: Bearer и без него: ожидайте различие кодов согласно политике.
export OPENCLAW_GATEWAY_TOKEN="$(cat "$RUNNER_TEMP/gw.token")"
openclaw doctor
openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json"
curl -fsS -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
"http://127.0.0.1:18789/v1/health"
Отказ запуска без аутентификации: типичные сообщения и официальный troubleshooting
Upstream блокирует небезопасные комбинации: stderr про отсутствие учётных данных или запрещённый bind — предохранители. Сверяйте формулировки с документацией вашей минорной версии.
| Симптом или фрагмент лога | Вероятная причина | Исправление в духе официальных разделов |
|---|---|---|
| Процесс выходит сразу после расширения bind за пределы loopback | Пустой OPENCLAW_GATEWAY_TOKEN при включённой нелокальной экспозиции |
Заполните переменную из vault, перезагрузите job или plist, перечитайте раздел security. |
| HTTP 401 на health или маршрутах инструментов из CI | Нет заголовка Authorization или опечатка в схеме Bearer | Выровняйте curl/SDK с документацией; проверьте отсутствие лишнего перевода строки при копировании токена. |
doctor зелёный в shell, демон не стартует |
В plist launchd нет новой переменной окружения |
Сравните блок EnvironmentVariables с логом CI, атомарно обновите plist, unload/load один раз. |
config validate печатает неверные ключи JSON |
Ручное редактирование конфига разошлось со схемой | Запускайте validate до merge; храните tarball-чекпойнты из статьи про ворота validate. |
Жёсткие паттерны egress и TLS описаны в руководстве по hardening; сопоставляйте сообщения с релиз-нотами вашей ветки.
Чеклист перед включением нелокального listen
- В логе зафиксированы Node 22.14+ или 24 и semver
openclaw. - Путь к
openclawвlaunchdсовпадает с тем, что показал CI (whichне из nvm-обёртки). OPENCLAW_GATEWAY_TOKENприсутствует в контексте listen и нигде не эхоится.- Файрвол пропускает только задокументированные CIDR или tailnet.
- Один объединённый лог doctor плюс validate без красных сигнатур.
curlhealth с Bearer даёт ожидаемый успех, без Bearer — ожидаемый отказ.
Ценность для CI и прокси-pull на том же удалённом Mac
Шлюз на том же Mac, что и прокси-pull npm/PyPI, даёт тёплый DNS и общий TLS-контур для вебхуков и установок. Bearer-check на health ловит misconfig до массовых таймаутов job; лишний hop на отдельную VM на трансграничных каналах дороже.
Резюме и покупка доступа к Mac
Итоговый контур: Node 22+, установщик или глобальный npm, переменные в стиле SecretRef, осторожное расширение listen, таблица отказов и пара команд doctor плюс validate с HTTP-зондом. Когда нужен долгоживущий Apple Silicon под шлюз и тяжёлые CI-потоки с прокси, откройте публичные страницы MacPull: цены, покупка и аренда, центр помощи, консоль и каталог блога — без обязательного входа для чтения.