DEV Community

Alex Shcoder?
Alex Shcoder?

Posted on

Codex CLI with a custom OpenAI-compatible provider: the config, and six errors that look like bugs

Codex CLI talks to OpenAI by default, but it can use any provider that speaks the OpenAI Responses API. The setup is ten lines of TOML. Most of the time people lose comes after that, from errors that look like Codex bugs but are configuration.

Disclosure: I run Model.sale, a prepaid OpenAI- and Anthropic-compatible API, so the examples use it. Everything below works the same with any compatible provider: swap the base URL, the key variable and the model ids. This post was drafted with AI assistance and checked by hand against our gateway's real error codes.

The config

Add a provider block to ~/.codex/config.toml. It does not touch your existing OpenAI setup:

[model_providers.model_sale]
name = "Model.sale"
base_url = "https://api.model.sale/v1"
env_key = "MODEL_SALE_API_KEY"
wire_api = "responses"
Enter fullscreen mode Exit fullscreen mode

Then start Codex on that provider and a model:

export MODEL_SALE_API_KEY="ms_live_..."
codex -c model_provider=model_sale -m gpt-6-astra
Enter fullscreen mode Exit fullscreen mode

To make it the default, put the same two choices at the top of config.toml:

model_provider = "model_sale"
model = "gpt-6-astra"
Enter fullscreen mode Exit fullscreen mode

Three details matter:

  • env_key is the name of an environment variable, not the key itself. Codex reads the key from that variable at start-up.
  • wire_api = "responses" tells Codex to call /v1/responses. Current Codex builds use that API for tools and reasoning; a provider that only offers /v1/chat/completions will not work well here.
  • base_url ends in /v1. Codex appends /responses to it.

Error 1: 401 invalid_api_key, but the key is right

Almost always the variable is not set in the shell that started Codex. You exported it in one terminal tab and launched Codex from another, or you put it in .zshrc and did not open a new shell.

Check with echo ${MODEL_SALE_API_KEY:0:12}. If it prints nothing, Codex sees nothing either. Put the export in your shell profile, or start Codex as MODEL_SALE_API_KEY=... codex ....

Error 2: 404 model_not_found

Model ids differ between providers. OpenAI's id, a router's openai/... id and a gateway's id for the same model are three different strings. Ask the provider which ids it serves instead of guessing:

curl -s https://api.model.sale/v1/models \
  -H "Authorization: Bearer $MODEL_SALE_API_KEY" | jq -r '.data[].id'
Enter fullscreen mode Exit fullscreen mode

Copy the id exactly, including dots and dashes (gpt-6.1-sol and gpt-6-sol are different models).

Error 3: the key name does not choose the model

One of our customers created four keys named "GPT-6 Astra" and was surprised that Codex kept running GPT-6 Sol. On most gateways a key works with every model: the key name is a label for you. The model comes from -m or from model in config.toml. If you want a key that can only call one model, look for a per-key model allow-list in the provider's dashboard.

Error 4: 503 model_unavailable

The model exists in the catalog, but the provider has no healthy route to it right now. This is not your config. Switch the session to another model (/model inside Codex, or restart with a different -m) and check the provider's status page. Retrying the same model in a tight loop does not help.

Error 5: 400 on reasoning effort

Codex lets you set reasoning effort (model_reasoning_effort in config.toml, or the in-session menu). The allowed values depend on the model, and a value one model accepts can be rejected by another. One customer set ultra and every request failed. The fix is to use a value the model lists: on our GPT-6.1 Sol that is low, medium, high, xhigh or max. If you are not sure, remove the setting and let the model use its default.

Error 6: 402 insufficient_balance with money on the balance

Prepaid providers hold an estimate before a request runs and release the unused part when it finishes. The estimate includes the full max_output_tokens and the size of the context, so an agent request with a big context can need a hold larger than its real cost.

If you see 402 with a small positive balance, the hold did not fit. Top up a little more, or lower the output limit. (We changed our gateway so that a small balance can still run a request: it now holds what is left instead of refusing. Not every provider does that.)

A quick checklist

  1. echo the key variable in the shell that runs Codex.
  2. Copy model ids from /v1/models, never from memory.
  3. wire_api = "responses" and a base_url ending in /v1.
  4. Reasoning effort: a value the model supports, or none.
  5. 503 means "pick another model for now", not "fix your config".
  6. On prepaid providers, keep a little more balance than one request costs.

If you want to try this with a small budget: Model.sale starts at $5, Google or Telegram sign-up gives $0.50 of test credit, and the Codex guide has the same config with your key filled in.

Top comments (0)