Run Codex CLI through an AI gateway with Groq

What this route changes

The direct path is Codex CLI to a model provider. This setup inserts AI Gateway HQ as the control point and keeps Groq behind a stable route alias. Codex presents a gateway workload key; AI Gateway HQ applies the workload's policy, budget, rate, route, and provider-health controls before it uses the separately stored Groq credential.

This does not transfer a ChatGPT or Codex subscription, turn subscription allowance into API credit, or resell an OpenAI login. It is an API-compatible route using provider access that the customer is authorized to connect.

1. Build the bounded workload in AI Gateway HQ

Connect Groq as a bring-your-own-key provider, create a route alias for the approved Groq model, and add a hard budget before issuing a workload key. Use a separate key for each machine or automation identity, give it the shortest practical lifetime, and store the one-time value in the operating system's credential store rather than in a repository or shell profile.

• Name the principal for the actual workload, such as “workload:local-codex-cli.”
• Set request, token, concurrency, and cost ceilings that fit the provider's published limits.
• Add a fallback only after a comparable model passes the same coding and tool tests.
• Keep prompt and response retention off unless an authorized owner deliberately enables a documented content control.

2. Create an isolated Codex profile

Codex supports user-level profiles and custom model providers. Put the provider definition in a user-level profile file, not a project-level file. Replace the example route alias with the alias created in the gateway. The base URL ends at /v1 because Codex appends the Responses endpoint.

model = "your-approved-route"
model_provider = "aighq"
model_catalog_json = "/absolute/path/to/aighq-models.json"
model_reasoning_effort = "medium"
approval_policy = "on-request"

[model_providers.aighq]
name = "AI Gateway HQ"
base_url = "https://api.aigatewayhq.com/v1"
env_key = "AIGHQ_API_KEY"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

3. Describe the route to Codex without inflating every request

A custom route alias is not part of Codex's built-in model catalog. Give it a small local catalog entry so Codex uses the route's real context and tool boundary instead of fallback metadata and a much larger default instruction set. The slug must exactly match the route alias. This Groq-oriented entry deliberately omits the freeform patch tool and provider-hosted search; add capabilities only after the exact upstream model completes their full multi-turn tests.

{
  "models": [{
    "slug": "your-approved-route",
    "display_name": "Company approved route",
    "description": "Governed cost-efficient coding route.",
    "base_instructions": "Follow the user request precisely and concisely.",
    "context_window": 100000,
    "max_context_window": 100000,
    "effective_context_window_percent": 90,
    "default_reasoning_level": "medium",
    "default_reasoning_summary": "none",
    "default_verbosity": "low",
    "supported_reasoning_levels": [{
      "effort": "medium",
      "description": "Bounded routing"
    }],
    "supports_reasoning_summaries": false,
    "support_verbosity": false,
    "supports_parallel_tool_calls": false,
    "supports_search_tool": false,
    "shell_type": "shell_command",
    "input_modalities": ["text"],
    "supported_in_api": true,
    "visibility": "list",
    "priority": 50,
    "truncation_policy": {"mode": "tokens", "limit": 100000}
  }]
}

4. Load the workload key without writing it to the project

Retrieve the one-time gateway key from your password manager or operating-system credential store and expose it only to the Codex process. The following interactive shell pattern avoids placing the secret in command history; a managed workstation should use its approved secret-injection mechanism instead.

read -s "AIGHQ_API_KEY?Gateway workload key: "
export AIGHQ_API_KEY
codex --profile aighq
unset AIGHQ_API_KEY

5. Verify the exact compatibility boundary

Start with a text-only request, then a read-only local function-tool task, streaming, cancellation, and a bounded multi-turn task. Confirm that the response came through the intended route and locate its request evidence before allowing write-capable work.

In the tested Groq route published on September 2, 2026, a bounded text request completed through the Production gateway. Ordinary function declarations were preserved, while Codex-specific namespace declarations and OpenAI web_search declarations were omitted and reported in response headers because that upstream path does not accept them.

That result does not prove a complete coding-agent loop. On the tested free-tier gpt-oss-120b target, the first local shell function executed, but Groq's beta Responses path rejected the structured function-call follow-up history. Use a target or governed fallback that passes the entire tool-call and tool-output round trip. Do not flatten tool output into ordinary prompt text to hide an incompatible provider boundary. Groq documents its Responses API as beta and says server-managed state is not currently supported.

• Confirm the requested route alias, selected provider target, model, principal, and cost basis in the gateway evidence.
• Confirm a rejected or expired workload key fails before provider dispatch.
• Confirm the hard budget and provider rate limit stop or queue work as configured.
• Confirm any omitted tool type is visible rather than silently treated as supported.

6. Decide whether the route is fit for real coding work

A successful one-line response proves connectivity, not equivalent coding quality. Use a fixed set of representative repository tasks and compare correctness, tool completion, latency, provider errors, context behavior, and observed cost. Retain a cheaper route only where the evaluation supports it; send difficult or unsupported work to a separately approved route.

Provider free tiers and limits can change. Treat them as external capacity, not as a guaranteed service level. Keep the gateway's own ceiling below the exposure you are willing to accept and reconcile usage against the provider account.