Codex Provider Configuration: How to Use --provider, config.toml, and Custom Endpoints

How Provider Selection Works

Codex CLI loads configuration from ~/.codex/config.toml at startup. Two keys control which API it talks to:

• model sets the model identifier (e.g., gpt-5-codex)
• model_provider selects which provider definition to use (default: openai)

Provider definitions live under [model_providers.<id>] in the same file. Each definition specifies a base URL, authentication method, and wire protocol. Codex ships with two built-in providers: openai (using the Responses API) and oss (using the Chat Completions API for local models).

# ~/.codex/config.toml
model = "gpt-5.1"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI via LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

The env_key field tells Codex which environment variable holds the API key. Codex reads that variable at runtime and sends it as a Bearer token. You never put API keys directly in config.toml (though an experimental_bearer_token field exists, it is discouraged).

Configuration Reference

Every provider definition supports the following keys. Only base_url is required for most setups.

# Point Codex at a different endpoint for one session
export OPENAI_BASE_URL="https://your-proxy.example.com/v1"
codex "refactor the auth module"

CLI Flags for Providers

Codex does not have a literal --provider flag. Provider selection happens through three mechanisms:

The --model flag

Overrides the configured model for a single session. Does not change the provider endpoint.

codex --model gpt-5.1 "explain this codebase"
codex -m gpt-5-codex "fix the failing tests"

The --oss flag

Switches to the local open-source provider. Equivalent to -c model_provider="oss". Codex validates that Ollama (or LM Studio) is running before starting.

# Use Ollama
codex --oss "write unit tests for utils.ts"

# Equivalent long form
codex -c model_provider='"oss"' "write unit tests for utils.ts"

The -c / --config flag

Overrides any config.toml key for a single invocation. Values parse as JSON when possible. This is how you select a custom provider from the command line.

# Use your custom "morph" provider for this session
codex -c model_provider='"morph"' -c model='"morph-v3-fast"' "apply the diff"

# Switch to OpenRouter
codex -c model_provider='"openrouter"' -c model='"anthropic/claude-sonnet-4.5"' "review this PR"

The --profile flag

Activates a named configuration profile. Profiles let you bundle model, provider, and other settings under a single name. More on this in the Profiles section.

codex --profile fast-local "refactor this function"
codex -p openrouter "explain the auth flow"

Provider Examples

Working configs for the providers developers ask about most. Each example is a complete ~/.codex/config.toml snippet you can paste and modify.

OpenRouter

Access 200+ models through one API. OpenRouter handles routing, fallback, and billing.

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

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

Ollama (Local)

Run models locally with zero API costs. Requires Ollama installed and a model pulled.

model = "qwen2.5-coder:32b"
model_provider = "ollama"

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

Azure OpenAI

For teams on Azure with data residency or compliance requirements.

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

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }

Mistral

model = "codestral-latest"
model_provider = "mistral"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"
wire_api = "chat"

LM Studio (Local)

model = "qwen2.5-coder-32b"
model_provider = "lmstudio"

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

OpenAI Data Residency

For organizations that need API traffic routed through a specific region.

model_provider = "openaidr"

[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1"
wire_api = "responses"

Using Morph as a Provider

Morph specializes in fast code transformations. The morph-v3-fast model runs code edits at 10,500+ tokens per second, which makes it useful as a Codex provider for apply-heavy workflows where the bottleneck is edit speed, not planning.

model = "morph-v3-fast"
model_provider = "morph"

[model_providers.morph]
name = "Morph"
base_url = "https://api.morphllm.com/v1"
env_key = "MORPH_API_KEY"
wire_api = "chat"

export MORPH_API_KEY="your-api-key-here"
codex -c model_provider='"morph"' "apply this diff to all test files"

Morph is not a general-purpose coding model. It excels at code editing, diff application, and file transformations. For planning and reasoning, pair it with a frontier model. See Codex pricing for how costs compare across providers.

Profiles for Provider Switching

Profiles bundle model, provider, and other settings under a name. Instead of remembering -c flags, you switch with --profile.

# Default: OpenAI
model = "gpt-5-codex"
model_provider = "openai"

# Fast local development
[profiles.local]
model = "qwen2.5-coder:32b"
model_provider = "ollama"

# OpenRouter for model variety
[profiles.openrouter]
model = "anthropic/claude-sonnet-4.5"
model_provider = "openrouter"

# Morph for bulk edits
[profiles.morph]
model = "morph-v3-fast"
model_provider = "morph"

# Provider definitions
[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

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

[model_providers.morph]
name = "Morph"
base_url = "https://api.morphllm.com/v1"
env_key = "MORPH_API_KEY"
wire_api = "chat"

# Use local Ollama
codex --profile local "write tests for auth.ts"

# Use OpenRouter
codex -p openrouter "explain this error"

# Use Morph for fast edits
codex -p morph "rename all instances of userId to user_id"

Profiles also support per-profile oss_provider settings. If you have both Ollama and LM Studio installed, you can assign different local backends to different profiles.

Troubleshooting

Authentication failures

The most common issue. Codex reads the API key from the environment variable specified in env_key. Verify the variable is set and exported in your shell.

# Check if the env var is set
echo $OPENROUTER_API_KEY

# If empty, set it
export OPENROUTER_API_KEY="sk-or-v1-..."

# For persistent config, add to ~/.zshrc or ~/.bashrc
echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.zshrc

wire_api mismatch

If Codex sends requests the provider does not understand, check wire_api. OpenAI and Azure use "responses". Everything else (OpenRouter, Ollama, Mistral, Morph, LM Studio) uses "chat".

Model not found errors

The model value must match exactly what the provider expects. OpenRouter uses format provider/model-name (e.g., anthropic/claude-sonnet-4.5). Ollama uses the local model name (e.g., qwen2.5-coder:32b). OpenAI uses IDs like gpt-5-codex.

Streaming timeouts with local models

Large local models can be slow to generate the first token. Increase the idle timeout:

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

Tool calling not supported

Codex relies on function/tool calling to read files, run commands, and edit code. Many smaller open-source models do not support tool calling. If Codex errors out or produces no file operations, the model likely lacks tool support. Stick to models that implement the OpenAI tool calling spec: GPT-5.x, Claude, Qwen 2.5 Coder (32B+), Mistral Large, and Codestral.

FAQ

Related Guides

• Codex Pricing Breakdown - Cost comparison across tiers and providers
• Use a Different LLM with Claude Code - Similar guide for Claude Code's provider system
• Codex vs Claude Code - Full feature and benchmark comparison