Codex CLI/App Custom Provider: config.toml, API Key, and Base URL

Codex CLI and Codex App connect to BetterToken through OpenAI Responses. The configuration file is ~/.codex/config.toml, and the API Key is supplied through BETTERTOKEN_API_KEY.

Key settings

Field	Value
API Key	`BETTERTOKEN_API_KEY` environment variable
Base URL	`https://bettertoken.ai/v1`
Model	`YOUR_MODEL_ID`

Prerequisites

Install Node.js
Create a BetterToken API Key
Copy a Model ID from the model plaza or the key Setup dialog

Install

npm install -g @openai/codex

Command-line setup

The BetterToken Automatic setup script writes the Codex provider configuration. It requires Node.js and prompts for the API Key or Model ID when they are not passed as arguments.

macOS / Linux
Windows

curl -fsSL "https://bettertoken.ai/install-codex-provider.sh" | bash

iwr "https://bettertoken.ai/install-codex-provider.ps1" -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

After it finishes, open ~/.codex/config.toml (or %USERPROFILE%\.codex\config.toml on Windows), confirm that model, review_model, and the BetterToken provider were written correctly, and fully restart Codex.

Manual setup

GPT, Kimi, and GLM use the same config.toml structure. Only replace YOUR_MODEL_ID with a current Model ID from the selected provider. One-click command-line setup is currently available for GPT only.

Set the API Key

macOS / Linux
Windows PowerShell

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Add this line to ~/.zshrc or ~/.bashrc to persist it.

[Environment]::SetEnvironmentVariable("BETTERTOKEN_API_KEY", "YOUR_API_KEY", "User")
$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Do not put a BetterToken API Key in ~/.codex/auth.json. That file is for the official Codex login; a custom provider should read the environment variable through env_key.

Configure config.toml

Edit ~/.codex/config.toml:

model_provider = "custom"
model = "YOUR_MODEL_ID"
review_model = "YOUR_MODEL_ID"
model_reasoning_effort = "high"

[model_providers.custom]
name = "BetterToken"
base_url = "https://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

model_provider = "custom" must match the [model_providers.custom] table. Replace both YOUR_MODEL_ID values with a current complete Model ID.

Verify the connection

Open a new terminal and run:

codex

Send a short task. A streamed response without login, 401, or model errors confirms the setup.

Switch models

Change model and, optionally, review_model. Save the file, stop the current Codex process, and start it again. Use the Model ID from the Setup dialog or model plaza.

Common errors

Error	Fix
`401` or an OpenAI sign-in prompt	Check `BETTERTOKEN_API_KEY` and confirm `requires_openai_auth = false`.
Provider not found	Make `model_provider = "custom"` match `[model_providers.custom]`.
API mode error	Keep `wire_api = "responses"`; do not switch to Chat Completions.
Model not found	Replace `YOUR_MODEL_ID` with a current complete ID from Setup or the model plaza.
Configuration not applied	Open a new terminal, verify the environment variable, and fully restart Codex.

Advanced setup

Supported providers

Provider	Status
Claude	Not supported
GPT	Command-line + manual setup
Kimi	Manual setup
GLM	Manual setup

Statuses apply to the BetterToken setup documented on this page.

What the setup methods mean

Command-line + manual setup: use a generated command or follow the complete manual steps.
Manual setup: enter the API Key, Base URL, and Model.
Not supported: no verified direct setup is currently available.

Codex Extension

The Codex VS Code Extension shares config.toml, but preserving the official login uses a different authentication configuration. See the Codex Extension setup guide.

CLI/App setup and Extension setup with an official login are alternatives. Do not paste two [model_providers.custom] tables into the same TOML file.

Official reference

Codex configuration reference

Technical details

Responses protocol

Codex uses OpenAI Responses. Set base_url to https://bettertoken.ai/v1 and keep wire_api = "responses". Codex appends /responses.

Getting started

Coding Agent setup

AI application platform setup

Advanced

Codex CLI/App Custom Provider: config.toml, API Key, and Base URL

Key settings

Prerequisites

Install

Command-line setup

Manual setup

Set the API Key

Configure config.toml

Verify the connection

Switch models

Common errors

Advanced setup

Supported providers

Codex Extension

Official reference

Technical details

​Key settings

​Prerequisites

​Install

​Command-line setup

​Manual setup

​Set the API Key

​Configure config.toml

​Verify the connection

​Switch models

​Common errors

​Advanced setup

​Supported providers

​Codex Extension

​Related FAQ

​Official reference

​Technical details

Key settings

Prerequisites

Install

Command-line setup

Manual setup

Set the API Key

Configure config.toml

Verify the connection

Switch models

Common errors

Advanced setup

Supported providers

Codex Extension

Related FAQ

Official reference

Technical details