Custom provider в Codex: API-ключ, Base URL и config.toml

При подключении своего API к Codex недостаточно найти три строки с key, Base URL и model. Эти значения должны принадлежать одному маршруту. Если ключ выдан одним сервисом, URL ведёт к другому, а в Codex осталась авторизация ChatGPT, ошибка 401 почти ничего не объясняет.

Начните не с TOML, а с владельцев:

• OpenAI Platform выдаёт ключ и оплачивает локальную работу — используйте вход Codex по OpenAI API key.
• Запрос остаётся у встроенного OpenAI provider, но проходит через proxy, router или подходящий региональный endpoint — задайте openai_base_url.
• Другой сервис выдаёт credential, модели, баланс и поддержку — объявите отдельный [model_providers.<id>].
• Локальный endpoint действительно не требует auth — создайте provider без env_key и requires_openai_auth.

Факты ниже сверены 1 сентября 2026 года с Advanced Configuration и Authentication OpenAI. Схема Codex меняется, поэтому старый пример нужно проверять по текущей документации, даже если TOML выглядит правдоподобно.

Паспорт маршрута: пять значений до первого запуска

Запишите рядом credential issuer, provider ID, Base URL, точный model ID и требуемые возможности. Например:

Фраза «совместимо с OpenAI» описывает формат только в общих чертах. Она не доказывает, что endpoint принимает нужную аутентификацию, реализует Responses API, корректно стримит события и поддерживает tool calls Codex.

Вход с OpenAI API key — это не custom provider

Для локальной работы CLI OpenAI документирует передачу ключа через стандартный ввод:

bash
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

Такой запуск относится к OpenAI Platform: расход и политика данных следуют API organization и project. Это не включённый расход подписки ChatGPT. Codex cloud по-прежнему требует вход через ChatGPT, поэтому API key не заменяет все cloud-функции.

Codex может хранить кэш авторизации в ~/.codex/auth.json или в системном credential store. Если используется файл, считайте его паролем: не добавляйте в Git, не прикладывайте к issue и не копируйте в чат поддержки. Способ входа проверяйте через codex login status, не публикацией содержимого файла.

Если вы ещё выбираете между подпиской и API-биллингом, сначала откройте Codex API key или подписка. Иначе технически рабочий route может оказаться не тем счётом, который вы собирались использовать.

Когда достаточно openai_base_url

Для встроенного OpenAI provider предусмотрен отдельный пользовательский параметр:

toml
# ~/.codex/config.toml
openai_base_url = "https://proxy.example.com/v1"

Он подходит, когда сохраняются OpenAI auth и API semantics, а меняется маршрут до endpoint. Не создавайте [model_providers.openai]: идентификаторы openai, ollama и lmstudio зарезервированы встроенными provider и не могут быть заменены одноимённым custom block.

Если gateway выдаёт собственный token, имеет отдельный баланс, model aliases и поддержку, это уже другой контракт. В таком случае отдельный provider делает причину ошибок наблюдаемой и не смешивает OpenAI login с чужим credential.

Минимальный блок отдельного provider

Настройки provider относятся к пользовательской машине:

toml
# ~/.codex/config.toml
model = "EXACT_PROVIDER_MODEL_ID"
model_provider = "company_gateway"

[model_providers.company_gateway]
name = "Company gateway"
base_url = "https://gateway.example.com/v1"
env_key = "COMPANY_GATEWAY_API_KEY"
wire_api = "responses"

Секрет находится в environment, а не в TOML:

bash
export COMPANY_GATEWAY_API_KEY="replace-with-provider-key"

env_key — имя переменной, а не значение ключа. Если variable экспортирована в shell, но Codex запускается из IDE или desktop с другим окружением, процесс её не увидит. Проверяйте только наличие:

bash
if [ -n "${COMPANY_GATEWAY_API_KEY:-}" ]; then
  echo "provider key is available"
else
  echo "provider key is missing"
fi

Нельзя автоматически добавлять /v1 ко всем адресам. Base URL и model ID берутся из текущей документации выбранного provider и должны описывать один аккаунт и один protocol contract.

Один provider — один источник авторизации

Раздел OpenAI об alternative providers различает три варианта:

1. requires_openai_auth = true использует OpenAI authentication и игнорирует env_key. Это возможно для proxy, который прямо принимает OpenAI auth.
2. env_key = "PROVIDER_VARIABLE" берёт собственный API key provider из environment.
3. Если нет обоих полей, Codex считает endpoint не требующим auth — это применимо к контролируемому локальному сервису.

Для короткоживущих bearer token Advanced Configuration также описывает [model_providers.<id>.auth] command. Его нельзя сочетать с env_key, requires_openai_auth или experimental bearer token. Несколько источников credential не создают fallback: они скрывают, какой ключ вызвал 401.

Почему блок игнорируется в .codex/config.toml проекта

Даже доверенный репозиторий не может перенаправить машинный provider и auth. В официальном описании project config указано, что проектный слой игнорирует, в частности:

• openai_base_url;
• model_provider;
• model_providers.

Перенесите их в ~/.codex/config.toml. Это не ошибка синтаксиса, а защита от ситуации, когда репозиторий незаметно отправляет ваш код и credentials на свой endpoint.

Если пользовательский файл всё равно не влияет на поведение, проверьте точную команду запуска, CLI --config и выбранный profile. Приоритет объясняет, какое разрешённое значение победило; он не делает запрещённый project key допустимым.

Проверяйте не список моделей, а рабочий контракт

Ответ 200 от /v1/models доказывает доступность только этого endpoint. Для Codex полезнее ступенчатая проверка:

1. Сохраните резервную копию и оставьте минимальный provider block.
2. Убедитесь, что provider ID, Base URL, model ID, wire API и credential issuer относятся к одному сервису.
3. Запустите Codex из того же окружения, где доступна переменная.
4. Отправьте короткую задачу без кода и персональных данных, например запрос точного ответа ROUTE_OK.
5. После текста отдельно проверьте нужные в работе streaming, tools, длинный context или web search.

Текстовый ответ не доказывает tool compatibility. Если запрос уже дошёл до нужного provider, постоянное редактирование слоёв конфигурации не исправит его account access или protocol adapter.

Ошибка указывает, кого проверять дальше

Для поддержки достаточно очищенного пакета: версия Codex, ОС, CLI/IDE/desktop, provider ID, hostname Base URL, model ID, wire_api, полный текст ошибки, status, request ID и timestamp. Удалите API key, Authorization header, auth.json, приватный код и данные клиентов.

Настройка закончена, когда вы можете назвать загруженный слой, издателя credential, получателя запроса, model namespace и следующего владельца сбоя. Если хотя бы один пункт неизвестен, вернитесь к одному provider, одному источнику auth и одному безопасному запросу. Такой маршрут диагностируется; «универсальный config» из нескольких несовместимых примеров — нет.