Развёртывание шлюза
Распространите настройки подключения Codex через шлюз в вашей организации и проверьте подключение
Как администратор шлюза настройте маршруты к моделям и предоставьте доступ участнику пилотного тестирования. Прежде чем распространять настройки среди разработчиков, проверьте подключение в каждом поддерживаемом клиенте. Для аутентификации на шлюзе используйте встроенную поддержку OAuth, API key или вспомогательные программы получения учётных данных. Чтобы совместить аутентификацию на шлюзе со входом в рабочее пространство ChatGPT, см. раздел Вход с помощью ChatGPT через шлюз.
Предварительные требования
Прежде чем развёртывать Codex для разработчиков, убедитесь, что у вас есть:
- Шлюз, обслуживающий HTTPS по тому самому базовому URL, который вы будете распространять.
- Учётные данные вышестоящего провайдера, хранящиеся на шлюзе.
- Одобренные псевдонимы моделей для Codex, сопоставленные с нужными моделями вышестоящего провайдера.
- Проверенный метод аутентификации: собственный OAuth шлюза, API keys шлюза с ограниченной областью доступа или вспомогательная программа для учётных данных.
- Для OAuth — зарегистрированный публичный клиент, одобренные тестовые пользователи и поддержка шлюзом проверки токенов доступа OAuth.
- Для API keys или вспомогательных программ — механизм доставки секретов или проверенная вспомогательная программа.
- Способ распространения конфигурации, необходимых вспомогательных программ и файлов каталога.
Требования к шлюзу
Перед подключением Codex убедитесь, что используемый шлюз обеспечивает следующее обязательное поведение:
- Принимает запросы Codex к Responses API по адресу
POST /v1/responses. - Передаёт поток событий SSE без буферизации и завершает его событием
response.completed. - Сохраняет возможность продолжения диалога с повторной передачей входных данных.
- Сохраняет
previous_response_idтолько при включённом WebSocket или инкрементальном транспорте. - Сохраняет вызовы функций и соответствующие элементы
function_call_output. - Направляет каждый псевдоним модели для Codex к нужной модели вышестоящего провайдера.
- Аутентифицирует пользователей по отдельности и возвращает информативные ошибки, не скрывая их причину.
Наличие конечной точки проверки работоспособности, /v1/models, ответа Chat Completions или одного текстового ответа не подтверждает пригодность шлюза. Подробный контракт см. в разделе Требования к совместимости шлюза.
Внедрение шлюза
Чтобы перейти от развёрнутого шлюза к проверенной рабочей среде разработчика, последовательно пройдите эти пять этапов:
- Выберите имена моделей и проверьте маршруты.
- Выберите способ аутентификации.
- Протестируйте Codex через шлюз.
- Распространите конфигурацию.
- Выполните проверку с компьютера разработчика.
Выбор имён моделей и маршрутов
Задайте для model в Codex имя модели на шлюзе. Настройте шлюз так, чтобы это имя направляло запросы к утверждённой модели вышестоящего провайдера.
| Имя модели в шлюзе | Конфигурация Codex |
|---|---|
| Встроенное имя модели, включённое в вашу версию Codex | Задайте для model в config.toml это точное имя. |
Пользовательский псевдоним, например company-coding-model |
Предоставьте удалённый или локальный каталог с псевдонимом и метаданными соответствующей модели. |
Использование каталога моделей для пользовательских имён
Для локального каталога начните с примера models.json.
Предоставьте каталог моделей, если шлюз использует имя модели, которое Codex не распознаёт. Каталог содержит инструкции, параметры рассуждения, ограничения контекста и возможности инструментов, используемые Codex для этого имени. Если соответствующей записи нет, запрос может поступить к нужной вышестоящей модели, но Codex будет использовать общие настройки.
Разместите удалённый каталог с помощью model_providers.<id>.model_catalog_url для централизованного обновления метаданных моделей или распространите локальный файл с помощью model_catalog_json. Используйте локальный каталог, если единственный способ аутентификации на шлюзе — его собственный OAuth; одного OAuth недостаточно для обнаружения удалённого каталога. Обе настройки описаны в справочнике по конфигурации.
Получите у поставщика облачных услуг или шлюза конечную точку каталога либо файл, совместимые с вашей версией Codex. Убедитесь, что каталог содержит каждый утверждённый псевдоним и метаданные соответствующей модели. Подробнее о реализации каталога см. в разделе Реализация каталогов моделей для шлюзов и облачных платформ.
Предоставление удалённого каталога
Используйте конечную точку каталога HTTPS, предоставленную вашим поставщиком.
Укажите полный URL конечной точки в таблице config.toml выбранного поставщика в распространяемой конфигурации:
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"Сделайте CODEX_GATEWAY_API_KEY доступной для процесса Codex. Задайте base_url
отдельно, чтобы направлять запросы на выполнение модели через шлюз. Если этот параметр не указан, Codex использует
конечную точку OpenAI по умолчанию для текущего режима аутентификации.
Для обнаружения требуется аутентификация с помощью API key, команды или серверной части Codex. Собственный OAuth шлюза или одни лишь пользовательские заголовки не запускают обнаружение.
При изменении набора утверждённых моделей согласуйте обновления каталога с поставщиком. Перезапустите клиент после изменения его конфигурации.
Удалите все действующие параметры model_catalog_json, включая заданные принудительно через
requirements.toml. Они имеют приоритет над удалённым URL-адресом и препятствуют получению данных.
Распространение локального каталога
Используйте model_catalog_json для загрузки предоставленного поставщиком файла при запуске. Локальный пользовательский
каталог заменяет встроенный каталог.
Задайте для псевдонима шлюза, slug в каталоге и model в Codex значение company-coding-model. Добавьте эти настройки перед первой таблицей TOML в распространяемой конфигурации Codex, указав фактический абсолютный путь к файлу:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"После изменения каталога перезапустите CLI или настольное приложение, поскольку Codex загружает каталог при запуске.
Проверка маршрутов моделей
Для каждой модели проверьте маршрут с помощью реального запроса Responses и записей
шлюза. Ответ /v1/models может помочь найти имена, но не доказывает, что
модель поддерживает требуемое поведение запросов и инструментов.
Маршрутизация моделей и авторизация инструментов — отдельные части внедрения. Настраивайте подключения MCP, распространение плагинов и их политики отдельно.
Выберите способ аутентификации
Собственный OAuth шлюза
- Зарегистрируйте публичный клиент OAuth, поддерживающий поток кода авторизации с PKCE, и одобрите пользователей или группы, которым разрешён вход.
- Настройте шлюз для проверки выданного токена доступа в выбранном cookie или пользовательском заголовке. Привяжите одобренные модели, ограничения частоты запросов и бюджеты к учётной записи каждого пользователя.
- Следуйте инструкциям в разделе Собственный OAuth шлюза, чтобы собрать URL авторизации и получения токенов, ID публичного клиента, области доступа, необязательный ресурс, настройки передачи токенов и фиксированный порт перенаправления, если он используется. Зарегистрируйте соответствующий URI перенаправления на петлевой адрес у своего провайдера удостоверений.
- Проверьте вход через браузер, обновление токенов и отзыв доступа с тестовым пользователем в CLI или настольном приложении, которое планируете развернуть. Убедитесь, что браузеру доступен адрес обратного вызова, в том числе для удалённых пользователей CLI.
Каждый пользователь входит самостоятельно. Вы распространяете конфигурацию OAuth, а не секрет клиента, API key шлюза или исполняемый файл вспомогательной программы. Храните учётные данные вышестоящего провайдера на шлюзе.
API keys или вспомогательные программы для учётных данных
- Выдайте каждому разработчику отдельные учётные данные шлюза с ограниченными правами, чтобы отслеживать использование и отзывать доступ индивидуально.
- Задайте разрешённые модели, ограничения частоты запросов, бюджет, срок действия и период продления для каждых учётных данных.
- Доставляйте учётные данные через менеджер секретов или установленную вспомогательную программу. Не размещайте учётные данные вышестоящего провайдера и администратора шлюза на компьютерах разработчиков.
- Если вы используете вспомогательную программу, соблюдайте контракт аутентификации через команду и до распространения проверьте получение и обновление токенов.
- Сообщите разработчикам, как продлевать учётные данные и к кому обращаться за помощью.
Тестирование Codex через шлюз
Перед распространением следуйте инструкциям в разделе Настройка провайдера, чтобы настроить одного изолированного тестового пользователя с блоком провайдера и методом аутентификации, которые вы планируете распространять.
Если шлюз предоставляет каталог моделей, убедитесь, что он возвращает совместимый с Codex массив models. При выполнении инференса OpenAI с учётными данными пользователя убедитесь, что шлюз пересылает необходимые заголовки ChatGPT в серверную часть Codex.
Зафиксируйте версию клиента, операционную систему, идентификатор провайдера, псевдоним модели и способ аутентификации для пилотного тестирования. Выполните приведённые ниже проверки в каждом интерфейсе CLI или настольного приложения, который планируете поддерживать. Если вы предлагаете как аутентификацию только на шлюзе, так и аутентификацию на шлюзе вместе со входом в ChatGPT, проверьте каждое сочетание отдельно.
| Проверка | Действие | Признаки успешного прохождения |
|---|---|---|
| Действующая конфигурация | Проверьте слои конфигурации и убедитесь, что используются нужные провайдер, модель и требования. | В пилотном проекте используются распространённые настройки. Пользовательские настройки или настройки профиля по умолчанию не выбирают другой маршрут. |
| Подключение | Следуйте инструкциям в разделе Проверка подключения. | Активны ожидаемые провайдер и псевдоним, тестовый запрос выполняется успешно, а журналы шлюза позволяют определить тестового пользователя. |
| Потоковая передача | Запросите короткий ответ из нескольких абзацев. | Текст поступает постепенно, а активный транспорт выдаёт response.completed. Отдельно протестируйте HTTP, чтобы убедиться, что шлюз пересылает события SSE без буферизации. |
| Цикл работы с локальными инструментами | Во временной папке с доступом только для чтения попросите Codex перечислить файлы верхнего уровня и кратко описать их. | Codex выполняет вызов локального инструмента, возвращает результат и выдаёт окончательный ответ без внесения изменений. |
| Последующий запрос | Задайте дополнительный вопрос в той же ветке. | Ответ учитывает предыдущий обмен сообщениями; шлюз принимает повторно переданные входные данные. Если включён WebSocket или инкрементальный транспорт, он также сохраняет previous_response_id. |
| Ошибки и привязка запросов к пользователю | Повторите проверку с заведомо неверным тестовым псевдонимом или просроченными тестовыми учётными данными. | Клиент получает информативную ошибку маршрутизации или аутентификации, а корректные запросы по-прежнему привязаны к тестовому пользователю. |
Если включено автоматическое одобрение, используйте временную тестовую папку, чтобы вызвать действие инструмента, требующее проверки согласно выбранной политике. Убедитесь, что шлюз обрабатывает запрос на проверку, а клиент применяет решение об одобрении. Вызов инструмента только для чтения, не требующий одобрения, не проверяет этот сценарий. Перед расширением пилотного проекта зафиксируйте все неподдерживаемые рабочие процессы.
Если при внедрении меняется провайдер для существующих пользователей, протестируйте новый диалог и диалог, созданный до изменения, в каждом поддерживаемом клиенте. Зафиксируйте, могут ли пользователи просматривать и продолжать существующий диалог, а также создавать его ответвления, и предоставьте инструкции по восстановлению работы для всех заблокированных сценариев. Не считайте, что смена провайдера по умолчанию переносит историю диалогов.
После успешного прохождения этих проверок подготовьте информацию для передачи разработчикам.
Распространение конфигурации
Чтобы все компьютеры подключались по одному и тому же маршруту, распространите базовый URL шлюза, ID провайдера, одобренный псевдоним модели и настройки аутентификации.
Что распространять
Для собственного OAuth шлюза распространите таблицу провайдера и таблицу
[model_providers.<id>.gateway_oauth] из руководства по
подключению с
собранными выше регистрационными значениями. Сохраните requires_openai_auth = false и исключите
env_key, experimental_bearer_token и таблицу auth для аутентификации через команду, если
OAuth — единственный способ аутентификации на шлюзе.
Для вспомогательной программы для учётных данных распространите следующий блок config.toml через
выбранный вами уровень конфигурации. Используйте модель, которую распознаёт ваша версия Codex, или
предоставьте соответствующий каталог, описанный выше. Установите программу получения токенов по
пути, указанному в настройке команды:
model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Для краткосрочного статического тестового ключа удалите блок аутентификации, поместите env_key = "CODEX_GATEWAY_API_KEY" внутрь [model_providers.enterprise-gateway] и задайте эту переменную вне TOML. Не сочетайте env_key с аутентификацией через команду.
Распространение настроек по умолчанию и обязательных требований
Если ваши пользователи не входят в Codex через ChatGPT, вы можете распространять настройки команды со своего сервера. Codex получает эти настройки независимо от того, как вы маршрутизируете запросы к моделям.
Используйте раздел Приоритет конфигурации, чтобы выбрать, где распространять настройки по умолчанию. Принудительно применяемые настройки и полезные нагрузки MDM для macOS описаны в разделе Управляемая конфигурация.
Для настроек по умолчанию на уровне компьютера в macOS или Linux используйте /etc/codex/config.toml. В
Windows разместите config.toml в %ProgramData%\OpenAI\Codex\. Пользователи и
профили могут переопределять эти настройки. Материалы по ссылкам описывают поддерживаемые
требования и расположение соответствующих файлов.
Распространяйте все упомянутые вспомогательные исполняемые файлы и локальные файлы каталогов отдельно.
Чтобы принудительно задать URL-адрес удалённого каталога, поместите полное определение провайдера в
requirements.toml в разделе [model_providers.<id>]. Принудительно заданное определение
провайдера заменяет соответствующую таблицу провайдера из обычной конфигурации;
включите в него base_url, параметры аутентификации и другие обязательные поля.
Используйте требование model_provider, если также необходимо принудительно задать выбор
провайдера.
model_catalog_json указывает на локальный файл JSON. Если вы принудительно задаёте его через
requirements.toml, требование фиксирует путь, но не распространяет сам
файл. Разместите каталог по этому абсолютному пути до запуска Codex.
Указывайте в TOML полностью определённые абсолютные пути Windows. Codex не раскрывает
%ProgramData% внутри значений model_catalog_json или command аутентификации провайдера. Например,
используйте следующие пути, только если при развёртывании файлы были размещены именно там:
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]CLI внутри WSL читает пути Linux и CODEX_HOME для Linux; он не наследует автоматически
собственную конфигурацию Windows.
Распространение заголовков маршрутизации
Если ваш шлюз маршрутизирует запросы по конфигурации или инструменту, добавьте ожидаемые им заголовки в настройки провайдера в управляемом файле requirements.toml. В следующем примере передаётся ID конфигурации маршрутизации и указывается, что клиентом является Codex:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Используйте env_http_headers для значений заголовков, получаемых из окружения клиента. Отправьте тестовый запрос и проверьте выбранный маршрут в журналах шлюза. Варианты настройки заголовков описаны в разделе Пользовательские провайдеры моделей.
Передача значений конфигурации разработчикам
Предоставьте разработчикам один способ настройки, соответствующий протестированному пилотному проекту. Включите следующую информацию, даже если конфигурация распространяется централизованно:
| Передаваемые сведения | Что предоставить |
|---|---|
| Одобренный клиент | Клиент, версию, операционную систему и инструкции по установке или обновлению, использованные в пилотном проекте. |
| Доставка конфигурации | Укажите, управляются ли настройки централизованно или требуется локальная настройка; перечислите вспомогательные программы и файлы каталога, устанавливаемые отдельно. |
| Ожидаемое подключение | ID провайдера, псевдоним модели и URL шлюза, включая путь API. Объясните, какие значения пользователи могут менять. |
| Порядок входа | Укажите, должны ли пользователи входить в рабочее пространство ChatGPT, проходить аутентификацию на шлюзе или выполнять оба действия. Назовите нужное рабочее пространство и способ аутентификации на шлюзе. |
| Учётные данные и каталоги | Параметры регистрации OAuth, переменную окружения с учётными данными или конфигурацию установленной вспомогательной программы, а также URL каталога или полученный локальный путь. Передавайте секреты через одобренный механизм распространения секретов. |
| Проверка и поддержка | Тест подключения, ожидаемый результат, ответственного за шлюз и сведения, которые нужно включить в сообщение о сбое. |
Для управляемых компьютеров направьте разработчиков к разделу Проверка существующей конфигурации. Для ручной настройки — к разделу Настройка провайдера.
Если при внедрении меняется провайдер, включите проверенные инструкции по работе с существующими диалогами. Сохраните предыдущую рабочую конфигурацию в доступном для ответственного за внедрение месте на случай, если пилотный проект выявит проблему.
Ручная настройка не обеспечивает принудительное применение требований. Локальный для проекта .codex/config.toml не может переопределять чувствительные ключи маршрутизации провайдера или аутентификации.
Проверка на компьютере разработчика
Чтобы убедиться, что распространяемые настройки дошли до компьютера разработчика:
- Убедитесь, что установлены одобренный клиент и все необходимые вспомогательные программы или файлы каталога. Перезапустите Codex и выполните вход согласно переданным инструкциям.
- Убедитесь, что используются ожидаемые провайдер и модель. В CLI используйте
/status. Используйте/debug-configдля проверки слоёв конфигурации, если действующие настройки отличаются от переданных. - Выполните короткий тест из раздела Подключение к шлюзу.
- Задайте один дополнительный вопрос, чтобы проверить продолжение диалога, затем найдите в журналах шлюза запрос этого разработчика.
Расширяйте доступ после успешного прохождения пилотного проекта во всех поддерживаемых сочетаниях клиентов и способов аутентификации. Храните протестированную конфигурацию и результаты вместе с инструкциями по внедрению, чтобы повторять проверки после обновления клиента, шлюза или политик.
Устранение сбоев при внедрении
По характеру проблемы определите, какой уровень требует внимания: конфигурация, учётные данные или шлюз:
| Проблема | Способ устранения |
|---|---|
| После перезапуска ожидаемый провайдер отсутствует. | Проверьте уровень конфигурации, который имеет приоритет. Конфигурация пользователя или профиля может переопределять системные значения по умолчанию. |
| Аутентификация не работает ни у одного пользователя. | Проверьте аутентификацию на шлюзе и учётные данные вышестоящего провайдера; определите, какой сервис отклонил запрос. |
| Аутентификация не работает у одного пользователя. | Проверьте доступ этого пользователя у провайдера удостоверений, его учётные данные шлюза или программу получения токенов. |
| Потоковая передача зависает. | Проверьте буферизацию на шлюзе и передачу завершающего события response.completed. |
| Модель отсутствует или использует стандартный набор возможностей. | Для пользовательского псевдонима убедитесь, что псевдоним на шлюзе, model в Codex и slug в каталоге совпадают. Проверьте путь к каталогу и совместимость с установленной версией Codex, затем перезапустите Codex. |
| Путь Windows не работает. | Используйте полностью разрешённые абсолютные пути. В TOML заключайте пути Windows с одиночными обратными косыми чертами в одинарные кавычки. |
Повторное использование существующего развёртывания шлюза
Если ваша организация уже использует Claude Code через шлюз, возможно,
вы сможете повторно использовать сам шлюз, сетевой путь, журналирование и доступ к Bedrock. Добавьте
маршрут Responses для Codex, учётные данные, псевдонимы моделей и config.toml,
сохранив существующую рабочую конфигурацию. Настройки клиента Claude и
контракт /v1/messages не настраивают Codex.
| Существующее развёртывание Claude | Миграция на Codex |
|---|---|
| Продукт шлюза, DNS, TLS, частная сеть, журналирование, удаление конфиденциальных данных и мониторинг | Сохраните эти сервисы. Добавьте маршрут для Codex, соответствующий требованиям к совместимости шлюза. |
| Учётная запись Bedrock, учётные данные провайдера, границы разрешений IAM, профили инференса и ротация учётных данных | Сохраните их, только если они предоставляют доступ к моделям вышестоящего провайдера, на которые указывают новые псевдонимы Codex. Учётные данные провайдера остаются на шлюзе. |
Маршрут Claude /v1/messages, формат Bedrock InvokeModel, заголовки Anthropic, а также повторные попытки или ошибки, специфичные для Claude |
Не считайте их подтверждением совместимости. Codex требуются POST /v1/responses, потоковая передача Responses, продолжение диалога, вызовы инструментов и информативные ошибки. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY или apiKeyHelper |
Codex не поддерживает apiKeyHelper. Настройте собственный OAuth шлюза, ключ с ограниченной областью доступа через env_key или программу получения токенов Codex, вызываемую командой. |
Имена моделей Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides и сопоставления профилей Bedrock |
Попросите команду шлюза выбрать имена моделей и настроить необходимые пользовательские псевдонимы. Используйте предоставленные ими имя модели и каталог моделей в формате JSON, если он нужен. |
settings.json Claude, managed-settings.json, блоки JSON env, plist или данные для реестра |
Сохраните тот же канал MDM или управления конфигурацией, но распространяйте через него config.toml Codex и поддерживаемые значения requirements.toml. |
Для безопасной миграции выполните следующие действия по порядку:
- Опишите текущую схему подключения Claude: URL шлюза, источник учётных данных, необходимые заголовки, псевдонимы моделей, сопоставления профилей Bedrock и канал централизованной доставки конфигурации.
- Добавьте параллельный маршрут Responses для Codex и псевдонимы моделей Codex.
- Выберите встроенный OAuth шлюза, API key или вспомогательную программу для учётных данных и авторизуйте одного тестового пользователя. Статические учётные данные предоставьте через
env_key; для вспомогательной программы реализуйте и протестируйте контракт Codex для получения учётных данных с помощью команды. - Настройте провайдера для этого разработчика, используя способ аутентификации, выбранный на шаге 3. При централизованном внедрении адаптируйте пакет конфигурации к путям и приоритетам Codex, описанным в разделе Внедрение шлюза.
- Выполните короткую проверку подключения в том CLI или настольном приложении, которым пользуется разработчик, затем выполните полный набор проверок потоковой передачи, продолжения диалога, вызовов инструментов, ошибок, журналирования и маршрутизации по псевдонимам из раздела Тестирование Codex через шлюз.
- После успешного прохождения пилотного проекта распространите конфигурацию среди остальных разработчиков.
Справочник по каталогу моделей
Начните с локального файла models.json
Сначала настройте и выберите провайдера шлюза на компьютере, где вы запускаете Codex.
Сохраните этот каталог как models.json на компьютере, где работает Codex. Замените
gateway-model на точный ID модели, который принимает ваш шлюз. Отображаемое имя —
это название, которое пользователи видят в списке выбора модели.
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}Более полный пример см. в каталоге моделей Codex.
Укажите в model_catalog_json в файле config.toml абсолютный путь к файлу.
Перезапустите Codex, выберите Gateway model и отправьте запрос. Убедитесь, что
шлюз получил ID модели, указанный в slug.
Для псевдонима встроенной модели скопируйте полную запись этой модели из каталога для вашей версии Codex
и измените её slug и display_name. Если для псевдонима не задана целевая модель для перехода, установите upgrade в null. Это сохранит
контекстное окно модели, параметры рассуждения и настройки инструментов.
Предоставление каталога клиентам
Эта страница предназначена для разработчиков, реализующих формат Codex Models, который определяет каталог моделей и обеспечивает работу списка выбора модели. Если вы разрабатываете провайдер инференса, например шлюз или облачный сервис, используйте эту спецификацию, чтобы настольное приложение Codex и CLI могли обнаруживать ваши модели и использовать их инструкции и настройки возможностей.
Если вы администрируете корпоративную среду и хотите управлять каталогом моделей, см.
рекомендации по настройке model_catalog_url.
Для поддержки этого формата реализуйте эндпоинт каталога с аутентификацией. Получите у вышестоящего провайдера актуальные значения по умолчанию для версии Codex, отправляющей запрос, примените свои переопределения и верните полученный каталог.
client_version Реализуйте эндпоинт каталога
По умолчанию эндпоинт каталога — /models относительно base_url провайдера.
Например, при base_url = "https://gateway.example.com/v1" Codex отправляет запрос:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>Обнаружение по умолчанию поддерживает аутентификацию с помощью команды и аутентификацию через бэкенд Codex,
например ChatGPT. Для пользовательского провайдера с аутентификацией через API key
без аутентификации с помощью команды явно задайте model_providers.<id>.model_catalog_url,
чтобы включить удалённое обнаружение. Сам по себе API key не запускает обнаружение
по пути по умолчанию.
Используйте model_catalog_url, чтобы задать полный URL каталога, например
https://gateway.example.com/codex/models. Он также может указывать на стандартный
эндпоинт /v1/models. Codex использует этот URL напрямую, не добавляя /models.
Для обнаружения с помощью API key оставьте features.api_key_model_discovery включённым; он включён
по умолчанию. Одни лишь пользовательские заголовки не включают обнаружение.
Codex отправляет данные аутентификации выбранного провайдера и настроенные заголовки, а также
добавляет client_version и все query_params провайдера. Размещайте каталог в
сервисе, которому разрешено получать эти учётные данные.
Аутентифицируйте вызывающую сторону, получите соответствующие значения по умолчанию у вышестоящего провайдера, примените свои
переопределения и верните полный JSON ModelsResponse напрямую. Задайте каждой
записи уникальный непустой slug. При явно заданном model_catalog_url Codex отклоняет
перенаправления и ответы размером более 1 МиБ. Продолжайте проверять права доступа к моделям при
запросах на инференс.
Удалите все действующие настройки model_catalog_json у клиентов, использующих эндпоинт:
локальный файл имеет приоритет и предотвращает удалённое получение каталога.
Обеспечьте соответствие схеме клиента
Считайте параметр запроса client_version из запроса каталога. Codex передаёт свою
версию CLI в формате major.minor.patch без суффикса предварительной версии. Для настольных
клиентов это версия встроенного CLI.
Используйте соответствующий тег rust-v<version> в публичном репозитории Codex или
точный коммит исходного кода для пользовательской сборки. В этих ссылках используется rust-v0.162.1; выберите
ревизию, соответствующую вашему клиенту:
- Изучите типы ответов
ModelsResponseиModelInfo, чтобы ознакомиться со схемой. - Изучите встроенный
models.json, чтобы увидеть полный пример. Это данные каталога, а не документ JSON Schema.
Встроенный файл — это снимок на момент выпуска. Получите актуальные значения по умолчанию перед формированием своего каталога.
Получите актуальные значения по умолчанию у вышестоящего провайдера
Облачные провайдеры, предоставляющие модели OpenAI, получают значения по умолчанию из OpenAI. Шлюзы считывают каталог своего облачного или вышестоящего провайдера, чтобы сохранить настройки развёрнутой модели и её доступность для учётной записи и региона. Передавайте версию Codex, отправляющей запрос, на каждом этапе и проходите аутентификацию отдельно на каждом эндпоинте.
Чтобы получить значения по умолчанию напрямую из OpenAI, вызовите эндпоинт моделей Codex с тем
же client_version. Например, с API key OpenAI:
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Для интеграции с ChatGPT используйте токен доступа ChatGPT вызывающей стороны и
заголовок ChatGPT-Account-ID, когда это применимо. Используйте учётные данные, предоставляющие доступ к
эндпоинту вышестоящего провайдера; собственный API key вашего шлюза не обеспечивает аутентификацию в OpenAI.
Разберите полный ответ, включая массив models верхнего уровня. Этот эндпоинт
возвращает метаданные Codex, такие как инструкции, параметры рассуждения по умолчанию, настройки инструментов,
ограничения контекста и уровни обслуживания. Публичный эндпоинт /v1/models не
предоставляет этот каталог.
Обновляйте эти значения по умолчанию, даже если версия Codex не изменилась. Выполняйте запросы только от имени нужной учётной записи у вышестоящего провайдера и соблюдайте директивы кеширования ответов: каталоги могут зависеть от прав доступа вызывающей стороны. Храните свои переопределения отдельно, чтобы повторно применять их к обновлённым значениям по умолчанию.
Примените переопределения провайдера
Изменяйте значения полей, сохраняя структуру ответа для этой версии:
- Оставьте только модели, доступные вызывающей стороне. Сопоставьте каждый
slugс поддерживаемым маршрутом инференса и скорректируйтеdisplay_name,descriptionилиpriority. Для псевдонима без миграции модели задайте дляupgradeзначениеnull. - Задайте для параметров рассуждения, ограничений контекста, входных модальностей и уровней обслуживания
значения, поддерживаемые вашей моделью и маршрутом. Значения по умолчанию должны входить в число поддерживаемых
вариантов. Для маршрута без уровней обслуживания очистите
service_tiersиadditional_speed_tiersи задайте дляdefault_service_tierзначениеnull. - Сохраняйте инструкции и настройки инструментов вышестоящего провайдера, если вы не протестировали замену. Метаданные не добавляют модели возможностей и не предоставляют доступ к инференсу.
Для псевдонима модели на шлюзе ознакомьтесь с тем, как предоставить метаданные модели. Протестируйте полученный каталог с каждой поддерживаемой версией Codex.
Используйте публичные типы Rust
Используйте крейты из того же публичного тега Git или коммита, что и схема клиента:
- Используйте
codex-protocolдляcodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Разберите данные с помощьюserde_json::from_slice::<ModelsResponse>(), изменитеcatalog.modelsи сериализуйте всю обёртку с помощьюserde_json::to_vec(). Обёртка обрабатывает поля совместимости для инструкций модели. - Используйте
codex-models-manager::bundled_models_response(), чтобы загрузить статический встроенный каталог этой ревизии какModelsResponse. Эта функция не получает актуальные значения по умолчанию у вышестоящего провайдера.