Codex CLI Integration

Codex CLI is OpenAI's open-source terminal coding agent. By default it connects to OpenAI's API, but with OffRail you can route it through a single gateway—use GPT-5.3 Codex, Gemini, Claude, or any of 200+ models while keeping full cost visibility.

One config file. No code changes. Full cost tracking in your dashboard.

Setup

codex logout

model = "auto"
model_reasoning_effort = "high"
openai_base_url = "https://api.offrail.ai/v1"

codex

Why This Works

OffRail's /v1 endpoint is fully OpenAI-compatible. Codex CLI sends requests to our gateway instead of OpenAI directly, and we route them to the right provider behind the scenes. This means:

• Use any model — GPT-5.3 Codex, Gemini, Claude, or 180+ others
• Keep your workflow — Codex CLI doesn't know the difference
• Track costs — Every request appears in your OffRail dashboard
• Automatic caching — Repeated requests hit cache, saving money

Configuration Explained

Base URL

The openai_base_url field points Codex CLI to OffRail instead of OpenAI:

openai_base_url = "https://api.offrail.ai/v1"

Model Selection

Use auto to let OffRail pick the best model, or set a specific one from the models page:

model = "auto"
# or pick a specific model
model = "gpt-5.3-codex"

Reasoning Effort

Control how much reasoning the model uses. Options are low, medium, and high:

model_reasoning_effort = "high"

Choosing Models

Use auto to let OffRail pick the best model automatically, or choose a specific one from the models page:

# let OffRail pick the best model
model = "auto"

# or pick a specific model
model = "gpt-5.3-codex"

What You Get

• Any model in Codex CLI — GPT-5.3 Codex for heavy lifting, lighter models for routine tasks
• Cost visibility — See exactly what each coding agent costs
• One bill — Stop managing separate accounts for OpenAI, Anthropic, Google
• Response caching — Repeated requests hit cache automatically
• Discounts — Check discounted models for savings up to 90%

Troubleshooting

Data retention required

Older versions of OffRail rejected Responses API requests with:

The Responses API requires data retention to be enabled.

This is no longer the case — the Responses API (which Codex CLI uses) works regardless of your organization's data retention policy. If you still see this error, the gateway you are talking to is running an outdated version; on a self-hosted deployment, update to the latest release.

Authentication errors

If you see 401 Unauthorized or requests going to api.openai.com instead of OffRail:

1. Make sure you've run codex logout to clear any ChatGPT session
2. Verify openai_base_url is set in ~/.codex/config.toml
3. When Codex prompts for authentication, select Provide your own API key and enter your OffRail key (starts with orl_)

Model not found

Verify the model ID matches exactly what's listed on the models page. Model IDs are case-sensitive.

Connection issues

Check that openai_base_url is set to https://api.offrail.ai/v1 (note the /v1 at the end).