Corveil Docs

Appearance

Codex CLI ​

Codex CLI is OpenAI's open-source coding agent that runs in your terminal. It supports both a custom OpenAI base URL via environment variables and a richer per-provider config block in ~/.codex/config.toml.

Prerequisites ​

  • A running Corveil instance (see deployment options)
  • A Corveil virtual API key (sk-citadel-...) — create one under Corveil → Settings → API Keys
  • Codex CLI installed (npm install -g @openai/codex)

Mode ​

Direct and Passthrough modes supported. Direct mode uses Codex's standard OpenAI environment variables. Passthrough mode uses a [model_providers.corveil] block in Codex's config file, which lets Codex keep its own ChatGPT/OpenAI authentication while Corveil layers virtual-key auth, spend tracking, and guardrails on top.

Option A: Direct Mode ​

Your OPENAI_API_KEY is a Corveil virtual key. Corveil authenticates the request and forwards it upstream using its own provider credentials.

bash
npm install -g @openai/codex
export OPENAI_BASE_URL="https://your-corveil-host/v1"
export OPENAI_API_KEY="sk-citadel-your-key-here"

Option B: 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.

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.
  • X-Corveil-Upstream header — chatgpt_codex routes the call to the ChatGPT Codex backend and ensures correct logging and spend attribution.

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 CLI 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 environment-variable indirection if your Codex release supports it.

Troubleshooting ​

  • 401 Unauthorized (Direct mode): Verify OPENAI_API_KEY is a valid Corveil virtual API key.
  • 401 Unauthorized (Passthrough mode): 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).
  • 404 Not Found: The base_url must include the /v1 path suffix.
  • "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.