> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Codex with the LLM Gateway

> Point Codex CLI and Codex Desktop at the Barndoor LLM Gateway using the OpenAI Responses wire format.

OpenAI Codex (CLI and Desktop) talks to models over the **OpenAI Responses API** (`POST /v1/responses`), not Chat Completions. The Barndoor LLM Gateway speaks that wire format natively — configure Codex with a custom provider whose `base_url` is your gateway endpoint and whose `wire_api` is `responses`.

<Info>
  This guide covers the DIY `~/.codex/config.toml` setup. Copy your exact gateway base URL and a `bd-…` API key from **Settings → My Models** first — see the [LLM Gateway Quickstart](/how-tos/llm-gateway-quickstart) if you do not have those yet.
</Info>

## Prerequisites

* Codex CLI installed, and/or the **Codex desktop app**.
* A Barndoor LLM Gateway endpoint and a `bd-…` API key from **Settings → My Models**.
* At least one **model route** (or enabled model) your key is allowed to call. Use the exact name shown under **Available Models**.

<Note>
  **Self-hosted and private-cloud deployments:** swap `app.barndoor.ai` for your organization's portal hostname everywhere below. The path (`/api/llm-gateway/v1`) is the same.
</Note>

## Why `/v1` matters

Codex appends `/responses` to the provider `base_url`. The gateway's Responses endpoint is `/api/llm-gateway/v1/responses`.

| `base_url` you set                           | Codex actually calls         | Result                                                        |
| -------------------------------------------- | ---------------------------- | ------------------------------------------------------------- |
| `https://app.barndoor.ai/api/llm-gateway/v1` | `…/llm-gateway/v1/responses` | Correct                                                       |
| `https://app.barndoor.ai/api/llm-gateway`    | `…/llm-gateway/responses`    | Wrong — often a `401` with `invalid JWT header: InvalidToken` |

Always keep the trailing `/v1` that **Settings → My Models** shows for OpenAI-compatible clients. (This is the opposite of Claude Code, which must *omit* `/v1` because it appends `/v1/messages` itself.)

## Configure Codex CLI

### 1. Add a Barndoor provider

Edit `~/.codex/config.toml` (create the file if it does not exist):

```toml theme={null}
model_provider = "barndoor"
model = "gpt-4o-mini"   # replace with a route or model from Settings → My Models

[model_providers.barndoor]
name = "Barndoor"
base_url = "https://app.barndoor.ai/api/llm-gateway/v1"
wire_api = "responses"
env_key = "BARNDOOR_API_KEY"
```

* `wire_api = "responses"` selects the Responses wire format Codex requires.
* `env_key` is only the **name** of the environment variable Codex should read for the API key — it is not the secret itself.
* `model` must match a name your key can call (a bare route alias like `gpt-4o-mini`, or a provider-prefixed form if that is how the model is listed).

### 2. Export the gateway key

```bash theme={null}
export BARNDOOR_API_KEY="bd-…"
```

`env_key` points Codex at this variable; the `export` supplies the value. Keeping the secret in the environment (not in `config.toml`) avoids committing it to git.

Add the export to your shell profile if you want it available in every new terminal.

### 3. Run Codex

```bash theme={null}
codex
```

Traffic goes to Barndoor on `POST /v1/responses`. Usage and governance follow the same rules as any other gateway client.

## Configure Codex Desktop

Codex Desktop uses the same provider configuration as the CLI. Custom providers are selected by `model_provider` / `model` in config — the in-app model picker may not list custom gateway models the way it lists built-in ones.

1. Put the same `model_provider`, `model`, and `[model_providers.barndoor]` block in `~/.codex/config.toml` (or in `$CODEX_HOME/config.toml` if you set `CODEX_HOME`).
2. Make `BARNDOOR_API_KEY` available to the Desktop process. Dock / Spotlight launches on macOS typically do **not** inherit exports from `.zshrc` or `.zprofile`. Prefer one of:
   * Start Desktop from a terminal after exporting the key (for example `export BARNDOOR_API_KEY="bd-…" && open -a "Codex"` — use the exact app name on your machine).
   * A small wrapper script that exports the key, then launches the app.
3. Fully quit and relaunch Desktop so it reloads `config.toml`. Routing follows the `model_provider` and `model` you set; you should not need to pick “Barndoor” from a provider menu.

<Warning>
  If Desktop starts without `BARNDOOR_API_KEY` in its environment, requests fail auth even when the same key works in the CLI. Confirm the launch path actually exports the variable — a terminal-only `export` does not help a Dock-launched app.
</Warning>

## Smoke-test without Codex

Confirm the gateway accepts Responses traffic with your key before debugging Codex itself:

```bash theme={null}
curl https://app.barndoor.ai/api/llm-gateway/v1/responses \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Reply with the single word pong."
  }'
```

A successful JSON response means the endpoint, key, and model name are fine — remaining issues are almost always Codex `base_url` / `wire_api` / env wiring.

## Troubleshooting

| Symptom                                    | Likely cause                                 | Fix                                                                                                                       |
| ------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `401` / `invalid JWT header: InvalidToken` | `base_url` missing `/v1`                     | Use `…/api/llm-gateway/v1`                                                                                                |
| `401` / invalid API key                    | Wrong or unset `BARNDOOR_API_KEY`            | Confirm `env_key` matches the variable you exported; recreate the key under **Settings → My Models** if needed            |
| Model not found / `404`                    | `model` is not an enabled route for your key | Copy an exact name from **Available Models**                                                                              |
| Desktop ignores the key                    | GUI process lacks the env var                | Launch Desktop from a shell/wrapper that exports `BARNDOOR_API_KEY` (Dock launches usually will not see `.zshrc` exports) |
| Works in `curl` but not in Codex           | Wrong `wire_api` or provider block           | Set `wire_api = "responses"` under `[model_providers.barndoor]`                                                           |

## Related

* [Using the LLM Gateway](/how-tos/use-llm-gateway) — overview and architecture
* [LLM Gateway Quickstart](/how-tos/llm-gateway-quickstart) — keys, routes, Cursor, Claude Code, SDKs
* [LLM Controls](/how-tos/use-llm-controls) — budgets, rate limits, and model access