How to configure a custom provider in Codex CLI config.toml

Direct answer

Put user-level settings in ~/.codex/config.toml and make model_provider = "custom" point to [model_providers.custom]. For BetterToken, use https://www.bettertoken.ai/v1 as base_url, responses as wire_api, and a Model ID from the GPT Key group. Use env_key to read the API Key from a local environment variable instead of storing it in TOML or a repository.

Find the correct config file

Environment	User-level config
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`
Windows + WSL	`~/.codex/config.toml` inside WSL

In the VS Code Codex extension, click the gear icon and choose Codex Settings → Open config.toml. The CLI and IDE extension share the same config layers.

Provider and authentication settings belong in user-level ~/.codex/config.toml. Project .codex/config.toml files can hold project overrides, but Codex ignores model_provider and model_providers there. Put project instructions in AGENTS.md.

Minimum working configuration

Set the API Key environment variable

macOS, Linux, or WSL:

export MODEL_PROVIDER_API_KEY="YOUR_API_KEY"

Windows PowerShell:

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

Replace YOUR_API_KEY with your BetterToken API Key. For persistent use, store it in a protected operating-system environment, not the project repository.

Edit config.toml

model_provider = "custom"
model = "gpt-5.5"

[model_providers.custom]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
env_key = "MODEL_PROVIDER_API_KEY"
wire_api = "responses"
requires_openai_auth = false

model is an example. Copy a currently available Model ID from the GPT Key group in the model plaza.

Restart and test

Exit Codex completely, open a new terminal, and run:

codex

Send a simple prompt. A normal response confirms the provider, authentication, and Model ID are active.

Recommended full configuration

Use this version when you need a review model and longer stream timeout:

model_provider = "custom"
model = "gpt-5.5"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
model_context_window = 1000000
model_auto_compact_token_limit = 900000
windows_wsl_setup_acknowledged = true

[model_providers.custom]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
env_key = "MODEL_PROVIDER_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

Merge existing top-level fields and [model_providers.custom] content. Do not declare the same TOML table twice.

How the fields fit together

Field	Purpose	BetterToken value
`model_provider`	Selects a provider ID	`"custom"`
`[model_providers.custom]`	Defines that provider	Must match `model_provider`
`base_url`	Model request endpoint	`https://www.bettertoken.ai/v1`
`env_key`	Names the environment variable containing the API Key	`MODEL_PROVIDER_API_KEY`
`wire_api`	Provider protocol	`"responses"`
`requires_openai_auth`	Uses official OpenAI authentication	`false` for ordinary third-party API setup
`model`	Default Model ID	A current GPT Key group ID

To keep the official Codex App login, plugins, and Remote Control while using a third-party API, use the dedicated official login and unified session setup instead of this ordinary authentication example.

Common errors

Symptom	Cause	Fix
Provider not found	`model_provider` does not match the table name	Use `custom` in both places
Missing API Key at startup	The environment variable is missing or the terminal has not reloaded it	Set `MODEL_PROVIDER_API_KEY` and open a new terminal
`401` or `403`	Wrong Key or mixed authentication methods	Copy the Key again; keep the `env_key` name aligned and `requires_openai_auth = false`
`404`	The Base URL lacks `/v1` or uses the wrong protocol	Use `https://www.bettertoken.ai/v1`
Model not found	The Model ID is unavailable or not in the GPT Key group	Copy a current ID from the model plaza
Changes do not apply	Wrong config layer, path, or WSL environment	Edit the user config in the environment that runs Codex, then restart Codex
TOML parse error	Duplicate table, quote, or nesting error	Remove duplicate `[model_providers.custom]` tables and check string quotes

Claude Code

Claude Desktop

Codex

Cursor

Cline

Model calls

Service assurance

Cost and tokens

Concepts

How to configure a custom provider in Codex CLI config.toml

Direct answer

Find the correct config file

Minimum working configuration

Recommended full configuration

How the fields fit together

Common errors

References

​Direct answer

​Find the correct config file

​Minimum working configuration

​Recommended full configuration

​How the fields fit together

​Common errors

​Related docs

​References

Direct answer

Find the correct config file

Minimum working configuration

Recommended full configuration

How the fields fit together

Common errors

Related docs

References