Подключение к шлюзу
Настройте шлюз моделей и пройдите аутентификацию с помощью встроенной поддержки OAuth шлюза, API key или вспомогательной программы для получения учётных данных.
Подключите Codex к шлюзу моделей вашей организации, используя настройки провайдера и способ аутентификации, предоставленные командой, отвечающей за шлюз. Шлюз направляет запросы к моделям в ваш бэкенд, например Amazon Bedrock.
Проверьте существующую конфигурацию
Установите клиент Codex той версии, которую протестировал ваш администратор. Если настройками управляет ваша организация, откройте этот клиент и выполните шаги входа из переданных вам инструкций. Примеры настройки провайдера ниже можно пропустить.
- Для CLI проверьте выбранный профиль и выполните
codex doctor. После запуска используйте/status, чтобы проверить активные модель и провайдера. - Для приложения macOS проверьте
~/.codex/config.tomlили управляемую конфигурацию, которую предоставляет ваша организация. - Для приложения Windows проверьте
%USERPROFILE%\.codex\config.tomlили системную конфигурацию, которую предоставляет ваша организация.
Если ожидаемые провайдер шлюза и модель уже активны, выполните все шаги входа, предоставленные администратором, затем перейдите к разделу Проверка подключения. Не добавляйте вторую конфигурацию провайдера на управляемый компьютер. Если настройки отличаются от инструкций администратора, перед редактированием локальных файлов уточните, на каком уровне конфигурации они должны задаваться.
Получите данные для подключения к шлюзу
При ручной настройке уточните, требуется ли вход в рабочее пространство ChatGPT, аутентификация на шлюзе или и то и другое.
Чтобы настроить Codex самостоятельно, получите у команды, отвечающей за шлюз, следующие значения:
- Базовый HTTPS URL шлюза, включая путь API, например
https://gateway.example.com/v1. - Имя модели и ID провайдера, которые следует использовать.
- Способ аутентификации: встроенный OAuth шлюза, API key с ограниченными правами и соответствующая переменная окружения либо установленная вспомогательная программа для получения учетных данных.
- Для OAuth — URL авторизации, URL токена, публичный ID клиента и все необходимые области доступа. Для шлюзов, использующих cookie или нестандартный заголовок, — его имя.
- URL каталога моделей, если он требуется, либо файл каталога и его абсолютный локальный путь.
Настройте провайдера
Откройте config.toml по пути ~/.codex/config.toml в macOS или Linux либо
%USERPROFILE%\.codex\config.toml в Windows.
Добавьте этот пример в существующую конфигурацию, заменив URL и модель
значениями, предоставленными администратором. Не добавляйте повторное определение
существующего ключа или таблицы. В этом примере используется gpt-6-sol; используйте его без собственного
каталога только в том случае, если администратор подтвердит, что ваша версия 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"
requires_openai_auth = falseЗатем добавьте настройки аутентификации, предоставленные командой, отвечающей за шлюз.
enterprise-gateway — пример ID провайдера. Используйте тот же ID в
model_provider и соответствующих таблицах провайдера и аутентификации.
В этом примере веб-поиск отключен
для первоначальной проверки подключения; администратор должен проверить поддержку этой функции,
прежде чем включать ее.
Настройте каталог моделей
Уточните у команды, отвечающей за шлюз, как Codex получает сведения о возможностях и инструкции для выбранной модели:
- Встроенное имя: если шлюз принимает точное имя модели, включенное в вашу версию Codex, и направляет запросы соответствующей модели, задайте это имя в
model. У Codex уже есть ее метаданные. - Конечная точка каталога: если шлюз предоставляет совместимые с Codex метаданные, используйте полный URL его каталога. Это может быть конечная точка
/v1/models, реализующая формат ответа каталога Codex. Для пользовательских псевдонимов недостаточно ответа, содержащего только список ID моделей. - Файл каталога: если шлюз использует пользовательские псевдонимы и администратор предоставляет файл, воспользуйтесь примером локального models.json. Используйте локальный файл, если встроенный OAuth шлюза — ваш единственный способ аутентификации и вам нужны пользовательские метаданные.
При аутентификации через API key или вспомогательную программу, если администратор предоставил
URL каталога, добавьте его в существующую
таблицу [model_providers.enterprise-gateway]:
model_catalog_url = "https://gateway.example.com/codex/models.json"Удалите все действующие параметры model_catalog_json: они имеют приоритет над
URL-адресом. Требования к конечной точке для администраторов приведены в разделе
Настройка удалённого каталога.
Если администратор предоставил локальный файл каталога моделей, сохраните его и добавьте
model_catalog_json перед первой таблицей TOML, указав абсолютный путь к файлу.
Для пользовательских псевдонимов требуются соответствующие метаданные каталога. Например:
model_catalog_json = "/etc/codex/gateway-models.json"Используйте имя модели и каталог, предоставленные администратором вместе. Не добавляйте путь к каталогу, если файла по этому пути нет.
Выбор способа аутентификации
Используйте встроенную поддержку OAuth шлюза для входа через браузер, API key для аутентификации с ограниченной областью действия или вспомогательную программу для получения учётных данных, если ваша организация предоставляет соответствующую команду.
{/* prettier-ignore */}
Использование встроенной поддержки OAuth шлюза
OAuth шлюза работает независимо от входа в ChatGPT. Используйте его, если шлюз принимает токены доступа, выданные провайдером удостоверений вашей организации, например Microsoft Entra ID. Codex обеспечивает вход через браузер, хранение учётных данных в зашифрованном виде и обновление токенов, если сервер авторизации выдаёт токен обновления.
При аутентификации только на шлюзе Codex CLI 0.166.0 и более поздних версий по умолчанию передаёт токен доступа в Authorization: Bearer <gateway access token>. Удалите запись Authorization из http_headers или env_http_headers этого провайдера.
Команда, отвечающая за шлюз, должна зарегистрировать публичный клиент OAuth, поддерживающий
поток кода авторизации с PKCE. Добавьте эту таблицу в конфигурацию провайдера
в config.toml, заменив URL и идентификатор клиента своими значениями:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127Добавьте scopes и, при необходимости, resource в эту таблицу, указав значения, которые
требуют ваш провайдер удостоверений и шлюз. Запросите области доступа, необходимые для получения токенов
обновления, если ваш провайдер их требует. По умолчанию Codex использует свободный порт петлевого интерфейса.
Если провайдер удостоверений требует фиксированный URI перенаправления, задайте redirect_port и
зарегистрируйте http://127.0.0.1:43127/callback для этого примера.
Если шлюз ожидает cookie или пользовательский заголовок, задайте необязательное поле delivery в таблице OAuth. Выберите способ, который проверяет ваш шлюз:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }Если ваше развёртывание также требует входа в ChatGPT, используйте cookie или отдельный заголовок шлюза, показанный выше. См. раздел Включение входа в ChatGPT.
Прежде чем вы сможете использовать этот поток, в шлюз, принимающий только статический API key, необходимо добавить поддержку токена OAuth и способа его передачи. Шлюз продолжает управлять собственными учётными данными для вышестоящих сервисов, например учётными данными AWS для Bedrock.
Если OAuth — единственный способ аутентификации, сохраните requires_openai_auth = false и удалите
прежние настройки env_key, experimental_bearer_token или auth, использовавшиеся для
учётных данных шлюза. Используйте локальный каталог моделей, если вам нужны собственные метаданные
моделей; сам по себе OAuth не обеспечивает обнаружение удалённого каталога.
Перезапустите настольное приложение и следуйте предложению войти на шлюз, чтобы открыть браузер.
В CLI запустите codex и выполните вход через браузер при первом обращении Codex
к шлюзу. Пройдите процедуру входа вашей организации и MFA, затем вернитесь в
клиент. Если срок действия авторизации истечёт или Codex не сможет её обновить, войдите снова при появлении запроса.
Для встроенной поддержки OAuth шлюза необходимы браузер и доступный адрес обратного вызова на петлевом интерфейсе. Резервный
вход по коду устройства не предусмотрен. Если CLI работает через SSH, задайте redirect_port = 43127 в
таблице OAuth и зарегистрируйте соответствующий URI перенаправления, описанный выше. С
компьютера, на котором запущен браузер, настройте перенаправление этого порта перед запуском Codex:
ssh -L 43127:127.0.0.1:43127 user@remoteВ этой SSH-сессии запустите codex и откройте URL входа на шлюз в локальном
браузере. Для CLI внутри контейнера также необходим адрес обратного вызова, доступный из
браузера. Если обеспечить его доступность невозможно, используйте API key или вспомогательную
программу для получения учётных данных.
Используйте API key
Используйте эту настройку, если шлюз ожидает API key в заголовке Authorization.
Добавьте следующую настройку в существующую
таблицу [model_providers.enterprise-gateway]:
env_key = "CODEX_GATEWAY_API_KEY"Сделайте учётные данные шлюза доступными через CODEX_GATEWAY_API_KEY в
окружении процесса, запускающего Codex, с помощью принятого в организации механизма
доставки секретов. Не помещайте учётные данные в TOML или репозиторий. Переменная,
заданная в терминале, может быть недоступна приложению, запущенному с рабочего стола.
Используйте собственный заголовок аутентификации
Если шлюзу вместо bearer-токена требуется заголовок, например X-API-Key,
замените env_key в таблице провайдера следующим:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Используйте точное имя заголовка, предоставленное администратором. Codex считывает значение из
указанной переменной окружения; не храните учётные данные в файле конфигурации.
Сведения о настройке см. в справочнике по конфигурации:
model_providers.<id>.env_http_headers.
При входе через ChatGPT используйте пользовательский заголовок для ключа шлюза, чтобы Codex мог передавать учётные данные пользователя OpenAI в Authorization.
Если пользовательский заголовок — единственный механизм аутентификации, используйте
model_catalog_json; обнаружение удалённого каталога выполняться не будет.
Используйте вспомогательную программу организации для учётных данных
Если администратор предоставляет аутентификацию с помощью команды, используйте установленную им
вспомогательную программу и конфигурацию вместо env_key. Не настраивайте оба механизма одновременно.
Вспомогательная программа должна быть установлена на вашем компьютере; Codex не устанавливает её. Например,
добавьте эту таблицу без env_key, указав путь к программе получения учётных данных и
аргументы, предоставленные администратором:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Справочник по аутентификации пользовательских провайдеров определяет команду, аргументы, тайм-аут, интервал обновления и требования к выводу токена. Уточните у администратора, как повторно войти в систему, если программа больше не может получить токен.
При входе через ChatGPT запустите вспомогательную программу перед запуском Codex и передайте её вывод через пользовательский заголовок шлюза вместо настройки таблицы auth. Когда срок действия ключа истечёт, получите новый ключ и перезапустите Codex.
Используйте полные абсолютные пути к исполняемым файлам вспомогательных программ и файлам каталогов.
Включите вход через ChatGPT (рекомендуется)
Если ваша организация использует рабочее пространство ChatGPT, вход в него даёт пользователям доступ к поддерживаемым функциям, например плагинам от OpenAI. При этом применяются настройки управления рабочего пространства, а запросы к моделям по-прежнему обрабатывает ваш шлюз. Сравнить доступность функций.
При ручной настройке перед входом обновите существующую таблицу [model_providers.enterprise-gateway]:
- Задайте
requires_openai_auth = trueи оставьте вbase_urlадрес вашего шлюза. Удалите настройкиenv_key,experimental_bearer_tokenиauthпровайдера, чтобы Codex использовал ваши учётные данные OpenAI для основной аутентификации. - Передавайте учётные данные шлюза отдельно. При использовании встроенной поддержки OAuth для шлюза настройте
gateway_oauth.deliveryна использование cookie или пользовательского заголовка, который принимает ваш шлюз. Для API key или вспомогательной программы получения учётных данных используйте пользовательский заголовок аутентификации. ОставьтеAuthorizationдля учётных данных OpenAI.
Войдите в рабочее пространство ChatGPT, указанное администратором. При появлении запроса выполните вход на шлюзе, затем проверьте подключение.
Администраторы могут распространять управляемые настройки провайдера и проверять пересылку учётных данных.
Обрабатывайте учётные данные на шлюзе
С каждым запросом к модели шлюз получает два набора учётных данных. Например, когда Codex передаёт токен OAuth шлюза в cookie:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>Проверьте учётные данные шлюза и удалите соответствующий cookie или пользовательский заголовок. Исключите учётные данные и конфиденциальные данные запросов из журналов. Выберите, какие учётные данные использовать при передаче запроса провайдеру:
- Передавайте учётные данные пользователя для выполнения инференса непосредственно в OpenAI (рекомендуется). Это позволяет OpenAI учитывать использование и применять настройки инференса для этого пользователя. При таком маршруте шлюз должен проксировать
/modelsи/responsesнаhttps://chatgpt.com/backend-api/codexи передаватьAuthorizationи любой заголовокChatGPT-Account-IDбез изменений. - Поручите шлюзу аутентификацию у провайдера инференса. Используйте учётные данные, настроенные на шлюзе для этого провайдера. Не включайте токен пользователя OpenAI и любой заголовок
ChatGPT-Account-IDв запрос к провайдеру.
На этих схемах показан рекомендуемый маршрут для инференса в OpenAI.
Как ключ шлюза работает совместно со входом через ChatGPT


