Documentation 2026-11-04 23:02 UTC to 2026-11-05 23:03 UTC

5<CodexDocsOverviewLanding5<CodexDocsOverviewLanding

6 title="Administration"6 title="Administration"

7 description="Set access and policy boundaries for ChatGPT, Codex developer tools, APIs, plugins, and connected systems."7 description="Set access and policy boundaries for ChatGPT, Codex developer tools, APIs, plugins, and connected systems."

8 intro="Start with workspace identity and access. Then configure local runtime policy for supported capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension; Codex cloud eligibility; Platform API access; plugins and connectors; and permissions in connected systems."8 intro="Start with the rollout guide, then set up identity and access. Use Configuration for app installation, updates, and workspace policies. Use Advanced deployment for Amazon Bedrock, Bedrock in GovCloud, or an organization gateway. Browse the sections for feature controls, usage, and security."

9 primaryCta={{9 primaryCta={{

10 label: "Explore authentication",10 label: "Start your rollout",

11 href: "/codex/auth?surface=app",11 href: "/codex/enterprise/admin-setup",

12 }}12 }}

13 hero={{13 hero={{

14 illustration: "administration",14 illustration: "administration",

148 ],148 ],

149 },149 },

150 {150 {

151 title: "Deployment and configuration",151 title: "Configuration",

152 description:152 description:

153 "Deploy apps and configure updates, runtime settings, remote connections, and model access.",153 "Manage app installation, updates, runtime settings, remote connections, and workspace model availability.",

154 pages: [154 pages: [

155 {155 {

156 title: "Windows app and CLI deployment",156 title: "Windows app and CLI deployment",

207 href: "/codex/enterprise/workspace-model-availability",207 href: "/codex/enterprise/workspace-model-availability",

208 icon: "settings",208 icon: "settings",

209 },209 },

210 ],

211 },

212 {

213 title: "Advanced deployment",

214 description:

215 "Connect directly to Amazon Bedrock, configure Bedrock in GovCloud, or deploy an organizational gateway that routes requests to your inference provider.",

216 pages: [

210 {217 {

211 title: "Amazon Bedrock",218 title: "Amazon Bedrock",

212 description:219 description:

215 icon: "storage",222 icon: "storage",

216 },223 },

217 {224 {

218 title: "Bedrock GovCloud configuration",225 title: "GovCloud deployment",

219 description:226 description:

220 "Configure local Codex workflows with Amazon Bedrock in AWS GovCloud.",227 "Configure local Codex workflows with Amazon Bedrock in AWS GovCloud.",

221 href: "/codex/enterprise/govcloud-configuration",228 href: "/codex/enterprise/govcloud-configuration",

235 href: "/codex/enterprise/roll-out-a-gateway",242 href: "/codex/enterprise/roll-out-a-gateway",

236 icon: "settings",243 icon: "settings",

237 },244 },

238 {

239 title: "Gateway compatibility",

240 description:

241 "Check the Responses API behavior required for model requests, streaming, and tool calls.",

242 href: "/codex/enterprise/gateway-compatibility",

243 icon: "code",

244 },

245 {

246 title: "Bedrock through LiteLLM",

247 description:

248 "Configure a LiteLLM gateway to route Codex model requests to Amazon Bedrock.",

249 href: "/codex/enterprise/bedrock-through-litellm",

250 icon: "storage",

251 },

252 ],245 ],

253 },246 },

