Codex config.toml (2026): Add Any Custom Provider in 6 Lines (OpenRouter, Azure, Ollama, DeepSeek)

Where config.toml Lives and What Wins

Codex resolves each key through these layers, highest precedence first:

1. CLI flags: -c key=value (or --config) and --model override everything for one invocation
2. Project config: .codex/config.toml files from the repo root down to your working directory, closest wins, loaded only when the project is trusted
3. Profile file: ~/.codex/<profile-name>.config.toml, activated with --profile <name>
4. User config: ~/.codex/config.toml (or $CODEX_HOME/config.toml if CODEX_HOME is set)
5. Cloud-managed defaults: delivered for the signed-in ChatGPT workspace, when your admin sets them
6. System config: /etc/codex/config.toml on Unix, then built-in defaults

# Default location
cat ~/.codex/config.toml

# If you set CODEX_HOME, that directory wins
echo $CODEX_HOME

# Per-invocation override beats every file
codex -c model='"gpt-6.1-sol"' "explain this module"

The 6-Line Custom Provider Block

Two keys at the top of config.toml select what runs: model picks the model ID, model_provider picks which provider definition to use. Definitions live under [model_providers.<id>]:

model = "your-model-id"
model_provider = "custom_provider"

[model_providers.custom_provider]
name = "Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"
query_params = { version = "2024" }
http_headers = { "User-Agent" = "Codex" }

Only base_url is required for most setups. The full key schema, with defaults from the official configuration reference:

wire_api: Only "responses" Works Now

This is the single biggest source of broken Codex provider configs in 2026. Guides written in 2025 show wire_api = "chat" for OpenRouter, Ollama, and every other third-party endpoint. The current configuration reference is explicit: responses is the only supported value, and it is the default when omitted.

Practical consequences:

• You can delete wire_api from your provider blocks entirely; the default is correct.
• Any endpoint you point Codex at must speak the OpenAI Responses API, not just Chat Completions.
• For providers that only expose Chat Completions, put a translating gateway (LiteLLM, or a router like OpenRouter that exposes a Responses-compatible surface) between Codex and the provider.

Copy-Paste Provider Configs

Each block is a complete ~/.codex/config.toml. wire_api is omitted because "responses" is the default. The Responses-compatibility requirement from the previous section applies to every endpoint here.

OpenRouter

One API key, hundreds of models, unified billing.

model = "anthropic/claude-sonnet-4.6"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

Azure OpenAI

Azure is the canonical use case for query_params: it versions its API through an api-version query parameter instead of the URL path.

model = "gpt-5.3-codex"
model_provider = "azure"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
# Match the api-version your Azure resource is deployed with
query_params = { api-version = "preview" }

