OpenAI Codex

OpenAI Codex is OpenAI's agentic coding tool. You can configure it to use Vercel AI Gateway, enabling you to:

• Route requests through multiple AI providers
• Monitor traffic and spend in your AI Gateway Overview
• View detailed traces in Vercel Observability under AI
• Use any model available through the gateway

Configure Codex to use AI Gateway through its configuration file for persistent settings.

1. Install OpenAI Codex CLI

   Follow the installation instructions on the OpenAI Codex repository to install the Codex CLI tool.

2. Configure environment variables

   Set your AI Gateway API key in your shell configuration file, for example in ~/.zshrc or ~/.bashrc:

   export AI_GATEWAY_API_KEY="your-ai-gateway-api-key"

   After adding this, reload your shell configuration:

   source ~/.zshrc  # or source ~/.bashrc

3. Set up the Codex config file

   Open ~/.codex/config.toml and add the following:

   ~/.codex/config.toml

   model_provider = "vercel"
   model = "openai/gpt-5.5"
    
   [model_providers.vercel]
   name = "Vercel AI Gateway"
   base_url = "https://ai-gateway.vercel.sh/v1"
   env_key = "AI_GATEWAY_API_KEY"

   The configuration above:

   • Sets up a model provider named vercel that points to the AI Gateway
   • References your AI_GATEWAY_API_KEY environment variable
   • Sets the vercel provider as the default for all sessions
   • Specifies openai/gpt-5.5 as the default model

4. Run Codex

   Start Codex:

   codex

   Vercel AI Gateway routes your requests. To confirm, check your AI Gateway Overview in the Vercel dashboard.

5. (Optional) Enable WebSocket streaming

   Codex can stream Responses API traffic over a persistent WebSocket connection, reducing per-turn latency. Enable it in your config:

   ~/.codex/config.toml

   [features]
   responses_websockets_v2 = true
    
   [model_providers.vercel]
   name = "Vercel AI Gateway"
   base_url = "https://ai-gateway.vercel.sh/v1"
   env_key = "AI_GATEWAY_API_KEY"
   supports_websockets = true

   WebSocket streaming is available for OpenAI models such as openai/gpt-5.5. Other models return a Model <name> is not available over WebSocket error, so remove supports_websockets = true when switching to a non-OpenAI model.

6. (Optional) Use a different model

   To use a different model, update the model field in your config:

   ~/.codex/config.toml

   model = "anthropic/claude-sonnet-4.6"
   # Or try other models:
   # model = "google/gemini-3.1-flash-lite-preview"
   # model = "openai/gpt-5.5"

   When using non-OpenAI models through the gateway, you may see warnings about model metadata not being found. These warnings are safe to ignore since the gateway handles model routing.

7. (Optional) Define multiple profiles

   Profiles let you switch models from the CLI. Create a file named ~/.codex/<profile-name>.config.toml for each profile, using top-level keys for the values that differ from your base config:

   ~/.codex/fast.config.toml

   model = "openai/gpt-5.4-nano"

   ~/.codex/claude.config.toml

   model = "anthropic/claude-sonnet-4.6"

   Codex loads ~/.codex/config.toml first, then overlays the profile file, so model_provider = "vercel" is inherited from your base config.

   Switch between profiles using the --profile flag:

   codex --profile fast
   codex --profile claude

   Codex 0.134.0 and later no longer reads [profiles.<name>] tables or the profile selector from config.toml. If you have legacy profile tables, move each one into its own ~/.codex/<profile-name>.config.toml file.