54Set Codex's `model` to the gateway's model name. Configure the gateway to route that name to the approved upstream model.54Set Codex's `model` to the gateway's model name. Configure the gateway to route that name to the approved upstream model.
55 55
56| Gateway model name | Codex configuration |56| Gateway model name | Codex configuration |
57| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |57| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
58| 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. |58| 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. |
59| A custom alias, such as `company-coding-model` | Set `model_catalog_json` to a catalog containing the alias and the corresponding model's metadata. |59| A custom alias, such as `company-coding-model` | Supply a remote or local catalog containing the alias and the corresponding model's metadata. |
60 60
61<a id="supply-metadata-for-a-custom-alias"></a>61<a id="supply-metadata-for-a-custom-alias"></a>
62 62
63### Use a model catalog for custom names63### Use a model catalog for custom names
64 64
65Use [`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.65Supply 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.
66
67Host a remote catalog with `model_providers.<id>.model_catalog_url` to update model metadata centrally, or distribute a local file with `model_catalog_json`. See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for both settings.
66 68
67For example, to use `company-coding-model` as an alias for `gpt-6-luna`:69For example, to use `company-coding-model` as an alias for `gpt-6-luna`:
68 70
691. Create the `company-coding-model` alias on the gateway and route it to the approved upstream `gpt-6-luna` model.711. Create the `company-coding-model` alias on the gateway and route it to the approved upstream `gpt-6-luna` model.
702. 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.722. 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.
713. 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`.733. 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`.
724. 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.744. Keep the entries in the top-level `models` array. Include every model users need to select, then serve the file from a catalog endpoint or distribute it locally as described below.
73 75
74To 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.76To 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.
75 77
76For Bedrock through LiteLLM, apply the [required catalog edits](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm#prepare-the-client-catalog).78For Bedrock through LiteLLM, apply the [required catalog edits](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm#prepare-the-client-catalog).
77 79
80#### Serve a remote catalog
81
82Serve the prepared `gateway-models.json` as the response body of an HTTPS endpoint.
83Distribute the full endpoint URL in the selected provider's `config.toml` table:
84
85```toml
86model = "company-coding-model"
87model_provider = "enterprise-gateway"
88web_search = "disabled"
89
90[model_providers.enterprise-gateway]
91name = "Organization Gateway"
92base_url = "https://gateway.example.com/v1"
93model_catalog_url = "https://gateway.example.com/codex/models.json"
94wire_api = "responses"
95env_key = "CODEX_GATEWAY_API_KEY"
96```
97
98Make `CODEX_GATEWAY_API_KEY` available to the Codex process. Set `base_url`
99separately to route inference through the gateway. If you omit it, Codex uses the
100default OpenAI endpoint for the current authentication mode.
101
102Discovery requires API-key, command-backed, or Codex-backend authentication.
103Custom headers alone don't trigger it.
104
105The catalog endpoint must:
106
107- Accept `GET` requests at the configured URL, including the `client_version`
108 query parameter Codex adds and any configured provider `query_params`.
109- Accept the selected provider's authentication and configured headers. Host
110 the catalog on a service authorized to receive those credentials.
111- Return a top-level `models` array with complete Codex model metadata matching
112 the client's version. Use the version-matched catalog prepared above, rather
113 than a list of model IDs. Give each entry a unique, nonempty `slug`.
114- Return the JSON directly without redirects and keep the response within 1 MiB.
115
116Update the catalog when your approved models change. Restart the client after
117changing its configuration.
118
119Remove any effective `model_catalog_json` setting, including one enforced through
120`requirements.toml`. It takes precedence over the remote URL and prevents fetching.
121
122#### Distribute a local catalog
123
124Use `model_catalog_json` to load the prepared file at startup. A local custom
125catalog replaces the bundled catalog.
126
78Set 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:127Set 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:
79 128
80```toml129```toml
169profiles can override these defaults. The linked references describe supported218profiles can override these defaults. The linked references describe supported
170requirements and their file locations.219requirements and their file locations.
171 220
172Distribute any referenced helper executables and catalog files separately.221Distribute any referenced helper executables and local catalog files separately.
222
223To enforce a remote catalog URL, put the complete provider definition in
224`requirements.toml` under `[model_providers.<id>]`. An enforced provider
225definition replaces the matching provider table from ordinary configuration;
226include its `base_url`, authentication settings, and other required fields.
227Use the `model_provider` requirement when you also need to enforce provider
228selection.
173 229
174`model_catalog_json` points to a local JSON file. If you enforce it through230`model_catalog_json` points to a local JSON file. If you enforce it through
175`requirements.toml`, the requirement pins the path; it doesn't distribute the231`requirements.toml`, the requirement pins the path; it doesn't distribute the
192 248
193### Hand developers the configuration values249### Hand developers the configuration values
194 250
195If 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 [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.251If you do not have managed distribution, give each developer the gateway URL, provider ID, model alias, credential variable or resolver, and any catalog URL or local path. Send them to [Use API/provider credentials](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway) to configure and verify their own machine.
196 252
197Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.253Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.
198 254
