Подключение к шлюзу

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

Проверьте существующую конфигурацию

Прежде чем что-либо добавлять, проверьте, не настроил ли администратор Codex заранее.

• Для CLI проверьте выбранный профиль и выполните codex doctor. После запуска используйте /status, чтобы проверить активные модель и провайдера.
• Для приложения macOS проверьте ~/.codex/config.toml или управляемую конфигурацию, которую предоставляет ваша организация.
• Для приложения Windows проверьте %USERPROFILE%\.codex\config.toml или системную конфигурацию, которую предоставляет ваша организация.

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

Получите данные для подключения к шлюзу

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

• Базовый HTTPS URL шлюза, включая путь API, например https://gateway.example.com/v1.
• Имя модели и ID провайдера, которые следует использовать.
• Учётные данные шлюза с ограниченными правами и соответствующую переменную окружения либо установленное средство получения токенов и его конфигурацию.
• Файл каталога моделей, если он требуется, и его абсолютный локальный путь.

Настройте провайдера

Откройте 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"
env_key = "CODEX_GATEWAY_API_KEY"

Если администратор предоставляет каталог моделей, сохраните его локально и добавьте model_catalog_json перед первой таблицей TOML, указав абсолютный путь к файлу. Для пользовательских псевдонимов нужны соответствующие метаданные каталога. Например:

model_catalog_json = "/etc/codex/gateway-models.json"

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

enterprise-gateway — пример ID провайдера. Используйте один и тот же ID в model_provider, [model_providers.<id>] и [model_providers.<id>.auth]. В этом примере веб-поиск отключён для первоначальной проверки подключения; администратор должен проверить поддержку этой возможности, прежде чем включать её.

Сделайте учётные данные шлюза доступными через 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.

Используйте вспомогательную программу организации для учётных данных

Если администратор предоставляет аутентификацию через команду, используйте установленную им вспомогательную программу и конфигурацию вместо 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

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

Используйте полные абсолютные пути к исполняемым файлам вспомогательных программ и файлам каталогов.

Настройте 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 и плагины отдельно. Учётные данные шлюза моделей не предоставляют доступ к вашим инструментам или подключённым системам.

Проверьте подключение

После изменения конфигурации перезапустите клиент. В CLI запустите codex и используйте /status для проверки активных модели и провайдера. В настольном приложении проверьте выбранную модель и конфигурацию.

Отправьте этот запрос в новой задаче:

Reply with exactly: gateway-ok

Ожидаемый ответ — gateway-ok. Сам по себе ответ не доказывает, по какому маршруту был обработан запрос: попросите администратора подтвердить, что шлюз зарегистрировал вашего пользователя, псевдоним модели и предполагаемый маршрут к вышестоящему провайдеру. Не определяйте модель, спрашивая у неё название.

Это проверяет первоначальное подключение. Администраторы также должны выполнить проверки перед внедрением для потоковой передачи, инструментов и последующих ходов диалога.

Устраните неполадки подключения

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

Используйте существующее развёртывание шлюза

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

1. Определите URL существующего шлюза, механизм учётных данных, обязательные заголовки, маршруты моделей и способ доставки конфигурации.
2. Попросите команду, отвечающую за шлюз, подтвердить, что шлюз поддерживает поведение API, необходимое Codex, и настроить маршрут модели для Codex.
3. Получите у команды шлюза учётные данные шлюза с ограниченными правами или вспомогательную программу для учётных данных, имя модели и каталог моделей, если он требуется.
4. Настройте Codex с этими значениями.
5. Проверьте подключение в CLI или настольном приложении, которое планируете использовать. Попросите команду шлюза выполнить проверки потоковой передачи, инструментов и последующих ходов диалога.
6. После успешного пилотного внедрения следуйте разделу Развёртывание Codex через шлюз, чтобы распространить конфигурацию среди других разработчиков.

Контрольный список миграции для администраторов и сопоставление конфигураций см. в разделе Повторное использование существующего развёртывания шлюза.

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

• Codex CLI
• MCP servers
• Плагины