Skip to content

Setting up Codex

Codex talks to Nexus over OpenAI Responses. Leave the default Codex connection in ~/.codex/config.toml and put Nexus in its own profile file.

The shared order is on Client setup.

Profile

Create ~/.codex/nexus.config.toml:

model = "MODEL_FROM_V1_MODELS"
model_provider = "nexus"

[model_providers.nexus]
name = "Nexus"
base_url = "https://api.nexus-hub.tech/v1"
env_key = "NEXUS_API_KEY"
wire_api = "responses"

Set the key and start that profile:

export NEXUS_API_KEY="your_nexus_key"
codex --profile nexus

Set model only to an id returned by GET /v1/models for your key. Codex sends POST /v1/responses. Do not store the key in the toml file. Do not change wire_api from responses to Chat Completions: that is a different route.

A project file .codex/config.toml cannot override model_provider or model_providers. Keep the Nexus profile in ~/.codex/nexus.config.toml.

Context window

Every model currently available in Nexus has a declared window of 1,050,000 tokens. Set model_context_window to that value for the id you selected from GET /v1/models. Set model_auto_compact_token_limit below that window so Codex does not summarize the thread early. The same number is on Models and prices.

model = "MODEL_FROM_V1_MODELS"
model_provider = "nexus"
model_context_window = 1050000
model_auto_compact_token_limit = 945000

[model_providers.nexus]
name = "Nexus"
base_url = "https://api.nexus-hub.tech/v1"
env_key = "NEXUS_API_KEY"
wire_api = "responses"

One session, without editing the file:

codex --profile nexus -m MODEL_FROM_V1_MODELS \
  -c model_context_window=1050000 \
  -c model_auto_compact_token_limit=945000

If the key's list does not include the id you typed, pick an id it does return. The window stays 1,050,000 tokens.

Check

Start codex --profile nexus and send a short prompt.

If it does not work

  • 401 or invalid_key: check NEXUS_API_KEY. Do not put the key in config.toml.
  • model_not_found or model_not_allowed: request GET /v1/models again.
  • unsupported_model: the id is not allowed on Responses. Pick another id. Do not switch wire_api to Chat Completions.
  • The profile did not apply: confirm the file name is nexus.config.toml inside ~/.codex, then run codex --profile nexus.
  • For support, keep x-request-id. Do not send the key or a full prompt.

Official reference: Codex config reference and Config basics.