Codex CLI — Configuration with OmniRoute

Complete guide for using the Codex CLI pointed at OmniRoute as an OpenAI-compatible backend.

Ready-to-paste config.toml

Replace <YOUR_HOST> and <YOUR_KEY> with your values:

# ~/.codex/config.toml
model                          = "cx/gpt-5.5"
model_provider                 = "omniroute"
model_reasoning_effort         = "xhigh"
model_context_window           = 400000
model_auto_compact_token_limit = 350000
model_max_output_tokens        = 65536    # max tokens per response (model cap = 128k)
tool_output_token_limit        = 32768    # history storage cap per tool call

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

# ~/.bashrc or ~/.zshrc — actual key value, never in config.toml
export OMNIROUTE_API_KEY="<YOUR_KEY>"

Common host options

Access	URL
Local network	http://192.168.0.1:20128/v1
Tailscale	http://100.x.x.x:20128/v1
Loopback	http://localhost:20128/v1

wire_api = "responses" — why it works for all models

Codex CLI deprecated wire_api = "chat" (Chat Completions) in February 2026 and now requires wire_api = "responses" (OpenAI Responses API).

DeepSeek and Mistral only expose a Chat Completions endpoint — not the Responses API. If you pointed Codex directly at DeepSeek or Mistral, it would fail with a 404.

OmniRoute solves this transparently:

Codex CLI
  → wire_api = "responses"
  → POST /v1/responses (OmniRoute)
    → OmniRoute Responses ↔ Chat Completions transformer
    → POST /chat/completions (DeepSeek / Mistral / any provider)

You never need a separate translation proxy (codex-relay, LiteLLM, etc.) when using OmniRoute. All models use wire_api = "responses" — OmniRoute handles the rest.

Context window and compaction

Why this matters

If the session history exceeds the model's context window, the Codex CLI either crashes or truncates silently. Different models have very different limits — setting these explicitly prevents surprises.

Token configuration fields

model_max_output_tokens vs tool_output_token_limit: these are two different things.

• model_max_output_tokens = max tokens the model may produce in a single API response.
• tool_output_token_limit = max tokens stored per tool call in the session history.

Context windows and output caps by model

Why not set model_max_output_tokens to the model's maximum? For a coding assistant that writes whole files and long diffs, 64k (65,536) is a practical sweet spot. The model can generate files up to ~50k tokens without hitting the cap. Reserve the higher limits for edge cases — they increase cost on every request regardless of output length.

Compaction formula: effective_window = model_context_window - min(model_max_output_tokens, 20000). Values above 20k do not reduce the compaction trigger — the formula caps the output reservation at 20k. So setting model_max_output_tokens = 65536 does not require lowering model_auto_compact_token_limit.

Rule of thumb: set model_auto_compact_token_limit to 85–90% of model_context_window. Never go above 90% — it is silently ignored.

How compaction works

When the session history exceeds model_auto_compact_token_limit, Codex CLI automatically summarises older turns into a compact form. The session continues without interruption — you lose verbatim history but keep context. This is different from truncation (which loses context).

For models with smaller windows (Mistral 256k), compaction fires earlier and more often. Setting a tighter tool_output_token_limit reduces how fast the window fills with tool call results.

Model prefix: cx/

All Codex models in OmniRoute use the cx/ prefix:

Other providers use their own prefix (ds/, mistral/, etc.) — the prefix matches the OmniRoute provider alias.

Never use bare gpt-5.5 or codex/gpt-5.5 — OmniRoute does not recognize those formats for the Codex provider.

Reasoning Effort

Controls how much the model "thinks" before responding. Higher effort = better quality, higher latency and cost.

Available values

Note: model_reasoning_effort applies to models that support reasoning (GPT-5.x, DeepSeek V4 Pro). Mistral Large does not expose a reasoning effort parameter — setting it has no effect on Mistral.

How to configure

In config.toml (global default):

model_reasoning_effort = "xhigh"

Per invocation via -c (overrides global):

codex -c model_reasoning_effort=low "rename variable x to count"
codex -c model_reasoning_effort=xhigh "design the auth module architecture"

Combining model and effort:

codex -m cx/gpt-5.4 -c model_reasoning_effort=medium "refactor the handler"

About the default: If model_reasoning_effort is not set, OmniRoute falls back to "medium". Set it explicitly for serious engineering work.

Selecting a model via the CLI

1. --model / -m flag — per invocation

codex -m cx/gpt-5.5 "analyze the full pipeline"
codex -m ds/deepseek-v4-pro "deep analysis of this algorithm"
codex -m mistral/mistral-large-latest "quick review"

Priority: CLI flags > profiles > config.toml

