Развёртывание Codex через шлюз

Разверните Codex через LLM-шлюз вашей организации. Настройте маршруты моделей, выдайте разработчикам учётные данные и распространите проверенную конфигурацию Codex.

Предварительные требования

Прежде чем развёртывать Codex для разработчиков, убедитесь, что у вас есть:

• Шлюз, обслуживающий HTTPS по тому самому базовому URL, который вы будете распространять.
• Учётные данные вышестоящего провайдера, хранящиеся на шлюзе.
• Утверждённые псевдонимы моделей для Codex, сопоставленные с нужными моделями вышестоящего провайдера.
• Тестовые учётные данные шлюза с ограниченными правами.
• Механизм доставки секретов или проверенная вспомогательная программа для получения учётных данных.
• Способ распространения конфигурации, вспомогательных исполняемых файлов и файлов каталогов.

Требования к шлюзу

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

• Принимает запросы Codex к Responses API по адресу POST /v1/responses.
• Передаёт поток событий SSE без буферизации и завершает его событием response.completed.
• Сохраняет возможность продолжения диалога с повторной передачей входных данных.
• Сохраняет previous_response_id только при включённом WebSocket или инкрементальном транспорте.
• Сохраняет вызовы функций и соответствующие элементы function_call_output.
• Направляет каждый псевдоним модели для Codex к нужной модели вышестоящего провайдера.
• Аутентифицирует пользователей по отдельности и возвращает информативные ошибки, не скрывая их причину.

Наличие конечной точки проверки работоспособности, /v1/models, ответа Chat Completions или одного текстового ответа не подтверждает пригодность шлюза. Подробный контракт см. в разделе Требования к совместимости шлюза.

Внедрение шлюза

Чтобы перейти от развёрнутого шлюза к проверенной рабочей среде разработчика, последовательно пройдите эти пять этапов:

1. Выберите имена моделей и проверьте маршруты.
2. Выдайте разработчикам учётные данные.
3. Протестируйте Codex через шлюз.
4. Распространите конфигурацию.
5. Выполните проверку на компьютере разработчика.

Выбор имён моделей и маршрутов

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

Использование каталога моделей для пользовательских имён

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

Например, чтобы использовать company-coding-model как псевдоним для gpt-6-luna:

1. Создайте на шлюзе псевдоним company-coding-model и направьте его к утверждённой модели gpt-6-luna вышестоящего провайдера.
2. Скачайте каталог моделей Codex для вашей версии Codex и сохраните копию как gateway-models.json. Используйте этот файл как основу.
3. Измените запись gpt-6-luna в своей копии: задайте для slug значение company-coding-model и проверьте, что остальные метаданные соответствуют модели вышестоящего провайдера и возможностям шлюза. Для псевдонима без миграции модели задайте для upgrade значение null.
4. Сохраните записи в массиве верхнего уровня models и распространите файл на каждый клиент. Пользовательский каталог заменяет встроенный, поэтому включите все модели, которые пользователям потребуется выбирать.

Для Bedrock через LiteLLM внесите обязательные изменения в каталог.

Задайте для псевдонима шлюза, 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, распространение плагинов и их политики отдельно.

Выдача учётных данных разработчикам

1. Выдайте каждому разработчику отдельные учётные данные шлюза с ограниченными правами, чтобы отслеживать использование и отзывать доступ индивидуально.
2. Задайте разрешённые модели, ограничения частоты запросов, бюджет, срок действия и период продления для каждых учётных данных.
3. Доставляйте учётные данные через менеджер секретов или установленную вспомогательную программу. Не размещайте учётные данные вышестоящего провайдера и администратора шлюза на компьютерах разработчиков.
4. Если вы используете вспомогательную программу, соблюдайте контракт аутентификации через команду и до распространения проверьте получение и обновление токенов.
5. Сообщите разработчикам, как продлевать учётные данные и к кому обращаться за помощью.

Тестирование Codex через шлюз

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

Выполните следующие проверки в том же интерфейсе CLI или настольного приложения, которым будут пользоваться разработчики:

