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. If your gateway is protected by Cloudflare Access, refer to Use with Cloudflare Access.

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.

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.tomltoml
```
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.
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.
# Run `wrangler auth token` to get an auth token. export CLOUDFLARE_API_KEY="<CLOUDFLARE_API_KEY>"
# Run `wrangler auth token` to get an auth token. $env:CLOUDFLARE_API_KEY = "<CLOUDFLARE_API_KEY>"
Start Codex with the profile and send a prompt. Requests now route through AI Gateway. The cloudflare-aig profile name matches the cloudflare-aig.config.toml file you created.
```
codex --profile cloudflare-aig
```

Use with Cloudflare Access

If your gateway is protected by Cloudflare Access, Codex can authenticate with a short-lived Access token instead of a Cloudflare API token. Point the provider at your custom domain, and configure the provider's auth command to fetch the token with cloudflared instead of passing a token through an environment variable.

Update the same ~/.codex/cloudflare-aig.config.toml profile from the Unified Billing setup so the provider points at your custom domain and uses cloudflared for authentication. The cloudflare-aig in codex --profile cloudflare-aig refers to this file's name. Replace ai-gateway.example.com with your custom domain.

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

model_provider = "cloudflare-ai-gateway"
model = "gpt-5.5"
model_reasoning_effort = "medium"

[model_providers.cloudflare-ai-gateway]
name = "Cloudflare AI Gateway"
base_url = "https://ai-gateway.example.com/openai"
wire_api = "responses"

[model_providers.cloudflare-ai-gateway.auth]
command = "cloudflared"
args = ["access", "login", "--no-verbose", "https://ai-gateway.example.com"]
timeout_ms = 30000
refresh_interval_ms = 0

Compared to the Unified Billing setup in the previous section, the custom domain replaces the account ID and gateway ID in base_url, and the auth block replaces env_key.

Start Codex with the profile:

codex --profile cloudflare-aig

The first request opens your identity provider's login flow. After you authenticate, requests route through AI Gateway with your Access identity attached as cf.user_id.

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