Roll out a gateway
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.mdto the page URL.
Roll out native gateway OAuth, API keys, or credential helpers without ChatGPT sign-in. Configure model routes, authorize users, and distribute a verified Codex configuration. For a gateway that forwards ChatGPT workspace requests, see Sign in with ChatGPT through a gateway.
To configure Codex on your own machine with values you were given, see Configure the provider. Before choosing or rolling out a gateway, review the gateway compatibility requirements.
Prerequisites
Before deploying Codex to developers, confirm that you have:
- A gateway serving HTTPS at the exact base URL you will distribute.
- An upstream provider credential held by the gateway.
- Approved Codex-facing model aliases mapped to intended upstream models.
- A tested authentication method: native gateway OAuth, scoped gateway API keys, or a credential helper.
- For OAuth, a registered public client, approved test users, and gateway support for validating OAuth access tokens.
- For API keys or helpers, a secret delivery mechanism or a tested helper.
- A way to distribute configuration, any required helpers, and catalog files.
Gateway requirements
Before connecting Codex, verify that the gateway product preserves these required behaviors:
- Accept Codex Responses API requests at
POST /v1/responses. - Stream SSE events without buffering and end with
response.completed. - Preserve follow-up continuation with replayed input.
- Preserve
previous_response_idonly when WebSocket or incremental transport is enabled. - Preserve function calls and matching
function_call_outputitems. - Route each Codex-facing model alias to the intended upstream model.
- Authenticate users separately and return useful errors without hiding the cause.
A health endpoint, /v1/models, Chat Completions response, or one plain-text reply does not qualify the gateway. See Gateway compatibility requirements for the detailed contract.
Need an implementation starting point? The Codex deployment guidance repository includes worked setups for different LLM gateway products. Use it as a reference after confirming your gateway meets the requirements above.
Roll out the gateway
To move from a deployed gateway to a verified developer experience, complete these five checkpoints in order:
- Choose model names and verify routes.
- Choose authentication.
- Test Codex through the gateway.
- Distribute the configuration.
- Verify from a developer machine.
Choose model names and routes
Set Codex's model to the gateway's model name. Configure the gateway to route that name to the approved upstream model.
| Gateway model name | Codex configuration |
|---|---|
| A built-in model name included in your Codex version | Set model in config.toml to this exact name. |
A custom alias, such as company-coding-model |
Supply a remote or local catalog containing the alias and the corresponding model's metadata. |
Use a model catalog for custom names
Supply a model catalog when your gateway uses a model name Codex does not recognize. The catalog supplies the instructions, reasoning options, context limits, and tool capabilities Codex uses for that name. Without a matching entry, a request can reach the intended upstream model while Codex uses generic settings.
Host a remote catalog with model_providers.<id>.model_catalog_url to update model metadata centrally, or distribute a local file with model_catalog_json. Use a local catalog when native gateway OAuth is the only credential; OAuth alone doesn't enable remote catalog discovery. See the configuration reference for both settings.
Get a catalog endpoint or file compatible with your Codex version from your cloud or gateway provider. Make sure it includes each approved alias and its model metadata. For catalog implementation, see Implementing model catalogs for gateways and clouds.
Serve a remote catalog
Use the HTTPS catalog endpoint supplied by your provider.
Distribute the full endpoint URL in the selected provider's config.toml table:
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"
Make CODEX_GATEWAY_API_KEY available to the Codex process. Set base_url
separately to route inference through the gateway. If you omit it, Codex uses the
default OpenAI endpoint for the current authentication mode.
Discovery requires API-key, command-backed, or Codex-backend authentication. Native gateway OAuth or custom headers alone don't trigger it.
Coordinate catalog updates with your provider when your approved models change. Restart the client after changing its configuration.
Remove any effective model_catalog_json setting, including one enforced through
requirements.toml. It takes precedence over the remote URL and prevents fetching.
Distribute a local catalog
Use model_catalog_json to load the provider-supplied file at startup. A local custom
catalog replaces the bundled catalog.
Set the gateway alias, catalog slug, and Codex model to company-coding-model. Add these settings before the first TOML table in the Codex configuration you distribute, using the file's actual absolute path:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"
Restart the CLI or desktop app after changing the catalog because Codex loads it at startup.
Verify model routes
For each model, verify the route with a real Responses request and gateway
records. A /v1/models response can help discover names but doesn't prove that a
model supports the required request and tool behavior.
Model routing and tool authorization are separate parts of the rollout. Configure MCP connections, plugin distribution, and their policies separately.
Choose authentication
Native gateway OAuth
- Register a public OAuth client that supports authorization code with PKCE, and approve the users or groups that can sign in.
- Configure the gateway to validate the issued access token in the selected cookie or custom header. Apply the approved models, rate limits, and budgets to each user's identity.
- Follow native gateway OAuth to collect the authorization and token URLs, public client ID, scopes, optional resource, token delivery settings, and any fixed redirect port. Register the matching loopback redirect URI with your identity provider.
- Test browser sign-in, token refresh, and access revocation with a test user on the CLI or desktop app you plan to deploy. Confirm that the browser can reach the callback, including for remote CLI users.
Users sign in individually. You distribute OAuth configuration, not a client secret, gateway API key, or helper executable. Keep upstream provider credentials on the gateway.
API keys or credential helpers
- Issue one scoped gateway credential per developer so you can attribute usage and revoke access individually.
- Set the approved models, rate limits, budget, expiration, and renewal period for each credential.
- Deliver credentials through your secret manager or an installed credential helper. Keep upstream provider and gateway administrator credentials off developer machines.
- If you use a helper, follow the command-backed authentication contract and test token retrieval and refresh before distribution.
- Tell developers how to renew their credentials and whom to contact for help.
Test Codex through the gateway
Before distributing anything, follow Configure the provider to configure one isolated test user with the provider block and authentication method you plan to distribute.
Run the checks below from the same CLI or desktop surface developers will use:
| Check | Action | Passing evidence |
|---|---|---|
| Connection | Follow Verify the connection. | The expected provider and alias are active, the test prompt succeeds, and gateway logs identify the test user. |
| Streaming | Ask for a short multi-paragraph answer. | The gateway forwards SSE events without buffering, text arrives incrementally, and the stream ends with response.completed. |
| Local tool loop | In a disposable folder with read-only permissions, ask Codex to list the top-level files and summarize them. | Codex issues a local tool call, returns the result, and produces a final answer without edits. |
| Follow-up | Ask a follow-up in the same thread. | The answer uses the prior turn; the gateway accepts replayed input. If WebSocket or incremental transport is enabled, it also preserves previous_response_id. |
| Errors and attribution | Repeat with an intentionally invalid test alias or expired test credential. | The client receives a useful routing or authentication error, and valid requests remain attributed to the test user. |
After these checks succeed, direct developers to Configure the provider to configure and verify their own machine.
Distribute the configuration
To give every machine the same connection path, distribute the gateway base URL, provider ID, approved model alias, and authentication settings.
What to distribute
For native gateway OAuth, distribute the provider and
[model_providers.<id>.gateway_oauth] tables from the connection
guide, with the
registration values collected above. Keep requires_openai_auth = false and omit
env_key, experimental_bearer_token, and the command-backed auth table when
OAuth is the only gateway credential.
For a credential helper, distribute the following config.toml block through the
configuration layer you chose. Use a model recognized by your Codex version, or
supply the matching catalog described above. Install your token resolver at the
configured command path:
Put model and model_provider before the first TOML table. If you set
model_catalog_json, keep it there too. TOML treats keys after
[model_providers...] as part of that table, not as top-level Codex
configuration.
model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000
For a short-lived static test key, remove the auth block and put env_key = "CODEX_GATEWAY_API_KEY" inside [model_providers.enterprise-gateway] and set that variable outside TOML. Do not combine env_key with command-backed auth.
Distribute defaults and requirements
Use Configuration precedence to choose where to distribute defaults. For enforced settings and macOS MDM payloads, see Managed configuration.
For host-wide defaults on macOS or Linux, use /etc/codex/config.toml. On
Windows, place config.toml in %ProgramData%\OpenAI\Codex\. Users and
profiles can override these defaults. The linked references describe supported
requirements and their file locations.
Distribute any referenced helper executables and local catalog files separately.
To enforce a remote catalog URL, put the complete provider definition in
requirements.toml under [model_providers.<id>]. An enforced provider
definition replaces the matching provider table from ordinary configuration;
include its base_url, authentication settings, and other required fields.
Use the model_provider requirement when you also need to enforce provider
selection.
model_catalog_json points to a local JSON file. If you enforce it through
requirements.toml, the requirement pins the path; it doesn't distribute the
file. Put the catalog at that absolute path before Codex starts.
Write resolved absolute Windows paths in TOML. Codex doesn't expand
%ProgramData% inside model_catalog_json or provider auth command values. For
example, use these paths only if your deployment placed the files there:
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]
A CLI inside WSL reads Linux paths and Linux CODEX_HOME; it doesn't automatically
inherit native Windows configuration.
Hand developers the configuration values
If you do not have managed distribution, give each developer the gateway URL, provider ID, model alias, OAuth configuration or credential variable or resolver, and any catalog URL or local path. Send them to Configure the provider to configure and verify their own machine.
Manual setup is not an enforcement channel. Project-local .codex/config.toml cannot override sensitive provider or authentication routing keys.
Verify from a developer machine
To confirm that the distributed settings reached a developer machine:
- Restart Codex and confirm the expected provider and model.
- Run the short test in Connect to a gateway.
- Ask one follow-up to confirm continuation, then check the gateway logs for that developer's request.
Troubleshoot rollout failures
Use the issue to find the configuration, credential, or gateway layer that needs attention:
| Issue | Remediation |
|---|---|
| Expected provider is missing after restart. | Inspect the winning configuration layer. User or profile configuration can override system defaults. |
| Authentication fails for every user. | Check gateway authentication and the upstream provider credential; identify which service rejected the request. |
| Authentication fails for one user. | Check that user's identity-provider access, gateway credential, or token resolver. |
| Streaming stalls. | Inspect gateway buffering and terminal response.completed forwarding. |
| A model is missing or uses generic capabilities. | For a custom alias, confirm the gateway alias, Codex model, and catalog slug match. Check the catalog path and compatibility with the installed Codex version, then restart Codex. |
| A Windows path fails. | Use resolved absolute paths. In TOML, use single-quoted strings for Windows paths with single backslashes. |
Reuse an existing gateway deployment
If your organization already uses Claude Code through a gateway, you may be able
to reuse the gateway product, network path, logging, and Bedrock access. Add a
Codex-facing Responses route, credential, model aliases, and config.toml while
retaining the existing working setup. Claude client settings and the
/v1/messages contract don't configure Codex.
| Existing Claude deployment | Codex migration |
|---|---|
| Gateway product, DNS, TLS, private networking, logging, redaction, and monitoring | Keep these services in place. Add a Codex-facing route that satisfies the Gateway compatibility requirements. |
| Bedrock account, provider credential, IAM boundary, inference profiles, and credential rotation | Keep them only when they authorize the upstream models behind the new Codex aliases. The provider credential remains on the gateway. |
Claude /v1/messages route, Bedrock InvokeModel shape, Anthropic headers, and Claude-specific retries or errors |
Do not reuse these as proof of compatibility. Codex needs POST /v1/responses, Responses streaming, continuation, tool calls, and useful errors. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, or apiKeyHelper |
Codex does not support apiKeyHelper. Configure native gateway OAuth, a scoped key with env_key, or a Codex command-backed token resolver. |
Claude model names, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides, and Bedrock profile mappings |
Have your gateway team choose model names and configure any custom aliases. Use the model name and any model catalog JSON they provide. |
Claude settings.json, managed-settings.json, JSON env blocks, plist, or registry payloads |
Keep the same MDM or configuration-management channel, but distribute Codex config.toml and supported requirements.toml values instead. |
To migrate safely, complete these steps in order:
- Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.
- Add a parallel Codex-facing Responses route and Codex model aliases.
- Choose native gateway OAuth, an API key, or a credential helper and authorize one test user. For a static credential, expose it through
env_key; for a helper, implement and test the Codex command-backed resolver contract. - Configure that developer with the provider block. For a managed rollout, translate the payload into the Codex paths and precedence described in Roll out a gateway.
- Run the short connection check on the developer's actual CLI or desktop surface, then run the full streaming, continuation, tool-call, error, logging, and alias-routing checks in Test Codex through the gateway.
- After the pilot passes, distribute the configuration to the remaining developers.