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

Codex CLI and Codex App share config.toml and auth.json for local tasks. This setup uses a BetterToken API Key through OpenAI Responses.

Key settings

Field	Value
API Key	`auth.json` → `OPENAI_API_KEY`
Base URL	`https://bettertoken.ai/v1`
Model	`gpt-6-astra`

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

Locate and back up your files

If you use a custom CODEX_HOME, edit config.toml and auth.json in that directory. Otherwise use ~/.codex on macOS / Linux or %USERPROFILE%\.codex on Windows. CLI and App must use the same directory. WSL has its own user directory. Fully quit Codex before editing. Back up both files to a private location. Create missing files if needed. Replace existing settings instead of appending duplicate keys or tables; keep unrelated settings.

This switches from ChatGPT login to API Key authentication. It does not preserve official account access. Protect auth.json and its backups; never commit or share them.

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 installation, check both files against the manual configuration below and correct any differences before starting Codex.

Manual setup

Edit config.toml

This guide uses user-level config.toml. Put root keys before all TOML tables, not inside [projects."<path>"]; that table stores project trust_level. The selected provider ID must match its table name. For file authentication, remove env_key and experimental_bearer_token from the selected provider.

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

This example uses GPT-6 Astra (gpt-6-astra). For another model, copy its complete ID from the model plaza and replace model. GPT, Kimi, and GLM use the same file-auth structure; automatic setup is available for GPT.

Edit auth.json

auth.json is in the same directory as config.toml. If auth.json does not exist, create it in that directory. Set its contents to the following JSON, replace YOUR_API_KEY with your BetterToken API Key, and save the file.

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

Configuration parameters

Parameter	Purpose and location	Defaults and examples
`model_provider`	User config root; selects the provider ID defined below.	Defaults to `openai`; this guide uses `bettertoken`.
`model`	Root; the full Model ID from the model plaza.	Example: `gpt-6-astra`; replace as needed.
`cli_auth_credentials_store`	Root; chooses the login credential store.	This guide sets `file` to read `auth.json` in the same directory.
`name`	Provider table; a display name only.	`BetterToken` is not a Model ID.
`base_url`	Provider table; the model API Base URL.	Use `https://bettertoken.ai/v1`; Codex appends `/responses`.
`wire_api`	Provider table; the request protocol.	Only `responses` is currently supported; it is also the default.
`requires_openai_auth`	Provider table; uses OpenAI authentication and its credential store.	Defaults to `false`; this guide uses `true`. It is not a switch that preserves login files.
`supports_websockets`	Provider table; Responses WebSocket support.	Defaults to `false`; this guide keeps HTTP/SSE transport.
`auth_mode`	In `auth.json`; selects the authentication mode.	Set to `apikey` here; this replaces official ChatGPT authentication.
`OPENAI_API_KEY`	In `auth.json`; the API authentication credential.	Replace `YOUR_API_KEY` with your BetterToken API Key.

File authentication here switches to API Key mode. To keep your official account, use official-login preservation; do not mix the two modes. They differ by authentication goal, not by CLI, App, or Extension.

Optional tuning

These three settings are optional tuning, not connection requirements. Merge them into the existing [model_providers.bettertoken] table when needed; do not create a duplicate table.

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000

Parameter	Purpose and location	Defaults and examples
`request_max_retries`	Provider table; maximum HTTP request retries.	Default: `4`; adjust for your connection.
`stream_max_retries`	Provider table; reconnection retries after a stream interruption.	Default: `5`; `8` is an optional custom value.
`stream_idle_timeout_ms`	Provider table; stream inactivity timeout in milliseconds.	Default: `300000`; this is an idle timeout, not a total task deadline.

Configuration layers and legacy keys

Do not put model or reasoning settings inside [projects."<path>"]. Project-specific models can use root keys in a trusted project’s .codex/config.toml; provider and authentication settings remain in user config. Current named profiles use NAME.config.toml under CODEX_HOME, selected with codex --profile NAME, not legacy [profiles.NAME] tables or the root profile selector.

Verify the connection

Save both files. In the terminal, start a new Codex CLI session directly:

codex

Fully quit Codex App, including background processes, then reopen it and create a new local task. Send a short prompt in each client you use. A normal response verifies that client’s connection.

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

For 401, 403, or a sign-in prompt, check the active directory, the Key in auth.json, auth_mode = apikey, cli_auth_credentials_store = file, and requires_openai_auth = true. For provider or model errors, check the matching provider ID, https://bettertoken.ai/v1, wire_api = responses, and the model’s availability. If changes do not apply, check configuration overrides and confirm CLI and App use the same CODEX_HOME.

Advanced setup

Codex Extension

CLI, App, and Extension share configuration when they use the same CODEX_HOME. Choose authentication by goal: API Key access or preserving official sign-in. Codex Extension setup guide

Official 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

Locate and back up your files

Command-line setup

Manual setup

Edit config.toml

Edit auth.json

Configuration parameters

Optional tuning

Configuration layers and legacy keys

Verify the connection

Switch models

Common errors

Advanced setup

Codex Extension

Official reference

Technical details

​Key settings

​Prerequisites

​Install

​Locate and back up your files

​Command-line setup

​Manual setup

​Edit config.toml

​Edit auth.json

​Configuration parameters

​Optional tuning

​Configuration layers and legacy keys

​Verify the connection

​Switch models

​Common errors

​Advanced setup

​Codex Extension

​Related FAQ

​Official reference

​Technical details

Key settings

Prerequisites

Install

Locate and back up your files

Command-line setup

Manual setup

Edit config.toml

Edit auth.json

Configuration parameters

Optional tuning

Configuration layers and legacy keys

Verify the connection

Switch models

Common errors

Advanced setup

Codex Extension

Related FAQ

Official reference

Technical details