1# Deploy Codex through a gateway
2
3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4
5Deploy Codex through your organization’s LLM gateway. Configure model routes, issue developer credentials, and distribute a verified Codex configuration.
6
7To configure Codex on your own machine with values you were given, see
8 [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). Before
9 choosing or rolling out a gateway, review the [gateway compatibility
10 requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility).
11
12## Prerequisites
13
14Before deploying Codex to developers, confirm that you have:
15
16- A gateway serving HTTPS at the exact base URL you will distribute.
17- An upstream provider credential held by the gateway.
18- Approved Codex-facing model aliases mapped to intended upstream models.
19- A scoped test gateway credential.
20- A secret delivery mechanism or a tested credential helper.
21- A way to distribute configuration, helper executables, and any catalog files.
22
23## Gateway requirements
24
25Before connecting Codex, verify that the gateway product preserves these required behaviors:
26
27- Accept Codex Responses API requests at `POST /v1/responses`.
28- Stream SSE events without buffering and end with `response.completed`.
29- Preserve follow-up continuation with replayed input.
30- Preserve `previous_response_id` only when WebSocket or incremental transport is enabled.
31- Preserve function calls and matching `function_call_output` items.
32- Route each Codex-facing model alias to the intended upstream model.
33- Authenticate users separately and return useful errors without hiding the cause.
34
35A health endpoint, `/v1/models`, Chat Completions response, or one plain-text reply does not qualify the gateway. See [Gateway compatibility requirements](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility) for the detailed contract.
36
37Need an implementation starting point? The [Codex deployment guidance repository](https://github.com/openai-on-aws/guidance-codex/tree/adbc00f353effbf0252e667ba41eb89c99324c8f) includes worked setups for different LLM gateway products. Use it as a reference after confirming your gateway meets the requirements above.
38
39## Roll out the gateway
40
41To move from a deployed gateway to a verified developer experience, complete these five checkpoints in order:
42
431. [Choose model names and verify routes](#choose-model-names-and-routes).
442. [Issue developer credentials](#issue-developer-credentials).
453. [Test Codex through the gateway](#test-the-client-and-gateway).
464. [Distribute the configuration](#distribute-the-configuration).
475. [Verify from a developer machine](#verify-and-operate-the-rollout).
48
49## Choose model names and routes
50
51Set Codex's `model` to the gateway's model name. Configure the gateway to route that name to the approved upstream model.
52
53| Gateway model name | Codex configuration |
54| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
55| A [built-in model name](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility#recognized-model-names) included in your Codex version | Set `model` in `config.toml` to this exact name. |
56| A custom alias, such as `company-coding-model` | Set `model_catalog_json` to a catalog containing the alias and the corresponding model's metadata. |
57
58<a id="supply-metadata-for-a-custom-alias"></a>
59
60### Use a model catalog for custom names
61
62Use [`model_catalog_json`](https://learn.chatgpt.com/docs/config-file/config-reference) 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.
63
64For example, to use `company-coding-model` as an alias for `gpt-6-luna`:
65
661. Create the `company-coding-model` alias on the gateway and route it to the approved upstream `gpt-6-luna` model.
672. Download the [Codex model catalog](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) for your Codex version and save a copy as `gateway-models.json`. Use this file as your starting point.
683. Edit the `gpt-6-luna` entry in your copy: set `slug` to `company-coding-model` and check that the remaining metadata matches the upstream model and gateway capabilities. For an alias without a model migration, set `upgrade` to `null`.
694. Keep the entries in the top-level `models` array and distribute the file to each client. A custom catalog replaces the bundled catalog, so include every model users need to select.
70
71To use a catalog for a specific Codex version, check `codex --version` and select the matching `rust-v<version>` tag. For a custom build, use its exact source commit. For a desktop deployment, match the bundled CLI version.
72
73For Bedrock through LiteLLM, apply the [required catalog edits](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm#prepare-the-client-catalog).
74
75Set 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:
76
77```toml
78model = "company-coding-model"
79model_catalog_json = "/absolute/path/to/gateway-models.json"
80```
81
82Restart the CLI or desktop app after changing the catalog because Codex loads it at startup.
83
84### Verify model routes
85
86For each model, verify the route with a real Responses request and gateway
87records. A `/v1/models` response can help discover names but doesn't prove that a
88model supports the required request and tool behavior.
89
90Model routing and tool authorization are separate parts of the rollout. Configure
91MCP connections, plugin distribution, and their policies separately.
92
93## Issue developer credentials
94
951. Issue one scoped gateway credential per developer so you can attribute usage
96 and revoke access individually.
972. Set the approved models, rate limits, budget, expiration, and renewal period
98 for each credential.
993. Deliver credentials through your secret manager or an installed credential
100 helper. Keep upstream provider and gateway administrator credentials off
101 developer machines.
1024. If you use a helper, follow the
103 [command-backed authentication contract](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)
104 and test token retrieval and refresh before distribution.
1055. Tell developers how to renew their credentials and whom to contact for help.
106
107<a id="test-the-client-and-gateway"></a>
108
109## Test Codex through the gateway
110
111Before distributing anything, follow [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure one isolated test user with the provider block and credential mechanism you plan to distribute.
112
113Run the checks below from the same CLI or desktop surface developers will use:
114
115| Check | Action | Passing evidence |
116| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117| Connection | Follow [Verify the connection](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection). | The expected provider and alias are active, the test prompt succeeds, and gateway logs identify the test user. |
118| 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`. |
119| 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. |
120| 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`. |
121| 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. |
122
123After these checks succeed, direct developers to [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.
124
125## Distribute the configuration
126
127To give every machine the same connection path, distribute the gateway base URL,
128provider ID, approved model alias, and credential mechanism.
129
130### What to distribute
131
132To set provider defaults, distribute this `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:
133
134Put `model` and `model_provider` before the first TOML table. If you set
135 `model_catalog_json`, keep it there too. TOML treats keys after
136 `[model_providers...]` as part of that table, not as top-level Codex
137 configuration.
138
139```toml
140model = "gpt-6-sol"
141model_provider = "enterprise-gateway"
142web_search = "disabled"
143
144[model_providers.enterprise-gateway]
145name = "Organization Gateway"
146base_url = "https://gateway.example.com/v1"
147wire_api = "responses"
148
149[model_providers.enterprise-gateway.auth]
150command = "/usr/local/bin/fetch-codex-gateway-token"
151args = ["print-token"]
152timeout_ms = 30000
153refresh_interval_ms = 300000
154```
155
156For 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.
157
158### Distribute defaults and requirements
159
160Use [Configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)
161to choose where to distribute defaults. For enforced settings and macOS MDM
162payloads, see [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).
163
164For host-wide defaults on macOS or Linux, use `/etc/codex/config.toml`. On
165Windows, place `config.toml` in `%ProgramData%\OpenAI\Codex\`. Users and
166profiles can override these defaults. The linked references describe supported
167requirements and their file locations.
168
169Distribute any referenced helper executables and catalog files separately.
170
171`model_catalog_json` points to a local JSON file. If you enforce it through
172`requirements.toml`, the requirement pins the path; it doesn't distribute the
173file. Put the catalog at that absolute path before Codex starts.
174
175Write resolved absolute Windows paths in TOML. Codex doesn't expand
176`%ProgramData%` inside `model_catalog_json` or provider auth `command` values. For
177example, use these paths only if your deployment placed the files there:
178
179```toml
180model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
181
182[model_providers.enterprise-gateway.auth]
183command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
184args = ["print-token"]
185```
186
187A CLI inside WSL reads Linux paths and Linux `CODEX_HOME`; it doesn't automatically
188inherit native Windows configuration.
189
190### Hand developers the configuration values
191
192If you do not have managed distribution, give each developer the gateway URL, provider ID, model alias, credential variable or resolver, and any catalog path. Send them to [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.
193
194Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.
195
196<a id="verify-and-operate-the-rollout"></a>
197
198## Verify from a developer machine
199
200To confirm that the distributed settings reached a developer machine:
201
2021. Restart Codex and confirm the expected provider and model.
2032. Run the short test in [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection).
2043. Ask one follow-up to confirm continuation, then check the gateway logs for that
205 developer's request.
206
207### Troubleshoot rollout failures
208
209Use the issue to find the configuration, credential, or gateway layer that needs attention:
210
211| Issue | Remediation |
212| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
213| Expected provider is missing after restart. | Inspect the winning configuration layer. User or profile configuration can override system defaults. |
214| Authentication fails for every user. | Check gateway authentication and the upstream provider credential; identify which service rejected the request. |
215| Authentication fails for one user. | Check that user's gateway credential or token resolver. |
216| Streaming stalls. | Inspect gateway buffering and terminal `response.completed` forwarding. |
217| 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](#use-a-model-catalog-for-custom-names) path and compatibility with the installed Codex version, then restart Codex. |
218| A Windows path fails. | Use resolved absolute paths. In TOML, use single-quoted strings for Windows paths with single backslashes. |
219
220## Reuse an existing gateway deployment
221
222If your organization already uses Claude Code through a gateway, you may be able
223to reuse the gateway product, network path, logging, and Bedrock access. Add a
224Codex-facing Responses route, credential, model aliases, and `config.toml` while
225retaining the existing working setup. Claude client settings and the
226`/v1/messages` contract don't configure Codex.
227
228| Existing Claude deployment | Codex migration |
229| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
230| 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](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |
231| 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. |
232| 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. |
233| `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or `apiKeyHelper` | Codex does not support `apiKeyHelper`. Issue a scoped Codex gateway credential and configure it with `env_key` or a Codex command-backed token resolver. |
234| 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](#choose-model-names-and-routes). Use the model name and any [model catalog JSON](https://learn.chatgpt.com/docs/config-file/config-reference) they provide. |
235| 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. |
236
237To migrate safely, complete these steps in order:
238
2391. Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.
2402. Add a parallel Codex-facing Responses route and Codex model aliases.
2413. Issue one scoped Codex credential. If Codex will use a static credential, expose that new credential through `env_key`; if Claude uses a credential helper, implement and test the Codex command-backed resolver contract.
2424. Configure that developer with the [provider block](#what-to-distribute). For a managed rollout, translate the payload into the Codex paths and precedence described in [Deploy Codex through a gateway](#distribute-the-configuration).
2435. 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](#test-the-client-and-gateway).
2446. After the pilot passes, [distribute the configuration](#distribute-the-configuration) to the remaining developers.
245
246## Related docs
247
248- [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)
249- [MCP](https://learn.chatgpt.com/docs/extend/mcp)
250- [Plugins](https://learn.chatgpt.com/docs/plugins)
251- [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration)
