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 do-it-yourself ~/.codex/config.toml setup. Copy your gateway base URL from Settings → My Models → Gateway Endpoint and create a bd-… key under API Keys first. See Connecting Your Tools to the LLM Gateway if you don’t have those yet.

​
Prerequisites

​
Which models Codex can use

The gateway translates between the OpenAI and Anthropic formats on Chat Completions and Messages, but not on the Responses API. A Responses request is passed to the provider in Responses format, so the model you give Codex must be served by a provider that implements it: A Model Route can mix provider types. If a route’s first target is an Anthropic model, Codex requests to it fail with provider '…' does not support endpoint /v1/responses. Ask your admin for a route whose targets all serve Responses, or use a standalone model (<provider name>/<model>) from an OpenAI provider.
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 use the OpenAI SDKs & compatible clients URL from the LLM Gateway Endpoint card, which ends in /v1. Claude Code is the opposite: it uses the URL without /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 Model Route name like gpt-5.4-mini, or a standalone model in <provider name>/<model> form, exactly as Available Models lists it.

​
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. Budgets, rate limits, model access policies, and usage reporting apply the same way as for any other gateway client. When a budget or rate limit blocks a request, Codex shows “You’ve hit your usage limit. Try again at …” with the time the limit lifts, if it is known, and does not retry.

​
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 shouldn’t 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.

​
ChatGPT subscriptions (OpenAI Codex OAuth providers)

The setup above works for providers with a stored credential, such as an OpenAI API key. Your admin can also add an OpenAI Codex OAuth provider under LLM Management → Providers, which bills each request against the developer’s own ChatGPT subscription instead. Barndoor stores no OpenAI credential for it. A request to a Codex OAuth provider must carry two credentials:
  • your ChatGPT OAuth token in Authorization: Bearer …, which the gateway forwards to OpenAI, and
  • your Barndoor key in x-api-key, which the gateway uses to authenticate you.
The env_key setup above sends only your Barndoor key, so a request that lands on a Codex OAuth provider fails with 401 OpenAI provider requires an incoming Codex OAuth bearer token. If your organization runs Codex on ChatGPT subscriptions, launch it with Barndoor Bridge (barndoor run codex, or Launch Codex Desktop in the Bridge app) instead of configuring it by hand. See Launching Claude Code or Codex with Barndoor Bridge.
Barndoor Bridge is in early access and may not be enabled for your organization yet. Contact Barndoor to turn it on.

​
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