Codex CLI with a custom provider: config.toml, GPT and Claude models, IDE extension and fixes
Codex reads one file, ~/.codex/config.toml, shared by the CLI, codex exec and the IDE extension. A custom provider in that file points Codex at this gateway, where the same setup runs GPT models and Claude models. Current Codex versions speak only the Responses API (wire_api = "responses"), so older guides that use wire_api = "chat" no longer work.
Install Codex
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# or with a package manager
npm install -g @openai/codex
brew install --cask codex
codex --versionpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"The Codex extension for VS Code, Cursor and Windsurf installs from the editor's extension marketplace and uses the same ~/.codex/config.toml as the CLI, so everything below applies to both.
Use a key from the right group
A gateway key belongs to one group, and the group decides which models the key can call. For GPT models, create the key in the **Codex** group in the dashboard. For Claude models, any Claude pay-as-you-go key works. A key from an Unlimited group needs an active plan; without one, every request fails with No active subscription found for this group.
export AIPRIME_CODEX_KEY=key_from_the_codex_group # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group # Claude modelssetx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwardsconfig.toml for GPT models
model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"
[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false| Setting | Why |
|---|---|
[model_providers.aiprime] | Any id except the reserved openai, ollama and lmstudio |
base_url = "https://aiprimetech.io/v1" | Codex appends /responses to it |
env_key | The **name** of the environment variable that holds the key, not the key itself |
wire_api = "responses" | The only value current Codex accepts |
supports_websockets = false | Keeps Codex on plain HTTP streaming, which works through any proxy or VPN |
requires_openai_auth = true or experimental_bearer_token to this provider. With requires_openai_auth = true Codex ignores env_key and sends your ChatGPT or OpenAI login instead, which the gateway rejects.Run Codex on Claude models
The gateway accepts Responses API requests for Claude models and translates them, so Codex can drive Claude as well. Add a second provider that uses your Claude key, then a profile to switch to it.
[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = falsemodel_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"codex --profile claude
codex exec --profile claude "review the last commit for bugs"Since Codex 0.134.0 a profile is its own file, ~/.codex/<name>.config.toml, with its keys at the top level; [profiles.<name>] tables inside config.toml are no longer read. Profiles and providers can only be set in your user config: a project's .codex/config.toml ignores model_provider and model_providers.
Models and reasoning effort
| Model ID | Provider | Use it for |
|---|---|---|
gpt-6-astra | Codex group key | The strongest GPT model on the gateway; long agent tasks |
gpt-6-sol | Codex group key | Faster and cheaper GPT for routine coding |
gpt-5.6-terra | Codex group key | Light tasks and quick edits |
claude-sonnet-5 | Claude key | Default Claude for coding work |
claude-opus-5-5 | Claude key | Harder reasoning and large refactors |
claude-fable-5-1 | Claude key | Most capable and most expensive |
model_reasoning_effort accepts low, medium, high, xhigh or max, depending on the model. Don't set none: these models reject it with 'none' is not supported. review_model sets a different model for /review if you want one. The dashboard shows every model your key's group can call.
IDE extension and codex exec
The IDE extension reads the same config.toml, but env_key is resolved from the editor's own environment. An editor started from the dock or Start menu does not see variables exported in .bashrc, and Codex then fails with Invalid API key while the CLI works. Set the variable system-wide (on Windows setx does this), or start the editor from a terminal, e.g. code ..
codex exec runs one task without the interactive UI, which suits scripts and CI. It uses the same config and profiles:
codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status # which authentication method is activeRetries and timeouts
Each provider has its own retry and stream settings. The defaults are 4 request retries, 5 stream reconnects and a 5-minute idle timeout per stream. Long reasoning turns can sit silent for a while, so raising the idle timeout helps on high effort levels.
[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000Troubleshooting: errors Codex users hit
The errors below are the ones Codex clients actually produce on this gateway, most common first.
| What you see | Cause | Fix |
|---|---|---|
403 No active subscription found for this group | The key belongs to an Unlimited group with no active plan | Use a key from a pay-as-you-go group (Codex for GPT), or buy a plan |
401 Invalid API key | The variable is empty in the process running Codex (often the IDE), or requires_openai_auth = true made Codex send another login | echo $AIPRIME_CODEX_KEY; remove requires_openai_auth; restart the editor |
404 Model "..." is not supported by any configured account in this group | The model doesn't belong to the key's group, e.g. a Claude model with a GPT key | Switch provider or profile so the key matches the model |
426 WebSocket upgrade required | The WebSocket transport is on but the connection was not upgraded | supports_websockets = false, and remove responses_websockets_v2 from [features] |
403 Your API key has expired | The key was created with an expiry date | Create a new key in the dashboard |
'none' is not supported | Reasoning effort set to none | Use low or higher |
404 page not found | base_url contains /v1 twice | Use exactly https://aiprimetech.io/v1 |
Config error about wire_api after an upgrade | A wire_api = "chat" line from an old guide | Set wire_api = "responses" |
Your balance is used up | Balance is empty | Top up |
Concurrency limit exceeded for user | Several Codex agents or windows running at once | Run fewer in parallel, or ask support for higher concurrency |
Comparing Codex with Claude Code before you commit to one? See Claude Code vs Codex.
Frequently asked questions
Where is the Codex config file?
Can Codex CLI use Claude models?
Does wire_api = "chat" still work in Codex?
Why does the Codex VS Code extension say invalid API key when the CLI works?
What does 'No active subscription found for this group' mean in Codex?
Get an API key — no Anthropic account or waitlist required.
Get your API keyAI Prime Tech is an independent API gateway. It is not affiliated with, endorsed by, or a reseller of Anthropic. Claude and related model names are trademarks of their respective owners.