# Codex CLI setup: add a custom model provider in config.toml

> Connect OpenAI Codex CLI to our gateway with a model_providers entry in ~/.codex/config.toml, a key env var and the Responses wire API, plus checks and fixes.

Source: https://oneaiapikey.com/docs/guides/codex-cli

Base URL: `https://api.oneaiapikey.com/v1`

Codex CLI lets you register any service that implements the OpenAI Responses API as a model provider. Our gateway does, so the whole setup is one small block in Codex’s config file plus an environment variable for your key. Every token Codex uses is billed against your prepaid balance at the published rates.

## What you need

- Codex CLI installed (for example with `npm install -g @openai/codex`) and starting normally.
- A funded account; top-ups start at $3: [create an account](https://oneaiapikey.com/console/sign-up).
- An API key from the [API keys page](https://oneaiapikey.com/console/keys) (it starts with `sk-`).

## Step 1: store your key in an environment variable

Codex never reads the key from the config file. Instead, the provider entry names an environment variable (`env_key`) and Codex reads the key from there at startup. We’ll call it `RELAYKIT_API_KEY`, but any name works as long as the config matches.

macOS / Linux / Git Bash:

```bash
# add to ~/.bashrc or ~/.zshrc to keep it
export RELAYKIT_API_KEY="sk-your-key-here"
```

Windows PowerShell:

```powershell
# current window only
$env:RELAYKIT_API_KEY = "sk-your-key-here"
# persist for new terminals (then open a new window)
setx RELAYKIT_API_KEY "sk-your-key-here"
```

`setx` only affects terminals opened afterwards, so close and reopen your terminal before running Codex.

## Step 2: add the provider to config.toml

Codex keeps its settings in `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`). Create the file if it doesn’t exist, then add:

~/.codex/config.toml:

```toml
# Default model and provider for every Codex session
model = "gpt-6.1-sol"
model_provider = "relaykit"

[model_providers.relaykit]
name = "Relaykit"
base_url = "https://api.oneaiapikey.com/v1"
env_key = "RELAYKIT_API_KEY"
wire_api = "responses"
# Optional resilience settings
stream_idle_timeout_ms = 300000
request_max_retries = 4
```

What each line does:

- `model_provider` tells Codex to send requests to the provider block below instead of OpenAI.
- `base_url` **must end in `/v1`**. Codex appends the endpoint path (`/responses`) to it.
- `env_key` is the name of the variable holding your key, not the key itself.
- `wire_api = "responses"` selects the Responses API, which is what current Codex releases speak. Older guides on the web show `wire_api = "chat"`; that value has been retired in recent versions.
- `stream_idle_timeout_ms` gives long reasoning steps more room before Codex treats a quiet stream as dead.

If you already have a `config.toml`, keep your other settings and just add these keys. TOML is strict: top-level keys such as `model` must appear before the first `[section]` header.

## Step 3: pick a model

Codex is tuned for GPT models and their tool-calling style, so those are what we recommend here. Rates are USD per 1M tokens:

| Model id | Good for | Input | Output |
| --- | --- | --- | --- |
| `gpt-6.1-sol` | Codex CLI, Tool calling, Long context | $2.20 | $11 |
| `gpt-5.6-terra` | General coding, Writing, RAG | $2.20 | $13.20 |
| `gpt-5.6-sol` | Hard reasoning, Planning, Math | $5.50 | $33 |

`gpt-6.1-sol` is a strong default for agentic coding. Switch per session with the `-m` flag or a one-off config override:

Per-session model:

```bash
codex -m gpt-5.6-terra
codex --config model='"gpt-5.6-sol"'
```

You can also change models inside the interactive UI with `/model`. Want Claude in the terminal instead? Use [Claude Code](https://oneaiapikey.com/docs/guides/claude-code), which talks to our Anthropic-compatible endpoint natively.

## Step 4: verify it works

Run a one-shot, non-interactive prompt:

Smoke test:

```bash
codex exec "Reply with the single word: ready"
```

You should see the model’s reply printed in the terminal, and a matching entry in your console’s usage log a few seconds later. In an interactive session, `/status` shows the active model and provider so you can confirm Codex picked up the right block.

## Troubleshooting

**“Missing environment variable” or 401 Unauthorized.** Codex couldn’t find a valid key. Check that the variable name in `env_key` matches exactly (it’s case-sensitive on macOS and Linux), that you opened a new terminal after `setx`, and that the key wasn’t revoked in the console. Paste the key without quotes or trailing spaces.

**404 Not Found.** The base URL is off by a path segment. It must be `https://api.oneaiapikey.com/v1`: without `/v1` Codex calls a path that doesn’t exist, and with a full endpoint such as `/v1/responses` the path gets doubled.

**Model not found / no available channel.** The `model` value doesn’t match a catalogue id. Ids are lowercase and use dots and dashes exactly as shown on the [models page](https://oneaiapikey.com/models).

**Stream disconnected or the request times out.** Codex always streams, so long outputs stay alive as long as tokens keep flowing. If a long reasoning pause trips the idle timer, raise `stream_idle_timeout_ms`. In your own scripts, use `"stream": true` for long generations: proxies cut idle non-streaming requests at roughly 100 seconds.

**Codex ignores my provider.** Usually a TOML ordering problem (top-level keys placed under a section) or a typo in `model_provider`. The value must equal the name after `model_providers.` exactly.

**Balance ran out mid-task.** Requests are refused at zero balance. [Top up](https://oneaiapikey.com/console/billing) in the console and re-run; nothing in your config needs to change.

## Next steps

Head to the [quickstart](https://oneaiapikey.com/docs/quickstart) for raw API and SDK examples using the same key, or browse the other [tool guides](https://oneaiapikey.com/docs/guides). Compare per-model costs on the [pricing page](https://oneaiapikey.com/pricing) before kicking off a long autonomous run.

## Other OpenAI format tools

- [Cursor IDE](https://oneaiapikey.com/docs/guides/cursor)
- [Cline Extension](https://oneaiapikey.com/docs/guides/cline)
- [Kilo Code Extension](https://oneaiapikey.com/docs/guides/kilo-code)