После успешного прохождения этих проверок направьте разработчиков к разделу Подключение к шлюзу, чтобы они настроили и проверили свои компьютеры.

Распространение конфигурации

Чтобы на всех компьютерах использовался один и тот же путь подключения, распространите базовый URL шлюза, идентификатор провайдера, утверждённый псевдоним модели и механизм получения учётных данных.

Что распространять

Чтобы задать настройки провайдера по умолчанию, распространите этот блок 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 с аутентификацией через команду.

Распространение настроек по умолчанию и обязательных требований

Используйте раздел Приоритет конфигурации, чтобы выбрать, где распространять настройки по умолчанию. Принудительно применяемые настройки и полезные нагрузки MDM для macOS описаны в разделе Управляемая конфигурация.

Для настроек по умолчанию на уровне компьютера в macOS или Linux используйте /etc/codex/config.toml. В Windows разместите config.toml в %ProgramData%\OpenAI\Codex\. Пользователи и профили могут переопределять эти настройки. Материалы по ссылкам описывают поддерживаемые требования и расположение соответствующих файлов.

Отдельно распространите все вспомогательные исполняемые файлы и файлы каталогов, на которые есть ссылки.

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.

Передача значений конфигурации разработчикам

Если у вас нет управляемого распространения, предоставьте каждому разработчику URL шлюза, идентификатор провайдера, псевдоним модели, переменную с учётными данными или программу их получения, а также путь к каталогу, если он используется. Направьте их к разделу Подключение к шлюзу, чтобы они настроили и проверили свои компьютеры.

Ручная настройка не обеспечивает принудительное применение требований. Локальный для проекта .codex/config.toml не может переопределять чувствительные ключи маршрутизации провайдера или аутентификации.

Проверка на компьютере разработчика

Чтобы убедиться, что распространяемые настройки дошли до компьютера разработчика:

1. Перезапустите Codex и убедитесь, что выбраны ожидаемые провайдер и модель.
2. Выполните короткий тест из раздела Подключение к шлюзу.
3. Задайте один уточняющий вопрос, чтобы проверить продолжение диалога, затем найдите в журналах шлюза запрос этого разработчика.

Устранение сбоев при внедрении

По характеру проблемы определите, какой уровень требует внимания: конфигурация, учётные данные или шлюз:

Повторное использование существующего развёртывания шлюза

Если ваша организация уже использует Claude Code через шлюз, возможно, вы сможете повторно использовать сам шлюз, сетевой путь, журналирование и доступ к Bedrock. Добавьте маршрут Responses для Codex, учётные данные, псевдонимы моделей и config.toml, сохранив существующую рабочую конфигурацию. Настройки клиента Claude и контракт /v1/messages не настраивают Codex.

Для безопасной миграции выполните следующие действия по порядку:

1. Составьте перечень компонентов текущего пути Claude: URL шлюза, источник учётных данных, обязательные заголовки, псевдонимы моделей, сопоставления профилей Bedrock и канал управляемой доставки.
2. Добавьте параллельный маршрут Responses для Codex и псевдонимы моделей Codex.
3. Выдайте одни учётные данные Codex с ограниченными правами. Если Codex будет использовать статические учётные данные, предоставьте эти новые данные через env_key; если Claude использует вспомогательную программу для получения учётных данных, реализуйте и протестируйте контракт программы получения токенов Codex, вызываемой командой.
4. Настройте среду этого разработчика с помощью блока провайдера. Для управляемого внедрения адаптируйте полезную нагрузку к путям и приоритетам Codex, описанным в разделе Развёртывание Codex через шлюз.
5. Выполните короткую проверку подключения в том интерфейсе CLI или настольного приложения, которым действительно пользуется разработчик, затем выполните полный набор проверок потоковой передачи, продолжения диалога, вызовов инструментов, ошибок, журналирования и маршрутизации псевдонимов из раздела Тестирование Codex через шлюз.
6. После успешного пилотного запуска распространите конфигурацию среди остальных разработчиков.

Связанная документация

• Подключение к шлюзу
• MCP
• Плагины
• Управляемая конфигурация