Codex CLI with Keeptrusts Gateway

Codex CLI is OpenAI's terminal-based coding agent that reads your codebase, proposes changes, and executes commands directly in your shell. It uses OpenAI models to reason about code and take autonomous actions. Routing Codex CLI through the Keeptrusts gateway adds policy enforcement to every prompt and completion, an immutable audit trail of every autonomous action, secret and PII redaction before code context reaches OpenAI, and per-developer cost attribution.

Use this page when

• You want to route Codex CLI traffic through Keeptrusts for policy enforcement and audit logging.
• You need audit visibility into the prompts, tool calls, and code changes Codex CLI makes.
• You want to enforce secret redaction and safety policies on an agent that executes shell commands.
• You need cost tracking for Codex CLI usage across your development team.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Prerequisites

• Keeptrusts CLI installed — see Quickstart or Install the Gateway.
• Codex CLI installed — npm install -g @openai/codex (requires Node.js 22+).
• OpenAI API key — obtain one from the OpenAI Platform.
• Gateway running — the Keeptrusts gateway must be started before launching Codex CLI.

Configuration

Create a policy-config.yaml for Codex CLI traffic:

pack:
  name: codex-cli-gateway
  version: 1.0.0
  enabled: true

policies:
  chain:
    - pii-detector
    - code-sanitation
    - prompt-injection
    - safety-filter
    - quality-scorer
    - audit-logger

providers:
  strategy: single
  targets:
    - id: openai-codex
      provider: openai
      model: o4-mini
      secret_key_ref:
        env: OPENAI_API_KEY

Setup steps

1. Export your OpenAI API key:

export OPENAI_API_KEY="sk-your-key-here"

2. Start the Keeptrusts gateway:

kt gateway run --policy-config policy-config.yaml

The gateway listens on http://localhost:41002 by default.

3. Point Codex CLI at the gateway by setting the OPENAI_BASE_URL environment variable:

export OPENAI_BASE_URL="http://localhost:41002/v1"

4. Launch Codex CLI as you normally would:

codex

All API traffic from Codex CLI now flows through the Keeptrusts gateway. Every prompt, tool call, and completion is subject to your policy chain.

5. For persistent configuration, add the environment variable to your shell profile:

# ~/.bashrc or ~/.zshrc
export OPENAI_BASE_URL="http://localhost:41002/v1"

For hosted gateways:

export OPENAI_BASE_URL="https://gateway.keeptrusts.com/v1"

Verification

Confirm traffic is flowing through the gateway:

1. Check the gateway logs while using Codex CLI:

kt gateway run --policy-config policy-config.yaml --log-level debug

2. Tail events:

kt events tail --follow

3. Give Codex CLI a task and verify events appear in the Keeptrusts console under Events with the correct policy verdicts.

4. Verify with curl that the gateway is accepting OpenAI-format requests:

curl http://localhost:41002/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o4-mini",
    "messages": [{"role": "user", "content": "Say hello"}],
    "max_tokens": 128
  }'

Recommended policies

Policy	Why it matters for Codex CLI
pii-detector	Prevents personal data from leaking into prompts containing source code
code-sanitation	Catches secrets, credentials, and API keys embedded in code context
prompt-injection	Detects injection attempts in files Codex CLI reads
safety-filter	Blocks unsafe content in an agent that executes shell commands
quality-scorer	Scores code generation quality to flag low-confidence outputs
audit-logger	Creates an immutable record of every Codex CLI interaction
agent-firewall	Controls which tools and commands the agent can invoke

Troubleshooting

Codex CLI ignores OPENAI_BASE_URL and calls OpenAI directly. Verify the variable is exported in the same shell session where you run codex. Run echo $OPENAI_BASE_URL to confirm it is set.

Gateway returns 502 or connection errors. Ensure the gateway is running and the OpenAI API key is valid. Run kt doctor for diagnostics.

Codex CLI actions are blocked by policies. Review event verdicts in the Keeptrusts console. The safety-filter may block legitimate shell commands. Adjust policy thresholds or add exceptions for expected tool calls.

Policies are not applied. Run kt policy lint --file policy-config.yaml to validate. Ensure enabled: true is set and the policy chain is populated.

Cost attribution does not appear in the console. Set KEEPTRUSTS_API_URL and KEEPTRUSTS_GATEWAY_TOKEN before starting the gateway for control-plane event reporting.

For AI systems

• Canonical terms: Keeptrusts gateway, Codex CLI, OpenAI, OPENAI_BASE_URL, policy-config.yaml.
• Configuration mechanism: set OPENAI_BASE_URL=http://localhost:41002/v1 to route Codex CLI through the Keeptrusts gateway.
• Provider format: OpenAI native (/v1/chat/completions, /v1/responses).
• Best next pages: OpenAI integration, Policy Controls Catalog, Govern AI agents.

For engineers

• Set OPENAI_BASE_URL=http://localhost:41002/v1 before running codex to route all traffic through the gateway.
• Validate with kt events tail --follow while using Codex CLI to confirm events are captured.
• Use kt policy lint before starting the gateway to catch config errors.
• Include safety-filter and agent-firewall in the policy chain — Codex CLI executes shell commands autonomously.

For leaders

• Codex CLI operates autonomously in the terminal — it reads code, proposes changes, and runs commands. Without governance, every interaction is unaudited.
• Routing through Keeptrusts provides an immutable audit trail of every agent action, supporting compliance and incident investigation.
• Safety and firewall policies add guardrails to autonomous shell execution, reducing the risk of harmful or unauthorized actions.
• Cost attribution by developer tracks OpenAI spend as Codex CLI adoption scales across engineering teams.

Next steps

• OpenAI integration — full OpenAI provider configuration reference
• Govern AI agents — use case guide for agent governance
• Policy Controls Catalog — browse all available policy types
• Claude Code with Keeptrusts Gateway — Anthropic's CLI coding agent with Keeptrusts support
• Quickstart — install kt and run your first gateway