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.
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):
| Field | Official 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
| Error | Usual cause | Fix |
|---|---|---|
401 invalid_api_key | CENT_AI_KEY is empty in this terminal, or env_key names another variable | Set the variable in the terminal that starts Codex; make the names match |
404 model_not_found | model is not a name from the model list | Copy the name exactly, for example gpt-6-sol |
501 not_available_yet | base_url points at the wrong path | Use https://api.cent-ai.dev/v1, with /v1 and nothing after it |
429 rate_limited | More than 600 requests per minute on one key | Spread 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:
| Model | Input | Cache read | Cache write | Output |
|---|---|---|---|---|
| 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
- learn.chatgpt.com/docs/config-file/config-reference (opens in a new tab) · accessed 2026-11-14
- learn.chatgpt.com/docs/config-file/config-advanced (opens in a new tab) · accessed 2026-11-14
- cent-ai.dev/docs/integrations/codex (opens in a new tab) · accessed 2026-11-14
Related posts
- Card declined when paying for an AI API? What to checkpayment · 3 minCommon things to check when a debit or credit card is declined while buying AI API credits, and a prepaid alternative with QRIS or USDT/USDC.
- OpenCode and Cline with a prepaid APIopencode · 3 minPoint OpenCode and the Cline CLI at an API funded with QRIS or crypto, the steps we ran on OpenCode 2.3.0 and Cline 3.0.74, and the measured cost of one turn.
- Claude Code usage limit reached: how to keep workingclaude-code · 5 minWhy Claude Code stops with "Usage limit reached" on a Pro or Max plan, the official ways to continue, and how to run it on a prepaid API key with no 5-hour window.