OpenAI Codex with AI Gateway

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

Run the Vercel CLI setup command for Codex:

npx vercel ai-gateway setup --agent codex

The command configures everything Codex needs to route through the gateway:

• Provisions an AI Gateway API key, or reuses one you pass with --key
• Writes ~/.codex/config.toml with a vercel model provider pointed at the Codex compatibility endpoint (wire_api = "responses")
• Exports AI_GATEWAY_API_KEY from a managed block in your shell startup file, backed by the macOS Keychain when available so the key stays out of plaintext config
• Copies your existing Codex Desktop sessions across (see session migration)

Every file the command changes is backed up alongside as a .bak file. Pass --dry-run to preview the changes without writing them. For the full command reference, see vercel ai-gateway setup.

To configure every installed supported agent at once, run the command without --agent. It detects and configures each supported agent it finds:

vercel ai-gateway setup

To verify the setup, run Codex:

codex

The gateway routes your requests. Confirm they appear in your AI Gateway Overview in the Vercel dashboard.

Only needed on machines where you can't use the Vercel CLI. When you use the CLI, it handles key storage for you, exporting AI_GATEWAY_API_KEY from a managed block in your shell startup file that is backed by the macOS Keychain when available. The steps below do the same configuration by hand.

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-6-astra"
    
   [model_providers.vercel]
   name = "Vercel AI Gateway"
   base_url = "https://ai-gateway.vercel.sh/codex/v1"
   env_key = "AI_GATEWAY_API_KEY"
   wire_api = "responses"

   The configuration above:

   • Sets up a model provider named vercel that points to the Codex compatibility endpoint
   • References your AI_GATEWAY_API_KEY environment variable
   • Sets the vercel provider as the default for all sessions
   • Uses the Responses API, which is the only wire protocol current Codex versions support
   • Specifies openai/gpt-6-astra 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.

Codex can stream Responses API traffic over a persistent WebSocket connection, reducing per-turn latency. This uses AI Gateway's Responses API WebSocket mode. Enable it in your config:

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

Run /model inside Codex to switch models without leaving your session. The picker lists the full gateway catalog and sets reasoning effort at the same time, because the Codex compatibility endpoint serves /codex/v1/models when the CLI starts.

To start a session on a specific model, pass --model (or -m):

codex --model openai/gpt-5.5-pro

To change the model for every session, update the model field in your config:

model = "openai/gpt-5.5-pro"
# Or try other models:
# model = "openai/gpt-5.4-mini"
# model = "openai/gpt-5.4-nano"

Every model in the gateway catalog works here, not only OpenAI ones. The examples stay on OpenAI models because Codex reads their metadata natively.

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:

model = "openai/gpt-5.4-nano"

model = "openai/gpt-5.5-pro"

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 pro

Codex records each session against the provider that served it, so switching to the gateway hides the sessions you created before the switch. To bring them across, re-run the Vercel CLI setup command:

vercel ai-gateway setup --agent codex

The command copies each rollout file under sessions and archived_sessions to a new deterministic session ID with model_provider set to vercel. Originals are never moved, edited, or deleted, and re-running never duplicates a session it already copied. Pass --no-session-migration to skip the step, and decompress any .jsonl.zst sessions first, since compressed rollouts can't be rewritten. See session migration for details.

Point Codex at its own compatibility endpoint:

[model_providers.vercel]
base_url = "https://ai-gateway.vercel.sh/codex/v1"

Use it everywhere on this page. It serves /codex/v1/models in the proprietary ModelsResponse shape Codex decodes at startup, so the CLI attaches its shell tool and sees the full gateway catalog. Every other path falls through to the standard handlers, so routing, billing, and errors are unchanged. To call the gateway from your own code rather than through Codex, see the Responses API instead.

wire_api must be responses. Codex removed Chat Completions support, and the gateway serves the Responses API at /v1/responses.