OpenClaw · /v1/models · OpenAI‑совместимость · monorepo · удалённый Mac · 2026

2026 OpenClaw на фронтенде:
шлюз /v1/models для OpenAI‑клиентов и смоук по путям monorepo на удалённом Mac

20.04.2026 Шлюз API и монорепозиторий 9 мин чтения
Slug: 2026-openclaw-v1-models-monorepo-smoke-checklist-remote-mac.html

Аудитория: команды, которые ставят OpenClaw перед LLM‑провайдерами и хотят оставить OpenAI SDK и HTTP‑клиенты без изменений. Здесь — как удержать /v1/models предсказуемым на удалённом Mac, связать диффы monorepo с шагами смоука и встроить проверки в PR без опоры на хостинговые цепочки деплоя. Связки: список блога, дисциплина фронтенд‑релиза и ESM, чек‑лист Service Worker для Safari — когда UI и шлюз выходят в одном спринте.

01 Почему /v1/models ломается незаметно

1) Многие клиенты кэшируют список моделей при старте. Шлюз может успешно отдавать chat, но возвращать пустой или некорректный массив data — это всплывает только в селекторах моделей.

2) Частая причина — дрейф пути у обратного прокси: команда проверяет /v1/chat/completions, а SDK вызывает /v1/models с тем же base URL и заголовками.

3) Таблицы алиасов расходятся между пакетами после рефакторинга. Без единого источника шлюз отдаёт идентификаторы, которые внутренние инструменты уже не узнают.

02 Матрица: клиент и шлюз

OpenAI‑совместимые клиенты ожидают стабильную форму JSON. Сверяйте таблицу до выката сборки шлюза.

Тема Клиент Ответственность шлюза
Endpoint GET /v1/models на том же baseURL, что и chat. Тот же TLS и те же middleware авторизации, чтобы curl и SDK совпадали.
Auth Authorization: Bearer …, если не отключено явно. Ранний 401 без секрета; без редиректов, превращающих POST в GET.
Форма ответа object=list и массив data с полями id, object, created, owned_by. Сохранять поля, по которым фильтруют клиенты; расширения документировать.
Алиасы Пользовательские подписи к провайдерским id. Версионировать карту рядом с конфигом шлюза, чтобы переименования не ветвились молча.

Если матрица не сходится, сначала чините маршрутизацию, затем квоты у провайдера.

03 HowTo: установка, маршруты, алиасы, карта monorepo

  1. Установка на удалённом Mac. Клонируйте monorepo, выполните install из корня, поднимите шлюз на той же мажорной версии Node или Bun, что в CI.
  2. Переменные. GATEWAY_BASE — публичный origin, OPENAI_API_KEY — тот же токен, что у клиентов, плюс PROVIDER_* для OpenClaw.
  3. Маршрутизация. Зарегистрируйте GET /v1/models до телеметрии и вспомогательных путей, чтобы порядок обработчиков не ломал список.
  4. Один модуль алиасов. Конфиг шлюза должен импортировать общий пакет, который используют CLI и сервис — тогда переименование модели атомарно.
  5. Карта путей к глубине смоука. Правки в packages/gateway, apps/proxy или общем auth всегда требуют полного зонда моделей; чисто документационные правки — линт без рантайма, если не менялись примеры .env.
  6. Артефакт. Сохраняйте models_smoke.json: HTTP‑статус, миллисекунды ответа, отсортированные id для диффа между ревизиями PR.

04 Исполняемые зонды и параметры

Запускайте на shell удалённого Mac, чтобы ревьюеры воспроизвели отказ один в один.

  • ▸GET моделей: curl -sS -H "Authorization: Bearer $OPENAI_API_KEY" "$GATEWAY_BASE/v1/models" -o models_smoke.json, затем jq '.data[].id' models_smoke.json | sort.
  • ▸Заголовки: curl -sSI "$GATEWAY_BASE/v1/models" — без токена ожидайте 401, а не цепочку редиректов.
  • ▸Дифф: экспорт отсортированных id в файлы с суффиксом GIT_SHA, затем git diff --no-index prior_models.txt current_models.txt.
  • ▸Поиск по коду: rg "v1/models" packages apps -n после рефакторинга Express или Fastify.
  • ▸Chat sanity: одноразовый вызов chat с тем же base URL доказывает, что сессия жива не только для GET.

Нестабильность провайдера признавайте «флаки» только после того, как прямой curl к upstream совпал с телом ответа шлюза.

05 PR: обязательные проверки и связка с OpenClaw

Публикуйте models_smoke.json как артефакт CI, добавьте обязательный чек gateway-models и при ненулевом диффе id оставляйте комментарий в PR со списком. Метка area:models на PR с алиасами подсказывает ревьюерам ожидать зонд.

Для изменений middleware запускайте ту же команду в job на удалённом Mac с теми же переменными, что в проде. Сводку в тред возвращайте с Idempotency-Key вида $GIT_SHA:models:$PR_NUMBER, чтобы повторные прогоны OpenClaw не дублировали сообщения. Такой контур дополняет сценарии с кэшем и SW и не заменяет отдельные задачи по фронту.

06 Три опорных факта для отчёта

Паритет base URL

Корень SDK заканчивается на origin шлюза без лишних сегментов, дублирующих /v1.

Сортировка id

Лексикографически отсортированные id облегчают ревью; неожиданный порядок часто сигнализирует о слиянии двух конфигов.

Область monorepo

Правки шлюза или auth требуют смоука моделей; чистый маркетинг или доки без env‑примеров могут обойтись без рантайма.

07 FAQ: типичные отказы

Симптом Вероятная причина Что сделать
401 на /v1/models Несовпадение Bearer или обрезанный секрет в SSH‑сессии. Сверить ключ с vault, убрать пробелы, повторить curl и сравнить с локальным .env только через менеджер секретов.
HTTP 200 и пустой data Задержка синхронизации у провайдера или фильтр по хостам. Логи шлюза, прямой запрос к провайдеру, проверка квот и ограничений по региону.
Модель в UI есть, в API нет Расхождение алиаса и провайдерского id после рефакторинга пакета. Единый импорт карты алиасов, дифф models_smoke.json между main и веткой.

Держите смоук моделей отдельной дорожкой от сценариев публикации статики: так вы не смешиваете сигналы шлюза с задачами CDN и кэша.

Удалённый Mac · паритет API · смоук monorepo

Арендуйте Mac под проверку шлюза и клиентов

Linux‑only CI не воспроизводит сетевой контур macOS один в один. Запускайте OpenClaw на выделенном Mac: откройте главную, изучите помощь по SSH и VNC без входа, сравните тарифы и оформите аренду или покупку, когда шлюз и фронт выходят в одном цикле.

/v1/models Monorepo Удалённый Mac
Тарифы Помощь Главная
Mac под шлюз /v1/models