Codex CLI

Quick

Codex CLI is an OpenAI-compatible client, so its base URL ends in /v1.

Add a provider to the configuration and select it. Do not put the key in the file — Codex reads it from an environment variable whose name you supply.

# ~/.codex/config.toml
model = "<model>"
model_provider = "kumo"

[model_providers.kumo]
name = "Kumo"
base_url = "https://api.kumorouter.com/v1"
env_key = "KUMO_API_KEY"
wire_api = "responses"

Where the configuration lives

The file is ~/.codex/config.toml. Create it if it is missing. If the CODEX_HOME environment variable is set, the configuration lives there instead of in your home directory.

The file may hold several providers. The [model_providers.kumo] block is added to whatever is already there; model_provider = "kumo" only decides which of them is used by default.

• base_url — the gateway address, https://api.kumorouter.com/v1, including the /v1.
• env_key — the name of the environment variable Codex takes the key from. Not the key itself.
• wire_api — the request shape; responses selects the Responses protocol, the only one the current Codex CLI reference admits.
• model — an identifier from the catalog, <model> in the example above.

Key names differ between releases. If yours names them differently, follow the docs of the release you have installed — the meaning of the fields is the same.

Verify

# 1. The gateway answers and the key is alive
curl https://api.kumorouter.com/v1/responses \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_output_tokens": 64,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "input_text", "text": "reply with OK" }]
      }
    ]
  }'

# 2. The client goes to the same place — new terminal, empty directory
codex exec --skip-git-repo-check "reply with OK"

Do the second step in an empty directory: Codex then has nothing to read and nothing to edit, and you are testing the connection alone. That is exactly why --skip-git-repo-check is here: outside a Git repository Codex stops with Not inside a trusted directory and --skip-git-repo-check was not specified and never reaches the gateway. Either keep the flag, or run the check from a Git repository you trust.

When it does not work

• 401 — the key never arrived. The variable named in env_key is not exported in the shell you launch Codex from; or the key is revoked.
• 404 — the address. base_url is missing the /v1, or carries an extra path segment.
• Model not found — the identifier is not from the catalog. Ask the gateway for the list at https://api.kumorouter.com/v1/models.
• The old provider is still used — model_provider was not switched, or a profile or a command-line flag overrides it.

How a model is named → Every status the gateway returns →