Appearance
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_headersare environment-variable names, not values."X-Corveil-Key" = "sk-citadel-..."is wrong: Codex looks for an environment variable literally namedsk-citadel-..., finds none, and sends noX-Corveil-Keyheader 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_headersandenv_http_headersare sent together, so the staticX-Corveil-Upstreamstays inhttp_headersand 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 becorveilto 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 viaX-Corveil-Key.X-Corveil-Keyheader — your Corveil virtual API key (inline inhttp_headers, or viaenv_http_headers).env_http_headers— maps a header name to the name of an environment variable holding its value.X-Corveil-Upstreamheader —chatgpt_codexroutes 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:
- Fully quit and reopen the desktop app (or reload the editor window) so it picks up the new config.
- Keep signing in with your ChatGPT account as usual —
requires_openai_auth = trueleaves Codex's own sign-in in charge of the upstreamAuthorizationheader. - 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 5Or 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
Authorizationheader, usually throughOPENAI_API_KEY. Use the provider block above, with the virtual key inX-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-Keyheader (notAuthorization), 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-KeyorX-Citadel-API-Key. Any other name, such asx-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_urlmust include the/v1path 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(oropenai_api). - 403 from a WAF / API gateway: If you're fronting Corveil with a private-link / VPC endpoint, allowlist the
X-Corveil-KeyandX-Corveil-Upstreamrequest headers. - TLS errors: If using a custom CA, set
CODEX_CA_CERTIFICATEto your CA certificate path.