Ollama (local, http://localhost:11434/v1)

Zero API cost. Pull the model first (ollama pull qwen3.5-coder), then point base_url at the local server. No env_key needed for localhost.

model = "qwen3.5-coder"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

If your Ollama version serves only Chat Completions, Codex's Responses-API calls will 404 against it; upgrade Ollama or front it with a translating proxy. Codex also needs tool calling, so small local models that lack tool support will connect but never edit a file.

LM Studio (local)

model = "qwen3.5-27b"
model_provider = "lmstudio"

[model_providers.lmstudio]
name = "LM Studio"
base_url = "http://localhost:1234/v1"

DeepSeek

The price outlier: DeepSeek V4.1 Flash costs $0.30/M input (cache miss), $0.006/M on cache hits, and $1.20/M output at peak hours, with a 1M-token context window. Off-peak rates are half. Peak output is about 12x cheaper than gpt-5.3-codex's $14/M. Use the deepseek-flash model ID. The legacy deepseek-v4-flash name is still accepted and is served by V4.1 Flash.

model = "deepseek-flash"  # DeepSeek-V4.1-Flash, 1M context
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

DeepSeek's API documents OpenAI Chat Completions and Anthropic formats. If its endpoint rejects Responses-API calls from your Codex build, route through a gateway that translates.

Morph

Two ways to use Morph in Codex: as a cheap chat provider behind a gateway, or as a zero-latency edit_file MCP tool.

As a chat provider. Morph serves an OpenAI-compatible Chat Completions API at https://api.morphllm.com/v1 (env MORPH_API_KEY), with morph-dsv41flash at a 1M-token context window (alternates: morph-glm53-744b, morph-kimik3). Morph exposes Chat Completions only and has no /v1/responses endpoint, so the raw block below does not work natively because Codex speaks the Responses API. Like DeepSeek and Ollama above, point base_url at a Responses-translating gateway (LiteLLM or an OpenRouter-style router) that fronts Morph:

model = "morph-dsv41flash"  # 1M context; via a Responses-translating gateway
model_provider = "morph"

[model_providers.morph]
name = "Morph"
base_url = "https://api.morphllm.com/v1"  # Chat Completions only; front with a gateway
env_key = "MORPH_API_KEY"

As an MCP tool. Morph's apply models are specialized code-edit appliers. The @morphllm/morphmcp server gives Codex an edit_file tool backed by morph-v3-fast at 10,500+ tok/s, which offloads bulk edits from your main model's output tokens. This path needs no gateway. MCP servers are configured in the same config.toml:

[mcp_servers.morph]
command = "npx"
args = ["-y", "@morphllm/morphmcp"]
env = { "MORPH_API_KEY" = "your-morph-api-key" }

See Morph pricing for apply-model rates.

Authentication: env_key and the auth Table

Three auth paths exist, and they do not stack:

• ChatGPT sign-in: the default for OpenAI's own provider. Usage draws from your plan's 5-hour-window message limits (Plus: an estimated 15-160 GPT-6.1 Sol local messages per 5 hours; Pro has no 5-hour limit). Custom providers cannot use this.
• env_key: the standard path for custom providers. Codex reads the named environment variable at runtime and sends its value as a Bearer token. Keys never go in the TOML file (an experimental_bearer_token field exists but is discouraged).
• [model_providers.<id>.auth]: command-backed token generation for short-lived credentials. Codex runs command with args and uses the output as the token, refreshing on refresh_interval_ms. The reference forbids combining auth with env_key, experimental_bearer_token, or requires_openai_auth.

experimental_bearer_token puts the API key directly in config.toml. Use it only when you cannot set an environment variable; env_key is the recommended path because the key stays out of the file:

model = "your-model-id"
model_provider = "custom_provider"

[model_providers.custom_provider]
name = "Custom Provider"
base_url = "https://api.example.com/v1"
experimental_bearer_token = "sk-..."

[model_providers.internal]
name = "Internal Gateway"
base_url = "https://llm-gateway.internal.example.com/v1"

[model_providers.internal.auth]
command = "get-llm-token"
args = ["--scope", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

# Set and persist the key the provider block names in env_key
export OPENROUTER_API_KEY="sk-or-v1-..."
echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.zshrc

# Verify Codex can see it (must print the key, not a blank line)
echo $OPENROUTER_API_KEY

Profiles: One File per Provider

Profiles are per-session config overlays. Each profile is its own file at $CODEX_HOME/<profile-name>.config.toml, next to the main config.toml, and is activated with --profile <name>. Whatever keys the profile sets override the main config for that session; everything else falls through.

model = "deepseek-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

model = "qwen3.5-coder"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

# Default config.toml (OpenAI)
codex "fix the failing tests"

# Cheap bulk work via DeepSeek
codex --profile deepseek "rename userId to user_id across the repo"

# Offline / airgapped
codex --profile local "write unit tests for utils.ts"

# One-off override without any profile
codex -c model_provider='"openrouter"' -c model='"anthropic/claude-sonnet-4.6"' "review this PR"

Reasoning, Approval, and Sandbox Keys

The same config.toml controls model behavior and execution safety. The three most-searched key groups:

model = "gpt-6.1-sol"
model_provider = "openai"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

approval_policy also accepts a granular table with boolean flags (sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval) when the three presets are too coarse.

Custom Provider vs ChatGPT Plan: The Cost Math

Codex has two billing modes. ChatGPT sign-in draws from plan credits with 5-hour-window limits. An API key (OpenAI's own or any custom provider) bills per token with no message caps. Which is cheaper depends entirely on volume:

On the plan side, OpenAI publishes exact credit burn rates per million tokens: GPT-6.1 Sol costs 50 credits input / 250 output, GPT-6 Astra costs 250/1,250, and GPT-6 Luna costs 2.5/12.5. Heavy agentic sessions chew through a Plus window fast, which is why the custom-provider block exists: route bulk refactors to a $1.20/M-output model and save the plan credits for planning. Full plan-by-plan analysis in Codex pricing.

Troubleshooting Exact Errors

401 Unauthorized from a custom provider

Codex sends the value of the env_key variable as a Bearer token. A 401 means that variable is empty in the shell that launched Codex, or the key is invalid for that endpoint.

# 1. Is the variable exported? (blank line = your problem)
echo $DEEPSEEK_API_KEY

# 2. Does the key work outside Codex?
curl -s https://api.deepseek.com/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"

# 3. Did you accidentally define BOTH env_key and an [auth] table?
#    The config reference forbids combining them. Pick one.

404 / unknown endpoint right after session start

Protocol mismatch. Codex speaks the Responses API; the endpoint behind base_url only implements Chat Completions. A curl to /v1/chat/completions succeeding while Codex fails is the giveaway. Fix: use an endpoint with Responses support or a translating gateway. Also check for a doubled or missing /v1 in base_url.

Model not found

The model string must match the provider's exact ID format: OpenRouter uses vendor/model-name (e.g. anthropic/claude-sonnet-4.6), Ollama uses the local tag you pulled, OpenAI uses bare IDs like gpt-5.3-codex. A model ID valid on one provider 404s on another.

Stream stalls, then dies

stream_idle_timeout_ms defaults to 300000 (5 minutes). Large local models can exceed that before the first token. Raise it per provider:

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
stream_idle_timeout_ms = 600000  # 10 minutes
request_max_retries = 2

Connects, chats, but never edits a file

Codex drives everything through tool calls: reading files, running commands, applying edits. Models without tool-calling support will answer in prose and touch nothing. Use models that implement the OpenAI tool spec; among open weights, DeepSeek V4, Qwen3.5 coder variants, and MiniMax M3 all support tool calls.

FAQ

Related Guides

• Codex Pricing Breakdown: plan limits, credit burn rates, and API costs
• Codex Multi-Agent Workflows: running parallel Codex agents
• Use a Different LLM with Claude Code: the same problem on Claude Code's side
• Codex vs Claude Code: feature and benchmark comparison