Skip to main content

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​

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

Step 1 — Configure ~/.codex/auth.json​

Create or edit ~/.codex/auth.json and select API-key authentication:

{
  "auth_mode": "apikey",
  "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.

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

Create or edit ~/.codex/config.toml and point Codex at your workspace proxy:

# ~/.codex/config.toml
openai_base_url = "https://YOUR_ORG.aicontrols.dev/v1"

Replace YOUR_ORG with your workspace subdomain.

warning

Setting only OPENAI_API_KEY and OPENAI_BASE_URL in your shell may not override credentials already saved by Codex. Configure both files above so Codex consistently uses the AIControls token and endpoint.

Run Codex​

codex "refactor the auth module to use JWT"

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 Security Events. The request should appear with the model name (codex-mini-latest or similar) and your identity within seconds. Opening the event detail's Request tab also shows the Prompt field with your last message — see Prompt capture. A follow-up turn that carries only previous_response_id and no new input legitimately has nothing to show here — an empty Prompt field on its own isn't a sign of a broken connection.

Sub-agents​

When Codex spawns sub-agents (its spawn_agent tool), each sub-agent's requests and tool calls are grouped under the spawn_agent call that started it on the session's Activity tab, labelled with the sub-agent's task name. See Subagent attribution.

Troubleshooting​

Authentication error (proxy mode)​

  • Confirm ~/.codex/auth.json contains "auth_mode": "apikey"
  • Confirm OPENAI_API_KEY in that file is your AIControls personal access token, not an OpenAI API key
  • Confirm openai_base_url in ~/.codex/config.toml is your workspace URL and ends with /v1
  • Regenerate the token 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 Security Events​

  • Confirm openai_base_url in ~/.codex/config.toml ends with /v1 (unlike Claude Code, Codex does not append this automatically)
  • Restart Codex after editing either configuration file

Attribute Codex-written PRs​

For automatic attribution, keep Codex requests routed through AIControls while it edits and commits code. AIControls extracts the successful commit result returned to Codex and matches its SHA to the PR's commit list. The PR appears as witnessed once GitHub ingestion and attribution complete; the next attribution pass normally runs within a minute. Full prompt capture is not required for new commit evidence.

For a self-declared fallback, add this instruction to the repository's AGENTS.md:

When Codex writes or materially modifies code in a PR, include this footer
in the PR description: Generated by OpenAI Codex
Only use this authoring declaration for code changes, not review-only work.

An explicit commit trailer, Co-authored-by: Codex <noreply@openai.com>, is also recognized. These markers are optional declarations; do not assume every Codex client adds them automatically. Keep AI code review separate from AI authorship.

For existing PRs, see Recover historical Codex attribution. If neither session evidence nor a marker is available, Outcomes shows Unknown, not confirmed manual work.

Last updated on