Checked 2026-10-27

Codex CLI on one key

Add RelaySwitch to Codex CLI as a custom model provider: one config.toml block, the key from an environment variable, and a profile file for each model you switch to.

A Codex CLI custom provider is a [model_providers.<id>] table in ~/.codex/config.toml: a base URL, a wire API and an environment variable that holds the key. Point it at https://api.relayswitch.io/v1 and Codex runs the GPT models on the Models page from a prepaid balance, billed per token.

Two changes break older setup guides. Codex now accepts one wire API, and profiles moved out of config.toml into their own files. Both are below, with the menu bug that rewrites a profile.

01What you need

  • Codex CLI installed (codex on your PATH). Profile files need Codex 0.134.0 or later.
  • A RelaySwitch key from the console (email-code sign-in). Keys start with sk-relay-.
  • A prepaid balance, from $10 by card or crypto, no subscription and no KYC. The console chat runs 12 free turns a day before the first top-up; Codex requests bill the balance.

02Codex CLI custom provider block

toml
1# ~/.codex/config.toml
2model = "gpt-5.5"
3model_provider = "relayswitch"
4
5[model_providers.relayswitch]
6name = "RelaySwitch"
7base_url = "https://api.relayswitch.io/v1"
8env_key = "RELAYSWITCH_API_KEY"
9wire_api = "responses"
  • model_provider selects the table by its id. The ids openai, ollama and lmstudio are reserved, so the table needs its own name.
  • base_url: https://api.relayswitch.io/v1, with the /v1. Codex adds /responses.
  • env_key names the variable that holds the key. The key never goes in the file.
  • wire_api = "responses": the Responses API. Codex's config reference lists responses as the only supported value and the default, so the line is optional. RelaySwitch serves /v1/responses and /v1/chat/completions; Codex uses the first.

Keys follow Codex's Advanced Configuration and Configuration Reference pages (read 2026-10-27).

03Steps

  1. Add the block above to ~/.codex/config.toml.
  2. Export the key in the shell that runs Codex, then start it:
bash
1export RELAYSWITCH_API_KEY="sk-relay-..."
2codex
  1. Send a prompt. The request shows on the console's Usage page within seconds, with its tokens and its charge.

Add the export to your shell profile so new terminals have it. For one run on another model, use the flag: codex --model gpt-5.3-codex.

04A profile per model

A profile is a file named ~/.codex/<name>.config.toml holding only the keys that differ from config.toml. Start Codex with --profile <name> and it layers the file on top. Since Codex 0.134.0, [profiles.<name>] tables inside config.toml are ignored and the top-level profile = selector is gone. Guides written before that still show the old form.

toml
1# ~/.codex/relay-codex.config.toml
2model_provider = "relayswitch"
3model = "gpt-5.3-codex"
4model_reasoning_effort = "medium"
toml
1# ~/.codex/relay-sol.config.toml
2model_provider = "relayswitch"
3model = "gpt-6.1-sol"
4model_reasoning_effort = "medium"
toml
1# ~/.codex/relay-mini.config.toml
2model_provider = "relayswitch"
3model = "gpt-5.4-mini"
4model_reasoning_effort = "medium"
bash
1codex --profile relay-codex
2codex exec --profile relay-codex "review this change"

model_reasoning_effort takes low, medium, high, xhigh or max, as far as the model offers them. Codex sends it with each request and RelaySwitch passes it through.

05The /model menu pitfall

With a custom provider active, the /model menu lists Codex's built-in OpenAI models, not your provider's. Picking one rewrites the active profile file: the model changes, the provider stays. The report is openai/codex issue #35487, open on 2026-10-27.

On RelaySwitch the damage depends on the id the menu writes. An id that is also on the Models page keeps working, at that model's price. Any other id returns 404. To undo it, open the profile file, set model back, and start Codex again. To switch models without the menu, use --profile or --model.

06Which model to pick

Codex is built around GPT models on the Responses API, so the table holds the GPT ids on the key. Every agent turn resends the session and the tool output, so input and cached rates carry most of the bill.

