Custom AI Providers

Configure Codex to use alternative AI providers like Anthropic, Ollama, or custom endpoints

Codex supports any AI provider that implements an OpenAI-compatible API. This guide shows you how to configure custom providers.

Built-in Provider Support

Codex includes built-in support for these providers:

• OpenAI (default) - OpenAI’s models including GPT-4, GPT-5, o-series
• Azure OpenAI - Enterprise Azure deployment
• Anthropic - Claude models via OpenAI-compatible endpoint
• OpenRouter - Access to multiple model providers
• Ollama - Local model inference
• LM Studio - Local model hosting
• Together AI - Fast inference for open models
• Mistral AI - Mistral and Mixtral models
• DeepSeek - DeepSeek models
• Groq - Ultra-fast LLM inference
• xAI - Grok models
• Gemini - Google’s Gemini models

Configuring a Custom Provider

Define custom providers in the [model_providers] section:

model_provider = "anthropic"

[model_providers.anthropic]
name = "Anthropic"
base_url = "https://api.anthropic.com/v1"
env_key = "ANTHROPIC_API_KEY"

Then set your API key:

export ANTHROPIC_API_KEY="sk-ant-..."

Provider Configuration Options

name · string · required

Friendly display name for the provider

base_url · string

Base URL for the provider’s OpenAI-compatible API

env_key · string

Environment variable name that stores the API key

env_key_instructions · string

Help text for obtaining and setting the API key

http_headers · object

Static HTTP headers to include in requests (key-value pairs)

env_http_headers · object

HTTP headers with values from environment variables (header name → env var name)

query_params · object

Query parameters to append to API requests

requires_openai_auth · boolean · default: "false"

Whether this provider requires OpenAI authentication (for proxies/gateways)

wire_api · string · default: "responses"

Which wire protocol the provider expects (currently only "responses" is supported)

supports_websockets · boolean · default: "false"

Whether the provider supports Responses API WebSocket transport

Common Provider Examples

Ollama (Local Models)

Run models locally with Ollama:

model_provider = "ollama"
model = "codestral"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
env_key = "OLLAMA_API_KEY"  # Can be empty for local

1. Install Ollama

   Download from ollama.ai

2. Pull a model

   ollama pull codestral
   
3. Run Codex

   codex --model codestral
   

Azure OpenAI

Use Azure’s OpenAI deployment:

model_provider = "azure"
model = "gpt-4"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.azure.query_params]
"api-version" = "2024-02-15-preview"

Set your credentials:

export AZURE_OPENAI_API_KEY="your-key-here"
export AZURE_OPENAI_API_VERSION="2024-02-15-preview"  # Optional

OpenRouter

Access multiple providers through OpenRouter:

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

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

export OPENROUTER_API_KEY="sk-or-..."

Anthropic (Claude)

Use Claude models via Anthropic’s API:

model_provider = "anthropic"
model = "claude-3-5-sonnet-20241022"

[model_providers.anthropic]
name = "Anthropic"
base_url = "https://api.anthropic.com/v1"
env_key = "ANTHROPIC_API_KEY"

export ANTHROPIC_API_KEY="sk-ant-..."

Anthropic’s API may require adapter middleware for full OpenAI compatibility. Consider using OpenRouter for easier Claude access.

Together AI

Use open models via Together AI:

model_provider = "together"
model = "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo"

[model_providers.together]
name = "Together AI"
base_url = "https://api.together.xyz/v1"
env_key = "TOGETHER_API_KEY"

DeepSeek

Use DeepSeek models:

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

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

Groq

Fast inference with Groq:

model_provider = "groq"
model = "llama-3.1-70b-versatile"

[model_providers.groq]
name = "Groq"
base_url = "https://api.groq.com/openai/v1"
env_key = "GROQ_API_KEY"

Mistral AI

Use Mistral models:

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

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

Advanced Provider Configuration

Custom HTTP Headers

Include static headers in requests:

[model_providers.custom]
name = "Custom Provider"
base_url = "https://api.custom.com/v1"
env_key = "CUSTOM_API_KEY"

[model_providers.custom.http_headers]
"X-Custom-Header" = "value"
"X-Organization-ID" = "org-123"

Dynamic Headers from Environment

Load header values from environment variables:

[model_providers.custom]
name = "Custom Provider"
base_url = "https://api.custom.com/v1"
env_key = "CUSTOM_API_KEY"

[model_providers.custom.env_http_headers]
"X-Organization-ID" = "ORG_ID_ENV_VAR"
"X-User-ID" = "USER_ID_ENV_VAR"

Then set:

export ORG_ID_ENV_VAR="org-123"
export USER_ID_ENV_VAR="user-456"

Retry and Timeout Configuration

[model_providers.custom]
name = "Custom Provider"
base_url = "https://api.custom.com/v1"
env_key = "CUSTOM_API_KEY"
request_max_retries = 5
stream_idle_timeout_ms = 30000
stream_max_retries = 3

request_max_retries · integer · default: "3"

Maximum HTTP request retries on failure

stream_idle_timeout_ms · integer · default: "30000"

Idle timeout in milliseconds before treating streaming connection as lost

stream_max_retries · integer · default: "3"

Maximum reconnection attempts for dropped streams

Switching Providers

You can switch providers in several ways:

In Configuration

model_provider = "ollama"
model = "codestral"

Via CLI Flag

codex --provider ollama --model codestral

Via Environment Variable

export CODEX_PROVIDER=ollama
export CODEX_MODEL=codestral
codex

Using Profiles

profile = "local"

[profiles.local]
model_provider = "ollama"
model = "codestral"

[profiles.cloud]
model_provider = "openai"
model = "gpt-4.1"

Switch with:

codex --profile local
codex --profile cloud

Testing Provider Configuration

Test your provider setup:

# Test connection and basic functionality
codex "What is 2+2?"

# Verbose mode to debug connection issues
DEBUG=true codex "test"

Troubleshooting

Connection refused or timeout

• Verify the base URL is correct
• Check if the service is running (for local providers)
• Test with curl: curl $BASE_URL/models
• Check firewall/network settings

Authentication errors

• Verify the API key environment variable is set
• Check the environment variable name matches env_key
• Ensure the API key has required permissions
• Try authenticating with the provider’s native CLI

API compatibility issues

• Verify the provider implements OpenAI-compatible endpoints
• Check if the model name is valid for the provider
• Review provider documentation for any non-standard behaviors
• Some providers may need middleware for full compatibility

Model not found

• Verify the model name exists on the provider
• Check capitalization and exact spelling
• For local providers (Ollama), ensure model is pulled
• Try listing available models via provider API

Provider Compatibility Notes

While Codex supports any OpenAI-compatible API, some features may have varying support:

• Streaming - Most providers support streaming responses
• Function calling - Required for Codex tool use; verify provider support
• Vision - Image input requires multimodal model support
• Reasoning effort - Only supported by reasoning-capable models (o-series)
• WebSocket transport - Optional; falls back to HTTP streaming

Complete Example

Here’s a full configuration with multiple providers:

# Default provider
model_provider = "openai"
model = "gpt-4.1"

# Define multiple providers
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

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

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://myorg.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.groq]
name = "Groq"
base_url = "https://api.groq.com/openai/v1"
env_key = "GROQ_API_KEY"

# Use profiles to switch easily
[profiles.local]
model_provider = "ollama"
model = "codestral"

[profiles.fast]
model_provider = "groq"
model = "llama-3.1-70b-versatile"

[profiles.enterprise]
model_provider = "azure"
model = "gpt-4"

Next Steps

MCP Servers

Integrate Model Context Protocol servers

Configuration Reference

Complete reference documentation