Слой OpenAI-совместимого HTTP на OpenClaw Gateway даёт привычные пути /v1/chat/completions и /v1/models, но эксплуатационная правда живёт в трёх местах одновременно: в заголовках, в машиночитаемом openclaw gateway status и в том, как ваш reverse-proxy обращается с долгим потоком ответа. Команда часто проверяет только CLI или только curl с localhost, забывает про --require-rpc и получает «зелёный» статус при том, что внешний клиент ловит 401 или обрыв по тайм-ауту на середине SSE. Интеграторы SDK иногда жёстко задают другой путь к «совместимому» API и тихо добавляют префикс версии, пока шлюз ожидает ровно /v1; такие расхождения не видны в логах модели, их ловят только сравнением полного URL из трейса клиента с тем, что показывает status. Ниже — сценарий приёмки, который можно повторить из тикета: одна и та же пара base URL и токена для HTTP, для RPC-проверки status и для сравнения с выводом CLI. Для смежной линии «HTTP-маршруты плагинов, Docker-песочница и doctor» см.
руководство по OpenClaw 2026.3.x, sandbox и HTTP-плагинам;
для контекста по нагрузке на высокопроизводительных нодах с быстрым NVMe — FAQ по Xcode 26 Compilation Cache и DerivedData на Mac CI.
1. Два входа, один контракт: HTTP и CLI должны сходиться
Когда оператор дергает модель через встроенный CLI-канал, а интеграция — через HTTP, первый источник расхождений — не «битая модель», а разный base path, другой виртуальный хост или прокси, который отрезает префикс /v1. Зафиксируйте в runbook одну строку BASE_URL и один способ подстановки токена. Затем выполните минимальный GET /v1/models и сравните список с тем, что CLI считает доступным для того же профиля. Если HTTP возвращает пустой или урезанный список при «живом» CLI, почти всегда виноваты маршрутизация, а не секрет. Имеет смысл заранее описать, какой из транспортов считается «истиной» для acceptance-тестов: если прод-трафик идёт только по HTTP, то и регрессию потока нужно гонять тем же клиентом, а не вспомогательной утилитой с другим стеком TLS.
/v1/models с тем же Authorization, что и у /v1/chat/completions, — обязательный шаг до любых нагрузочных тестов потока.2. /v1/models как быстрый индикатор auth и маршрута
Эндпоинт моделей дешёв по телу ответа и хорошо кэшируется промежуточными слоями — намеренно используйте это. Снимите два запроса подряд с одинаковыми заголовками и сравните ETag или полное тело: расхождение между «снаружи» и «с loopback на хосте» указывает на другой апстрим или на другой блок gateway.auth для внешнего интерфейса. Не интерпретируйте 401 на completions как «ошибка модели», пока models с тем же токеном не дал однозначный ответ. Дополнительно полезно логировать только длину ответа и код статуса, без полного JSON, чтобы не раздувать журналы и не ухудшать задержку на горячем пути. Если второй запрос внезапно стал быстрее на порядки при неизменном коде, проверьте, не включился ли прозрачный кэш на CDN — он маскирует проблемы ротации токена до первого промаха.
3. Заголовки Authorization, Api-Key и согласование с gateway.auth
Клиенты OpenAI-экосистемы чаще всего шлют Authorization: Bearer …; часть прокладок ожидает Api-Key. Шлюзу важнее стабильный контракт, чем «как привыкли в примере из блога». Зафиксируйте в документации команды ровно один поддерживаемый вариант для внешнего периметра и проверьте, что балансировщик не выкидывает нестандартные заголовки. После смены секрета прогоните два запроса: с намеренно неверным токеном (ожидаемый 401) и с верным — так вы отделяете проблему ротации от проблемы маршрута. Отдельно проверьте, что секрет в CI не содержит перевода строки из-за копирования из веб-консоли: такой дефект даёт «плавающий» 401 только в части job, что выглядит как нестабильность шлюза. Нормализуйте хранение токена в secret manager и запретите ручную подстановку в логируемые артефакты.
4. openclaw gateway status --require-rpc и перекрёстная сверка с curl
Флаг --require-rpc заставляет CLI проверить не только локальную косметику, но и живой RPC-контур, на котором держится согласованность с HTTP-обработчиком. Снимите вывод status в машиночитаемом виде, выпишите фактический endpoint, версию сборки и поля, относящиеся к аутентификации, затем немедленно выполните curl к /v1/models с теми же переменными окружения, что и у сервисного юнита. Если RPC «зелёный», а HTTP даёт 401, ищите расслоение между процессом шлюза и фронтом TLS — другой сокет, другой пользователь окружения или устаревший reload nginx без upstream refresh. Повторите пару из интерактивной оболочки и из того же пользователя, под которым запущен демон: расхождение здесь классически объясняет жалобы «у меня работает, у дежурного нет». Для аудита приложите к тикету оба вывода status и короткий дамп заголовков curl без секрета.
5. Потоковый режим: воспроизводимый тайм-аут между клиентом, прокси и шлюзом
Поток stream: true держит соединение открытым минутами; типичный стек ломается на idle-тайм-ауте балансировщика или на лимите буфера, когда промежуточный слой ждёт «полного» HTTP-тела. Воспроизведение: тот же запрос сначала на loopback без прокси, затем через прод-ingress с включённым логированием времени между чанками. Если обрыв совпадает с кратным значением тайм-аута провайдера (например 60 или 120 секунд), меняйте политику прокси и keep-alive, а не параметры модели. Для длинных сессий разумно вынести генерацию на ноду с запасом RAM и оставить на ingress только короткие health-запросы. Проверьте также, что клиентская библиотека не включает агрессивный read-timeout меньше, чем ожидаемая пауза между чанками при «размышлении» модели: иначе вы увидите обрыв на стороне SDK при полностью исправном шлюзе. Фиксируйте в отчёте p95 интервала между чанками и версию клиента.
6. Таблица «401 и не-401»: не путать симптомы
Зафиксируйте для дежурной смены простую матрицу. 401 на обоих models и chat/completions с одинаковым токеном — почти всегда секрет, часы или запрет заголовка. 401 только на completions при живых models — чаще ограничение политики или отдельный location в nginx. 499 / 502 вместо 401 — клиент закрыл сокет или апстрим сбросил долгий поток; это не авторизация. Такая таблица снимает ложные эскалации к владельцам модели.
- Один токен, два запроса:
/v1/modelsи короткий non-stream completions. - Один и тот же
Host/ SNI в curl, CLI и мониторинге. - Логи прокси с upstream_response_time для потоковых маршрутов.
- Снимок
openclaw gateway status --require-rpcв тикете до и после изменения.
7. Эксплуатация 2026.5.x: npm, внешние плагины и один релизный прогон
В ветке 2026.5.x критично не смешивать глобальный npm-префикс пользователя интерактивного входа с тем, под которым крутится демон шлюза: вы получите «частично обновлённые» плагины и расхождение HTTP-маршрутов после деплоя. После обновления держите один прогон: doctor, затем status --require-rpc, затем smoke-тест /v1/models из CI. Не включайте канареечный трафик на completions, пока models и status не совпали по версии и auth. Если параллельно держите beta-канал для плагинов, явно зафиксируйте fallback на stable в runbook, чтобы ночной автодеплой не оставил шлюз с набором маршрутов, который не совпадает с ожиданиями reverse-proxy. Сохраните хэш lock-файла или точный номер версии пакета в описании релиза — это ускорит откат.
8. Постоянный удалённый высокопамятный Mac под длинный поток
Типичный шаблон для команд без своей стойки — выделенный Mac с большим объёмом ОЗУ как «рабочая лошадь» для агента: шлюз остаётся лёгким, а тяжёлый контекст и длинные потоки уезжают на ноду, где проще держать стабильный launchd-юнит и предсказуемый swap-профиль. Закрепите за машиной фиксированный hostname в конфиге клиентов, отдельный секрет ротации и те же тайм-ауты curl, что и в прод-интеграции; иначе вы снова поймаете «локально работает, из офиса рвёт». Имеет смысл разнести роли: одна нода принимает внешний TLS и ограниченный параллелизм, вторая — длинные сессии с большим рабочим набором; так проще масштабировать наблюдаемость и изоляцию сбоев. Регулярно снимайте снимок vm_stat и загрузки сети в минуты пикового потока, чтобы отличить нехватку RAM от сетевого узкого места.
Почему для такого шлюза и потоковых клиентов удобен Mac mini и macOS
HTTP-шлюз с долгими SSE-сессиями нагружает не столько CPU, сколько память, сеть и дисциплину таймеров в ОС. Mac mini на Apple Silicon даёт высокую пропускную способность памяти и предсказуемый простой по энергии — удобно для круглосуточного сервиса рядом с разработчиками или в периметре малого ЦОД. macOS сочетает нативный стек TLS, привычный launchd для юнитов шлюза и инструменты наблюдаемости без лишних слоёв гипервизора. Gatekeeper, SIP и FileVault снижают класс риска «случайно поставили троян в PATH того же пользователя, что и демон», а компактный корпус и низкий шум упрощают соседство с рабочими местами. Если вы хотите закрепить OpenClaw Gateway и длинные потоки на надёжном железе с запасом по ОЗУ, Mac mini M4 — практичная стартовая точка по совокупной стоимости владения. Чтобы подобрать выделенную облачную машину под такой профиль, откройте главную страницу Macstripe и согласуйте регион и объём памяти с командой.
