Agents & CLIs · Client configuration

Run Codex through a separate, governed profile.

Point a separate Codex profile at the gateway. Give the agent a workload key, hard budget, approved model alias, and tested fallback without changing your normal ChatGPT-backed profile.

Create a free workspace Try the no-card Test Lab

How the connection works

How Codex CLI works with the gateway

Keep the normal ChatGPT profile intact

The gateway settings live in $CODEX_HOME/aighq.config.toml and apply only when Codex starts with --profile aighq. A normal Codex launch can continue to use the existing ChatGPT sign-in and subscription allowance.

Keep provider selection at user level

Codex ignores model_provider and model_providers when a repository puts them in a project-local .codex/config.toml. The gateway provider belongs in the named user profile, while the workload key stays in an environment variable or approved secret store.

Validate the complete agent loop

The custom provider uses the Responses wire API. Test streamed events, reasoning items, shell tool calls and follow-up outputs, context limits, and the selected backend's model behavior; ChatGPT workspace and cloud-only capabilities are not inherited by the gateway profile.

Runnable client path

Connect Codex CLI while keeping provider secrets off the machine.

Use a separate user-level Codex profile so the governed base URL and workload key do not alter your normal ChatGPT-backed configuration.

Test the controls first

1
Create a Codex CLI workload
Give each environment or agent its own key. Set the Codex CLI budget, rate limit, route, and fallback first.
2
Keep the key out of configuration files
Store the Codex CLI workload key in a keychain, CI secret, or secrets manager. The example contains no real credential.
3
Test both success and failure
Send a small Codex CLI request and inspect its receipt. Test Codex CLI's zero-balance stop and provider fallback too.

Personal subscription allowances are not imported.

Codex CLI uses an AI Gateway HQ workload key. Requests from Codex CLI charge the BYOK provider account or prepaid Bedrock balance selected by the route, not a personal subscription allowance.

Codex CLI configuration

# Save as $CODEX_HOME/aighq.config.toml (normally ~/.codex/aighq.config.toml).
# This profile uses gateway/provider billing, not ChatGPT subscription allowance.
# Keep the workload key out of this file.
model = "company-approved-fast"
model_provider = "aighq"

[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

# Then export AIGHQ_API_KEY and run: codex --profile aighq

Use the Codex CLI production URL shown. For Codex CLI, replace only the workload key and approved alias from the customer console.

This Codex CLI setup was checked against the vendor's published interface. Before a broad Codex CLI rollout, review the primary documentation because the vendor can change its interface.

Current shared controls

What every supported connection includes

Encrypted BYOK credentials that remain hidden after setup Stable model aliases and compatible route targets Organization and key budgets, rate limits, and concurrency limits Observe, Shadow, and Enforce modes with metadata-only evidence

Test the installed Codex version, Responses event streaming, shell tool round trips, context handling, budget stop, and fallback against the exact approved backend before normal use.

Client boundary

AIGHQ_BASE_URL=https://api.aigatewayhq.com/v1
AIGHQ_API_KEY=from-your-workspace
AIGHQ_MODEL=company-approved-fast

Codex sends Responses requests to the stable gateway URL with a scoped workload key and approved model alias. Administrators can change the eligible backend or compatible fallback without editing the repository. This profile does not transfer an active session between ChatGPT subscription access and gateway access; automatic subscription-first continuity remains under validation.

Implemented boundary

Supported protocols

Save aighq.config.toml beside your normal user configuration in $CODEX_HOME, keep the workload key in AIGHQ_API_KEY, and start Codex with --profile aighq. Codex currently supports the Responses wire API for custom providers.

POST /v1/responses Responses SSE event streaming User-level profile selected by --profile aighq

Compatibility follows the provider's current published interface. Review the provider documentation before approving Codex CLI for production.

Need the complete client-to-provider path? Follow the tested Codex CLI, AI Gateway HQ, and Groq setup