OpenAI Codex

Tasks

Route Codex CLI traffic through AIControls to audit and govern every code generation request. Two modes are available depending on whether your team holds a shared OpenAI API key or developers use their own ChatGPT accounts.

Prerequisites

• Codex CLI installed — npm install -g @openai/codex
• Your workspace proxy URL — find it in Settings → Integrations
• A personal access token — create one in Settings → Access Tokens

Proxy vs ChatGPT OAuth

Proxy (API key)

AIControls holds your organization's OpenAI API key. Developers authenticate with their personal access token — no OpenAI credentials on their machines.

Set environment variables

Set these before running Codex, or add them permanently to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export OPENAI_BASE_URL="https://YOUR_ORG.aicontrols.dev/v1"
export OPENAI_API_KEY="YOUR_ACCESS_TOKEN"

note

OPENAI_API_KEY here is your AIControls personal access token, not an OpenAI API key. AIControls authenticates you with this token and uses the organization's OpenAI credential to reach the API.

Run Codex

codex "refactor the auth module to use JWT"

Passthrough (ChatGPT OAuth)

Developers use their own ChatGPT Plus or Pro accounts. Their ChatGPT JWT is forwarded automatically — AIControls adds governance without replacing their credentials.

Step 1 — Log in with ChatGPT

Run codex login to authenticate and store your ChatGPT JWT locally:

codex login

This opens a browser window. Complete the login and return to the terminal. Your JWT is saved to ~/.codex/auth.json.

Step 2 — Configure ~/.codex/config.toml

Create or edit ~/.codex/config.toml:

# ~/.codex/config.toml
model_provider = "aicontrols"

[model_providers.aicontrols]
name = "AIControls Governance Proxy"
base_url = "https://YOUR_ORG.aicontrols.dev/v1"
requires_openai_auth = true
wire_api = "responses"
http_headers = { "X-AIControls-Token" = "YOUR_ACCESS_TOKEN" }

Replace YOUR_ORG with your workspace subdomain and YOUR_ACCESS_TOKEN with your personal access token.

note

requires_openai_auth = true tells Codex to forward the JWT from ~/.codex/auth.json to AIControls automatically. Your ChatGPT subscription is used for billing — AIControls never stores your ChatGPT credentials.

tip

config.toml is recommended over shell env vars — it keeps model provider settings and proxy config together and avoids conflicts with other OpenAI-compatible tools.

Run Codex

codex "write a test for the payment handler"

Direct API calls

If you call the OpenAI Responses API directly in code, point the client at the proxy with your personal access token as the API key:

# Python
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR_ORG.aicontrols.dev/v1",
    api_key="YOUR_ACCESS_TOKEN",
)

response = client.responses.create(
    model="codex-mini-latest",
    instructions="You are a coding assistant.",
    input="Write a Python function to parse ISO 8601 dates.",
)

// TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://YOUR_ORG.aicontrols.dev/v1",
  apiKey: "YOUR_ACCESS_TOKEN",
});

Verify the connection

Run a Codex command and check your workspace Audit Log. The request should appear with the model name (codex-mini-latest or similar) and your identity within seconds.

Troubleshooting

Authentication error (proxy mode)

Confirm OPENAI_API_KEY is your AIControls personal access token, not an OpenAI API key. The token should start with aic_ — regenerate it in Settings → Access Tokens if needed.

Authentication error (ChatGPT OAuth mode)

• Re-run codex login to refresh your JWT if it has expired
• Confirm ~/.codex/config.toml has the correct base_url and X-AIControls-Token value
• Verify requires_openai_auth = true is set — without it, the JWT is not forwarded

Model not available

Codex models require specific account access on OpenAI. In proxy mode, your administrator needs to ensure the OpenAI upstream account has Codex access enabled. In ChatGPT OAuth mode, confirm your ChatGPT subscription includes Codex access.

Requests not appearing in Audit Log

• Confirm OPENAI_BASE_URL ends with /v1 (unlike Claude Code, Codex does not append this automatically)
• Restart your terminal after editing shell profiles