Как подключить OpenAI-совместимый API к Codex

Что подготовить

• Node.js и npm: они нужны для установки официального Codex CLI.
• Свой аккаунт BetterToken, собственный API Key и текущий полный Model ID из Setup или model plaza.
• Баланс или доступный тестовый лимит для одного короткого запроса.
• Терминал macOS/Linux либо Windows PowerShell. Ниже приведены команды для обеих систем.
• Для другого провайдера — подтверждение поддержки Responses API, SSE streaming и нужных вам tool calls.

Перед настройкой проверьте совместимость

Если провайдер показывает только пример 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?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie"
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%60.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-016&utm_content=openai-sovmestimyy-api-codex-podklyuchenie

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.