Connect Codex to your organization’s model gateway using the provider settings and authentication method your gateway team supplies. The gateway routes model requests to your backend, such as Amazon Bedrock.
For an organization-wide rollout, see Roll out a gateway. For the required API behavior, see Gateway compatibility. To connect directly to Bedrock without a gateway, see Amazon Bedrock.
Check for an existing configuration
Before adding anything, check whether your administrator already configured Codex.
- For the CLI, inspect the selected profile and run
codex doctor. After startup, use/statusto confirm the active model and provider. - For the macOS app, inspect
~/.codex/config.tomlor the managed configuration your organization delivers. - For the Windows app, inspect
%USERPROFILE%\.codex\config.tomlor the system configuration your organization delivers.
If the expected gateway provider and model are already active, continue to Verify the connection.
Get your gateway connection details
Install the Codex CLI or the desktop app approved by your organization. To configure Codex yourself, get these values from your gateway team:
- The HTTPS gateway base URL, including its API path, such as
https://gateway.example.com/v1. - The model name and provider ID to use.
- The authentication method: native gateway OAuth, a scoped API key and its environment variable, or an installed credential helper.
- For OAuth, the authorization URL, token URL, public client ID, required scopes, and the cookie or custom header the gateway accepts.
- Any required model catalog URL, or a catalog file and its absolute local path.
Configure the provider
Open config.toml at ~/.codex/config.toml on macOS or Linux, or
%USERPROFILE%\.codex\config.toml on Windows.
Merge this example into your existing configuration, replacing the URL and model
with the values your administrator supplied. Don’t add a second definition of an
existing key or table. This example uses gpt-6-sol; use it without a custom
catalog only if your administrator confirms that your Codex version recognizes
the model and its bundled metadata matches the gateway.
Keep model, model_provider, model_catalog_json, and web_search before
the first TOML table. Keys placed after a table header belong to that table,
so Codex won’t read them as top-level settings.
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"
requires_openai_auth = falseThen add the authentication settings your gateway team supplies.
For API-key or helper authentication, if your administrator supplies a catalog
URL, add it to the existing
[model_providers.enterprise-gateway] table:
model_catalog_url = "https://gateway.example.com/codex/models.json"Remove any effective model_catalog_json setting; it takes precedence over the
URL. Administrators can find endpoint requirements in
remote catalog setup.
If your administrator supplies a local model catalog file, save it and add
model_catalog_json before the first TOML table, using the file’s absolute path.
Custom aliases need matching catalog metadata. For example:
model_catalog_json = "/etc/codex/gateway-models.json"Use the model name and catalog supplied together by your administrator. Don’t add a catalog path unless the file exists at that location.
enterprise-gateway is an illustrative provider ID. Use the same ID in
model_provider and its provider and authentication tables.
This example disables web search
for the initial connection test; your administrator should verify feature support
before enabling it.
Choose an authentication method
Use native gateway OAuth for browser sign-in, an API key for a scoped credential, or a credential helper if your organization supplies a command.
Use native gateway OAuth
Gateway OAuth works independently of ChatGPT sign-in. Use it when your gateway accepts access tokens issued by your organization’s identity provider, such as Microsoft Entra ID. Codex handles the browser sign-in, encrypted credential storage, and token refresh when the authorization server issues a refresh token.
Your gateway team must register a public OAuth client that supports the
authorization code flow with PKCE. Add this table to the provider configuration
in config.toml, replacing the URLs, client ID, and cookie name with their values:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
delivery = { kind = "cookie", name = "auth-openid" }
# redirect_port = 43127Add scopes and, if required, resource to this table using the values your
identity provider and gateway require. Request the scopes needed for refresh
tokens if your provider requires them. Codex uses an available loopback port by default.
If your identity provider requires a fixed redirect URI, set redirect_port and
register http://127.0.0.1:43127/callback for this example.
The gateway must validate the OAuth access token received in the configured
cookie. If it accepts a custom header instead, replace delivery with the header
your administrator provides, for example:
delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }Codex reserves Authorization; you can’t use it as the gateway_oauth delivery header.
A gateway that accepts only a static API key must add support for the OAuth token
and its delivery method before you can use this flow. The gateway continues to
manage its own upstream credentials, such as its AWS credentials for Bedrock.
When OAuth is your only credential, keep requires_openai_auth = false and remove the
previous env_key, experimental_bearer_token, or auth settings used for the
gateway credential. Use a local model_catalog_json file if you need custom model
metadata; OAuth alone doesn’t enable remote catalog discovery.
Restart the desktop app and follow its gateway sign-in prompt to open the browser.
In the CLI, start codex and follow the browser sign-in when Codex first accesses
the gateway. Complete your organization’s sign-in and MFA, then return to the
client. If the grant expires or Codex can’t refresh it, sign in again when prompted.
Native gateway OAuth requires a browser and a reachable loopback callback. It has
no device-code fallback. If the CLI runs over SSH, set redirect_port = 43127 in
the OAuth table and register the matching redirect URI described above. From the
machine with your browser, forward that port before starting Codex:
ssh -L 43127:127.0.0.1:43127 user@remoteIn that SSH session, start codex and open the gateway sign-in URL in your local
browser. A CLI inside a container also needs a callback reachable from the
browser. If you can’t make the callback reachable, use an API key or credential
helper instead.
Use an API key
Use this setting when the gateway expects an API key in the Authorization header.
Add the following setting inside the existing
[model_providers.enterprise-gateway] table:
env_key = "CODEX_GATEWAY_API_KEY"Make your gateway credential available as CODEX_GATEWAY_API_KEY in the
environment of the process that launches Codex, using your organization’s secret
delivery mechanism. Don’t put the credential in TOML or a repository. A variable
set in a terminal may not be available to an app launched from the desktop.
Use a custom authentication header
If your gateway requires a header such as X-API-Key instead of a bearer token,
replace env_key in the provider table with:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Use the exact header name your administrator provides. Codex reads the value from
the named environment variable; keep the credential out of the configuration file.
See the configuration reference for
model_providers.<id>.env_http_headers.
With ChatGPT sign-in, use the custom header for the gateway key so Codex can send the user’s OpenAI credential in Authorization.
If the custom header is your only authentication mechanism, use
model_catalog_json; remote catalog discovery won’t run.
Use an organization credential helper
If your administrator provides command-backed authentication, use their installed
helper and configuration instead of env_key. Don’t configure both mechanisms.
The helper must exist on your machine; Codex doesn’t install it. For example,
add this table without env_key, using the resolver path and
arguments your administrator supplies:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000The custom provider authentication reference defines the command, arguments, timeout, refresh interval, and token output contract. Ask your administrator how to renew your sign-in if the helper can no longer retrieve a token.
With ChatGPT sign-in, run the helper before launching Codex and pass its output through a custom gateway header instead of configuring the auth table. When the key expires, get a new key and relaunch Codex.
Use resolved absolute paths for helper executables and catalog files.
Enable ChatGPT sign-in (recommended)
If your organization uses a ChatGPT workspace, signing in gives users access to eligible features such as first-party plugins. Your workspace controls apply, and your gateway still handles model requests. Compare feature availability.
Add the gateway provider to your workspace’s managed requirements.toml. These settings apply when users sign in to that workspace.
# requirements.toml
model_provider = "enterprise-gateway"
[model_providers.enterprise-gateway]
name = "Enterprise gateway"
base_url = "https://gateway.example.com/backend-api/codex"
requires_openai_auth = trueConfigure gateway authentication as described above. Codex sends the user’s OpenAI credential to your gateway in Authorization. Use a separate header for the gateway credential. With native gateway OAuth, gateway_oauth.delivery can specify a header or a cookie.
Handle credentials at the gateway
The gateway receives two credentials on each model request. For example, when Codex sends the gateway OAuth token in a cookie:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>Validate the gateway credential and strip its cookie or custom header. Redact credentials and sensitive request data from logs. Choose which credential to use upstream:
- Forward the user’s credential for direct OpenAI inference (recommended). This lets OpenAI attribute usage and apply inference settings for that user. For this route, the gateway must proxy
/modelsand/responsestohttps://chatgpt.com/backend-api/codexand forwardAuthorizationand anyChatGPT-Account-IDheader unchanged. - Let the gateway authenticate to the inference provider. Use the credentials configured on the gateway for that provider. Leave the user’s OpenAI token and any
ChatGPT-Account-IDheader out of the upstream request.
These diagrams show the recommended route for OpenAI inference.
How a gateway key works with ChatGPT sign-in
How gateway OAuth works with ChatGPT sign-in
Add routing headers (optional)
To route requests by configuration or tool, add headers to the same enterprise-gateway provider in your cloud-managed requirements.toml:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Use env_http_headers for values supplied by the client environment. Send a test request and confirm that the gateway selects the intended route. See Custom model providers for more header options.
Only model-provider requests use this gateway route. Voice sessions use a separate route. Workspace sign-in, MCP servers, and plugins can also use other network paths.
Start the client
With ChatGPT sign-in, start the client and sign in to the workspace that provides the managed configuration. If you use native gateway OAuth, also complete your organization’s gateway sign-in when prompted. Then verify the connection.
For a locally configured provider, follow the instructions for your client.
Configure the CLI
The CLI reads ~/.codex/config.toml by default on macOS or Linux. After saving
the provider settings, run codex. Inside WSL, use the Linux configuration and
paths unless CODEX_HOME points elsewhere.
Configure the macOS app
The macOS app reads the same ~/.codex/config.toml. After saving the provider
settings, restart the app. If you use an environment variable for the credential,
make sure it’s available to the app process.
Configure the Windows app
Place the provider settings in %USERPROFILE%\.codex\config.toml, then restart
the app. For command-backed authentication, use the resolver installed by your
administrator. For example, replace the Unix auth table with:
[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000In Windows TOML, single-quoted literal strings preserve backslashes. Replace
Unix catalog paths too, for example with
'C:\ProgramData\OpenAI\Codex\models.json', using the actual path your
administrator supplied.
Configure MCP servers and plugins separately. A model gateway credential doesn’t authorize access to your tools or connected systems.
Verify the connection
Restart the client after changing the configuration. In the CLI, start codex
and use /status to inspect the active model and provider. In the desktop app,
check the selected model and configuration.
Send this prompt in a new task:
Reply with exactly: gateway-okExpect gateway-ok. A response alone doesn’t prove which route handled it: ask
your administrator to confirm that the gateway recorded your user, model alias,
and intended upstream route. Don’t identify the model by asking it its name.
If the gateway serves the model catalog, check that it returns a Codex-compatible models array. For OpenAI inference using the user’s credential, verify that the gateway forwards the ChatGPT headers to the Codex backend.
This verifies an initial connection. Administrators should also complete the rollout checks for streaming, tools, and follow-up turns.
Troubleshoot the connection
| Symptom | What to check |
|---|---|
| The expected provider isn’t active. | Check the selected profile and configuration precedence. Confirm that top-level keys aren’t inside a provider table. |
| OAuth sign-in or token delivery fails. | Check the public client registration, redirect URI, scopes, and configured cookie or header. Confirm that the gateway accepts the issued access token. |
| API-key or helper authentication fails. | Check that the credential variable reaches the client process, or that the installed helper can retrieve a current token. Ask the administrator to distinguish gateway authentication from upstream authentication. |
| The model isn’t found. | Confirm the supplied model name and ask the administrator to check its route. |
| The model uses unexpected capabilities. | Ask the administrator to check that the catalog metadata matches the model behind the alias. |
| Streaming stalls or follow-ups fail. | Ask the gateway owner to check proxy buffering, the terminal response.completed event, and Gateway compatibility. |
| A catalog or helper path fails. | Confirm that the file exists at the configured absolute path in the environment running Codex. |
When requesting help, include the error message with tokens and sensitive prompts removed.
Use an existing gateway deployment
If your organization already uses a gateway with another coding tool, you may be able to reuse its network path, logging, and provider access. Work with your gateway team to configure and test a Codex connection:
- Identify the existing gateway URL, credential mechanism, required headers, model routes, and configuration delivery method.
- Ask your gateway team to confirm that the gateway supports the API behavior Codex requires and to configure a Codex model route.
- Obtain the OAuth settings, scoped gateway credential, or credential helper, along with the model name and any required catalog from your gateway team.
- Configure Codex with those values.
- Verify the connection in the CLI or desktop app you plan to use. Have your gateway team complete the streaming, tool, and follow-up checks.
- After the pilot passes, follow Roll out a gateway to distribute the configuration to other developers.
For the administrator migration checklist and configuration mapping, see Reuse an existing gateway deployment.