---
title: Codex CLI Integration
description: Use any model with OpenAI's Codex CLI through LLM Gateway. One config file, full cost tracking.
icon: CodexCli
---

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

Codex CLI is OpenAI's open-source terminal coding agent. By default it connects to OpenAI's API, but with LLM Gateway 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.

<Callout type="info">
	**Using DevPass?** This integration also works with a
	[DevPass](https://devpass.llmgateway.io) plan key. Use root model IDs without
	a provider prefix (`claude-sonnet-4-5`, not `anthropic/claude-sonnet-4-5`) —
	provider-pinned routing is not available on coding plans; the gateway picks
	the provider for you.
</Callout>

## Setup

<Steps>
<Step>
### Sign Up for LLM Gateway

[Sign up free](https://llmgateway.io/signup) — no credit card required. Copy your API key from the dashboard.

</Step>

<Step>
### Log Out of ChatGPT

If you're logged into ChatGPT in Codex CLI, the stored session will override your custom config. Log out first:

```bash
codex logout
```

</Step>

<Step>
### Create Config File

Create or edit `~/.codex/config.toml`:

```bash
model = "auto"
model_reasoning_effort = "high"
openai_base_url = "https://api.llmgateway.io/v1"
```

</Step>

<Step>
### Run Codex CLI

```bash
codex
```

On first launch, Codex will prompt you for authentication. Select **Provide your own API key**, then enter your LLM Gateway API key (starts with `llmgtwy_`).

All requests will now be routed through LLM Gateway.

</Step>
</Steps>

## Why This Works

LLM Gateway'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 LLM Gateway dashboard
- **Automatic caching** — Repeated requests hit cache, saving money

## Configuration Explained

### Base URL

The `openai_base_url` field points Codex CLI to LLM Gateway instead of OpenAI:

```bash
openai_base_url = "https://api.llmgateway.io/v1"
```

### Model Selection

Use `auto` to let LLM Gateway pick the best model, or set a specific one from the [models page](https://llmgateway.io/models):

```bash
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`:

```bash
model_reasoning_effort = "high"
```

## Choosing Models

Use `auto` to let LLM Gateway pick the best model automatically, or choose a specific one from the [models page](https://llmgateway.io/models):

```bash
# let LLM Gateway 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](https://llmgateway.io/models?discounted=true) for savings up to 90%

## Troubleshooting

### Data retention required

Older versions of LLM Gateway 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 LLM Gateway:

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 LLM Gateway key (starts with `llmgtwy_`)

### Model not found

Verify the model ID matches exactly what's listed on the [models page](https://llmgateway.io/models). Model IDs are case-sensitive.

### Connection issues

Check that `openai_base_url` is set to `https://api.llmgateway.io/v1` (note the `/v1` at the end).

<Callout type="info">
	View all available models on the [models page](https://llmgateway.io/models).
</Callout>

<Callout type="info">
	Need help? Join our [Discord community](https://llmgateway.io/discord) for
	support and troubleshooting assistance.
</Callout>
