OpenAI Codex

OpenAI Codex ↗ is a coding agent you run in your terminal. It supports custom model providers ↗ defined in config.toml. This configuration adds a provider that points at AI Gateway's OpenAI endpoint, so Codex sends its requests through AI Gateway. AI Gateway authenticates the model provider for you through Unified Billing, so you pass a Cloudflare API token instead of an OpenAI API key.

Note

Codex custom providers only support the OpenAI Responses API (wire_api = "responses"). This means you can only use OpenAI models that support the Responses API, such as gpt-5.5. Models from other providers (for example, Anthropic or Google) do not use the OpenAI Responses request format, so they do not work with Codex through this configuration.

Prerequisites

Before you start, you need:

• Your Cloudflare account ID. To find it, refer to Find your account and zone IDs.
• An AI Gateway. You can use your account's default gateway or create a gateway and use its slug.
• A Cloudflare API token with AI Gateway permission.
• Credits loaded on your account for third-party models.
• Codex ↗ installed and updated to the latest version.

1. Create a Codex profile ↗ file at ~/.codex/cloudflare-aig.config.toml. The profile defines a custom model provider that points at your gateway's OpenAI endpoint and reads your Cloudflare API token from an environment variable.

   Replace <ACCOUNT_ID> and <GATEWAY_ID> with your values. You can use default for the gateway to route through your account's default gateway, or change it to another gateway slug.

   ~/.codex/cloudflare-aig.config.toml

   model_provider = "cloudflare-ai-gateway"
   model = "gpt-5.5"
   model_reasoning_effort = "medium"
   
   [model_providers.cloudflare-ai-gateway]
   name = "Cloudflare AI Gateway"
   # Run `wrangler whoami` to get your account ID, then replace <ACCOUNT_ID>.
   # Use `default` for <GATEWAY_ID> to route through your account's default gateway.
   base_url = "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/openai"
   env_key = "CLOUDFLARE_API_KEY"
   wire_api = "responses"

   Note

   Codex does not expand environment variables inside base_url, so the account ID and gateway slug must be literal values. Only CLOUDFLARE_API_KEY is read from the environment.

2. Set your Cloudflare API token as the CLOUDFLARE_API_KEY environment variable. The following commands set it for the current session. To persist it, add it to your shell profile (for example, ~/.zshrc or ~/.bashrc).

   Replace <CLOUDFLARE_API_KEY> with your value.

   macOS / Linux

   # Run `wrangler auth token` to get an auth token.
   export CLOUDFLARE_API_KEY="<CLOUDFLARE_API_KEY>"

   Windows (PowerShell)

   PowerShell

   # Run `wrangler auth token` to get an auth token.
   $env:CLOUDFLARE_API_KEY = "<CLOUDFLARE_API_KEY>"

3. Start Codex with the profile and send a prompt. Requests now route through AI Gateway.

   codex --profile cloudflare-aig

To confirm traffic reaches AI Gateway, refer to Verify it works.