--- title: "Codex CLI custom provider setup with one key" canonical: https://relayswitch.io/guides/codex-cli generated: 2026-11-02T12:05:57.610Z source: https://api.relayswitch.io/v1/catalog base_url: https://api.relayswitch.io/v1 --- 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.]` 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](https://relayswitch.io/models) 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](https://app.relayswitch.io/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` 2`model = "gpt-5.5"` 3`model_provider = "relayswitch"` 4 5`[model_providers.relayswitch]` 6`name = "RelaySwitch"` 7`base_url = "https://api.relayswitch.io/v1"` 8`env_key = "RELAYSWITCH_API_KEY"` 9`wire_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](https://learn.chatgpt.com/docs/config-file/config-advanced) and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-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 1`export RELAYSWITCH_API_KEY="sk-relay-..."` 2`codex` 3. 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/.config.toml` holding only the keys that differ from config.toml. Start Codex with `--profile ` and it layers the file on top. Since Codex 0.134.0, `[profiles.]` 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` 2`model_provider = "relayswitch"` 3`model = "gpt-5.3-codex"` 4`model_reasoning_effort = "medium"` toml 1`# ~/.codex/relay-sol.config.toml` 2`model_provider = "relayswitch"` 3`model = "gpt-6.1-sol"` 4`model_reasoning_effort = "medium"` toml 1`# ~/.codex/relay-mini.config.toml` 2`model_provider = "relayswitch"` 3`model = "gpt-5.4-mini"` 4`model_reasoning_effort = "medium"` bash 1`codex --profile relay-codex` 2`codex 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](https://github.com/openai/codex/issues/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. | Model | Input | Cached | Output | Developer list in / out | Context | | --- | --- | --- | --- | --- | --- | | [GPT-5.5](https://relayswitch.io/models/gpt-5.5) | $1.80 (64% under) | $0.16 | $9.00 (70% under) | $5.00 / $30.00 | 1.1M tokens | | [GPT-5.3-Codex](https://relayswitch.io/models/gpt-5.3-codex) | $1.75 | $0.18 | $14.00 | $1.75 / $14.00 | 400K tokens | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.60 (70% under) | $0.06 | $3.00 (70% under) | $2.00 / $10.00 | 1.1M tokens | | [GPT-5.4 Mini](https://relayswitch.io/models/gpt-5.4-mini) | $0.75 | $0.075 | $4.50 | $0.75 / $4.50 | 400K tokens | | [GPT-6 Luna](https://relayswitch.io/models/gpt-6-luna) | $0.0625 (37% under) | $0.0125 | $0.20 (60% under) | $0.10 / $0.50 | 1.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](https://relayswitch.io/guides/opencode), which talks Chat Completions. How the prepaid balance and the cached rate work is on [Pricing](https://relayswitch.io/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. | Model | Context from cache | No cache hits | | --- | --- | --- | | [GPT-6 Luna](https://relayswitch.io/models/gpt-6-luna) | $0.057 | $0.217 | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.42 | $2.15 | | [GPT-5.4 Mini](https://relayswitch.io/models/gpt-5.4-mini) | $0.57 | $2.73 | | [GPT-5.5](https://relayswitch.io/models/gpt-5.5) | $1.20 | $6.44 | | [GPT-5.3-Codex](https://relayswitch.io/models/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 1`curl -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.]` table in config.toml. Move its keys into `~/.codex/.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](https://relayswitch.io/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/.config.toml and start Codex with --profile , 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 - [All guides](https://relayswitch.io/guides) - [OpenCode](https://relayswitch.io/guides/opencode) - [Cursor](https://relayswitch.io/guides/cursor) - [Models and prices](https://relayswitch.io/models) - [How pricing works](https://relayswitch.io/pricing) - [Pay by card or crypto](https://relayswitch.io/pay-with-crypto) - [Docs](https://relayswitch.io/docs) ## Run Codex on a prepaid balance One key, from $10 by card or crypto. No KYC, no subscription. [Models](https://relayswitch.io/models)[Get a key](https://app.relayswitch.io/console)