Предварительные условия (Node 24 / шлюз)
Шлюз, TLS-терминация и self-hosted раннер должны согласовывать одного и того же UNIX-пользователя: тогда launchd, неинтерактивные shell-шаги CI и ручная отладка по SSH читают одинаковые PATH, файлы окружения и каталоги логов.
- Node 24 LTS закрепите через
.node-version, nvm по умолчанию для сервисной УЗ или контейнерный pin; в неинтерактивной сессии обязательно проверьтеnode -v. - Для каждого апстрима заранее опишите исходящий HTTPS, единый
HTTPS_PROXYгде нужно и явныйNO_PROXYдля внутренних зон. - Файлы с ключами и токенами — только
chmod 600, вне Git; путь к логам шлюза зафиксируйте в runbook рядом с портом и bind-адресом.
Выделенный удалённый Mac под шлюз и кеши даёт один контур сети для pull кода и вызовов моделей и уменьшает разрыв между «зелёным» health и реальным чатом.
Установка и ключевые моменты
Один официальный канал установки CLI зафиксируйте в документации, чтобы релизы не расходились между ноутбуком и продом.
openclaw onboard— каталоги, порт, автозапуск.openclaw doctorпосле обновлений macOS или смены корневых сертификатов.- Прокси передаёт
HostиX-Forwarded-Proto; reload — по runbook. - Текстовый профиль шлюза рядом с YAML: публичный URL, bind, путь логов.
Таблица шагов: несколько OpenAI-совместимых эндпоинтов и маршрутизация
Совместимые API похожи по схеме, но отличаются model id, квотами и auth. Таблица — каркас runbook; третий столбец заполните своими env и владельцами.
| Шаг | Действие | Запись в runbook | Критерий готовности |
|---|---|---|---|
| 1 | Инвентаризация апстримов (облако A, on-prem B, аварийный регион C). | Таблица base URL, владелец, лимиты стоимости и токенов. | Каждый URL отвечает на curl в пределах восьми секунд без пустого TCP. |
| 2 | Ввести логические псевдонимы (fast, cheap, local). |
Матрица псевдоним → реальный model id, версия в Git без секретов. | Два инженера независимо трактуют псевдоним одинаково. |
| 3 | Регистрация авторизации: Bearer, кастомные заголовки, mTLS. | Путь к env-файлу на узле и дата ротации ключа. | После reload в логе есть успешные тестовые вызовы по каждому апстриму. |
| 4 | Правила маршрутизации: префикс модели, тег тенанта, метка CI job. | Упорядоченный список правил и безопасный fallback по умолчанию. | Искусственный промах правила уводит на ожидаемый запасной маршрут за один хоп. |
| 5 | Circuit breaker на серии 429 и 5xx. | Порог срабатывания и длительность cooldown в минутах. | При симулированном 503 трафик переключается без ручного рестарта всего шлюза. |
| 6 | Формальное одобрение нового вендорского endpoint. | Шаблон тикета с чеклистом ИБ и ссылкой на DPIA при необходимости. | Последние три изменения в Git содержат идентификатор тикета. |
Пример раскладки имён (подставьте свои пути и ключи):
Короткие упорядоченные правила и шаблон конфига проще ревьюить, чем один огромный JSON.
Проверка /health
Используйте лёгкий маршрут вроде /health, /healthz или /ready, который не дергает платные вызовы ко всем моделям подряд. Глубокие проверки вынесите на редкий cron или отдельный операторский endpoint.
launchd с ThrottleInterval и логами в ~/Library/Logs даёт ранний сигнал; статусы апстримов из JSON health удобно слать в метрики. Детали — в гайде по LaunchAgent.
Связка с CI: webhook и краткое резюме логов
После правок инфраструктуры в CI полезно сохранять не только exit 0, но и какие апстримы отвечали, без ручного обхода Mac по SSH.
Вариант A — сводка шага GitHub Actions. Если задан GITHUB_STEP_SUMMARY, добавьте компактный markdown с профилем шлюза, усечённым JSON health и хвостом лога.
Маскируйте секреты в логах платформы, в тексте оставляйте только псевдонимы и версии конфигурации.
Вариант B — webhook. Подписанный JSON в автоматизацию шлюза и дубль в мессенджер; см. FAQ по Telegram и Slack.
Один канал к зеркалам и API, меньше расхождения кеша и вызовов моделей; в сводке CI видны активные маршруты — R&D реже гадает про инфраструктуру.
Частые ошибки: FAQ
Апстрим отвечает 401, хотя в Postman тот же ключ принимается
Ищите двойной префикс Bearer, устаревшие переменные в plist launchd и расхождение пользователя между интерактивной zsh и демоном. Сверьте окружение в минимальном скрипте воспроизведения.
Обновили правила маршрутизации, но трафик идёт по старой схеме
Проверьте что перезагружен именно рабочий процесс, освободите порт через lsof -i :PORT и повторите openclaw doctor.
/health успешен, а диалоги «висят»
Health мог быть слишком поверхностным; выполните короткий завершённый запрос к каждому апстриму с малым лимитом токенов и проверьте TLS, HTTP/2 и корпоративный MITM.
В сводке CI нечитаемые символы
Скорее всего в summary попали не-UTF-8 байты из сырого лога. Копируйте только выбранные поля JSON или пропускайте текст через фильтр; ключи API в сводку не включайте.
Node 24, doctor, версионируемая маршрутизация, /health и короткие сводки в CI превращают несколько совместимых эндпоинтов в управляемую зависимость. Стабильный шлюз на удалённом Mac связывает pull и вызовы моделей. Ещё статьи — блог.
Стабильный шлюз — быстрее R&D и автоматизация
Главная, покупка, центр помощи и блог доступны без входа. Тарифы узлов — на странице цен.