Skip to main content
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.
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 if you do not have those yet.

​
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.
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.

​
Why /v1 matters

Codex appends /responses to the provider base_url. The gateway’s Responses endpoint is /api/llm-gateway/v1/responses. 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):
  • 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

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

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.
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.

​
Smoke-test without Codex

Confirm the gateway accepts Responses traffic with your key before debugging Codex itself:
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