Use a Third-Party API with Codex CLI: Custom model_providers in config.toml

Disclosure: LLM API Guide is maintained by the SeedRouter team, and this guide uses SeedRouter as the example. The same steps work with any gateway that supports the OpenAI Responses API.

When this helps

• You want Codex CLI to use a cheaper or more resilient model route instead of only your official account quota.
• Your team buys API access centrally and wants one base URL and API key per project for usage and billing.
• You want to switch between the official sign-in and a gateway without rewriting your setup each time.

Step 1: Collect three values

Double-check the domain. Several sites use similar names, and a mistyped base URL sends your requests to a different service. SeedRouter's only official domain is seedrouter.net; see its official channels page.

Step 2: Edit ~/.codex/config.toml

Location:

• macOS / Linux: ~/.codex/config.toml
• Windows: C:\Users\<you>\.codex\config.toml

Create the file if it does not exist, then add:

model = "gpt-6.1-sol"
model_provider = "seedrouter"

[model_providers.seedrouter]
name = "SeedRouter"
base_url = "https://seedrouter.net/v1"
env_key = "SEEDROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Step 3: Export the API key

macOS / Linux (zsh or bash):

echo 'export SEEDROUTER_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

Use ~/.bashrc instead of ~/.zshrc if you run bash.

Windows PowerShell:

setx SEEDROUTER_API_KEY "sk-your-key"

setx only affects new terminals, so close and reopen PowerShell afterwards.

Step 4: Verify

Check the key and URL first. A model list in the response means authentication works:

curl https://seedrouter.net/v1/models \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Then start Codex:

codex

Ask a quick question. If it answers, you are done, and the request also appears in the usage logs of the SeedRouter dashboard.

Switch between the official sign-in and the gateway

Keep both setups in one file with a profile:

[profiles.seedrouter]
model = "gpt-6.1-sol"
model_provider = "seedrouter"

Run codex --profile seedrouter to use the gateway; without the flag Codex uses the top-level defaults. If you prefer a GUI, CC Switch can manage several providers for Codex and Claude Code.

Common errors

Summary

Three things connect Codex to a gateway: a provider table in config.toml, an environment variable for the key, and wire_api = "responses". If you do not have a gateway account yet, you can sign up on the SeedRouter website. New accounts get two free popular-model trials, and the homepage compares each model's price with official API pricing.