Codex CLI

Codex is an OpenAI-shape client, so it plugs into the gateway the same way any OpenAI SDK does: point it at the gateway base URL and give it a gateway key. Codex reads provider configuration from ~/.codex/config.toml. Once the custom provider is the default, every Codex turn (planning, edits, shell commands) routes through the gateway.

Drop-in switch

Add a custom model provider to ~/.codex/config.toml and make it the default:

model = "auto"
model_provider = "iq-routing"

[model_providers.iq-routing]
name = "IQ Routing"
base_url = "https://gateway.iq-routing.com/v1"
env_key = "IQ_GATEWAY_KEY"
wire_api = "chat"

Then export your gateway key under the name you gave env_key and run Codex:

export IQ_GATEWAY_KEY="gw_live_xxxxxxxx"
codex

base_url keeps the /v1 suffix here, since Codex calls /v1/chat/completions. wire_api = "chat" pins the Chat Completions wire format, which the gateway routes and caches like any other OpenAI-shape call. model = "auto" hands model choice to the classifier; pin a concrete id or a capability alias instead if you want (see below).

Verify it routes

Start Codex in a scratch repo and give it a one-line task (“print the current date”). The turn completes with the gateway's standard latency. Open your dashboard at /requests and the most-recent row is the Codex request, with the classifier's chosen model and the cache-hit status. The response also carries the x-iq-routing header (chosen_provider, chosen_model, cache_hit), so you can confirm which concrete model handled the turn.

Using capability aliases

Set model to a cap:<name> alias to route by stable intent instead of a pinned model id. The six default capabilities are reason-heavy, tool-call-strict, long-context-128k, vision, cheap-fast, and json-mode:

model = "cap:reason-heavy"
model_provider = "iq-routing"

Codex sends that string through as the model field on each call, and the gateway resolves it to a concrete model at routing time, shaped by your per-org overrides and circuit-breaker state. See the capability aliases docs for the full resolver decision tree.

Common gotchas

Codex resolves configuration in the order CLI flags, then environment, then config.toml. If a global OPENAI_BASE_URL is already exported it can shadow the named provider; unset it and rely on the model_providers.iq-routing block, which is explicit.

If a run errors with a wire-format complaint, confirm wire_api = "chat". Some Codex models default to the Responses API; the gateway supports both, but Chat Completions is the broadest-compatible path and the one this recipe pins.

Codex sends its own system prompt and tool definitions; the gateway passes them through untouched and routes on the full request. Each Codex turn is its own row in /requests; the gateway does not collapse a multi-turn session into one entry.

The field names above match the current Codex CLI provider schema. If a future Codex release renames them, the mechanism is unchanged: a custom provider whose base_url is the gateway and whose key is your gw_live_ gateway key.

Verify it routed

Every Codex turn shows up as its own row in /requests with the routing decision and cost. Send one prompt, then open the requests view to confirm the gateway received it and picked a model.