2. /model — interactive switch inside a session

During an open session, type /model + Enter to open the model picker.

3. -c key=value — inline override for any field

# Change context window for one run
codex -m ds/deepseek-v4-pro -c model_context_window=1000000 -c model_auto_compact_token_limit=900000 "task"

Profiles — named usage profiles

Profiles let you have named configurations for different workflows. Each profile is a file at ~/.codex/<name>.config.toml that layers on top of the base config.toml.

Naming rule (Codex CLI v0.137+): the file must be named ~/.codex/<name>.config.toml — no profile- prefix. The CLI resolves -p chat to ~/.codex/chat.config.toml. If the file is not found, the default silently applies with no error.

How to use

codex --profile deepseek "analyze 10k lines of this codebase"
codex --profile mistral "quick code review"
codex --profile low "rename variable"
codex -p chat "explain this function"

All available profiles

chat.config.toml — no reasoning effort (server default = medium)

model          = "cx/gpt-5.5"
model_provider = "omniroute"
# No model_reasoning_effort — uses server default (medium)

low.config.toml / medium.config.toml / high.config.toml / xhigh.config.toml

model                  = "cx/gpt-5.5"
model_reasoning_effort = "low"   # or medium / high / xhigh
model_provider         = "omniroute"

Context window is inherited from config.toml (400k for gpt-5.5).

deepseek.config.toml — DeepSeek V4 Pro, 1M context

model          = "ds/deepseek-v4-pro"
model_provider = "omniroute"

model_context_window           = 1000000
model_auto_compact_token_limit = 900000
model_max_output_tokens        = 65536    # practical cap; model max = 384k
tool_output_token_limit        = 65536

mistral.config.toml — Mistral Large Latest, 256k context

model          = "mistral/mistral-large-latest"
model_provider = "omniroute"

model_context_window           = 262144
model_auto_compact_token_limit = 220000
model_max_output_tokens        = 32768    # ~32k; Mistral Large model max ~128k
tool_output_token_limit        = 16384

Quick decision table

Multiple models and servers

Multiple models — same server

Change only model and model_provider (and context window fields if the model differs):

model                         = "ds/deepseek-v4-pro"
model_provider                = "omniroute"
model_context_window          = 1000000
model_auto_compact_token_limit = 900000

Multiple servers

model          = "cx/gpt-5.5"
model_provider = "omniroute-main"

[model_providers.omniroute-main]
name                 = "OmniRoute (Main)"
base_url             = "http://192.168.0.1:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

[model_providers.omniroute-tailscale]
name                 = "OmniRoute (Tailscale)"
base_url             = "http://100.x.x.x:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

[model_providers.omniroute-staging]
name                 = "OmniRoute (Staging)"
base_url             = "http://192.168.0.2:20128/v1"
env_key              = "OMNIROUTE_STAGING_KEY"
requires_openai_auth = false
wire_api             = "responses"

All providers use wire_api = "responses" — OmniRoute handles translation for each upstream provider internally.

Claude Code — equivalent configuration

Claude Code (Anthropic's CLI) uses a different mechanism for the same concept: environment variables in ~/.bashrc / ~/.zshrc.

# ~/.bashrc — Claude Code token cap (equivalent to Codex model_max_output_tokens)
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536

Why 64k and not 128k? The Claude 4.x family supports up to 128k output, but for interactive coding sessions 64k covers any file or diff you realistically generate. Setting 128k reserves the full slot on every request, which increases latency and cost even for short responses. Use 128k only for batch/document-generation workflows where you routinely need very long outputs.

About [notice.model_migrations]

Auto-generated by the Codex CLI to record acknowledged deprecation warnings. Not an alias system — safe to ignore.

Quick reference — CLI flags

Inside an interactive session:

Troubleshooting

Error: model not found Verify the model exists in OmniRoute with the correct prefix. Open /dashboard/providers/<provider> and check available models.

Authentication error Confirm OMNIROUTE_API_KEY is exported: echo $OMNIROUTE_API_KEY.

Connection refused Verify OmniRoute is running and the base_url host/port is correct for your network (local vs Tailscale vs VPS).

Session crashes near context limit Set model_context_window and model_auto_compact_token_limit explicitly for the model you are using. See the context window table above.

Compaction fires too late / history is cut Lower model_auto_compact_token_limit to trigger compaction earlier (e.g. 75% of the window). Never set it above 90% — silently ignored.

DeepSeek / Mistral returns 404 You are likely pointing Codex directly at the provider API. Route through OmniRoute — it translates Responses API → Chat Completions automatically. Confirm base_url points to your OmniRoute instance, not directly to api.deepseek.com or api.mistral.ai.