Codex CLI → Nexus

Route the OpenAI Codex CLI through the Nexus OpenAI-compatible edge. Codex speaks the Responses API (POST /v1/responses); Nexus supports that route for OpenAI-routed models and verifies a gateway API key (nxs_…).

Shared prerequisites (gateway URL, nxs_… key, registry model, BYOK/PTB): Client Integrations.

1. Prefer a dedicated Nexus provider

Put provider settings in the user config (~/.codex/config.toml). Project-local .codex/config.toml files cannot override model_providers, model_provider, or openai_base_url.

Do not reuse the reserved built-in ids openai, ollama, or lmstudio. A custom nexus provider keeps ChatGPT subscription OAuth from overriding your gateway key.

model = "openai/gpt-5.4-mini"
model_provider = "nexus"

[model_providers.nexus]
name = "Nexus"
base_url = "https://api.example.com/v1"
env_key = "NEXUS_API_KEY"
# wire_api defaults to "responses" — required by current Codex; Nexus supports it.

Local Compose: base_url = "http://127.0.0.1:14450/v1".

export NEXUS_API_KEY='nxs_…'
codex

Alternative: override the built-in OpenAI base URL

If you intentionally use the built-in openai provider:

openai_base_url = "https://api.example.com/v1"
model = "openai/gpt-5.4-mini"

Then set OPENAI_API_KEY to the Nexus nxs_… secret. Avoid this when a ChatGPT login is active and may win over the env key; the dedicated nexus provider above is clearer.

2. Model selection

model must resolve in the tenant catalog (GET /v1/models). Codex’s agent loop uses Responses; pick an OpenAI-routed (or otherwise Responses-capable) registry model. Anthropic-only catalog rows that only succeed on /anthropic/v1/messages are the wrong fit for Codex — use Claude Code for those.

3. Smoke test

GATEWAY_URL="${GATEWAY_URL:-https://api.example.com}"
export NEXUS_API_KEY='nxs_…'

curl -sS "$GATEWAY_URL/v1/responses" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "ping"
  }' | jq .

Then:

codex exec "Say hello in one short sentence."

Common failures

Symptom	Likely cause
Auth / 401	ChatGPT OAuth used instead of NEXUS_API_KEY; or nxd_… pasted
Provider ignored	Settings placed only in project .codex/config.toml
Reserved provider id	Tried to redefine openai / ollama / lmstudio
Chat-completions-only assumptions	Older guides set wire_api = "chat"; current Codex expects Responses — leave the default
Model / route errors	Model not OpenAI-routed for Responses, or missing from registry

Related

• Shared setup: Client Integrations
• First gateway chat: End-to-End Walkthrough
• Compatibility (Responses): Compatibility Matrix