Use with Codex

[!WARNING] We recommend CC Switch for managing and switching Codex provider configurations — no manual environment-variable or config-file editing needed.

[!INFO] This page is for the official Codex CLI (command line). If you use the Codex desktop app with the third-party enhancement tool Codex++, see Use with Codex++ instead.

Codex CLI supports adding custom model providers through its config file. This is a good fit for saving LofeeRouter as a standalone provider you can then select directly inside Codex.

[!INFO] The config file suits long-term use. For a quick test, you can just set the environment variable and specify the model with a command-line flag.

What you need

First, open the "API Keys" page in the LofeeRouter console and create or pick a Key dedicated to Codex. Including codex in the name makes usage easier to trace later.

Set the API Key

Set the Key in your terminal first:

export LOFEE_API_KEY="sk-your-api-key"

For long-term use, add it to ~/.zshrc or ~/.bashrc.

If you added it to a shell config file, remember to run:

source ~/.zshrc

Confirm the current terminal can read the variable:

echo $LOFEE_API_KEY

Any non-empty output is fine — don't paste the full Key into public chats or issues.

Configure the Codex provider

Edit ~/.codex/config.toml and add:

model = "your-model-name"
model_provider = "lofee"

[model_providers.lofee]
name = "LofeeRouter"
base_url = "https://app.lofeerouter.com/v1"
env_key = "LOFEE_API_KEY"
wire_api = "responses"

Replace your-model-name with a model name shown in the LofeeRouter console.

Field reference

[!TIP] If your Codex version's config fields differ slightly from the example, keep the same core pieces: provider ID, Base URL, environment variable name, and model name. After upgrading Codex, it's also worth re-checking the config file format.

Launch

codex

To switch models temporarily, use Codex's launch flags or its in-session model picker. On first launch, start with a lightweight request — for example, ask the model to print its configured model name or a one-line summary — to confirm the provider is active.

Verify requests reach LofeeRouter

Check both sides:

If nothing shows up in the LofeeRouter usage log, Codex usually isn't using the lofee provider, or the current terminal can't read LOFEE_API_KEY.

Troubleshooting

For authentication errors, first confirm the terminal can read the variable:

echo $LOFEE_API_KEY

If the 401 or API_KEY_REQUIRED error only appeared after upgrading Codex to 0.149.0 or later, the Key itself is usually fine: newer versions no longer let custom providers automatically inherit the credentials in ~/.codex/auth.json unless requires_openai_auth is enabled. The env_key approach on this page is explicit authentication and is unaffected by this change. If your previous configuration had no env_key and relied on the OPENAI_API_KEY in auth.json, either switch to the configuration on this page, or add requires_openai_auth = true to [model_providers.lofee] and keep the Key in auth.json (as {"OPENAI_API_KEY": "sk-your-api-key"} — Codex then ignores env_key). Restart Codex after the change.

For unknown-model errors, make sure the model field matches the console name exactly.

For network or API-format errors, check that base_url stops at /v1 — not /v1/chat/completions or /v1/responses.

[!TIP] If you switch between providers often, let CC Switch manage the LofeeRouter configuration to cut down on manual edits to ~/.codex/config.toml.