Skip to content

Codex (CLI, desktop app, IDE extension) ​

Codex is OpenAI's coding agent. It ships as a terminal CLI, a desktop app, and an IDE extension. It reaches Corveil through a per-provider config block in ~/.codex/config.toml.

All three read the same ~/.codex/config.toml, so the Passthrough provider block below routes the CLI, the desktop app, and the IDE extension through Corveil without any per-surface setup. See Desktop app and IDE extension.

Prerequisites ​

  • A running Corveil instance (see deployment options)
  • A Corveil virtual API key (sk-citadel-...) — create one under People & Access → API Keys
  • Codex installed — the CLI (npm install -g @openai/codex), the desktop app, or the IDE extension

Mode ​

Passthrough mode only. Codex speaks the OpenAI Responses API, and Corveil holds no OpenAI credential for it: /v1/responses forwards Codex's own ChatGPT sign-in or OpenAI API key, from the Authorization header, to OpenAI. A [model_providers.corveil] block in Codex's config file keeps that sign-in in charge of Authorization and sends your Corveil virtual key in X-Corveil-Key, so Corveil can layer virtual-key auth, spend tracking, and guardrails on top.

Don't point OPENAI_BASE_URL at Corveil with OPENAI_API_KEY set to your virtual key. Codex would send the virtual key in Authorization, and Corveil refuses that with a 401 rather than forward its own key to OpenAI.

Passthrough mode (config.toml) ​

Codex sends its own ChatGPT-Codex OAuth session (or OpenAI API key) upstream in the Authorization header. A separate X-Corveil-Key header identifies the Corveil-side virtual key, and X-Corveil-Upstream: chatgpt_codex tells Corveil which upstream backend the request is bound for so it is logged and spend-tracked correctly.

Open (or create) ~/.codex/config.toml and add:

toml
model = "gpt-5.5"
model_provider = "corveil"
model_reasoning_effort = "medium"

[model_providers.corveil]
name = "Corveil"
base_url = "https://your-corveil-host/v1"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "X-Corveil-Key" = "sk-citadel-your-key-here", "X-Corveil-Upstream" = "chatgpt_codex" }

Replace your-corveil-host with your Corveil URL (the /v1 suffix is required) and sk-citadel-your-key-here with your virtual API key.

Keep the key out of config.toml (env_http_headers) ​

Instead of writing the virtual key inline, Codex can read a header value from an environment variable with env_http_headers:

toml
[model_providers.corveil]
name = "Corveil"
base_url = "https://your-corveil-host/v1"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "X-Corveil-Upstream" = "chatgpt_codex" }
env_http_headers = { "X-Corveil-Key" = "CORVEIL_API_KEY" }
bash
export CORVEIL_API_KEY="sk-citadel-your-key-here"
  • The values in env_http_headers are environment-variable names, not values. "X-Corveil-Key" = "sk-citadel-..." is wrong: Codex looks for an environment variable literally named sk-citadel-..., finds none, and sends no X-Corveil-Key header at all.
  • If the named variable is unset or empty, Codex omits the header and Corveil rejects the request with a 401.
  • Headers from http_headers and env_http_headers are sent together, so the static X-Corveil-Upstream stays in http_headers and only the key moves.
  • The variable must be set in the environment Codex is launched from. For the desktop app that is not your shell — see Desktop app and IDE extension.

Field reference ​

  • model — upstream model identifier Codex will request.
  • model_provider — must be corveil to route through the provider block below.
  • model_reasoning_effort — Codex's reasoning effort setting; passes through.
  • base_url — the Corveil instance's API root. Must end in /v1.
  • wire_api = "responses" — tells Codex to talk to Corveil's OpenAI Responses API surface.
  • requires_openai_auth = true — keeps Codex's existing OpenAI/ChatGPT auth handshake on; Corveil layers its own auth via X-Corveil-Key.
  • X-Corveil-Key header — your Corveil virtual API key (inline in http_headers, or via env_http_headers).
  • env_http_headers — maps a header name to the name of an environment variable holding its value.
  • X-Corveil-Upstream header — chatgpt_codex routes the call to the ChatGPT Codex backend and ensures correct logging and spend attribution. It also sends Codex's model-list refresh (GET /v1/models) to that backend, so the model picker shows your account's models.

Desktop app and IDE extension ​

The Codex desktop app and the Codex IDE extension read the same ~/.codex/config.toml as the CLI. Once the Passthrough block is in place:

  1. Fully quit and reopen the desktop app (or reload the editor window) so it picks up the new config.
  2. Keep signing in with your ChatGPT account as usual — requires_openai_auth = true leaves Codex's own sign-in in charge of the upstream Authorization header.
  3. Send a prompt and confirm it appears in the Corveil request log (see Verification).

The env_http_headers form depends on an environment variable. An app launched from the Dock, Finder, or Start menu does not inherit variables exported in your shell profile, so prefer the inline http_headers form for the desktop app, or launch the app (or the editor) from a shell where the variable is set.

Verification ​

bash
codex --version
codex "Say hello and nothing else."

If you get a response, the pipe is working. Confirm the request was logged in Corveil:

bash
corveil logs --tail 5

Or open the Corveil request log / spend dashboard in the UI — the call should appear with upstream = chatgpt_codex.

Custom TLS Certificates ​

For deployments with custom TLS certificates (common in GovCloud environments), Codex supports a dedicated environment variable:

bash
export CODEX_CA_CERTIFICATE="/path/to/your/ca-cert.pem"

Security note ​

sk-citadel-... keys are long-lived credentials. Don't commit ~/.codex/config.toml to version control with a real key inline — prefer per-user config or the env_http_headers form.

Troubleshooting ​

  • 401 "Authorization carries a Corveil credential": Your virtual key reached the Authorization header, usually through OPENAI_API_KEY. Use the provider block above, with the virtual key in X-Corveil-Key. Corveil v0.5.11 and earlier forwarded that header to OpenAI, so if you ran Codex this way before, rotate the key.
  • 401 Unauthorized: Confirm the Corveil-side key is in the X-Corveil-Key header (not Authorization), and that Codex's own ChatGPT/OpenAI auth is still valid (codex login).
  • Wrong header name: Corveil reads the virtual key only from X-Corveil-Key or X-Citadel-API-Key. Any other name, such as x-corveil-api-key, is ignored, and the request fails as if no key were sent.
  • 401 with env_http_headers: The value must be an environment-variable name ("CORVEIL_API_KEY"), not the key itself, and that variable must be set where Codex was launched. GUI-launched desktop apps don't see variables exported in your shell profile.
  • 404 Not Found: The base_url must include the /v1 path suffix.
  • **failed to refresh available models … missing field \models`, or a "1 warning" footer in the TUI:** Codex fetched /v1/modelsand got Corveil's own model catalog instead of your ChatGPT account's model list. Make sureX-Corveil-Upstreamis inhttp_headers, which Codex sends on every request, and update Corveil if it still happens: current versions pass that request through to the upstream you name. Until it refreshes, Codex picks models from a stale ~/.codex/models_cache.json`.
  • "Unknown X-Corveil-Upstream value": Check spelling — it must be exactly chatgpt_codex (or openai_api).
  • 403 from a WAF / API gateway: If you're fronting Corveil with a private-link / VPC endpoint, allowlist the X-Corveil-Key and X-Corveil-Upstream request headers.
  • TLS errors: If using a custom CA, set CODEX_CA_CERTIFICATE to your CA certificate path.