Codex CLI custom provider in config.toml

Add a custom model provider to Codex CLI in ~/.codex/config.toml with wire_api = "responses", keep the key in an environment variable, and check it with one curl request.

Cent AIPublished 3 min read

Codex CLI talks to OpenAI by default, but its config file can point it at any provider that speaks the OpenAI Responses format. This post shows the provider block in ~/.codex/config.toml, what each field does, and how to check the setup before you start a session.

Where the config lives

The Codex configuration reference says: "User-level configuration lives in ~/.codex/config.toml" (source). On Windows that is %USERPROFILE%\.codex\config.toml. Custom providers go in this user file; a project's .codex/config.toml cannot define them.

The fields of a custom provider

A custom provider is a [model_providers.<id>] table. The reference lists these fields (source):

FieldOfficial description
name"Display name for a custom model provider."
base_url"API base URL for the model provider."
env_key"Environment variable supplying the provider API key."
wire_api"Protocol used by the provider. responses is the only supported value, and it is the default when omitted."

Two top-level keys choose what Codex uses: model, the model name, and model_provider, the "Provider id from model_providers (default: openai)". The IDs openai, ollama and lmstudio "are reserved and cannot be overridden", so give your provider its own ID.

Older guides on the web still show wire_api = "chat". The current reference lists responses as the only supported value, so a provider must serve the Responses endpoint.

A working example

Cent AI serves the Responses format at https://api.cent-ai.dev/v1, and Codex adds /responses itself. Add this to ~/.codex/config.toml:

model = "gpt-6-sol"
model_provider = "centai"

[model_providers.centai]
name = "Cent AI"
base_url = "https://api.cent-ai.dev/v1"
env_key = "CENT_AI_KEY"
wire_api = "responses"

The key stays out of the file. Set it in the environment, replacing YOUR_API_KEY with a key from Keys:

export CENT_AI_KEY="YOUR_API_KEY"
$env:CENT_AI_KEY = "YOUR_API_KEY"

Codex sends the key as Authorization: Bearer. To keep it across terminals, add the same line to ~/.bashrc or your PowerShell $PROFILE. We tested this block with Codex 0.161.0 on 2026-11-13; the Codex guide has the full steps.

Check it before the first session

Send one Responses request with the same key and base URL:

curl https://api.cent-ai.dev/v1/responses \
  -H "Authorization: Bearer $CENT_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"Hello"}'

If it answers, start codex from the same terminal. If curl works and Codex does not, the difference is in the config file or the environment, not in the key. The response has usage.cost, the amount charged for that request in USD.

Common errors

ErrorUsual causeFix
401 invalid_api_keyCENT_AI_KEY is empty in this terminal, or env_key names another variableSet the variable in the terminal that starts Codex; make the names match
404 model_not_foundmodel is not a name from the model listCopy the name exactly, for example gpt-6-sol
501 not_available_yetbase_url points at the wrong pathUse https://api.cent-ai.dev/v1, with /v1 and nothing after it
429 rate_limitedMore than 600 requests per minute on one keySpread parallel sessions over several keys

What it costs

Every model has four rates per million tokens. Codex resends the conversation on every turn, so most input of a long session is usually read from cache. Rates of two models that work well with Codex, from the pricing page on 2026-11-14, per 1M tokens:

ModelInputCache readCache writeOutput
gpt-6-sol$0.26$0.044$0.26$1.30
gpt-6.1-sol$0.20$0.02$0.20$1.00

Each turn appears on the Requests page of the dashboard with its tokens per rate and its cost. You pay from a prepaid balance, topped up with QRIS or with USDT or USDC on Solana (network fees charged by your wallet are yours). Every payment is manual, with no auto-renewal.

Sources

  1. learn.chatgpt.com/docs/config-file/config-reference (opens in a new tab) · accessed 2026-11-14
  2. learn.chatgpt.com/docs/config-file/config-advanced (opens in a new tab) · accessed 2026-11-14
  3. cent-ai.dev/docs/integrations/codex (opens in a new tab) · accessed 2026-11-14
ShareXThreads