ModelInputCachedOutputDeveloper list in / outContext
GPT-5.5$1.80 (64% under)$0.16$9.00 (70% under)$5.00 / $30.001.1M tokens
GPT-5.3-Codex$1.75$0.18$14.00$1.75 / $14.00400K tokens
GPT-6.1 Sol$0.60 (70% under)$0.06$3.00 (70% under)$2.00 / $10.001.1M tokens
GPT-5.4 Mini$0.75$0.075$4.50$0.75 / $4.50400K tokens
GPT-6 Luna$0.0625 (37% under)$0.0125$0.20 (60% under)$0.10 / $0.501.1M tokens

USD per million tokens, read from the RelaySwitch catalog when this page was built. Developer list: the catalog's record of the developer's own price.

For Claude, DeepSeek or Kimi in a terminal agent, use OpenCode, which talks Chat Completions. How the prepaid balance and the cached rate work is on Pricing.

07What a coding task costs

The task: 40 Codex turns on one change, each sending 80,000 tokens of earlier context and 2,000 new input tokens, with 1,500 output tokens back. The sizes are an assumption; the console's Usage page shows your real ones.

ModelContext from cacheNo cache hits
GPT-6 Luna$0.057$0.217
GPT-6.1 Sol$0.42$2.15
GPT-5.4 Mini$0.57$2.73
GPT-5.5$1.20$6.44
GPT-5.3-Codex$1.56$6.58

40 turns at the live per-token prices. A model with no cached rate bills cached tokens at its input rate.

Cache hits depend on the model and the request. When earlier context comes from the cache, the response reports cached tokens and they bill at the cached rate.

With cache hits the task runs $0.057 on GPT-6 Luna and $1.56 on GPT-5.3-Codex. A light profile for routine edits and the flagship for hard reviews keeps the balance going longer.

08Errors and fixes

Check the key and the Responses path outside Codex first. -i prints the headers, including the request id:

bash
1curl -i https://api.relayswitch.io/v1/responses \
2 -H "Authorization: Bearer $RELAYSWITCH_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{"model": "gpt-5.5", "input": "Say ok."}'
  • 401: the key is wrong or revoked, or RELAYSWITCH_API_KEY is empty in the shell that started Codex. Export it and start Codex again.
  • 402: the balance is too low. Top up in the console; the key works again at once.
  • 404: the model id is not in the catalog, often after the /model menu rewrote a profile. Fix the model line.
  • 429: the key hit its rate limit. Wait and resend, or create a key with a higher Requests / min in the console.
  • wire_api = "chat" from an older guide: Codex no longer accepts it. Set responses or delete the line.
  • A profile has no effect: it is still a [profiles.<name>] table in config.toml. Move its keys into ~/.codex/<name>.config.toml.
  • The table is not used: its id is a reserved name (openai, ollama, lmstudio), or model_provider names a different id.

The full error table is in the docs.

Questions

How do I add a custom provider to Codex CLI?
Add a [model_providers.relayswitch] table to ~/.codex/config.toml with name, base_url and env_key, then set model_provider = "relayswitch" and a model id.
Which wire_api should a Codex custom provider use?
responses. Codex lists it as the only supported value and the default, so the line can be left out. Older guides that set chat no longer work.
Where does Codex read the API key for a custom provider?
From the environment variable named in env_key. Export RELAYSWITCH_API_KEY in the shell that runs Codex; the key stays out of config.toml.
How do I switch providers or models in Codex CLI?
Keep one profile file per setup in ~/.codex/<name>.config.toml and start Codex with --profile <name>, or pass --model for one run. Avoid the /model menu while a custom provider is active.
Can Codex CLI use a custom API endpoint for non-OpenAI models?
Codex speaks only the Responses API, and it is built around GPT models. For Claude, DeepSeek or Kimi in a terminal agent, the OpenCode guide covers a Chat Completions setup on the same key.
Related

Run Codex on a prepaid balance

One key, from $10 by card or crypto. No KYC, no subscription.

ModelsGet a key