254 {247 {

10 provides a model gateway, follow [Connect to a gateway without ChatGPT10 provides a model gateway, follow [Connect to a gateway without ChatGPT

11 sign-in](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). That path supports native11 sign-in](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway). That path supports native

12 gateway OAuth with your organization's identity provider; the gateway manages12 gateway OAuth with your organization's identity provider; the gateway manages

13 the Bedrock credentials. To configure a gateway backed by Bedrock, see13 the Bedrock credentials. For deployment guidance, see [Roll out a

14 [Bedrock through LiteLLM](https://learn.chatgpt.com/docs/enterprise/bedrock-through-litellm).14 gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway).

15 15 

16## How it works16## How it works

17 17 

36Check the model-specific IAM requirements. For example, GPT-6 Sol through Runtime36Check the model-specific IAM requirements. For example, GPT-6 Sol through Runtime

37also requires `bedrock:InvokeModel` on the account's default project. See AWS's [GPT-6 Sol setup instructions](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-openai-gpt-6-sol.html).37also requires `bedrock:InvokeModel` on the account's default project. See AWS's [GPT-6 Sol setup instructions](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-openai-gpt-6-sol.html).

38 38 

39## Configure the provider39## Set up Codex with Amazon Bedrock

40 40 

41Codex allows you to configure the provider by setting `model_provider` in `~/.codex/config.toml`. The ChatGPT desktop app, Codex CLI, IDE extension, and SDK read the same local configuration layers.41<a id="configure-the-provider"></a>

42 

43### Choose Amazon Bedrock as your provider

44 

45<Tabs

46 id="bedrock-client-setup"

47 ariaLabel="Bedrock setup by client"

48 param="setup"

49 defaultTab="cli"

50 tabs={[

51 { id: "cli", label: "CLI" },

52 { id: "desktop", label: "Desktop" },

53 ]}

54>

55

56 

57 

58If Codex already uses your AWS credentials for Bedrock, [verify your connection](#verify-your-connection). For first-time setup or a signed-out CLI session:

59 

601. Start `codex`. On the sign-in screen, choose **Use Amazon Bedrock**.

612. Choose a detected AWS profile or credentials, or select a credential method. If Codex finds no credentials, choose **AWS profile**, **AWS access keys**, **Environment variables**, or **Bedrock API key**.

623. Follow the prompts for your credential method. Enter the AWS Region when prompted. If you choose environment variables, set them in your shell and restart Codex.

63 

64![Codex CLI showing the four Amazon Bedrock credential options when it finds no AWS credentials.](https://developers.openai.com/images/codex/amazon-bedrock/cli-credential-options.webp)

65 

66

67 

68

69 

70 

711. On **Sign in another way**, select **Use Amazon Bedrock**.

72 

73![Desktop sign-in screen showing the Use Amazon Bedrock option.](https://developers.openai.com/images/codex/amazon-bedrock/desktop-provider-selection.webp)

74 

752. On **Set up Amazon Bedrock**, open **Choose sign-in method**. Choose **AWS profile**, **AWS access keys**, or **Bedrock API key**. For an AWS profile, enter the profile name and AWS Region, then select **Continue**.

76 

77![Amazon Bedrock setup with AWS profile selected and fields for the profile name and AWS Region.](https://developers.openai.com/images/codex/amazon-bedrock/desktop-credential-options.webp)

78 

793. Open a new task and [verify setup](#verify-setup). If your organization supplies a configuration file, follow the [manual configuration steps](#configure-bedrock-manually).

80 

81

82 

83</Tabs>

84 

85### Configure Bedrock manually

86 

87The ChatGPT desktop app, Codex CLI, IDE extension, and SDK read the same local configuration layers. To configure the provider manually or change endpoints, edit `~/.codex/config.toml`.

42 88 

43Choose the provider for the Amazon Bedrock endpoint you want to use: Bedrock89Choose the provider for the Amazon Bedrock endpoint you want to use: Bedrock

44Runtime for cross-Region inference (CRIS), or Bedrock Mantle for in-Region inference.90Runtime for cross-Region inference (CRIS), or Bedrock Mantle for in-Region inference.

57 [Bedrock Mantle](#use-mantle-for-hosted-web-search). The `amazon-bedrock`103 [Bedrock Mantle](#use-mantle-for-hosted-web-search). The `amazon-bedrock`

58 provider selects Mantle; `amazon-bedrock-runtime` selects Runtime.104 provider selects Mantle; `amazon-bedrock-runtime` selects Runtime.

59 105 

60### Use Mantle for hosted web search106<a id="authentication-options"></a>

61 

62For the Bedrock Mantle endpoint:

63 

64```toml

65model_provider = "amazon-bedrock"

66web_search = "cached"

67```

68 

69### Choose a model

70 

71Codex uses the configured `model_provider` to choose which models appear in the

72model picker: models supported through the Bedrock Runtime endpoint for

73`amazon-bedrock-runtime`, or through the Bedrock Mantle endpoint for

74`amazon-bedrock`.

75 

76You can optionally specify a [supported model](#supported-models) in the

77configuration file. The built-in provider supplies its own model catalog.

78When switching endpoints, change the provider and any explicit model ID together.

79 107 

80Model availability varies by AWS Region. Refer to AWS [Regional availability by models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-region-compatibility.html#model-regions-openai).108<a id="authenticate-to-amazon-bedrock"></a>

81 109 

82## Authentication options110#### Configure AWS credentials

83 111 

84Local ChatGPT Work and Codex surfaces support two Bedrock authentication paths.112Local ChatGPT Work and Codex surfaces support two Bedrock authentication paths.

85They check them in this order:113They check them in this order:

871. Bedrock API key.1151. Bedrock API key.

882. AWS SDK credential chain.1162. AWS SDK credential chain.

89 117 

90### Option 1: Bedrock API key118<a id="option-1-bedrock-api-key"></a>

119 

120##### Bedrock API key

91 121 

92Set the Bedrock API key in the environment the local client reads. You must122Set the Bedrock API key in the environment the local client reads. You must

93specify a Region when using API-key authentication.123specify a Region when using API-key authentication.

94 124 

95```shell125```shell

96export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>126export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"

97export AWS_REGION=us-east-2127export AWS_REGION=us-east-2

98```128```

99 129 

104$env:AWS_REGION = "us-east-2"134$env:AWS_REGION = "us-east-2"

105```135```

106 136 

107### Option 2: AWS SDK credentials137<a id="option-2-aws-sdk-credentials"></a>

108 

109Use this path when your organization manages Bedrock access through the AWS SDK

110credential chain. The local client can use these standard AWS SDK credential

111sources:

112 138 

113#### Shared AWS configuration files139##### Shared AWS configuration files

114 140 

115Configure the shared AWS `config` and `credentials` files:141Configure the shared AWS `config` and `credentials` files:

116 142 

118aws configure144aws configure

119```145```

120 146 

121#### Environment variables147<a id="environment-variables"></a>

148 

149##### AWS access keys

150 

151Set your AWS access keys as environment variables:

152 

153```shell

154export AWS_ACCESS_KEY_ID="<your-access-key-id>"

155export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"

156```

122 157 

123Set the standard AWS SDK credential environment variables:158For temporary credentials, also set the session token:

124 159 

125```shell160```shell

126export AWS_ACCESS_KEY_ID=<your-access-key-id>161export AWS_SESSION_TOKEN="<your-session-token>"

127export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>

128export AWS_SESSION_TOKEN=<your-session-token>

129```162```

130 163 

131#### AWS Management Console credentials164##### AWS Management Console credentials

132 165 

133Log in with AWS Management Console credentials:166Log in with AWS Management Console credentials:

134 167 

136aws login169aws login

137```170```

138 171 

139#### AWS SSO or a named profile172##### AWS SSO or a named profile

140 173 

141Log in with AWS SSO and select the named profile:174Log in with AWS SSO and select the named profile:

142 175 

145export AWS_PROFILE=codex-bedrock178export AWS_PROFILE=codex-bedrock

146```179```

147 180 

148#### Federated identity181##### Federated identity

149 182 

150For corporate SSO or OIDC federation, configure a federated identity with183For corporate SSO or OIDC federation, configure a federated identity with

151`credential_process` outside the local client and let the AWS SDK resolve184`credential_process` outside the local client and let the AWS SDK resolve

152credentials. Put browser login, token exchange, caching, and refresh in your185credentials. Put browser login, token exchange, caching, and refresh in your

153AWS profile's `credential_process` helper.186AWS profile's `credential_process` helper.

154 187 

155## Desktop app and IDE extension188#### Desktop app and IDE extension

156 189 

157Desktop apps and IDE extensions may not inherit environment variables from the190Desktop apps and IDE extensions may not inherit environment variables from the

158shell. Put required values in `~/.codex/.env`, then restart the app or191shell. Put required values in `~/.codex/.env`, then restart the app or

159extension. On Windows, the default path is `%USERPROFILE%\.codex\.env`.192extension. On Windows, the default path is `%USERPROFILE%\.codex\.env`.

160 193 

161```shell194```shell

162export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>195export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"

163export AWS_REGION=us-east-2196export AWS_REGION=us-east-2

164```197```

165 198 

166## Verify setup199### Choose a model

200 

201Codex uses the configured `model_provider` to choose which models appear in the

202model picker: models supported through the Bedrock Runtime endpoint for

203`amazon-bedrock-runtime`, or through the Bedrock Mantle endpoint for

204`amazon-bedrock`.

205 

206You can optionally specify a [supported model](#supported-models) in the

207configuration file. The built-in provider supplies its own model catalog.

208When switching endpoints, change the provider and any explicit model ID together.

209 

210Model availability varies by AWS Region. Refer to AWS [Regional availability by models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-region-compatibility.html#model-regions-openai).

211 

212<a id="verify-setup"></a>

213 

214### Verify your connection

167 215 

168- In Codex CLI, open `/status` and confirm the model provider matches your216- In Codex CLI, open `/status` and confirm the model provider matches your

169 endpoint: `amazon-bedrock` for Mantle in-Region inference, or217 endpoint: `amazon-bedrock` for Mantle in-Region inference, or

446 bedrock: "available",494 bedrock: "available",

447 },495 },

448 },496 },

449 {

450 name: "Scheduled tasks",

451 href: "/codex/automations",

452 availability: {

453 bedrock: "available",

454 },

455 },

456 {497 {

457 name: "Worktrees and built-in Git tools",498 name: "Worktrees and built-in Git tools",

458 shortName: "Built-in Git tools",499 shortName: "Built-in Git tools",

766 807 

767</ToggleSection>808</ToggleSection>

768 809 

810### Use Mantle for hosted web search

811 

812For the Bedrock Mantle endpoint:

813 

814```toml

815model_provider = "amazon-bedrock"

816web_search = "cached"

817```

818 

769## Troubleshooting819## Troubleshooting

770 820 

771If setup fails, check the following:821If setup fails, check the following:

303| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |303| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

304| `mode` | Use `"advanced"` to open advanced controls for an element, or `"default"` to use the default editor behavior. Defaults to `"default"`. Custom controls can still open with `"default"`; see [Editor defaults](#choose-the-editors-default-mode). Text ranges support only `"default"`. |304| `mode` | Use `"advanced"` to open advanced controls for an element, or `"default"` to use the default editor behavior. Defaults to `"default"`. Custom controls can still open with `"default"`; see [Editor defaults](#choose-the-editors-default-mode). Text ranges support only `"default"`. |

305| `enterAnnotationMode` | Set to `true` to enter Annotation mode and remain in it after canceling or sending the annotation. |305| `enterAnnotationMode` | Set to `true` to enter Annotation mode and remain in it after canceling or sending the annotation. |

306| `omitScreenshot` | Set to `true` to omit the automatic screenshot for this annotation. Defaults to `false`, which preserves normal screenshot behavior. Applies to element and text-range requests. |

306| `metadata` | Valid, nonempty metadata replaces the target's HTML metadata for this request. This option is ignored for text ranges and when the target element is inside a shadow DOM. |307| `metadata` | Valid, nonempty metadata replaces the target's HTML metadata for this request. This option is ignored for text ranges and when the target element is inside a shadow DOM. |

307| `initialComment` | Supplies an editable comment, up to 240 UTF-16 code units. |308| `initialComment` | Supplies an editable comment, up to 240 UTF-16 code units. |

308 309 

169 });169 });

170 }170 }

171 if (msg.method === "turn/completed") {171 if (msg.method === "turn/completed") {

172 if (msg.params?.turn?.status !== "completed") {

173 console.error(msg.params?.turn?.error ?? "The turn did not complete.");

174 process.exitCode = 1;

175 }

172 proc.stdin.end();176 proc.stdin.end();

173 rl.close();177 rl.close();

174 }178 }

206 process.exitCode = 1;210 process.exitCode = 1;

207 rl.close();211 rl.close();

208});212});

213proc.on("exit", (code) => {

214 if (code !== 0) process.exitCode = code ?? 1;

215});

209```216```

210 217 

211 218 

62// resuming past thread62// resuming past thread

63 63 

64const threadId = thread.id!;64const threadId = thread.id!;

65const thread2 = codex.resumeThread(threadId);65const thread2 = codex.resumeThread(threadId, {

66 sandboxMode: "workspace-write",

67});

66const result2 = await thread2.run("Pick up where you left off");68const result2 = await thread2.run("Pick up where you left off");

67 69 

68console.log(result2.finalResponse);70console.log(result2.finalResponse);

134 href: "/codex/app-server",134 href: "/codex/app-server",

135 icon: "storage",135 icon: "storage",

136 },136 },

137 {

138 title: "Model catalogs",

139 description:

140 "Serve current model defaults through a cloud or gateway integration.",

141 href: "/codex/model-catalogs",

142 icon: "settings",

143 },

144 {137 {

145 title: "GitHub Action",138 title: "GitHub Action",

146 description: "Run Codex from GitHub Actions workflows.",139 description: "Run Codex from GitHub Actions workflows.",

23 23 

24<a id="access-to-dots"></a>24<a id="access-to-dots"></a>

25 25 

26**Dots are rolling out gradually to eligible accounts.** See [availability and access](#access) for plan, region, and workspace requirements.26See [availability and access](#access) for plan, region, and workspace requirements.

27 27 

28<a id="meet-your-o"></a>28<a id="meet-your-o"></a>

29 29 

262 262 

263**For workspace admins:** See [Set up dots for work](https://learn.chatgpt.com/docs/enterprise/dots-admin-guide) for workspace setup, permissions, and security and governance guidance.263**For workspace admins:** See [Set up dots for work](https://learn.chatgpt.com/docs/enterprise/dots-admin-guide) for workspace setup, permissions, and security and governance guidance.

264 264 

265Dots are rolling out gradually. You may not see dots immediately, even if your plan is eligible.265Access depends on your plan, region, and workspace settings. Dots are rolling out gradually to eligible Pro and Business Premium accounts.

266 266 

267- **Pro 100, Pro 200, and Pro 500:** For users over 18 outside the European Economic Area, United Kingdom, and Switzerland.267- **Pro 100, Pro 200, and Pro 500:** For users aged 18 and older outside the European Economic Area, United Kingdom, and Switzerland.

268- **Business Premium:** Rolling out worldwide.268- **Business Premium:** Available in supported ChatGPT regions, subject to workspace eligibility.

269- **Enterprise:** Rolling out worldwide. Dots are off by default and must be enabled by a workspace administrator.269- **Enterprise, Edu, and Healthcare:** Generally available in eligible workspaces. Workspaces with UAE data or inference residency are ineligible. During the admin preview, your admin can enable access for your role. Starting November 18, 2026, access is on by default unless your workspace opts out.

270 270 

271Conversations with your dot don’t count toward your ChatGPT usage limits. Tasks your dot starts or manages in Work or Codex count toward those products’ usage limits as usual. Your plan includes an allowance for deeper work, with extended limits for the first month after launch.271For Pro and Business Premium, conversations with your dot don’t count toward your ChatGPT usage limits. Tasks your dot starts or manages in Work or Codex count toward those products’ usage limits as usual. Your plan includes an allowance for deeper work, with extended limits for the first month after launch. For Enterprise pricing and delegated task charges, see [Enterprise preview and billing](https://learn.chatgpt.com/docs/enterprise/dots-admin-guide#enterprise-preview-and-billing).

272 272 

273You can create your dot in the ChatGPT mobile app, desktop app, or a desktop browser. Use the latest version of the mobile app for mobile setup. Mobile web is not supported.273You can create your dot in the ChatGPT mobile app, desktop app, or a desktop browser. Use the latest version of the mobile app for mobile setup. Mobile web is not supported.

274 274 

36 36 

37 37 

38 38 

39## Reply and share on iOS

40 

41To reply from a notification, touch and hold the notification from your dot, type your reply, and tap **Send**.

42 

43To share a photo with your dot, open the photo, tap **Share**, and choose your dot. Review the photo in the composer, add a message if you want, and tap **Send**. You can also share content from other apps that use the iOS share sheet.

44 

39## iOS widgets and shortcuts45## iOS widgets and shortcuts

40 46 

41Open your dot from your iPhone Home Screen, or use Apple Shortcuts to choose how to start a conversation. Use the latest ChatGPT iOS app and sign in to the account where you set up your dot. These features are rolling out with ChatGPT for iOS 1.2026.279 and require [dot access](https://learn.chatgpt.com/docs/dots#access).47Open your dot from your iPhone Home Screen, or use Apple Shortcuts to choose how to start a conversation. Use the latest ChatGPT iOS app and sign in to the account where you set up your dot. These features are rolling out with ChatGPT for iOS 1.2026.279 and require [dot access](https://learn.chatgpt.com/docs/dots#access).

24browser sessions. Signing in to a website on your computer doesn't sign your24browser sessions. Signing in to a website on your computer doesn't sign your

25dot in to that website.25dot in to that website.

26 26 

27## Annotate a browser page or file

28 

29Browser and file annotations are rolling out in the ChatGPT desktop app for Pro, Business Premium, and Enterprise. Use an annotation to show your dot which part of a page or file you want it to work on.

30 

31For a browser page, use the annotation tool in the in-app browser toolbar. Select the part of the page you want to discuss, add a comment, and send it to your dot.

32 

33For a file, open a PDF, document, presentation, or spreadsheet in your own dot. Select the part you want to discuss, add a comment, and select **Send** in the file viewer.

34 

27## Cloud threads35## Cloud threads

28 36 

29Your dot can start separate threads for cloud work. These appear in your desktop, web, and mobile apps, where you can review results and give further instructions while your dot continues coordinating. For coding work, it can use a Codex cloud environment you’ve set up with the repository and configuration it needs.37Your dot can start separate threads for cloud work. These appear in your desktop, web, and mobile apps, where you can review results and give further instructions while your dot continues coordinating. For coding work, it can use a Codex cloud environment you’ve set up with the repository and configuration it needs.

93 101 

94Your dot can use supported [plugins](https://learn.chatgpt.com/docs/plugins) installed and enabled for your account. Access depends on the plugin’s connected account, permissions, and the environment where the work runs. Local skills require a connected computer.102Your dot can use supported [plugins](https://learn.chatgpt.com/docs/plugins) installed and enabled for your account. Access depends on the plugin’s connected account, permissions, and the environment where the work runs. Local skills require a connected computer.

95 103 

96For example, connect Gmail to find relevant email, Google Drive to read and update documents, or GitHub to investigate an issue and prepare a pull request. Install and connect each plugin you want your dot to use.104For example, connect Gmail to find relevant email, Google Drive to read and update documents, or GitHub to investigate an issue and prepare a pull request. Install and connect each plugin you want your dot to use. On iOS, supported Gmail message links from your dot open the referenced email in the Gmail app when available, or in your browser.

97 105 

98Review106Review

99the connected account and its allowed actions. Your existing ChatGPT app107the connected account and its allowed actions. Your existing ChatGPT app

12 12 

13## Check for an existing configuration13## Check for an existing configuration

14 14 

15Before adding anything, check whether your administrator already configured Codex.15Install the Codex client and version your administrator tested. If your organization manages the settings, open that client and complete the sign-in steps in your handoff. You can skip the provider configuration examples below.

16 16 

17- For the CLI, inspect the selected profile and run `codex doctor`. After startup,17- For the CLI, inspect the selected profile and run `codex doctor`. After startup,

18 use `/status` to confirm the active model and provider.18 use `/status` to confirm the active model and provider.

21- For the Windows app, inspect `%USERPROFILE%\.codex\config.toml` or the system21- For the Windows app, inspect `%USERPROFILE%\.codex\config.toml` or the system

22 configuration your organization delivers.22 configuration your organization delivers.

23 23 

24If the expected gateway provider and model are already active, continue to24If the expected gateway provider and model are already active, complete any sign-in steps supplied by your administrator, then continue to [Verify the connection](#verify-the-connection). Avoid adding a second provider configuration to a managed machine. If the settings differ from your administrator's handoff, ask which configuration layer should supply them before editing local files.

25[Verify the connection](#verify-the-connection).

26 25 

27## Get your gateway connection details26## Get your gateway connection details

28 27 

29Install the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) or the desktop app approved by your28For manual setup, confirm whether you need ChatGPT workspace sign-in, gateway authentication, or both.

30organization. To configure Codex yourself, get these values from your gateway team:29 

30To configure Codex yourself, get these values from your gateway team:

31 31 

32- The HTTPS gateway base URL, including its API path, such as `https://gateway.example.com/v1`.32- The HTTPS gateway base URL, including its API path, such as `https://gateway.example.com/v1`.

33- The model name and provider ID to use.33- The model name and provider ID to use.

34- The authentication method: [native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=oauth#use-native-gateway-oauth),34- The authentication method: [native gateway OAuth](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=oauth#use-native-gateway-oauth),

35 a scoped API key and its environment variable, or an installed credential helper.35 a scoped API key and its environment variable, or an installed credential helper.

36- For OAuth, the authorization URL, token URL, public client ID, required scopes,36- For OAuth, the authorization URL, token URL, public client ID, and any required scopes. For gateways that use a cookie or custom header, its name.

37 and the cookie or custom header the gateway accepts.

38- Any required model catalog URL, or a catalog file and its absolute local path.37- Any required model catalog URL, or a catalog file and its absolute local path.

39 38 

40<a id="without-chatgpt-sign-in"></a>39<a id="without-chatgpt-sign-in"></a>

69Then add the [authentication settings](#choose-an-authentication-method) your68Then add the [authentication settings](#choose-an-authentication-method) your

70gateway team supplies.69gateway team supplies.

71 70 

71`enterprise-gateway` is an illustrative provider ID. Use the same ID in

72`model_provider` and its provider and authentication tables.

73This example disables web search

74for the initial connection test; your administrator should verify feature support

75before enabling it.

76 

77## Configure your model catalog

78 

79Confirm with your gateway team how Codex gets the capabilities and instructions for your selected model:

80 

81- **Built-in name:** If the gateway accepts the exact model name bundled with your Codex version and routes it to the matching model, set `model` to that name. Codex already has its metadata.

82- **Catalog endpoint:** If the gateway serves Codex-compatible metadata, use its full catalog URL. This can be a `/v1/models` endpoint that implements the [Codex catalog response](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#implement-the-catalog-endpoint). A response that only lists model IDs is insufficient for custom aliases.

83- **Catalog file:** If your gateway uses custom aliases and your administrator distributes a file, use the [local models.json example](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#start-with-a-local-modelsjson-file). Use a local file when native gateway OAuth is your only credential and you need custom metadata.

84 

72For API-key or helper authentication, if your administrator supplies a catalog85For API-key or helper authentication, if your administrator supplies a catalog

73URL, add it to the existing86URL, add it to the existing

74`[model_providers.enterprise-gateway]` table:87`[model_providers.enterprise-gateway]` table:

92Use the model name and catalog supplied together by your administrator. Don't105Use the model name and catalog supplied together by your administrator. Don't

93add a catalog path unless the file exists at that location.106add a catalog path unless the file exists at that location.

94 107 

95`enterprise-gateway` is an illustrative provider ID. Use the same ID in

96`model_provider` and its provider and authentication tables.

97This example disables web search

98for the initial connection test; your administrator should verify feature support

99before enabling it.

100 

101## Choose an authentication method108## Choose an authentication method

102 109 

103Use native gateway OAuth for browser sign-in, an API key for a scoped credential, or a credential helper if your organization supplies a command.110Use native gateway OAuth for browser sign-in, an API key for a scoped credential, or a credential helper if your organization supplies a command.

126browser sign-in, encrypted credential storage, and token refresh when the133browser sign-in, encrypted credential storage, and token refresh when the

127authorization server issues a refresh token.134authorization server issues a refresh token.

128 135 

136For gateway-only authentication, Codex CLI 0.166.0 and later sends the access token in `Authorization: Bearer <gateway access token>` by default. Remove any `Authorization` entry from this provider's `http_headers` or `env_http_headers`.

137 

129Your gateway team must register a public OAuth client that supports the138Your gateway team must register a public OAuth client that supports the

130authorization code flow with PKCE. Add this table to the provider configuration139authorization code flow with PKCE. Add this table to the provider configuration

131in `config.toml`, replacing the URLs, client ID, and cookie name with their values:140in `config.toml`, replacing the URLs and client ID with their values:

132 141 

133```toml142```toml

134[model_providers.enterprise-gateway.gateway_oauth]143[model_providers.enterprise-gateway.gateway_oauth]

135authorization_url = "https://login.example.com/oauth/authorize"144authorization_url = "https://login.example.com/oauth/authorize"

136token_url = "https://login.example.com/oauth/token"145token_url = "https://login.example.com/oauth/token"

137client_id = "YOUR_PUBLIC_CLIENT_ID"146client_id = "YOUR_PUBLIC_CLIENT_ID"

138delivery = { kind = "cookie", name = "auth-openid" }

139# redirect_port = 43127147# redirect_port = 43127

140```148```

141 149 

145If your identity provider requires a fixed redirect URI, set `redirect_port` and153If your identity provider requires a fixed redirect URI, set `redirect_port` and

146register `http://127.0.0.1:43127/callback` for this example.154register `http://127.0.0.1:43127/callback` for this example.

147 155 

148The gateway must validate the OAuth access token received in the configured156If your gateway expects a cookie or custom header, set the optional `delivery` field in the OAuth table. Choose the method your gateway validates:

149cookie. If it accepts a custom header instead, replace `delivery` with the header157 

150your administrator provides, for example:158```toml

159delivery = { kind = "cookie", name = "auth-openid" }

160```

151 161 

152```toml162```toml

153delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }163delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

154```164```

155 165 

156Codex reserves `Authorization`; you can't use it as the `gateway_oauth` delivery header.166If your deployment also requires ChatGPT sign-in, use the cookie or a separate

167gateway header shown above. See [Enable ChatGPT sign-in](#enable-chatgpt-sign-in-recommended).

168 

157A gateway that accepts only a static API key must add support for the OAuth token169A gateway that accepts only a static API key must add support for the OAuth token

158and its delivery method before you can use this flow. The gateway continues to170and its delivery method before you can use this flow. The gateway continues to

159manage its own upstream credentials, such as its AWS credentials for Bedrock.171manage its own upstream credentials, such as its AWS credentials for Bedrock.

160 172 

161When OAuth is your only credential, keep `requires_openai_auth = false` and remove the173When OAuth is your only credential, keep `requires_openai_auth = false` and remove the

162previous `env_key`, `experimental_bearer_token`, or `auth` settings used for the174previous `env_key`, `experimental_bearer_token`, or `auth` settings used for the

163gateway credential. Use a local `model_catalog_json` file if you need custom model175gateway credential. Use a [local model catalog](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#start-with-a-local-modelsjson-file) if you need custom model

164metadata; OAuth alone doesn't enable remote catalog discovery.176metadata; OAuth alone doesn't enable remote catalog discovery.

165 177 

166Restart the desktop app and follow its gateway sign-in prompt to open the browser.178Restart the desktop app and follow its gateway sign-in prompt to open the browser.

203delivery mechanism. Don't put the credential in TOML or a repository. A variable215delivery mechanism. Don't put the credential in TOML or a repository. A variable

204set in a terminal may not be available to an app launched from the desktop.216set in a terminal may not be available to an app launched from the desktop.

205 217 

206<a id="option-a-reuse-your-credential-command-with-a-helper"></a>

207 

208### Use a custom authentication header218### Use a custom authentication header

209 219 

210If your gateway requires a header such as `X-API-Key` instead of a bearer token,220If your gateway requires a header such as `X-API-Key` instead of a bearer token,

250contract. Ask your administrator how to renew your sign-in if the helper can no260contract. Ask your administrator how to renew your sign-in if the helper can no

251longer retrieve a token.261longer retrieve a token.

252 262 

263<a id="option-a-reuse-your-credential-command-with-a-helper"></a>

264 

253With ChatGPT sign-in, run the helper before launching Codex and pass its output through a [custom gateway header](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=api-key#use-a-custom-authentication-header) instead of configuring the `auth` table. When the key expires, get a new key and relaunch Codex.265With ChatGPT sign-in, run the helper before launching Codex and pass its output through a [custom gateway header](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?gateway-auth=api-key#use-a-custom-authentication-header) instead of configuring the `auth` table. When the key expires, get a new key and relaunch Codex.

254 266 

255Use resolved absolute paths for helper executables and catalog files.267Use resolved absolute paths for helper executables and catalog files.

268 280 

269If 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](https://learn.chatgpt.com/docs/pricing#feature-availability).281If 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](https://learn.chatgpt.com/docs/pricing#feature-availability).

270 282 

271Add the gateway provider to your workspace's [managed `requirements.toml`](https://learn.chatgpt.com/docs/enterprise/managed-configuration). These settings apply when users sign in to that workspace.283For manual setup, update the existing `[model_providers.enterprise-gateway]` table before signing in:

272 284 

273```toml2851. Set `requires_openai_auth = true` and keep `base_url` pointing to your gateway. Remove any `env_key`, `experimental_bearer_token`, and provider `auth` settings so Codex uses your OpenAI credential for primary authentication.

274# requirements.toml2862. Send the gateway credential separately. For [native gateway OAuth](#use-native-gateway-oauth), configure `gateway_oauth.delivery` to use the cookie or custom header your gateway accepts. For an API key or credential helper, use a [custom authentication header](#use-a-custom-authentication-header). Reserve `Authorization` for the OpenAI credential.

275model_provider = "enterprise-gateway"

276 287 

277[model_providers.enterprise-gateway]288Sign in to the ChatGPT workspace your administrator named. Complete the gateway sign-in if prompted, then [verify your connection](#verify-the-connection).

278name = "Enterprise gateway"

279base_url = "https://gateway.example.com/backend-api/codex"

280requires_openai_auth = true

281```

282 289 

283Configure [gateway authentication](#choose-an-authentication-method) 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.290Administrators can [distribute managed provider settings](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#distribute-the-configuration) and [verify credential forwarding](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#test-codex-through-the-gateway).

284 291 

285<a id="keep-the-credentials-on-their-own-paths"></a>292<a id="keep-the-credentials-on-their-own-paths"></a>

286 293 

338 345 

339### Add routing headers (optional)346### Add routing headers (optional)

340 347 

341To route requests by configuration or tool, add headers to the same `enterprise-gateway` provider in your cloud-managed `requirements.toml`:348Use the routing settings supplied by your administrator. Gateway operators can [distribute these settings](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#distribute-the-configuration) and check the selected route in gateway logs.

342 

343```toml

344[model_providers.enterprise-gateway.http_headers]

345x-portkey-config = "<gateway-routing-config-id>"

346x-portkey-metadata = '{"tool_id":"codex"}'

347```

348 

349Use `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](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers) for more header options.

350 349 

351<a id="caveats-and-limitations"></a>350<a id="caveats-and-limitations"></a>

352<a id="voice-through-a-gateway"></a>351<a id="voice-through-a-gateway"></a>

395 394 

396## Verify the connection395## Verify the connection

397 396 

397Use the provider ID and model alias in your administrator's handoff. The provider identifies the configured connection; the model alias identifies a model routed through that connection. ChatGPT sign-in and gateway authentication control access and may both be required.

398 

398Restart the client after changing the configuration. In the CLI, start `codex`399Restart the client after changing the configuration. In the CLI, start `codex`

399and use `/status` to inspect the active model and provider. In the desktop app,400and use `/status` to inspect the active model and provider. In the desktop app,

400check the selected model and configuration.401check the selected model and configuration.

409your administrator to confirm that the gateway recorded your user, model alias,410your administrator to confirm that the gateway recorded your user, model alias,

410and intended upstream route. Don't identify the model by asking it its name.411and intended upstream route. Don't identify the model by asking it its name.

411 412 

412If 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.

413 

414This verifies an initial connection. Administrators should also complete the

415[rollout checks](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#test-the-client-and-gateway)

416for streaming, tools, and follow-up turns.

417 

418## Troubleshoot the connection413## Troubleshoot the connection

419 414 

420| Symptom | What to check |415| Symptom | What to check |

427| Streaming stalls or follow-ups fail. | Ask the gateway owner to check proxy buffering, the terminal `response.completed` event, and [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |422| Streaming stalls or follow-ups fail. | Ask the gateway owner to check proxy buffering, the terminal `response.completed` event, and [Gateway compatibility](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility). |

428| A catalog or helper path fails. | Confirm that the file exists at the configured absolute path in the environment running Codex. |423| A catalog or helper path fails. | Confirm that the file exists at the configured absolute path in the environment running Codex. |

429 424 

430When requesting help, include the error message with tokens and sensitive prompts removed.425When requesting help, include your client version, operating system, expected provider and model alias, authentication method, and the step that failed. Include the error message and request time so the gateway owner can locate the request. Remove tokens, cookies, authorization headers, and sensitive prompts. Don't send credential files or a configuration dump containing secrets.

431 426 

432## Use an existing gateway deployment427## Use an existing gateway deployment

433 428 

434If your organization already uses a gateway with another coding tool, you may be429Ask your gateway team for the Codex provider settings and approved model alias. If the team still needs to enable a Codex route, share the [administrator migration checklist](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#reuse-an-existing-gateway-deployment).

435able to reuse its network path, logging, and provider access. Work with your

436gateway team to configure and test a Codex connection:

437 

4381. Identify the existing gateway URL, credential mechanism, required headers,

439 model routes, and configuration delivery method.

4402. Ask your gateway team to confirm that the gateway supports the

441 [API behavior Codex requires](https://learn.chatgpt.com/docs/enterprise/gateway-compatibility) and to

442 configure a Codex model route.

4433. Obtain the OAuth settings, scoped gateway credential, or credential helper,

444 along with the model name and any required catalog from your gateway team.

4454. [Configure Codex](#configure-the-provider) with those values.

4465. [Verify the connection](#verify-the-connection) in the CLI or desktop app you

447 plan to use. Have your gateway team complete the

448 [streaming, tool, and follow-up checks](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#test-the-client-and-gateway).

4496. After the pilot passes, follow

450 [Roll out a gateway](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway) to distribute the

451 configuration to other developers.

452 

453For the administrator migration checklist and configuration mapping, see

454[Reuse an existing gateway deployment](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#reuse-an-existing-gateway-deployment).

455 430 

456## Related docs431## Related docs

457 432 

33| Track adoption or investigate an action | [Monitor usage](#monitor-usage) and [Review admin activity and compliance records](#review-admin-activity-and-compliance-records) |33| Track adoption or investigate an action | [Monitor usage](#monitor-usage) and [Review admin activity and compliance records](#review-admin-activity-and-compliance-records) |

34| Remove access when someone changes roles or leaves | [Manage access changes](#manage-access-changes) |34| Remove access when someone changes roles or leaves | [Manage access changes](#manage-access-changes) |

35 35 

36## Enterprise preview and billing

37 

38During the preview, admins in eligible ChatGPT Enterprise, Edu, and Healthcare workspaces can enable dots for selected roles. Starting November 18, 2026, members have access by default unless the workspace opts out. Each member chooses whether to create a personal dot.

39 

40Eligible Enterprise workspaces can pay a flat rate based on the type of work a dot does or pay based on consumption. The preview is free. Billing for enabled dots begins November 18, 2026. Tasks a dot delegates to ChatGPT Work or Codex threads incur separate charges at the standard rates. See [Dots pricing in the Help Center](https://help.openai.com/en/articles/20001530-getting-started-with-your-dot).

41 

36 42 

37 43 

38 44 

2 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.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 4 

5Roll out native gateway OAuth, API keys, or credential helpers without ChatGPT5As the gateway administrator, configure the model routes and authorize a pilot user. Test the connection on each client you support before distributing settings to developers. Use native gateway OAuth, API keys, or credential helpers for gateway

6sign-in. Configure model routes, authorize users, and distribute a verified Codex6authentication. To combine gateway authentication with ChatGPT workspace sign-in, see

7configuration. For a gateway that forwards ChatGPT workspace requests, see

8[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#enable-chatgpt-sign-in-recommended).7[Sign in with ChatGPT through a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#enable-chatgpt-sign-in-recommended).

9 8 

10To configure Codex on your own machine with values you were given, see9To configure Codex on your own machine with values you were given, see

66 65 

67### Use a model catalog for custom names66### Use a model catalog for custom names

68 67 

68For a local catalog, start with the [models.json example](#start-with-a-local-modelsjson-file).

69 

69Supply 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.70Supply 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.

70 71 

71Host 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](https://learn.chatgpt.com/docs/config-file/config-reference) for both settings.72Host 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](https://learn.chatgpt.com/docs/config-file/config-reference) for both settings.

73Get a catalog endpoint or file compatible with your Codex version from your cloud74Get a catalog endpoint or file compatible with your Codex version from your cloud

74or gateway provider. Make sure it includes each approved alias and its model75or gateway provider. Make sure it includes each approved alias and its model

75metadata. For catalog implementation, see76metadata. For catalog implementation, see

76[Implementing model catalogs for gateways and clouds](https://learn.chatgpt.com/docs/model-catalogs).77[Implementing model catalogs for gateways and clouds](#model-catalog-reference).

77 78 

78#### Serve a remote catalog79#### Serve a remote catalog

79 80 

173 174 

174Before distributing anything, follow [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure one isolated test user with the provider block and authentication method you plan to distribute.175Before distributing anything, follow [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure one isolated test user with the provider block and authentication method you plan to distribute.

175 176 

176Run the checks below from the same CLI or desktop surface developers will use:177If the gateway serves the model catalog, confirm it returns a Codex-compatible `models` array. For OpenAI inference using the user's credential, confirm the gateway forwards the required ChatGPT headers to the Codex backend.

178 

179Record the client version, operating system, provider ID, model alias, and authentication method for your pilot. Run the checks below from each CLI or desktop surface you plan to support. If you offer both gateway-only authentication and gateway authentication alongside ChatGPT sign-in, test each combination separately.

177 180 

178| Check | Action | Passing evidence |181| Check | Action | Passing evidence |

179| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |182| ----------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

183| Effective configuration | Inspect the configuration layers and confirm the intended provider, model, and requirements. | The pilot uses the distributed settings. User or profile defaults do not select a different route. |

180| 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. |184| 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. |

181| 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`. |185| Streaming | Ask for a short multi-paragraph answer. | Text arrives incrementally and the active transport emits `response.completed`. Test HTTP separately to verify that the gateway forwards SSE events without buffering. |

182| 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. |186| 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. |

183| 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`. |187| 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`. |

184| 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. |188| 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. |

185 189 

186After these checks succeed, direct developers to [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure and verify their own machine.190If automatic approval is enabled, use a disposable test folder to trigger a tool action that requires review under your intended policy. Confirm that the gateway handles the review request and that the client applies the approval decision. A read-only tool call that needs no approval does not test this path. Record any unsupported workflow before expanding the pilot.

191 

192If the rollout changes the provider for existing users, test a new conversation and a conversation created before the change on each supported client. Record whether users can view, continue, or branch the existing conversation, and give them a recovery procedure for any blocked workflow. Don't assume that changing the default provider migrates conversation history.

193 

194After these checks succeed, prepare the [developer handoff](#hand-developers-the-configuration-values).

187 195 

188## Distribute the configuration196## Distribute the configuration

189 197 

269A CLI inside WSL reads Linux paths and Linux `CODEX_HOME`; it doesn't automatically277A CLI inside WSL reads Linux paths and Linux `CODEX_HOME`; it doesn't automatically

270inherit native Windows configuration.278inherit native Windows configuration.

271 279 

280### Distribute routing headers

281 

282If your gateway routes requests by configuration or tool, add the headers it expects to the provider in your managed `requirements.toml`. The following example supplies a routing configuration ID and identifies Codex as the client:

283 

284```toml

285[model_providers.enterprise-gateway.http_headers]

286x-portkey-config = "<gateway-routing-config-id>"

287x-portkey-metadata = '{"tool_id":"codex"}'

288```

289 

290Use `env_http_headers` for header values supplied by the client environment. Send a test request and confirm the selected route in gateway logs. See [Custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers) for header options.

291 

272### Hand developers the configuration values292### Hand developers the configuration values

273 293 

274If 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](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) to configure and verify their own machine.294Give developers one setup path that matches the pilot you tested. Include the following information even when you distribute configuration centrally:

295 

296| Handoff item | What to provide |

297| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

298| Approved client | The client, version, operating system, and installation or update instructions used in the pilot. |

299| Configuration delivery | Whether settings are already managed or require local setup; identify any helper or catalog file installed separately. |

300| Expected connection | The provider ID, model alias, and gateway URL, including its API path. Explain which values users may change. |

301| Sign-in steps | Whether users must sign in to a ChatGPT workspace, authenticate to the gateway, or do both. Name the required workspace and gateway authentication method. |

302| Credentials and catalogs | The OAuth registration values, credential environment variable, or installed helper configuration, plus any catalog URL or resolved local path. Deliver secrets through your approved secret-distribution mechanism. |

303| Verification and support | The [connection test](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection), expected result, gateway owner, and information to include when reporting a failure. |

304 

305For managed machines, send developers to [Check for an existing configuration](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#check-for-an-existing-configuration). For manual setup, send them to [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider).

306 

307Include your tested instructions for existing conversations if this rollout changes the provider. Keep the previous working configuration available to the rollout owner in case the pilot exposes a problem.

275 308 

276Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.309Manual setup is not an enforcement channel. Project-local `.codex/config.toml` cannot override sensitive provider or authentication routing keys.

277 310 

281 314 

282To confirm that the distributed settings reached a developer machine:315To confirm that the distributed settings reached a developer machine:

283 316 

2841. Restart Codex and confirm the expected provider and model.3171. Confirm that the approved client and any required helper or catalog files are installed. Restart Codex and complete the sign-ins in your handoff.

2852. Run the short test in [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection).3182. Confirm the expected provider and model. In the CLI, use `/status`. Use [`/debug-config`](https://learn.chatgpt.com/docs/developer-commands?surface=cli#cli-inspect-config-layers-with-debug-config) to inspect configuration layers when the effective settings differ from the handoff.

2863. Ask one follow-up to confirm continuation, then check the gateway logs for that3193. Run the short test in [Connect to a gateway](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#verify-the-connection).

3204. Ask one follow-up to confirm continuation, then check the gateway logs for that

287 developer's request.321 developer's request.

288 322 

323Expand access after the pilot passes on the clients and authentication combinations you support. Keep the tested configuration and results with your rollout instructions so you can repeat the checks after client, gateway, or policy updates.

324 

289### Troubleshoot rollout failures325### Troubleshoot rollout failures

290 326 

291Use the issue to find the configuration, credential, or gateway layer that needs attention:327Use the issue to find the configuration, credential, or gateway layer that needs attention:

3211. Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.3571. Inventory the current Claude path: gateway URL, credential source, required headers, model aliases, Bedrock profile mappings, and managed delivery channel.

3222. Add a parallel Codex-facing Responses route and Codex model aliases.3582. Add a parallel Codex-facing Responses route and Codex model aliases.

3233. Choose [native gateway OAuth, an API key, or a credential helper](#choose-authentication) 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.3593. Choose [native gateway OAuth, an API key, or a credential helper](#choose-authentication) 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.

3244. 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 [Roll out a gateway](#distribute-the-configuration).3604. [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) for that developer using the authentication method you selected in step 3. For a managed rollout, translate the payload into the Codex paths and precedence described in [Roll out a gateway](#distribute-the-configuration).

3255. 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).3615. 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).

3266. After the pilot passes, [distribute the configuration](#distribute-the-configuration) to the remaining developers.3626. After the pilot passes, [distribute the configuration](#distribute-the-configuration) to the remaining developers.

327 363 

364## Model catalog reference

365 

366### Start with a local models.json file

367 

368First, [configure and select your gateway provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider) on the machine where you run Codex.

369 

370Save this catalog as `models.json` on the machine running Codex. Replace

371`gateway-model` with the exact model ID your gateway accepts. The display name

372is the label users see in the model picker.

373 

374```json

375{

376 "models": [

377 {

378 "slug": "gateway-model",

379 "display_name": "Gateway model",

380 "base_instructions": "Help the user with their coding tasks.",

381 "supported_reasoning_levels": [],

382 "shell_type": "shell_command",

383 "visibility": "list",

384 "supported_in_api": true,

385 "priority": 0,

386 "support_verbosity": false,

387 "truncation_policy": { "mode": "tokens", "limit": 10000 },

388 "experimental_supported_tools": []

389 }

390 ]

391}

392```

393 

394For a larger example, see [Codex's model catalog](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json).

395 

396Set `model_catalog_json` in `config.toml` to the absolute path of the file.

397Restart Codex, select **Gateway model**, and send a request. Check that the

398gateway received the model ID you set in `slug`.

399 

400For an alias of a bundled model, copy its full catalog entry for your Codex

401version and change its `slug` and `display_name`. If the alias has no migration target, set `upgrade` to `null`. This preserves the model's

402context window, reasoning options, and tool settings.

403 

404### Serve a catalog to clients

405 

406This page is for developers implementing the Codex Models format, which defines

407the model catalog and powers the model picker. If you build an inference

408provider, such as a gateway or cloud service, use this specification to let the

409Codex desktop app and CLI discover your models and use their instructions and

410capability settings.

411 

412If you administer an enterprise and want to control the model catalog, see the

413[`model_catalog_url` configuration guidance](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#serve-a-remote-catalog).

414 

415To support the format, implement an authenticated catalog endpoint. Fetch your

416upstream provider's current defaults for the requesting Codex version, apply

417your overrides, and return the resulting catalog.

418 

419 

420 

421> Illustration: Cloud providers fetch OpenAI model defaults for the requesting Codex version. Gateways read catalogs from their cloud or upstream providers, then apply caller filtering, aliases, and supported settings. Codex reads the gateway catalog to show available models and use compatible settings. Reads are authenticated at each step, and catalog responses return toward Codex. Optional enterprise or custom model definitions can feed the gateway and need not originate from OpenAI.

422 

423 

424 

425### Implement the catalog endpoint

426 

427The default catalog endpoint is `/models` under the provider's `base_url`.

428For example, with `base_url = "https://gateway.example.com/v1"`, Codex requests:

429 

430```http

431GET /v1/models?client_version=0.162.1

432Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

433```

434 

435Default discovery supports command-backed authentication and Codex-backend

436authentication, such as ChatGPT. For a custom provider using API-key authentication

437without command-backed authentication, set `model_providers.<id>.model_catalog_url`

438explicitly to enable remote discovery. An API key alone doesn't trigger discovery

439at the default path.

440 

441Use `model_catalog_url` to choose a full catalog URL, such as

442`https://gateway.example.com/codex/models`. It can also point to the default

443`/v1/models` endpoint. Codex uses this URL directly without appending `/models`.

444For API-key discovery, keep `features.api_key_model_discovery` enabled; it is on

445by default. Custom headers alone don't enable discovery.

446 

447Codex sends the selected provider's authentication and configured headers, and

448appends `client_version` and any provider `query_params`. Host the catalog on a

449service authorized to receive those credentials.

450 

451Authenticate the caller, fetch the corresponding upstream defaults, apply your

452overrides, and return the complete `ModelsResponse` JSON directly. Give every

453entry a unique, nonempty `slug`. For an explicit `model_catalog_url`, Codex rejects

454redirects and responses larger than 1 MiB. Continue enforcing model access on

455inference requests.

456 

457Remove any effective `model_catalog_json` setting from clients using the endpoint:

458the local file takes precedence and prevents remote fetching.

459 

460### Match the client's schema

461 

462Read the `client_version` query parameter on the catalog request. Codex sends its

463CLI version as `major.minor.patch`, with any prerelease suffix removed. For desktop

464clients, this is the bundled CLI version.

465 

466Use the matching `rust-v<version>` tag in the public Codex repository, or the

467exact source commit for a custom build. These links use `rust-v0.162.1`; select

468the revision matching your client:

469 

470- Read the [`ModelsResponse` and `ModelInfo` response types](https://github.com/openai/codex/blob/rust-v0.162.1/codex-rs/protocol/src/openai_models.rs) for the schema.

471- Inspect the [bundled `models.json`](https://github.com/openai/codex/blob/rust-v0.162.1/codex-rs/models-manager/models.json) for a complete example. This is catalog data, not a JSON Schema document.

472 

473The bundled file is a release snapshot. Fetch current defaults before producing

474your catalog.

475 

476### Fetch current upstream defaults

477 

478Cloud providers serving OpenAI models fetch defaults from OpenAI. Gateways read

479their cloud or upstream provider's catalog so they retain the deployed model's

480settings and account and region availability. Pass the requesting Codex version

481at each step, and authenticate separately to each endpoint.

482 

483To fetch defaults directly from OpenAI, call the Codex models endpoint with the

484same `client_version`. For example, with an OpenAI API key:

485 

486```bash

487curl --fail --silent --show-error \

488 'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \

489 -H "Authorization: Bearer $OPENAI_API_KEY"

490```

491 

492For a ChatGPT integration, use the caller's ChatGPT access token and

493`ChatGPT-Account-ID` header when applicable. Use credentials authorized for the

494upstream endpoint; your gateway's own API key doesn't authenticate to OpenAI.

495 

496Parse the full response, including its top-level `models` array. This endpoint

497returns Codex metadata such as instructions, reasoning defaults, tool settings,

498context limits, and service tiers. The public `/v1/models` endpoint doesn't

499supply this catalog.

500 

501Refresh these defaults even when the Codex version hasn't changed. Keep requests

502scoped to the intended upstream identity and honor response cache controls:

503catalogs can depend on the caller's access. Keep your overrides separate so you

504can reapply them to fresh defaults.

505 

506### Apply provider overrides

507 

508Change field values while preserving the version's response structure:

509 

510- Filter models to those the caller can use. Map each `slug` to a supported

511 inference route, and adjust `display_name`, `description`, or `priority`.

512 For an alias without a model migration, set `upgrade` to `null`.

513- Set reasoning options, context limits, input modalities, and service tiers to

514 values your model and route support. Keep defaults within the supported

515 choices. For a route without service tiers, clear `service_tiers` and

516 `additional_speed_tiers`, and set `default_service_tier` to `null`.

517- Preserve upstream instructions and tool settings unless you have tested a

518 replacement. Metadata doesn't add model capabilities or grant inference access.

519 

520For a gateway model alias, see how to

521[supply model metadata](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#use-a-model-catalog-for-custom-names).

522Test the resulting catalog with each supported Codex version.

523 

524### Use the public Rust types

525 

526Use crates from the same public Git tag or commit as the client's schema:

527 

528- Use [`codex-protocol`](https://github.com/openai/codex/tree/rust-v0.162.1/codex-rs/protocol) for `codex_protocol::openai_models::{ModelsResponse, ModelInfo}`. Parse with `serde_json::from_slice::<ModelsResponse>()`, edit `catalog.models`, and serialize the whole wrapper with `serde_json::to_vec()`. The wrapper handles compatibility fields for model instructions.

529- Use [`codex-models-manager::bundled_models_response()`](https://github.com/openai/codex/blob/rust-v0.162.1/codex-rs/models-manager/src/lib.rs) to load that revision's static bundled catalog as a `ModelsResponse`. It doesn't fetch current upstream defaults.

530 

328## Related docs531## Related docs

329 532 

330- [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider)533- [Configure the provider](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway#configure-the-provider)

62// resuming past thread62// resuming past thread

63 63 

64const threadId = thread.id!;64const threadId = thread.id!;

65const thread2 = codex.resumeThread(threadId);65const thread2 = codex.resumeThread(threadId, {

66 sandboxMode: "workspace-write",

67});

66const result2 = await thread2.run("Pick up where you left off");68const result2 = await thread2.run("Pick up where you left off");

67 69 

68console.log(result2.finalResponse);70console.log(result2.finalResponse);

138archive path with `onOutputArchived`:138archive path with `onOutputArchived`:

139 139 

140```typescript140```typescript

141await security.run(repository, {141try {

142 await security.run(repository, {

142 outputDir: outputDir,143 outputDir: outputDir,

143 archiveExisting: true,144 archiveExisting: true,

144 onOutputArchived(archiveDir) {145 onOutputArchived(archiveDir) {

145 console.log("Archived results:", archiveDir);146 console.log("Archived results:", archiveDir);

146 },147 },

147});148 });

149} finally {

150 await security.close();

151}

148```152```

149 153 

150 154 

161Pass an array of paths inside the repository:165Pass an array of paths inside the repository:

162 166 

163```typescript167```typescript

164const result = await security.run(repository, {168try {

169 const result = await security.run(repository, {

165 target: ["services/billing", "packages/auth"],170 target: ["services/billing", "packages/auth"],

166});171 });

172} finally {

173 await security.close();

174}

167```175```

168 176 

169 177 

183 head: "HEAD",191 head: "HEAD",

184});192});

185 193 

186const result = await security.run(repository, { target });194try {

195 const result = await security.run(repository, { target });

196} finally {

197 await security.close();

198}

187```199```

188 200 

189 201 

198```typescript210```typescript

199import { DiffTarget } from "@openai/codex-security";211import { DiffTarget } from "@openai/codex-security";

200const target = DiffTarget.workingTree({ base: "HEAD" });212const target = DiffTarget.workingTree({ base: "HEAD" });

201const result = await security.run(repository, { target });213try {

214 const result = await security.run(repository, { target });

215} finally {

216 await security.close();

217}

202```218```

203 219 

204 220 

210Set `mode: "deep"` for a repository or path scan that needs broader review:226Set `mode: "deep"` for a repository or path scan that needs broader review:

211 227 

212```typescript228```typescript

213const result = await security.run(repository, {229try {

230 const result = await security.run(repository, {

214 target: ["services/billing"],231 target: ["services/billing"],

215 mode: "deep",232 mode: "deep",

216 workers: 2,233 workers: 2,

218 stopAfterNoNew: 3,235 stopAfterNoNew: 3,

219 maxDiscoveryRuns: 10,236 maxDiscoveryRuns: 10,

220 maxTimeMinutes: 90,237 maxTimeMinutes: 90,

221});238 });

239} finally {

240 await security.close();

241}

222```242```

223 243 

224 244 

244 264 

245const knowledgeBase = join(repository, "security.md");265const knowledgeBase = join(repository, "security.md");

246 266 

247const result = await security.run(repository, {267try {

268 const result = await security.run(repository, {

248 knowledgeBasePaths: [knowledgeBase],269 knowledgeBasePaths: [knowledgeBase],

249});270 });

271} finally {

272 await security.close();

273}

250```274```

251 275 

252 276 

265Use `scanPrompt` to focus the scan and `postScanPrompt` to request a follow-up:289Use `scanPrompt` to focus the scan and `postScanPrompt` to request a follow-up:

266 290 

267```typescript291```typescript

268const result = await security.run(repository, {292try {

293 const result = await security.run(repository, {

269 scanPrompt: "Focus on tenant isolation and authorization checks.",294 scanPrompt: "Focus on tenant isolation and authorization checks.",

270 postScanPrompt: "Write confirmed findings to post-scan-summary.md.",295 postScanPrompt: "Write confirmed findings to post-scan-summary.md.",

271});296 });

297} finally {

298 await security.close();

299}

272```300```

273 301 

274 302 

310Use `onCost` to track cost as the scan runs and report `estimatedUsdRange`:338Use `onCost` to track cost as the scan runs and report `estimatedUsdRange`:

311 339 

312```typescript340```typescript

313const result = await security.run(repository, {341try {

342 const result = await security.run(repository, {

314 maxCostUsd: 5,343 maxCostUsd: 5,

315 onCost(cost) {344 onCost(cost) {

316 console.log(cost.estimatedUsdRange);345 console.log(cost.estimatedUsdRange);

317 },346 },

318});347 });

319 348 

320console.log(result.cost?.estimatedUsdRange);349 console.log(result.cost?.estimatedUsdRange);

350} finally {

351 await security.close();

352}

321```353```

322 354 

323 355 

354});386});

355 387 

356console.log(result.reportPath);388console.log(result.reportPath);

389if (result.failed > 0) {

390 throw new Error(`${result.failed} component scans failed.`);

391}

357```392```

358 393 

359 394 

522connection retries:557connection retries:

523 558 

524```typescript559```typescript

525const result = await security.run(repository, {560try {

561 const result = await security.run(repository, {

526 outputDir: outputDir,562 outputDir: outputDir,

527 onScanStarted() {563 onScanStarted() {

528 console.log("Scan started");564 console.log("Scan started");

542 onObserverError(observer, error) {578 onObserverError(observer, error) {

543 console.error(`${observer} failed`, error);579 console.error(`${observer} failed`, error);

544 },580 },

545});581 });

546 582 

547console.log(result.reportPath);583 console.log(result.reportPath);

584} finally {

585 await security.close();

586}

548```587```

549 588 

550 589 

566 } else {605 } else {

567 throw error;606 throw error;

568 }607 }

608} finally {

609 await security.close();

569}610}

570```611```

571 612