Требования к совместимости шлюза

Шлюзы Codex должны сохранять описанное здесь поведение Responses API: конечные точки, потоковую передачу, продолжение диалога, вызовы инструментов, аутентификацию, маршрутизацию и информативные ошибки.

Запросы и конечные точки

Настройте провайдера шлюза с помощью wire_api = "responses". Для базового URL, например https://gateway.example.com/v1, шлюз должен принимать POST /v1/responses и сохранять используемые клиентом поля запросов и ответов. Работающая конечная точка Chat Completions или Anthropic Messages не подтверждает совместимость с Responses.

Конечные точки проверки работоспособности и списка моделей — необязательные вспомогательные средства эксплуатации. Они не проверяют диалог Codex и не подтверждают поддержку инструментов.

Потоковая передача

Передавайте события сервера (SSE) по мере поступления, не буферизуя весь ответ. Сохраняйте типы событий и их полезные нагрузки, включая завершающее событие response.completed при успешном выполнении. Передавайте события ошибок и сбоев, чтобы клиент мог отличить неудачный ответ от зависшего соединения.

Проверяйте весь поток не только через шлюз, но и через балансировщики нагрузки и обратные прокси. Текстового ответа без завершённого потока недостаточно.

Продолжение диалога

Сохраняйте повторно передаваемые входные данные диалога при последующих ходах. Шлюз должен принимать предыдущие сообщения, вызовы инструментов и результаты инструментов, необходимые для следующего хода.

Если вы включаете WebSocket или инкрементальный транспорт, также проверяйте поведение previous_response_id. Маршрут HTTP Responses без сохранения состояния может использовать повторно переданные входные данные, не требуя этого механизма продолжения.

Инструменты

Сохраняйте элементы вызовов функций и соответствующие им элементы function_call_output, включая идентификаторы, связывающие вызовы с результатами. Должен работать полный цикл: Codex получает вызов, выполняет инструмент, отправляет его результат и получает окончательный ответ.

Успешный текстовый запрос не проверяет этот цикл. Тестируйте именно те модели и возможности клиента, которые планируете включить. То, что шлюз принимает поле запроса, не доказывает, что модель вышестоящего провайдера реализует соответствующую возможность.

Аутентификация и заголовки

Поддерживайте выбранный для развёртывания механизм аутентификации клиента: env_key или bearer-токены, получаемые через команду, либо env_http_headers для учётных данных, передаваемых в пользовательском заголовке. Используйте переменные окружения для секретных значений заголовков; не прописывайте их непосредственно в конфигурации. См. справочник по пользовательским провайдерам, где описаны конфигурация и контракт вспомогательной программы для получения учётных данных.

Аутентифицируйте разработчиков отдельно от учётной записи шлюза у вышестоящего провайдера. Храните ключи администратора и учётные данные вышестоящего провайдера на шлюзе. Сохраняйте заголовки, от которых зависят маршрутизация и атрибуция, и проверяйте истечение срока действия, продление и отзыв учётных данных.

Маршрутизация моделей и метаданные

Каждое имя модели для Codex должно направлять запросы к нужной модели вышестоящего провайдера. Проверяйте маршрут по записям шлюза, не полагаясь на то, как модель описывает себя.

Используйте имя, распознаваемое развёрнутой версией Codex, или предоставьте соответствующий каталог для пользовательского псевдонима. Также проверьте метаданные доступности моделей и миграции: любая модель для замены должна быть доступна через шлюз. Для принадлежащего организации псевдонима без миграции задайте в его записи каталога для upgrade значение null. Метаданные каталога определяют поведение клиента; они не добавляют модели возможностей и не создают маршруты шлюза. Сверяйте ограничения контекста, параметры рассуждения и инструменты с фактической моделью вышестоящего провайдера и самим провайдером. Обычное подключение через шлюз не получает автоматически корректировки метаданных, которые вносят встроенные интеграции Codex с провайдерами.

Распознаваемые имена моделей

Используйте точное имя модели, распознаваемое вашей развёрнутой версией Codex, в качестве псевдонима шлюза и значения model в Codex. Убедитесь, что вышестоящий провайдер поддерживает модель и ваша организация разрешает её использование.

Проверьте codex --version и выберите соответствующий тег rust-v<version> в каталоге моделей Codex. Для пользовательской сборки используйте коммит её исходного кода; при развёртывании настольного приложения ориентируйтесь на версию встроенного CLI. Проверьте значения slug в записях, чтобы найти имена, которые распознаёт эта версия. Если шлюз меняет возможности модели, предоставьте метаданные каталога, отражающие эти отличия, даже если имя распознаётся.

Ошибки

Сохраняйте информативные различия между ошибками аутентификации клиента, неизвестными маршрутами моделей, ограничениями частоты запросов и сбоями вышестоящего провайдера. Не сводите все сбои к общему ответу 500. Возвращайте достаточно информации для диагностики уровня, на котором возник сбой, не раскрывая токены, учётные данные провайдера или чувствительное содержимое запросов.

Границы передачи данных и работы инструментов

Трафик модели проходит по следующему пути:

Codex client -> LLM gateway -> model provider

Клиент аутентифицируется на шлюзе с помощью учётных данных разработчика. Шлюз использует свои учётные данные вышестоящего провайдера для доступа к модели. Запросы пользователя, фрагменты исходного кода, аргументы инструментов и результаты инструментов, включённые в запросы к модели, могут проходить через шлюз. Настройте журналирование, хранение, скрытие чувствительных данных, доступ и контроль экспорта соответствующим образом.

Шлюз моделей не маршрутизирует все подключения Codex. Локальные команды выполняются в среде исполнения клиента. MCP servers, сервисы плагинов, взаимодействия с браузером и приложениями, а также другие включённые сервисы могут использовать отдельные сетевые пути и учётные данные. Конфигурация провайдера модели не предоставляет эти разрешения и не заменяет средства контроля их сетевого доступа. См. Подтверждения действий агента и безопасность и MCP, где описаны эти границы.

Контрольный список проверки пригодности

Зафиксируйте подтверждения для каждой развёрнутой комбинации клиента, шлюза и модели:

• Поля запросов и ответов Responses.
• Постепенная доставка SSE и успешное завершение потока.
• Последующие ходы с повторной передачей входных данных.
• previous_response_id, если выбранный транспорт его использует.
• Вызовы функций, соответствующие результаты и окончательный ответ.
• Корректная маршрутизация моделей и соответствующие метаданные.
• Атрибуция по пользователям, продление и отзыв учётных данных.
• Информативные ошибки аутентификации, маршрутизации, ограничений частоты запросов и вышестоящего провайдера.
• Диагностические данные со скрытой чувствительной информацией и предусмотренная политика журналирования.

Используйте процедуру тестирования при внедрении, чтобы собрать эти подтверждения до распространения конфигурации.