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

A repo-level .codex/config.toml cannot override provider, auth, notification, telemetry, or profile-selection keys. This is a security boundary: cloning a repo cannot silently redirect your prompts and API key to someone else's endpoint. Provider definitions belong in the user-level file.

Check which config Codex is reading

# 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-5.4"' "explain this module"

~/.codex/config.toml: complete custom provider

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" }

If the endpoint behind base_url only implements Chat Completions, Codex's Responses-API requests hit a route that does not exist. You see 404s, "unknown endpoint" errors, or empty streams immediately after the session starts, even though a curl to /v1/chat/completions on the same host works fine. The host is up; the protocol is wrong.

OpenRouter provider

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 provider

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 provider

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

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

LM Studio provider

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

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

DeepSeek provider

model = "deepseek-chat" # maps to deepseek-v4-flash; legacy ID retires after 2026-07-24
model_provider = "deepseek"

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

Morph as a chat provider (needs a Responses gateway)

model = "morph-dsv4flash" # 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"

Morph MCP server in config.toml

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

Inline token with experimental_bearer_token

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-..."

Command-backed auth for rotating tokens

[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

Wire up the API key for env_key providers

# 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

~/.codex/deepseek.config.toml

model = "deepseek-chat"
model_provider = "deepseek"

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

~/.codex/local.config.toml

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

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

Switch per session

# 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"

A complete daily-driver config.toml

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

Debug a 401

# 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.

Longer timeout for slow local models

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

Where is the Codex config.toml file located?

User-level config lives at ~/.codex/config.toml (or $CODEX_HOME/config.toml if CODEX_HOME is set). A project-scoped .codex/config.toml in the repo root is loaded only when you have marked the project as trusted, and it cannot override provider, auth, notification, telemetry, or profile-selection keys. CLI -c flags override both for a single invocation.

Does Codex CLI have a --provider flag?

No. Provider selection uses the model_provider key in config.toml, a per-invocation override like codex -c model_provider="openrouter", or a profile selected with codex --profile <name>. The provider itself is defined under [model_providers.<id>] with base_url and env_key.

Does Codex still support wire_api = "chat"?

No. The current Codex configuration reference states that "responses" is the only supported value for wire_api, and it is the default when omitted. Configs copied from 2025 tutorials that set wire_api = "chat" target removed behavior. Providers that only expose a Chat Completions endpoint need a translating gateway (LiteLLM or similar) in front, or a native Responses-compatible endpoint.

Can Codex use Ollama at http://localhost:11434/v1?

Define [model_providers.ollama] with base_url = "http://localhost:11434/v1" and set model to a model you have pulled locally. No env_key is needed for a local server. Because current Codex builds speak only the Responses API, your Ollama version must serve a Responses-compatible endpoint; if it only serves Chat Completions, put a translating proxy in front.

What is the Codex equivalent of cursor.general.customEndpoint in settings.json?

Cursor points at a custom endpoint (for example http://localhost:11434/v1) via the cursor.general.customEndpoint key in settings.json. The Codex equivalent is the base_url key inside a [model_providers.<id>] table in ~/.codex/config.toml, plus model_provider = "<id>" to activate it.

How do I switch Codex between providers per session?

Two ways. Profiles: create $CODEX_HOME/<name>.config.toml next to config.toml and run codex --profile <name>. One-off overrides: codex -c model_provider='"openrouter"' -c model='"<model-id>"' applies for a single invocation and beats every config file.

Why does my Codex custom provider return 401 Unauthorized?

Codex reads the API key from the environment variable named in env_key and sends it as a Bearer token. A 401 almost always means that variable is unset or not exported in the shell that launched Codex. Run echo on the variable to check. Also: do not combine the [model_providers.<id>.auth] command table with env_key or experimental_bearer_token; the reference forbids mixing them.

Is custom-provider usage billed against my ChatGPT plan?

No. ChatGPT-plan credits (Plus: 15-80 GPT-5.5 messages per 5-hour window) apply only when you sign in with ChatGPT and use OpenAI's own provider. A custom provider with an API key bills at that provider's token rates: $1.75/M input and $14/M output for gpt-5.3-codex, $0.14/M input and $0.28/M output for DeepSeek V4 Flash.

What is experimental_bearer_token in Codex config.toml?

experimental_bearer_token is a key inside a [model_providers.<id>] table that holds the API key inline in the TOML file, sent as a Bearer token. It is discouraged: prefer env_key, which names an environment variable so the key never lives in the file. Use experimental_bearer_token only when you cannot set an environment variable. It cannot be combined with the [auth] command table.

Can I use Morph with Codex CLI?

Two ways. As a chat provider: Morph serves an OpenAI-compatible Chat Completions API at https://api.morphllm.com/v1 (env MORPH_API_KEY, model morph-dsv4flash with 1M context). Because Morph exposes Chat Completions only and has no /v1/responses endpoint, while Codex speaks the Responses API, you must front Morph with a Responses-translating gateway (LiteLLM or an OpenRouter-style router); a raw [model_providers.morph] block does not work natively. As an MCP tool: add @morphllm/morphmcp under [mcp_servers.morph] for a zero-latency edit_file tool backed by morph-v3-fast at 10,500+ tok/s, which needs no gateway.