# 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

```bash
# 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 --version
```

```powershell
powershell -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`.

```bash
export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models
```

```powershell
setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards
```

## config.toml for GPT models

```toml
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 |

> Don't add `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.

```toml
[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 = false
```

```toml
model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"
```

```bash
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/.config.toml`, with its keys at the top level; `[profiles.]` 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:

```bash
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 active
```

## Retries 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.

```toml
[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000
```

## Troubleshooting: 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](/topup/) |
| `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](/claude-code/vs-codex/).

## FAQ

### Where is the Codex config file?

~/.codex/config.toml (or $CODEX_HOME/config.toml). The CLI, codex exec and the IDE extension all read it. A project's .codex/config.toml cannot set providers.

### Can Codex CLI use Claude models?

Yes, through a gateway that accepts Responses API requests for Claude models. Add a provider with a Claude key and set model to an ID such as claude-sonnet-5.

### Does wire_api = "chat" still work in Codex?

No. The Codex config reference lists responses as the only supported value, and it is the default when omitted.

### Why does the Codex VS Code extension say invalid API key when the CLI works?

env_key is read from the editor's environment. Set the variable system-wide or start the editor from a terminal where it is exported.

### What does 'No active subscription found for this group' mean in Codex?

The key belongs to a subscription (Unlimited) group with no active plan. Use a key from a pay-as-you-go group or buy a plan.

---

Source: https://aiprimetech.io/learn/use-claude-api-with-codex/
Provider: AI Prime Tech — independent Anthropic-compatible API gateway (not affiliated with Anthropic).