Как подключить OpenAI-совместимый API к Codex
Как настроить custom model provider в Codex, выбрать правильный Base URL и Responses API, а затем проверить запрос.
Содержание
Как подключить OpenAI-совместимый API к Codex
Чтобы подключить совместимый API к Codex, добавьте custom model provider в пользовательскую конфигурацию, укажите Base URL провайдера, переменную с API Key и протокол responses. Совместимости с /v1/chat/completions недостаточно: текущий Codex использует Responses API. Пошаговый запуск через --profile ниже относится к Codex CLI.
Для BetterToken рабочая схема — base_url = "https://www.bettertoken.ai/v1", env_key = "BETTERTOKEN_API_KEY", wire_api = "responses". Откройте актуальную инструкцию Codex, создайте отдельный ключ и скопируйте текущий полный Model ID из Setup или model plaza. Названия групп и mappings могут меняться, поэтому не переносите их из старых примеров. Это отдельный API workflow с оплатой по мере использования, а не доступ к функциям подписки ChatGPT.
Что подготовить
- Node.js и npm: они нужны для установки официального Codex CLI.
- Свой аккаунт BetterToken, собственный API Key и текущий полный Model ID из Setup или model plaza.
- Баланс или доступный тестовый лимит для одного короткого запроса.
- Терминал macOS/Linux либо Windows PowerShell. Ниже приведены команды для обеих систем.
- Для другого провайдера — подтверждение поддержки Responses API, SSE streaming и нужных вам tool calls.
Перед настройкой проверьте совместимость
| Требование Codex | Что спросить у провайдера | Почему это важно |
|---|---|---|
| Responses API | Поддерживается ли /v1/responses и streaming | Chat Completions сам по себе не заменяет Responses |
| Bearer authentication | Можно ли передать ключ из переменной окружения | Ключ не должен храниться в публичном TOML |
| Model ID | Какой точный ID доступен этому ключу | Маркетинговое название может отличаться от API ID |
| SSE streaming | Как обрабатываются долгие ответы и разрывы | Codex работает с потоковыми ответами |
| Tool calls | Какие инструменты и поля Responses поддерживаются | «OpenAI-compatible» не гарантирует полную совместимость функций |
Если провайдер показывает только пример Chat Completions и ничего не говорит о Responses, сначала запросите подтверждение или сделайте маленький тест. Не переносите в Codex конфигурацию из обычного чат-клиента вслепую.
Шаг 1. Установите или обновите Codex CLI
npm install -g @openai/codex
codex --versionТекущие поля конфигурации проверяйте по официальному Config Reference. На 14 августа 2026 года справочник указывает, что model_provider выбирает запись из model_providers, env_key задаёт переменную с ключом, а единственное поддерживаемое значение wire_api — responses.
Шаг 2. Создайте отдельный файл профиля
Текущий OpenAI Config Reference хранит именованный профиль в $CODEX_HOME/bt.config.toml. По умолчанию CODEX_HOME обычно соответствует ~/.codex в macOS/Linux и %USERPROFILE%\.codex в Windows, но пользовательское значение меняет реальный путь.
Проверьте каталог в macOS/Linux, не изменяя переменную:
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"В PowerShell:
if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }Создайте bt.config.toml именно в показанном каталоге:
model = "YOUR_MODEL_ID"
model_provider = "bettertoken"
[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
env_key = "BETTERTOKEN_API_KEY"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000
supports_websockets = falseИмя файла $CODEX_HOME/bt.config.toml соответствует команде --profile bt. Такой профиль не заменяет основной $CODEX_HOME/config.toml, поэтому официальный provider остаётся доступен. Замените YOUR_MODEL_ID текущим API ID из Setup, model plaza или актуальной инструкции. Не подставляйте название из заголовка модели, если оно отличается от API ID.
Codex сам добавляет /responses, поэтому Base URL заканчивается на /v1, а не на /v1/responses. Иначе получится двойной путь.
Шаг 3. Передайте API Key через окружение
В macOS/Linux:
export BETTERTOKEN_API_KEY="YOUR_API_KEY"Для постоянной настройки используйте защищённый менеджер секретов или shell-конфигурацию с подходящими правами. Не добавляйте ключ в репозиторий, .env.example, README или команду, которая попадёт в shell history общего компьютера.
Проверить наличие значения без его вывода:
test -n "$BETTERTOKEN_API_KEY" && echo "BETTERTOKEN_API_KEY is set"В Windows PowerShell задайте значение для текущего окна и сохраните его для следующих сессий:
$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"
[Environment]::SetEnvironmentVariable("BETTERTOKEN_API_KEY", "YOUR_API_KEY", "User")
if ($env:BETTERTOKEN_API_KEY) { "BETTERTOKEN_API_KEY is set" }Шаг 4. Запустите профиль и проверьте запрос
Перезапустите Codex и выполните:
codex --profile btПервый тест должен быть маленьким и не менять файлы:
Ответь одной строкой: CODEX_PROVIDER_OK. Не изменяй файлы и не запускай команды.Подключение подтверждено, если ответ пришёл без ошибки, модель совпадает с выбранным ID, а запрос и расход видны в BetterToken Workspace. После этого попробуйте чтение одного тестового файла и только потом разрешайте изменения в рабочем проекте.
Codex Desktop использует те же поля custom provider, но способ выбора конфигурации и запуска проверяйте по текущей инструкции BetterToken. Для VS Code Extension используйте отдельную инструкцию: не переносите туда CLI-профиль и способ аутентификации без проверки.
Диагностика по коду ошибки
Профиль не найден или конфигурация не применилась
Проверьте три точных совпадения: файл называется bt.config.toml, команда содержит --profile bt, а model_provider = "bettertoken" соответствует таблице [model_providers.bettertoken]. Затем полностью закройте Codex, откройте новый терминал и повторите короткий тест.
Старые переменные OpenAI могут перекрывать ожидаемый маршрут. В macOS/Linux проверьте только факт их наличия, не выводя значения:
test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY is set"
test -n "$OPENAI_BASE_URL" && echo "OPENAI_BASE_URL is set"
unset OPENAI_API_KEY OPENAI_BASE_URLВ PowerShell очистите их в текущей и будущих пользовательских сессиях:
Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")После очистки откройте новый терминал, снова задайте только BETTERTOKEN_API_KEY и запустите codex --profile bt.
404 или HTML вместо JSON
Чаще всего неверно собран endpoint. Проверьте, что в base_url нет /responses, /chat/completions или лишнего proxy-пути. Для BetterToken нужно ровно https://www.bettertoken.ai/v1.
401 или 403
Проверьте имя env_key, наличие переменной в том же процессе и права ключа. Если ключ мог попасть в лог, отзовите его и создайте новый.
model not found
Скопируйте текущий полный Model ID из Setup, model plaza или актуальной инструкции и убедитесь, что он доступен вашему ключу. Не угадывайте суффикс версии и не считайте название старой группы постоянным.
Ошибка Chat Completions или неподдерживаемого поля
Убедитесь, что wire_api = "responses" и провайдер действительно реализует Responses API, включая нужные Codex функции. Замена значения на chat не поможет: текущий справочник Codex поддерживает только responses.
Поток начинается и обрывается
Сначала повторите один маленький запрос. Затем проверьте proxy, timeout и поддержку SSE. Увеличение retry без ограничения может создать дублирующие запросы и лишний расход.
Как откатиться без потери официальной настройки
Поскольку provider вынесен в отдельный $CODEX_HOME/bt.config.toml, завершите текущую сессию и запустите Codex без --profile bt: тогда снова применяется основной $CODEX_HOME/config.toml. Не удаляйте auth.json и не заменяйте официальный токен сторонним API Key. Для VS Code Extension выполняйте откат по его отдельной инструкции.
Итог
Успешное подключение требует не просто «OpenAI-compatible» URL, а четыре совпадающих элемента: Responses API, правильный Base URL, доступный Model ID и ключ в окружении. Настройте их в отдельном профиле, выполните безопасный тест и проверьте расход.
Чтобы не копировать устаревшие поля, откройте текущую настройку BetterToken для Codex, создайте ключ с рабочим лимитом и запустите первый read-only запрос через профиль bt.
