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

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.
• An API key from the API keys page (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.

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

# 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:

# 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:

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

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, which talks to our Anthropic-compatible endpoint natively.

Step 4: verify it works

Run a one-shot, non-interactive prompt:

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.

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 in the console and re-run; nothing in your config needs to change.

Next steps

Head to the quickstart for raw API and SDK examples using the same key, or browse the other tool guides. Compare per-model costs on the pricing page before kicking off a long autonomous run.