Ir al contenido
Nexus Docs
↑↓Navigate↵SelectescClose

Codex CLI → Nexus

Route the OpenAI Codex CLI through the Nexus OpenAI-compatible edge

Last updated on:

Esta página aún no está disponible en tu idioma.

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): README.md.

1. Prefer a dedicated Nexus provider

Section titled “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".

Terminal window
export NEXUS_API_KEY='nxs_…'
codex

Alternative: override the built-in OpenAI base URL

Section titled “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

Section titled “2. Model selection”

model must resolve in the tenant catalog (GET /v1/models). Codex’s agent loop uses Responses. OpenAI models serve it natively. Models whose provider serves chat but not Responses (Anthropic, Bedrock, Bedrock GovCloud, Azure AI Foundry, and chat-only Bedrock Mantle rows) are served through the gateway’s Responses-to-chat bridge and work with default Codex settings. The bridge turns Codex’s multi_agent_v1 namespace tool into ordinary function tools and reports tools:namespace in x-nexus-dropped-params; calls to those tools come back with their namespace, as OpenAI returns them. Bedrock Mantle and xAI models that serve Responses natively reject the namespace tool upstream. For those, run Codex with --disable multi_agent.

3. Smoke test

Section titled “3. Smoke test”
Terminal window
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:

Terminal window
codex exec "Say hello in one short sentence."

Common failures

Section titled “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
400 naming paid hosted tools Codex attaches its built-in web_search tool, which the gateway rejects by default (see below)
Section titled “Web search”

Codex enables its built-in web_search tool by default. The gateway rejects OpenAI paid hosted tools unless the operator opts in, because it does not meter their per-call fees. Either turn search off in Codex:

web_search = "disabled"

or, on a BYOK deployment, have the operator set NEXUS_GATEWAY_ALLOW_UNMETERED_HOSTED_TOOLS=1 on the gateway so the tool is forwarded to OpenAI and billed to the tenant’s own OpenAI account.

Section titled “Related”