Как OAuth шлюза работает совместно со входом через ChatGPT


Добавьте заголовки маршрутизации (необязательно)
Используйте настройки маршрутизации, предоставленные администратором. Операторы шлюза могут распространять эти настройки и проверять выбранный маршрут в журналах шлюза.
Этот маршрут через шлюз используется только для запросов к провайдеру моделей. Голосовые сеансы используют отдельный маршрут. Вход в рабочее пространство, MCP servers и плагины также могут использовать другие сетевые пути.
Запустите клиент
Если вы используете вход через ChatGPT, запустите клиент и войдите в рабочее пространство, которое предоставляет управляемую конфигурацию. Если вы используете встроенную поддержку OAuth для шлюза, при появлении запроса также выполните вход на шлюз вашей организации. Затем проверьте подключение.
Для локально настроенного провайдера следуйте инструкциям для вашего клиента.
Настройте CLI
В macOS или Linux CLI по умолчанию читает ~/.codex/config.toml. После сохранения
настроек провайдера выполните codex. В WSL используйте конфигурацию и пути Linux,
если CODEX_HOME не указывает на другое расположение.
Настройте приложение macOS
Приложение macOS читает тот же файл ~/.codex/config.toml. После сохранения настроек
провайдера перезапустите приложение. Если вы используете переменную окружения для учётных данных,
убедитесь, что она доступна процессу приложения.
Настройте приложение Windows
Поместите настройки провайдера в %USERPROFILE%\.codex\config.toml, затем перезапустите
приложение. Для аутентификации через команду используйте средство получения токенов, установленное вашим
администратором. Например, замените таблицу аутентификации Unix следующей:
[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000В TOML для Windows литеральные строки в одинарных кавычках сохраняют обратные косые черты. Замените
также пути к каталогам Unix, например на
'C:\ProgramData\OpenAI\Codex\models.json', указав фактический путь,
предоставленный администратором.
Настраивайте MCP servers и плагины отдельно. Учётные данные шлюза моделей не предоставляют доступ к вашим инструментам или подключённым системам.
Проверьте подключение
Используйте идентификатор провайдера и псевдоним модели, предоставленные администратором. Провайдер определяет настроенное подключение, а псевдоним модели — модель, запросы к которой направляются через это подключение. Вход в ChatGPT и аутентификация на шлюзе управляют доступом; могут потребоваться оба способа.
После изменения конфигурации перезапустите клиент. В CLI запустите codex
и используйте /status для проверки активных модели и провайдера. В настольном приложении
проверьте выбранную модель и конфигурацию.
Отправьте этот запрос в новой задаче:
Reply with exactly: gateway-okОжидаемый ответ — gateway-ok. Сам по себе ответ не доказывает, по какому маршруту был обработан запрос: попросите
администратора подтвердить, что шлюз зарегистрировал вашего пользователя, псевдоним модели
и предполагаемый маршрут к вышестоящему провайдеру. Не определяйте модель, спрашивая у неё название.
Устраните неполадки подключения
| Симптом | Что проверить |
|---|---|
| Ожидаемый провайдер не активен. | Проверьте выбранный профиль и приоритет конфигураций. Убедитесь, что ключи верхнего уровня не находятся внутри таблицы провайдера. |
| Не удаётся войти через OAuth или передать токен. | Проверьте регистрацию публичного клиента, URI перенаправления, области доступа и настроенные cookie или заголовок. Убедитесь, что шлюз принимает выданный токен доступа. |
| Не удаётся пройти аутентификацию с помощью API key или вспомогательной программы. | Убедитесь, что переменная с учётными данными доступна клиентскому процессу или что установленная вспомогательная программа может получить действующий токен. Попросите администратора определить, связана ли проблема с аутентификацией на шлюзе или у вышестоящего провайдера. |
| Модель не найдена. | Проверьте указанное имя модели и попросите администратора проверить её маршрут. |
| Модель использует неожиданные возможности. | Попросите администратора проверить, соответствуют ли метаданные каталога модели, на которую указывает псевдоним. |
| Потоковая передача зависает или последующие запросы завершаются ошибкой. | Попросите владельца шлюза проверить буферизацию на прокси, завершающее событие response.completed и раздел Совместимость шлюза. |
| Не удаётся обратиться к каталогу или вспомогательной программе по указанному пути. | Убедитесь, что файл существует по настроенному абсолютному пути в среде, где работает Codex. |
Обращаясь за помощью, укажите версию клиента, операционную систему, ожидаемого провайдера и псевдоним модели, способ аутентификации и шаг, на котором произошёл сбой. Приложите сообщение об ошибке и время запроса, чтобы владелец шлюза мог найти запрос. Удалите токены, cookie, заголовки авторизации и запросы с конфиденциальной информацией. Не отправляйте файлы учётных данных или дамп конфигурации, содержащий секреты.
Используйте существующее развёртывание шлюза
Запросите у команды, отвечающей за шлюз, настройки провайдера Codex и утверждённый псевдоним модели. Если команде ещё нужно включить маршрут для Codex, передайте ей контрольный список миграции для администратора.