12- `approval_policy`, `sandbox_mode`, `permissions`, `permission profiles`, `network access`, `read-only`, `workspace-write`, `danger-full-access`, `security`, `cyber`: [Approvals, Sandboxing, and Security](#approvals-sandboxing-and-security)12- `approval_policy`, `sandbox_mode`, `permissions`, `permission profiles`, `network access`, `read-only`, `workspace-write`, `danger-full-access`, `security`, `cyber`: [Approvals, Sandboxing, and Security](#approvals-sandboxing-and-security)
13- `config.toml`, `.codex/config.toml`, `auth.json`, `ChatGPT sign-in`, `API key login`, `models`, `providers`, `model_reasoning_effort`: [Configuration, Authentication, and Models](#configuration-auth-and-models)13- `config.toml`, `.codex/config.toml`, `auth.json`, `ChatGPT sign-in`, `API key login`, `models`, `providers`, `model_reasoning_effort`: [Configuration, Authentication, and Models](#configuration-auth-and-models)
14- `codex exec`, `codex cloud`, `codex mcp`, `worktrees`, `cloud environments`, `internet access`, `Voice`, `remote connections`, `web search`, `image generation`: [CLI, IDE, App, and Cloud Behavior](#surface-behavior)14- `codex exec`, `codex cloud`, `codex mcp`, `worktrees`, `cloud environments`, `internet access`, `Voice`, `remote connections`, `web search`, `image generation`: [CLI, IDE, App, and Cloud Behavior](#surface-behavior)
15- `AGENTS.md`, `skills`, `plugins`, `plugin packaging`, `plugin marketplace`, `hooks`, `Docs MCP`, `rules`, `Code Review rules`, `custom prompts`, `MCP`, `GitHub integration`, `Slack integration`: [Customization, Skills, Rules, MCP, and Integrations](#customization-and-tooling)15- `AGENTS.md`, `skills`, `plugins`, `plugin packaging`, `plugin marketplace`, `hooks`, `Docs MCP`, `rules`, `Code Review rules`, `custom prompts`, `MCP`, `GitHub integration`, `GitLab integration`, `Slack integration`: [Customization, Skills, Rules, MCP, and Integrations](#customization-and-tooling)
16- `sdk`, `noninteractive`, `app-server`, `scheduled tasks`, `github-action`, `CI`, `auth in CI`: [Noninteractive and Programmatic Interfaces](#automation-and-programmatic-interfaces)16- `sdk`, `noninteractive`, `app-server`, `scheduled tasks`, `github-action`, `CI`, `auth in CI`: [Noninteractive and Programmatic Interfaces](#automation-and-programmatic-interfaces)
17- `Linux`, `Ubuntu`, `Debian`, `Fedora`, `Windows`, `WSL`, `enterprise`, `managed configuration`, `Amazon Bedrock`, `RBAC`, `data residency`, `OSS`: [Platform, Enterprise, and Caveats](#platform-enterprise-and-caveats)17- `Linux`, `Ubuntu`, `Debian`, `Fedora`, `Windows`, `WSL`, `enterprise`, `managed configuration`, `Amazon Bedrock`, `RBAC`, `data residency`, `OSS`: [Platform, Enterprise, and Caveats](#platform-enterprise-and-caveats)
18 18
284Plugin availability depends on your plan, workspace settings, and the plugin284Plugin availability depends on your plan, workspace settings, and the plugin
285itself. Learn more about [skills and plugins](https://learn.chatgpt.com/docs/skills-and-plugins).285itself. Learn more about [skills and plugins](https://learn.chatgpt.com/docs/skills-and-plugins).
286 286
287#### Share a read-only snapshot of a Codex thread
288
289On all Codex plans, you can create a read-only snapshot of a local Codex thread
290in the ChatGPT desktop app for macOS. The snapshot doesn't give other people
291access to your project or computer.
292
293Before sharing, check who can open the link:
294
295- **Personal account:** Anyone with the link can open the snapshot.
296- **Workspace account:** Only authenticated members of the workspace that
297 created the snapshot can open it. You can allow everyone in that workspace
298 or restrict access to invited people and groups. A workspace administrator
299 can turn off workspace share links.
300
3011. Open the thread and select **Share**. You can also use `/share` where slash
302 commands are available.
3032. For a workspace account, use **Who has access** to choose everyone in your
304 workspace or **Only people and groups invited**. For invited-only access,
305 add existing workspace members by email or choose workspace groups.
3063. Wait for the snapshot to finish uploading, then select **Copy link**.
307 Opening the dialog starts the upload, but Codex publishes the snapshot only
308 when you select **Copy link**, using your chosen audience and recipients.
3094. Open the copied link and review the shared view before sending it to anyone.
310
311A snapshot captures the supported thread content available when you share it.
312Later messages and changes don't update the existing snapshot.
313
314Shared snapshots can include user-visible messages, reasoning summaries, image
315attachments, images viewed or generated by the agent, and file changes,
316including paths and diffs. They don't include the original thread's tool calls,
317shell commands, or tool input or output.
318
319Codex redacts known secret patterns before uploading a snapshot. Review the
320shared view before sending its link because sensitive content, including file
321paths, may remain in messages, images, or diffs.
322
323You can't fork the original thread from a shared snapshot. You can import the
324snapshot as an attachment and refer to it in a new thread.
325
326To view or revoke a shared link, open [ChatGPT data
327controls](https://chatgpt.com/#settings/DataControls) and select **Shared links**.
328
287#### Make the result ready to use329#### Make the result ready to use
288 330
289Treat the first result as a draft you can inspect, challenge, and improve. A331Treat the first result as a draft you can inspect, challenge, and improve. A
343work, with examples and links to learn more. For every versioned update, bug fix,385work, with examples and links to learn more. For every versioned update, bug fix,
344and minor improvement, see the [Codex changelog](https://learn.chatgpt.com/docs/changelog).386and minor improvement, see the [Codex changelog](https://learn.chatgpt.com/docs/changelog).
345 387
388#### August 17–21, 2026
389
390#### Work with more of your apps and content
391
392- **Apple Messages:** [Find chats, summarize messages, prepare replies, and send through Messages on your Mac](https://learn.chatgpt.com/docs/plugins?surface=app#app-use-apple-messages-from-codex). The plugin is available on all plans in the ChatGPT desktop app for macOS. Use it in ChatGPT Work and Codex, not in regular ChatGPT chats. By default, ChatGPT sends messages only after you approve the message and its recipients.
393
394- **Site co-editing:** Where available, [invite active members of your workspace as editors](https://learn.chatgpt.com/docs/sites#collaborate-on-a-site). Editors can refine the Site and publish updates after its owner publishes it for the first time. Invited editors can read the Site's live database data; owners retain control of sharing and settings.
395
396- **Editable Site URLs:** Where available, [choose a new ChatGPT-hosted address for an existing Site](https://learn.chatgpt.com/docs/sites#change-a-site-url) without redeploying it. The previous address redirects to the new one.
397
398- **Computer History in Europe:** Use [Computer History](https://learn.chatgpt.com/docs/customization/computer-history) in the EEA, Switzerland, and the United Kingdom. It remains off by default for ChatGPT Pro, Business, and Enterprise users on macOS. Business and Enterprise administrators must enable access first.
399
400- **Shared thread snapshots:** [Share a read-only snapshot of a local Codex thread](https://learn.chatgpt.com/docs/use-chatgpt#share-a-read-only-snapshot-of-a-codex-thread) from the ChatGPT desktop app for macOS. Personal-account links are viewable by anyone with the link; workspace-account links are limited to the originating workspace. Codex redacts known secret patterns, but review the snapshot before sharing because sensitive content may remain.
401
402- **Unified pinned threads:** Keep your [pinned chats](https://learn.chatgpt.com/docs/projects?surface=app#app-organize-projects-and-chats) in sync between desktop and iOS.
403
404[Read the August 20 release notes](https://learn.chatgpt.com/docs/changelog#codex-2026-08-20-app).
405
406#### Work with GitLab projects in Codex cloud
407
408[GitLab support](https://learn.chatgpt.com/docs/third-party/gitlab) is available in beta on all ChatGPT
409plans. Connect a project, create a cloud environment, start tasks from issues
410or merge requests with `@codex`, and request one-off or automatic merge request
411reviews.
412
413The integration runs in Codex cloud, and a managed workspace admin can disable
414it. GitLab-triggered activity requires permission to configure the applicable
415webhook. GitLab Self-Managed and GitLab Dedicated connections require
416workspace admin setup; webhook activity requires GitLab 19.0 or later.
417
418[Read the August 19 GitLab release
419notes](https://learn.chatgpt.com/docs/changelog#codex-2026-08-19-gitlab).
420
421#### Export public plugin metadata for review
422
423Eligible ChatGPT Enterprise workspace owners and admins can download a CSV of
424the public plugins visible to their workspace. In
425[Admin > Plugins](https://chatgpt.com/admin/plugins), select **Public**, then
426select the download icon (**Export CSV**).
427
428The export lists plugin, app, and Chat skill names and descriptions, together
429with developer, version, date added in UTC, and OpenAI verification metadata.
430It uses a public-catalog snapshot that can be up to 48 hours old and excludes
431plugins created for the workspace. The export isn't available in FedRAMP
432workspaces.
433
434[Read the August 17 admin export release
435notes](https://learn.chatgpt.com/docs/changelog#codex-2026-08-17-admin-csv).
436
346#### August 10–14, 2026437#### August 10–14, 2026
347 438
348#### Find earlier work with Computer History439#### Find earlier work with Computer History
2777 2868
2778- [GitHub](https://learn.chatgpt.com/docs/third-party/github): Assign work, review changes, and move toward a pull request.2869- [GitHub](https://learn.chatgpt.com/docs/third-party/github): Assign work, review changes, and move toward a pull request.
2779 2870
2871- [GitLab (Beta)](https://learn.chatgpt.com/docs/third-party/gitlab): Connect projects, delegate work, and review merge requests.
2872
2780- [Slack](https://learn.chatgpt.com/docs/third-party/slack): Start Codex chats from external discussions and return results.2873- [Slack](https://learn.chatgpt.com/docs/third-party/slack): Start Codex chats from external discussions and return results.
2781 2874
2782- [Linear](https://learn.chatgpt.com/docs/third-party/linear): Assign issues to Codex and follow work through delivery.2875- [Linear](https://learn.chatgpt.com/docs/third-party/linear): Assign issues to Codex and follow work through delivery.
8746in the Codex desktop app. Codex performs scan analysis in a regular task, while8839in the Codex desktop app. Codex performs scan analysis in a regular task, while
8747the workbench keeps the scan and its results available when you return.8840the workbench keeps the scan and its results available when you return.
8748 8841
8842In the ChatGPT desktop app, open the ChatGPT dropdown and select **Codex**.
8749Install and enable the [Codex Security plugin](https://learn.chatgpt.com/docs/security/plugin), then8843Install and enable the [Codex Security plugin](https://learn.chatgpt.com/docs/security/plugin), then
8750select **Security** in the desktop-app sidebar.8844select **Security** in the sidebar.
8751 8845
8752If **Security** doesn't appear, confirm that the plugin is installed and8846If **Security** doesn't appear, confirm that **Codex** is selected and the
8753enabled. Update the desktop app and plugin if needed, and check whether your8847plugin is installed and enabled. Update the desktop app and plugin if needed,
8754workspace administrator allows the plugin.8848and check whether your workspace administrator allows the plugin.
8755 8849
8756#### Start a scan8850#### Start a scan
8757 8851
8924 9018
8925Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.9019Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.
8926 9020
8927Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).9021Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation (unless the tool advertises a read annotation, which takes priority).
8928 9022
8929#### Network access9023#### Network access
8930 9024
10826 10920
10827#### Use Codex Security in the desktop app10921#### Use Codex Security in the desktop app
10828 10922
10923In the ChatGPT desktop app, open the ChatGPT dropdown and select **Codex**.
10829Install and enable the Codex Security plugin to open **Security** in the10924Install and enable the Codex Security plugin to open **Security** in the
10830desktop-app sidebar. The Security workbench keeps your scans, findings, and10925sidebar. The Security workbench keeps your scans, findings, and repositories in
10831repositories in one place while Codex runs each scan in a task.10926one place while Codex runs each scan in a task.
10832 10927
10833- Use **Scans** to start scans, follow their progress, and review saved results.10928- Use **Scans** to start scans, follow their progress, and review saved results.
10834- Use **Findings** to inspect issues and evidence across completed scans.10929- Use **Findings** to inspect issues and evidence across completed scans.
11495#### Authentication and network11590#### Authentication and network
11496 11591
11497| Variable | Used by | Description |11592| Variable | Used by | Description |
11498| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |11593| ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
11499| `CODEX_API_KEY` | `codex exec` | Provides an API key for a single non-interactive run. This is only supported in `codex exec`; set it inline rather than job-wide when running repository-controlled code. |11594| `CODEX_API_KEY` | Exec, review, TypeScript SDK, remote exec-server | Provides an API key to a non-interactive Codex process. Set it inline rather than job-wide when running repository-controlled code. |
11500| `CODEX_ACCESS_TOKEN` | CLI, app-server, trusted automation | Provides a ChatGPT or Codex access token for trusted automation. For persisted login, pipe it to `codex login --with-access-token`. |11595| `CODEX_ACCESS_TOKEN` | CLI, app-server, trusted automation | Provides a ChatGPT or Codex access token for trusted automation. For persisted login, pipe it to `codex login --with-access-token`. |
11501| `CODEX_CA_CERTIFICATE` | HTTPS, login, and WebSocket clients | Points to a PEM CA bundle for environments with corporate TLS interception or private root CAs. Takes precedence over `SSL_CERT_FILE`. |11596| `OPENAI_FEDERATION_RULE_ID` | Workload identity | Selects the federation rule configured for the workload. |
11597| `OPENAI_IDENTITY_TOKEN_FILE` | Workload identity | Points to the absolute path of the file that contains the current OIDC token or SPIFFE JWT-SVID. |
11598| `OPENAI_WORKLOAD_IDENTITY_CONTEXT` | Workload identity | Optionally supplies bounded JSON identifiers for client-reported audit attribution. It does not affect authentication or authorization. |
11599| `CODEX_CA_CERTIFICATE` | HTTPS, login, and WebSocket clients | Points to a PEM CA bundle for environments with corporate TLS interception or private root certificates. Takes precedence over `SSL_CERT_FILE`. |
11502| `SSL_CERT_FILE` | HTTPS, login, and WebSocket clients | Fallback PEM CA bundle path when `CODEX_CA_CERTIFICATE` is unset. |11600| `SSL_CERT_FILE` | HTTPS, login, and WebSocket clients | Fallback PEM CA bundle path when `CODEX_CA_CERTIFICATE` is unset. |
11503 11601
11504For provider API keys, set11602For provider API keys, set
11509For automation secret handling, see11607For automation secret handling, see
11510[Use API key auth](https://learn.chatgpt.com/docs/non-interactive-mode#use-api-key-auth).11608[Use API key auth](https://learn.chatgpt.com/docs/non-interactive-mode#use-api-key-auth).
11511For access token setup, see [Access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).11609For access token setup, see [Access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).
11610For workload identity setup, see
11611[Workload identity federation](https://learn.chatgpt.com/docs/enterprise/workload-identity).
11512 11612
11513#### Diagnostics11613#### Diagnostics
11514 11614
12388 12488
12389#### OpenAI authentication12489#### OpenAI authentication
12390 12490
12391Codex supports two ways to sign in when using OpenAI models:12491Codex supports two ways for a person to sign in when using OpenAI models:
12392 12492
12393- Sign in with ChatGPT for subscription access12493- Sign in with ChatGPT for subscription access
12394- Sign in with an API key for usage-based access12494- Sign in with an API key for usage-based access
12485Open the profile menu to see the active account or API key status. Select12585Open the profile menu to see the active account or API key status. Select
12486**Log out** to clear the current credentials.12586**Log out** to clear the current credentials.
12487 12587
12488Run `codex login status` to see the active authentication method. Run12588Run `codex login status` to see the active authentication method. For stored
12489`codex logout` to clear the current credentials.12589authentication, run `codex logout` to clear the current credentials. When
12590the process selects workload identity, Codex rejects `codex login` and
12591`codex logout` because the process environment controls authentication.
12490 12592
12491Open the profile menu to see the active account or API key status. Select12593Open the profile menu to see the active account or API key status. Select
12492**Log out** to clear the current credentials.12594**Log out** to clear the current credentials.
12505For setup steps, permissions, rotation, and revocation guidance, see12607For setup steps, permissions, rotation, and revocation guidance, see
12506[Access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).12608[Access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).
12507 12609
12610If your cloud platform, CI system, or cluster already issues short-lived
12611workload tokens, use
12612[workload identity federation](https://learn.chatgpt.com/docs/enterprise/workload-identity)
12613instead of storing an OpenAI credential.
12614
12508If your environment already provides a Codex access token, pipe it to the CLI:12615If your environment already provides a Codex access token, pipe it to the CLI:
12509 12616
12510```shell12617```shell
18894- **Anyone in the workspace**, where supported19001- **Anyone in the workspace**, where supported
18895- **Anyone on the internet**, only when public publishing is enabled19002- **Anyone on the internet**, only when public publishing is enabled
18896 19003
18897Sharing lets people visit the Site; it doesn't let them edit it. In Enterprise19004Visitor access lets people open the Site; it doesn't give them editing access.
18898workspaces, public publishing is off by default and must be enabled by an admin.19005In Enterprise workspaces, public publishing is off by default and must be
19006enabled by an admin.
18899 19007
18900For limited sharing, invited visitors must sign in with the account that19008For limited sharing, invited visitors must sign in with the account that
18901received access. A public Site is available without ChatGPT workspace access. A19009received access. A public Site is available without ChatGPT workspace access. A
18909current Site and confirming its URL.19017current Site and confirming its URL.
18910```19018```
18911 19019
19020#### Collaborate on a Site
19021
19022Site collaboration requires a workspace. When the feature is available, a Site
19023owner can invite active members of the same workspace as editors.
19024
19025Editors can read the Site's live database data. Invite only people you trust
19026with the Site's code and data.
19027
190281. Open the Site and select **Share**.
190292. Under **Add people or groups**, find and select a workspace member. They
19030 are added as a visitor.
190313. Open **Can view** next to that person and choose **Can edit**. Access saves
19032 automatically. The Site appears under **Shared with you** in the member's
19033 Sites view.
190344. The editor can open the Site, make changes, save versions, and publish
19035 updates after the owner has published the Site for the first time.
19036
19037The Site owner manages editor access and can promote an existing visitor to
19038editor, change an editor to **Can view**, or remove their access. Co-editing
19039doesn't add a separate workspace permission toggle.
19040
19041Editors can't change the Site's audience, invite or remove other people, manage
19042settings or analytics, restore an earlier version, or transfer ownership. An
19043editor also can't perform the Site's first publish; the owner must publish the
19044Site before editors can publish later updates.
19045
19046Editor access is separate from visitor access. The steps above first add the
19047person as a visitor, then grant editing access. Promoting a visitor to editor
19048doesn't change the Site's audience setting.
19049
18912#### Configure runtime environment values19050#### Configure runtime environment values
18913 19051
18914Open **Sites**, then open the Site's settings to add, update, or remove hosted19052Open **Sites**, then open the Site's settings to add, update, or remove hosted
18926redeploy the approved saved version so the next deployment uses the updated19064redeploy the approved saved version so the next deployment uses the updated
18927configuration.19065configuration.
18928 19066
19067#### Change a Site URL
19068
19069Where URL editing is available, Site owners can change the ChatGPT-hosted URL
19070for an existing Site without creating another deployment.
19071
190721. Open **Sites**, find the Site, and open its settings.
190732. Find the Site URL and select **Change URL**.
190743. Enter an available name. It must contain at least five characters, start
19075 with a lowercase letter, and use only lowercase letters, numbers, and single
19076 hyphens. It can't end with a hyphen or contain consecutive hyphens.
190774. Confirm the change and wait while Sites updates the address.
19078
19079The URL change doesn't create another deployment. The previous address
19080redirects to the new one, including routes and query parameters.
19081
19082Changing the ChatGPT-hosted URL doesn't add, remove, or change a custom domain.
19083Custom domains are a separate, existing feature; use the custom-domain
19084settings when that feature is available.
19085
18929#### Connect a custom domain19086#### Connect a custom domain
18930 19087
18931Where custom domains are available, you can connect an apex domain or subdomain19088Where custom domains are available, you can connect an apex domain or subdomain
21504turn it on. For Business and Enterprise workspaces, an administrator must21661turn it on. For Business and Enterprise workspaces, an administrator must
21505explicitly grant access before each member can choose to turn it on. Computer21662explicitly grant access before each member can choose to turn it on. Computer
21506History also requires [Memories](https://learn.chatgpt.com/docs/customization/memories) and is not21663History also requires [Memories](https://learn.chatgpt.com/docs/customization/memories) and is not
21507available with an API key or Amazon Bedrock. Computer History is not currently21664available with an API key or Amazon Bedrock. It's available in supported
21508available in the European Economic Area (EEA), Switzerland, or the United21665regions, including the European Economic Area (EEA), Switzerland, and the
21509Kingdom.21666United Kingdom.
21510 21667
21511Computer History turns your activity across apps and websites into memories and21668Computer History turns your activity across apps and websites into memories and
21512a timeline that ChatGPT and Codex can reference. You can ask natural questions21669a timeline that ChatGPT and Codex can reference. You can ask natural questions
27738- For automatic reviews, check that you turned on **Automatic reviews** and that27895- For automatic reviews, check that you turned on **Automatic reviews** and that
27739 the pull request event matches your review trigger settings.27896 the pull request event matches your review trigger settings.
27740 27897
27898### Review GitLab merge requests with Codex
27899
27900Source: [Review GitLab merge requests with Codex](https://learn.chatgpt.com/docs/third-party/gitlab.md)
27901
27902Use Codex code review to get another high-signal review pass on GitLab merge
27903requests. Codex reviews the merge request diff, follows your repository
27904guidance, and posts a standard GitLab code review focused on serious issues.
27905
27906GitLab support is in beta and is available on all ChatGPT plans. The Codex
27907integration runs in Codex cloud. GitHub-style repository controls in the
27908desktop app, such as **Create pull request**, aren't included in this beta.
27909
27910#### Before you start
27911
27912Make sure you have:
27913
27914- A connected GitLab account. GitLab.com requires the
27915 [standard connection flow](https://help.openai.com/articles/20001486);
27916 self-managed or Dedicated GitLab instances require
27917 [workspace-admin template setup](https://help.openai.com/articles/20001487).
27918- An `AGENTS.md` file if you want Codex to follow repository-specific review
27919 guidance.
27920
27921#### Set up Codex code review
27922
27923#### Set up the GitLab connection and Codex review identity
27924
27925For GitLab.com, connect your GitLab account in Codex once you've
27926[connected to GitLab in ChatGPT](https://help.openai.com/articles/20001486).
27927For self-managed or Dedicated GitLab, each reviewer should connect after the
27928[workspace-admin template](https://help.openai.com/articles/20001487) has been
27929published.
27930
27931For self-managed or Dedicated GitLab, open **Codex Cloud** → **Settings** →
27932[**Connectors**](https://chatgpt.com/codex/cloud/settings/connectors). A
27933workspace admin can let Codex create a service account or save an existing
27934service-account personal access token.
27935
27936#### Let Codex create the account
27937
27938In **Codex Cloud** → **Settings** → **Connectors**, select the app for your
27939self-managed or Dedicated GitLab host → select **Set up service account** →
27940**Create a service account**. The workspace admin completing setup must have
27941administrator access to the GitLab instance. Choose either **Selected groups**
27942or **Selected projects only**, then select where Codex should operate and create
27943the account. The group option grants Developer access to each chosen group,
27944inherited by its projects and subgroups; the project option grants Developer
27945access only to the individual projects you choose. Codex will create the ChatGPT
27946Codex Connector instance service account with a personal access token with the
27947`api` scope.
27948
27949#### Use an existing account
27950
27951In GitLab, create or choose a service account and grant it Developer access
27952only in the groups or projects where Codex should operate. From the **Service
27953accounts** page, select the account → **Manage access tokens** → **Add new
27954token** to
27955[create a personal access token](https://docs.gitlab.com/user/profile/service_accounts/#create-a-personal-access-token-for-a-service-account)
27956with the `api` scope and an expiration date at least 30 days away. Back in
27957Codex, choose **Use an existing service account**, paste the token, and select
27958**Save token**. The token is encrypted when saved and is never shown again.
27959
27960#### Manage the service-account token
27961
27962Workspace admins can manage the service account in **Codex Cloud** →
27963**Settings** → **Connectors**. For a Codex-created account, admins can revoke
27964the current token and generate a new one. For an existing account, admins can
27965replace or remove the saved token in Codex and revoke it separately in GitLab if
27966needed. Codex cannot respond to GitLab activity until a valid token is
27967configured.
27968
27969#### Choose how GitLab activity reaches Codex
27970
27971#### Create a project environment for coding tasks or project-specific setup
27972
27973In **Codex Cloud** → **Settings** → **Environments**, choose the GitLab project
27974and create a project environment when you want Codex to write or execute code
27975for that project—for example, to edit files, commit changes, or push updates to
27976a merge request branch—or when a review depends on project-specific secrets,
27977network access, or setup commands.
27978
27979For GitLab.com, a project environment is also required to enable Codex reviews.
27980
27981While creating the environment, turn on **Enable Codex activity from GitLab**
27982to install the project webhook that delivers merge request, comment, and issue
27983events to Codex. Creating the project webhook requires Maintainer or Owner
27984access, administrator access, or a custom role that can administer project
27985webhooks. Signed project and group webhooks require GitLab 19.0 or newer. On
27986self-managed GitLab 19.0, confirm the `webhook_signing_token` feature flag is
27987enabled; it is enabled by default and was removed in GitLab 19.1.
27988
27989#### Enable activity for Codex reviews for projects across a GitLab group
27990
27991For self-managed or Dedicated GitLab, workspace admins can open **Environments**
27992→ **GitLab activity** → **Manage groups** to enable Codex reviews across a group
27993and its subgroups. Codex will install a group webhook covering projects
27994throughout that group. The connected GitLab user must be a group Owner, and
27995group webhooks require GitLab Premium or Ultimate and GitLab 19.0 or newer.
27996
27997Group activity enables code reviews but does not create project environments.
27998To run GitLab-triggered coding tasks, such as editing files, running commands,
27999committing changes, or pushing updates to a merge request, create a project
28000environment.
28001
28002#### Configure code review policies
28003
28004Configure code review policies in
28005[Codex review settings](https://chatgpt.com/codex/cloud/settings/code-review?provider=gitlab).
28006Choose the repository policy: `Review my MRs`, `Review team MRs`,
28007`Review all MRs`, or `Follow personal`. Then choose when reviews run: **On MR open**,
28008**On every push**, or **Smart Trigger (Experimental)**. Repository settings can
28009override personal defaults.
28010
28011#### Request a Codex review
28012
280131. In a merge request comment, mention `@codex review`.
280142. Wait for Codex to react (👀) and post a review.
28015
28016Codex posts GitLab discussions and notes on the merge request, just like a
28017teammate would. By default, manually requested reviews can include P0, P1, and
28018P2 findings, while automatic reviews focus on P0 and P1 findings.
28019
28020#### Enable automatic reviews
28021
28022To review qualifying merge requests automatically, turn on **Automatic
28023reviews** in Codex settings, choose the GitLab repository policy, and choose a
28024trigger: **On MR open**, **On every push**, or **Smart Trigger (Experimental)**.
28025Codex runs without an `@codex review` comment when the merge request event
28026matches that policy and trigger.
28027
28028GitLab activity must be enabled through a project webhook or an ancestor group
28029webhook. For self-managed or Dedicated GitLab, the configured service account
28030must also have access to write back to the project. Codex uses a configured
28031project environment when present. If an ancestor group already enables
28032activity, descendant projects inherit that coverage.
28033
28034#### Customize what Codex reviews
28035
28036Codex searches your repository for `AGENTS.md` files and follows the applicable
28037code review rules. Add a `## Code Review Rules` section to the file closest to
28038the code the rules govern. Use `###` headings to group related checks when
28039helpful.
28040
28041For example, an experiment-reporting service can keep post-exposure behavior
28042from changing a comparison cohort:
28043
28044```md
28045## Code Review Rules
28046
28047### Experiment cohorts
28048
28049- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
28050 Safe path: build cohorts from assignment or exposure; report conversion as an outcome.
28051```
28052
28053Put repository-wide rules in the root `AGENTS.md` and service-specific rules in
28054a nested file, such as `services/experiment_reporting/AGENTS.md`. Codex applies
28055the root and more-specific guidance that covers each changed file, so unrelated
28056changes don't have to carry service-specific context.
28057
28058Start with two or three concise rules that encode checks reviewers often
28059explain. Useful rules:
28060
28061- **Focus on consequential, repository-specific behavior.** Describe the
28062 compatibility constraint, data boundary, or unsafe side effect to flag and
28063 why it matters.
28064- **State the safe path or exception.** Give Codex enough context to distinguish
28065 a real issue from expected behavior.
28066- **Keep rules scoped and durable.** Prefer outcomes over function names that
28067 can change, and place guidance near the code it governs.
28068- **Leave mechanical checks in CI.** Keep formatting, lint, and other
28069 deterministic checks out of review rules.
28070
28071Open a representative merge request and request a review with `@codex review`.
28072Refine the rules based on the findings and feedback you see, and narrow or
28073remove guidance that produces noise.
28074
28075Code review rules guide Codex; they don't replace tests, branch protections, or
28076required approvals.
28077
28078For a one-off focus, add it to your merge request comment:
28079
28080`@codex review for issues in the database migration`
28081
28082#### Act on review findings
28083
28084Fixing review findings requires a **configured project environment**; group
28085activity alone supports reviews but cannot run coding tasks. If the project has
28086an environment, ask Codex to fix an issue in the same merge request by leaving
28087another comment:
28088
28089```md
28090@codex fix the P1 issue
28091```
28092
28093Codex starts a [cloud chat](https://learn.chatgpt.com/docs/cloud) with the merge request as context and
28094can push a fix back to the branch when it has permission to do so.
28095
28096#### Give Codex other tasks
28097
28098Other coding tasks also require a **configured project environment**; group
28099activity alone supports reviews. If you mention `@codex` in a comment with
28100anything other than `review`, Codex starts a [cloud chat](https://learn.chatgpt.com/docs/cloud) using
28101your merge request as context.
28102
28103```md
28104@codex fix the CI failures
28105```
28106
28107#### Troubleshoot code review
28108
28109If Codex doesn't react or post a review:
28110
28111- Confirm the intended GitLab app has been selected; if you use project-specific
28112 setup, confirm the project has the intended Codex cloud environment.
28113- Confirm activity for the project or an ancestor group. In GitLab, check
28114 **Webhooks** →
28115 [**Recent events**](https://docs.gitlab.com/user/project/integrations/webhooks/)
28116 and verify merge request and note deliveries succeed.
28117- For self-managed or Dedicated GitLab, confirm the project or group webhook is
28118 signed, SSL verification is enabled, and the instance is on GitLab 19.0 or
28119 newer. On self-managed GitLab 19.0, confirm the `webhook_signing_token` feature
28120 flag is enabled; repair hooks disabled automatically after failures.
28121- For self-managed or Dedicated GitLab, confirm an existing service-account
28122 personal access token is active and has the `api` scope. If Codex created the
28123 service account, confirm it is correctly configured in
28124 [Codex connector settings](https://chatgpt.com/codex/cloud/settings/connectors)
28125 and that the project or group is enabled.
28126- For self-managed or Dedicated GitLab, confirm the workspace service
28127 account—not just the connected GitLab user—has Developer access to the project
28128 or a parent group so Codex can post reviews and reactions. Membership is
28129 inherited; activity and service-account access are separate.
28130- Confirm **Code review** or **Automatic reviews** is enabled and the MR matches
28131 the repository policy and trigger.
28132- Use `@codex review`.
28133
27741### Rules28134### Rules
27742 28135
27743Source: [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules.md)28136Source: [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules.md)
28966 Use this when you want to be specific about which plugin or skill ChatGPT29359 Use this when you want to be specific about which plugin or skill ChatGPT
28967 should use. See Skills & Plugins.29360 should use. See Skills & Plugins.
28968 29361
29362#### Use Apple Messages from Codex
29363
29364The Apple Messages plugin is available on all plans in the ChatGPT desktop app
29365for macOS. In Codex and ChatGPT Work, it can read and search iMessage, SMS, and
29366RCS chats on your Mac and send messages on your behalf through the Messages app.
29367It doesn't let you interact with ChatGPT remotely through Messages, and it
29368doesn't work in regular ChatGPT chats.
29369
29370For this release, the Messages plugin is included only in the Apple Silicon
29371(arm64) build of the ChatGPT desktop app.
29372
293731. Open **Plugins**, find the Apple Messages plugin, and install it.
293742. Start a new Codex or ChatGPT Work chat and ask it to find, summarize, draft,
29375 or send a message.
293763. Grant the requested macOS permissions before ChatGPT reads Messages.
293774. Review the message and its recipients before allowing a send.
29378
29379By default, ChatGPT sends messages only after you approve the message and its
29380recipients. Choose **Allow once** to approve only that send. If you select
29381**Always allow sending to this chat**, ChatGPT can send future messages to that
29382Messages chat without another send approval.
29383
29384Keep per-send approval for chats that may contain untrusted or misleading
29385instructions. Persistent approval removes your final chance to review a message
29386before ChatGPT sends it as you. Use it only when you accept that risk.
29387
29388To restore per-send approval, open **Settings** > **Computer use** and select
29389**Manage** next to **Messages**. Under **Always allowed to send**, select the
29390trash icon next to the chat, then confirm **Remove**. ChatGPT will ask
29391before sending to that chat again.
29392
29393**Known issue:** If your task is set to **Full access** or otherwise disables
29394approval prompts, Apple Messages may be unable to show the confirmation needed
29395to send. Switch to **Ask for approval** or **Approve for me** and try again.
29396
29397Apple Messages runs on your Mac. It isn't directly available in ChatGPT on the
29398web or mobile, Codex CLI, or the IDE extension.
29399
29400In managed workspaces, administrators can disable Apple Messages through the
29401existing Computer Use control.
29402
28969#### Plugin browser in Codex CLI29403#### Plugin browser in Codex CLI
28970 29404
28971In Codex CLI, run the following command to open the plugin browser:29405In Codex CLI, run the following command to open the plugin browser:
31771 32205
31772If stdin is piped and you also provide a prompt argument, Codex treats the prompt as the instruction and the piped content as additional context.32206If stdin is piped and you also provide a prompt argument, Codex treats the prompt as the instruction and the piped content as additional context.
31773 32207
31774This makes it easy to generate input with one command and hand it directly to Codex:32208This lets you generate input with one command and hand it directly to Codex:
31775 32209
31776```bash32210```bash
31777curl -s https://jsonplaceholder.typicode.com/comments \32211curl -s https://jsonplaceholder.typicode.com/comments \
31863 32297
31864`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:32298`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:
31865 32299
32300If your trusted cloud or CI runtime already receives short-lived workload
32301tokens, use
32302[workload identity federation](https://learn.chatgpt.com/docs/enterprise/workload-identity)
32303instead of storing an OpenAI credential.
32304
31866#### Use API key auth32305#### Use API key auth
31867 32306
31868For GitHub Actions, use the [Codex GitHub Action](https://learn.chatgpt.com/docs/github-action) instead of installing and authenticating the CLI yourself. The action is designed to reduce API key exposure by installing Codex, starting a Responses API proxy, and running Codex with a configurable safety strategy.32307For GitHub Actions, use the [Codex GitHub Action](https://learn.chatgpt.com/docs/github-action) instead of installing and authenticating the CLI yourself. The action is designed to reduce API key exposure by installing Codex, starting a Responses API proxy, and running Codex with a configurable safety strategy.
31869 32308
31870Do not set `OPENAI_API_KEY` or `CODEX_API_KEY` as a job-level environment variable in workflows that check out or run repository-controlled code. Build scripts, tests, dependency lifecycle hooks, or a compromised action in the same job can read those environment variables.32309Do not set `OPENAI_API_KEY` or `CODEX_API_KEY` as a job-level environment variable in workflows that check out or run repository-controlled code. Build scripts, tests, dependency lifecycle hooks, or a compromised action in the same job can read those environment variables.
31871 32310
31872For other automation environments, set `CODEX_API_KEY` only for the single `codex exec` invocation and make sure no untrusted code runs in the same process environment.32311For other automation environments, set `CODEX_API_KEY` only for the Codex
32312invocation that needs it, and make sure no untrusted code runs in the same
32313process environment.
31873 32314
31874To use a different API key for a single run, set `CODEX_API_KEY` inline:32315To use a different API key for a single run, set `CODEX_API_KEY` inline:
31875 32316
31877CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"32318CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
31878```32319```
31879 32320
31880`CODEX_API_KEY` is only supported in `codex exec`.32321You can use `CODEX_API_KEY` with `codex exec`, `codex review`, the TypeScript
32322SDK, and `codex exec-server --remote`.
31881 32323
31882#### Use ChatGPT-managed auth in CI/CD (advanced)32324#### Use ChatGPT-managed auth in CI/CD (advanced)
31883 32325
33663The files and tools available to ChatGPT Work depend on where Work is running,34105The files and tools available to ChatGPT Work depend on where Work is running,
33664user permissions and admin configuration.34106user permissions and admin configuration.
33665 34107
33666**Local Work** runs tasks through the ChatGPT desktop app on the user's device.34108#### Local Work
34109
34110Local Work runs tasks through the ChatGPT desktop app on the user's device.
33667It can access local files, applications, and other resources made available to34111It can access local files, applications, and other resources made available to
33668it, subject to the user's permissions, applicable workspace controls, and device34112it, subject to the user's permissions, applicable workspace controls, and device
33669security policies. Unlike Work on the Web, local Work can operate on resources34113security policies. Unlike Work on the Web, local Work can operate on resources
33670that remain on your computer without requiring you to upload files to a cloud34114that remain on your computer without requiring you to upload files to a cloud
33671conversation.34115conversation.
33672 34116
33673**Cloud Work**, accessed via the web or mobile, runs the Codex harness in an34117#### Cloud Work
33674isolated environment on OpenAI-managed infrastructure. Cloud conversations can34118
33675be available across supported web, mobile, and desktop surfaces, and supported34119Cloud Work is available on supported web, mobile, and desktop surfaces. It runs
33676tasks can continue while the user is away from the conversation.34120the Codex harness in an isolated environment on OpenAI-managed infrastructure.
34121Cloud conversations can sync across these surfaces, and supported tasks can
34122continue while the user is away from the conversation.
33677 34123
33678Work on the web can't directly access files, applications, or open browser tabs34124Work on the web can't directly access files, applications, or open browser tabs
33679on the user's computer. A user can provide files by uploading them, adding them34125on the user's computer. A user can provide files by uploading them, adding them
33700 34146
33701- **Code and shell commands**: Public internet access depends on the applicable34147- **Code and shell commands**: Public internet access depends on the applicable
33702 workspace policy and individual Work network setting. When public internet34148 workspace policy and individual Work network setting. When public internet
33703 access isn't allowed, commands can still reach required destinations on a34149 access isn't allowed, commands can still reach OpenAI-approved destinations
33704 managed allowlist.34150 required for Work to function. This controls network destinations, not which
34151 commands can run.
33705- **Web search**: Search has controls separate from the Work code and shell34152- **Web search**: Search has controls separate from the Work code and shell
33706 network setting.34153 network setting.
33707 34154
34106 34553
34107Source: [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning.md)34554Source: [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning.md)
34108 34555
34109Groups organize ChatGPT workspace access for a set of members and can carry34556Groups organize people in a ChatGPT workspace and can carry custom roles. Group
34110custom roles. Group membership is separate from local runtime policy and34557membership doesn't replace seat assignments, grant workspace feature permissions
34111permissions in connected systems.34558by itself, override local runtime policy, or provide access to the Platform API
34559or connected systems.
34112 34560
34113For the complete control model, see34561For the complete control model, see
34114[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).34562[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).
34115 34563
34116#### Compare membership sources34564#### Compare membership sources
34117 34565
34566Use groups for people with a shared access need, such as a pilot cohort,
34567workspace operators, or members who need the same supported feature.
34568
34569#### Create a group for a shared access need
34570
34571Workspace owners and admins can create and manage groups. Create a manually
34572managed group for a small or temporary audience, or sync an established group
34573from your identity provider when membership should follow your directory.
34574
34118Each group has one authoritative membership source:34575Each group has one authoritative membership source:
34119 34576
34120| Group type | Membership source | When it applies |34577| Group type | Membership source | When it applies |
34129 34586
34130#### Understand the access boundary34587#### Understand the access boundary
34131 34588
34589Group membership by itself doesn't grant a workspace feature permission.
34590
34591#### Connect a group to the right permissions
34592
34593Workspace owners can assign custom roles to groups or, where available, directly
34594to members. Check every applicable role: an explicit **Off** in any role
34595denies that permission, even when another role grants it. A member's seat type
34596and product eligibility still apply.
34597
34132SCIM provisions workspace membership and group assignments. It doesn't grant34598SCIM provisions workspace membership and group assignments. It doesn't grant
34133permissions in GitHub, Google Drive, Slack, or another connected system. It also34599permissions in GitHub, Google Drive, Slack, or another connected system. It also
34134doesn't replace local runtime requirements or Platform API organization access.34600doesn't replace local runtime requirements or Platform API organization access.
34149- [SCIM integration FAQ](https://help.openai.com/en/articles/10011769-openai-platform-scim-integration-faq)34615- [SCIM integration FAQ](https://help.openai.com/en/articles/10011769-openai-platform-scim-integration-faq)
34150- [Manage workspace settings](https://help.openai.com/en/articles/8411955)34616- [Manage workspace settings](https://help.openai.com/en/articles/8411955)
34151 34617
34618#### Verify joiners, movers, and leavers
34619
34620- **Joiners:** Confirm the member accepts any pending workspace invitation and
34621 receives the intended seat, group memberships, permissions, and supported
34622 features.
34623- **Movers:** Update the authoritative membership source and verify the
34624 member's effective permissions across all applicable roles.
34625- **Leavers:** Remove a SCIM-managed member's access through the identity
34626 provider and confirm that the member can no longer access the workspace. If
34627 you remove the member only from the workspace, a later sync can restore
34628 access.
34629
34152#### Related docs34630#### Related docs
34153 34631
34154- [Authentication](https://learn.chatgpt.com/docs/auth)34632- [Authentication](https://learn.chatgpt.com/docs/auth)
34430cache for a later start; it doesn't replace the requirements already loaded34908cache for a later start; it doesn't replace the requirements already loaded
34431into the current process.34909into the current process.
34432 34910
34911#### Confirm the admin and employee experience
34912
34913Assign a person to own each managed policy, record which users or groups should
34914receive it, and document the business reason for any filesystem, network,
34915approval, or permission-profile restriction.
34916
34917Before expanding the rollout, test an approved workflow and an intentionally
34918disallowed workflow with a representative user. Verify the effective settings
34919in the supported client rather than assuming a workspace role or group alone
34920enforces the local restriction.
34921
34433#### Example requirements.toml34922#### Example requirements.toml
34434 34923
34435This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):34924This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):
34924 35413
34925#### Managed defaults (`managed_config.toml`)35414#### Managed defaults (`managed_config.toml`)
34926 35415
34927Managed defaults merge on top of a user's local `config.toml` and take35416Managed defaults set the configuration a supported local client starts with. At
34928precedence over any CLI `--config` overrides, setting the starting values when a35417startup, they override the user's local `config.toml` and any CLI `--config`
34929supported local client launches. Users can still change those settings during a35418overrides. Users can still change those settings during the current run, and the
34930run; the client reapplies managed defaults the next time it starts.35419defaults apply again the next time the client starts.
34931 35420
34932If a managed default, macOS MDM profile, or saved configuration pins `gpt-5.4`35421If a managed default, macOS MDM profile, or saved configuration pins `gpt-5.4`
34933or `gpt-5.4-mini` for users signed in with ChatGPT, update it before August 31, 2026. Replace `gpt-5.4` with `gpt-5.6-terra` and `gpt-5.4-mini` with35422or `gpt-5.4-mini` for users signed in with ChatGPT, update it before August 31, 2026. Replace `gpt-5.4` with `gpt-5.6-terra` and `gpt-5.4-mini` with
35058[Build plugins](https://developers.openai.com/plugins/build/plugins) for35547[Build plugins](https://developers.openai.com/plugins/build/plugins) for
35059packaging and distribution.35548packaging and distribution.
35060 35549
35550#### Export the public catalog for review
35551
35552Eligible ChatGPT Enterprise workspace owners and admins can download a CSV of
35553the public plugins available to their workspace. Use the export to review
35554plugin, app, and skill metadata before changing plugin availability.
35555
355561. Open [Admin > Plugins](https://chatgpt.com/admin/plugins).
355572. Select **Public**.
355583. Select the download icon (**Export CSV**) in the page header.
35559
35560The download uses the filename `public-plugins-security-review.csv` and includes:
35561
35562- Plugin metadata: `Plugin Name`, `Plugin Description`, `Date Added (UTC)`,
35563 `OpenAI Verified`, `Developer Name`, and `Version`.
35564- App metadata: `App Name(s)` and `App Description(s)`.
35565- Chat skill metadata: `Skill Name(s)` and `Skill Description(s)`.
35566
35567When a plugin includes more than one app or skill, semicolons separate the
35568corresponding values. The export uses a public-catalog snapshot that can be up
35569to 48 hours old,
35570includes only public plugins visible to the current workspace, and does not
35571include plugins created for that workspace. It isn't available in FedRAMP
35572workspaces.
35573
35061#### Step 2: Manage capabilities35574#### Step 2: Manage capabilities
35062 35575
35063Making an app or plugin available in ChatGPT doesn't grant access to files,35576Making an app or plugin available in ChatGPT doesn't grant access to files,
35258 35771
35259Source: [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions.md)35772Source: [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions.md)
35260 35773
35261Administration spans six control boundaries. Granting access at one boundary35774Different settings cover different parts of your organization's ChatGPT
35262doesn't grant access at another. Use this page as the canonical map,35775experience. Giving someone access in one area doesn't automatically give them
35263then follow the linked source for current settings and procedures.35776access in another. Use this page to see how the six control boundaries work
35777together, then follow the linked guidance for current setup steps.
35264 35778
35265In workspace settings, **Codex Local** is a grouping label for certain local35779In workspace settings, **Codex Local** is a grouping label for certain local
35266access and access-token controls, not a separate product or client. Individual35780access and access-token controls, not a separate product or client. Individual
35290#### Assign workspace access35804#### Assign workspace access
35291 35805
35292ChatGPT workspace administration separates product access from administrative35806ChatGPT workspace administration separates product access from administrative
35293authority. The workspace plan and a member's seat determine which product35807authority.
35294surfaces are available. Built-in workspace roles determine who can administer35808
35295the workspace. Role-based access control (RBAC) determines which supported35809#### Understand the difference between a seat, an admin role, and a custom role
35296features members can use.35810
35811A seat determines which product surfaces a member can access. Depending on the
35812workspace plan, available seat types can include ChatGPT and Codex seats.
35813
35814Built-in workspace roles determine administrative authority. The **Owner** role
35815manages workspace-wide settings, the **Admin** role manages supported operations
35816and groups, the **Member** role doesn't have administrative rights, and the
35817**Analytics Viewer** role can access workspace analytics.
35818
35819Custom roles define which supported features a member can use. They don't
35820replace seat or plan eligibility, grant permissions in a connected system, or
35821change local runtime requirements.
35822
35823#### Set the workspace default, then create targeted custom roles
35824
35825Only workspace owners can configure role-based access control (RBAC) and create
35826custom roles. Workspace settings establish the baseline for eligible
35827permissions. Owners can assign custom roles through manually managed or
35828SCIM-synced groups, or directly to individual members where supported. A member
35829can receive more than one custom role.
35830
35831For eligible permissions, **Default** inherits the workspace setting, **On**
35832grants access, and **Off** explicitly denies access. An explicit **Off** in any
35833applicable role blocks access even when another role grants it. Available
35834permission states can vary by feature.
35835
35836#### Review Work Local and Work Cloud permissions
35837
35838When your workspace offers **Work Local** and **Work Cloud**, check both the
35839workspace default and each applicable custom role. Work is available only to
35840eligible workspaces, and available controls can differ by plan, workspace
35841configuration, and rollout. A role can't expand the access allowed by a
35842member's seat.
35843
35844**Work Cloud** governs supported ChatGPT Work tasks in the cloud. **Work
35845Local** without **Work Cloud** allows local work in the ChatGPT desktop app but
35846doesn't allow members to start cloud tasks. Codex Local access instead uses the
35847separate **Allow members to use Codex Local** permission. Changing a Work
35848permission doesn't change Codex Local access or replace local runtime
35849requirements.
35297 35850
35298Administrators can assign custom roles through groups, and a member can receive35851For current eligibility and settings, see
35299access from more than one group. Because available seats, roles, and permissions35852[ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex).
35300change with product and plan updates, use the Help Center for the current35853
35301permission list and setup procedure:35854Because available seats, roles, and permissions change with product and plan
35855updates, use the Help Center for the current permission list and setup
35856procedure:
35302 35857
35303- [Manage members, seat types, roles, and access](https://help.openai.com/en/articles/8266401-managing-members-seat-types-roles-and-access-in-chatgpt-enterprise)35858- [Manage members, seat types, roles, and access](https://help.openai.com/en/articles/8266401-managing-members-seat-types-roles-and-access-in-chatgpt-enterprise)
35304- [Configure role-based access control](https://help.openai.com/en/articles/11750701-rbac)35859- [Configure role-based access control](https://help.openai.com/en/articles/11750701-rbac)
35555- [Admin rollout guide](https://learn.chatgpt.com/docs/enterprise/admin-setup)36110- [Admin rollout guide](https://learn.chatgpt.com/docs/enterprise/admin-setup)
35556- [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors)36111- [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors)
35557 36112
36113### Workload identity federation
36114
36115Source: [Workload identity federation](https://learn.chatgpt.com/docs/enterprise/workload-identity.md)
36116
36117Workload identity federation lets trusted automation use Codex without storing
36118a personal access token or another long-lived OpenAI credential. Your workload
36119presents a short-lived identity token from a provider you already operate.
36120OpenAI verifies that token and returns a short-lived access token for a user or
36121service account in your managed ChatGPT workspace.
36122
36123Use workload identity for unattended Codex processes in cloud platforms,
36124Kubernetes, CI systems, and other environments that can issue OIDC tokens or
36125SPIFFE JWT-SVIDs. For the shared trust model and the separate OpenAI API flow,
36126see the [workload identity overview](https://developers.openai.com/api/docs/guides/workload-identity-federation).
36127
36128Codex workload identity federation is in beta and must be enabled for your
36129workspace. To request access, contact your OpenAI representative or [OpenAI
36130Support](https://help.openai.com/en/articles/6614161-how-can-i-contact-support).
36131
36132#### Before you begin
36133
36134You need:
36135
36136- Permission to manage workload identity in the OpenAI Admin Portal.
36137- A managed ChatGPT workspace.
36138- A ChatGPT user or service account that is an active member of that workspace,
36139 or permission to create one during setup.
36140- An OIDC token or SPIFFE JWT-SVID whose issuer, audience, and identifying
36141 claims you know.
36142- A runtime that can keep that token current in a protected file at an absolute
36143 path.
36144- Codex 0.148.0 or later.
36145- An effective Codex authentication policy that permits ChatGPT authentication
36146 and the workspace selected by the federation rule. See [Enforce a login
36147 method or workspace](https://learn.chatgpt.com/docs/auth#enforce-a-login-method-or-workspace).
36148
36149OpenAI does not create a principal or workspace membership during token
36150exchange. An administrator selects or creates the principal before the workload
36151connects. Creating a human user consumes a workspace seat and follows the
36152membership rules for that workspace.
36153
36154On native Windows, use the **elevated**
36155[Windows sandbox](https://learn.chatgpt.com/docs/windows/windows-sandbox). Other Windows sandbox modes
36156cannot protect the identity-token file from model-controlled commands.
36157
36158#### Get an identity token
36159
36160Your workload runtime gets and refreshes the upstream identity token. Codex does
36161not call cloud metadata services or identity-provider client libraries on your
36162behalf.
36163
36164| Runtime | Recommended token-file source |
36165| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
36166| Kubernetes, AKS, EKS, or GKE | Mount a projected service-account token and point Codex at that file. The platform rotates it. |
36167| Microsoft Entra managed identity | Run a trusted host process or sidecar that requests a token from Azure IMDS and replaces the file before expiry. |
36168| AWS outbound identity federation | Run a trusted host process that calls regional STS `GetWebIdentityToken` and replaces the file before expiry. |
36169| Google Cloud | Run a trusted host process that requests an identity token from the metadata server and replaces the file before expiry. |
36170| Oracle Cloud Infrastructure | Run a trusted host process that uses an instance principal to request an IDCS access token and replaces the file before expiry. |
36171| GitHub Actions | Request the job's OIDC token, write it to a protected file, and request a new token before a later exchange. |
36172| SPIFFE | Use the SPIFFE Workload API or an approved helper to write a current JWT-SVID to the file. |
36173| Custom OIDC provider | Use the issuer's workload flow to get a JWT, then refresh the protected file before the JWT expires. |
36174
36175Follow the guide for your provider to configure token issuance and inspect a
36176sample token:
36177
36178- [Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure)
36179- [AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws)
36180- [Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud)
36181- [Oracle Cloud Infrastructure](https://developers.openai.com/api/docs/guides/workload-identity-federation/oracle-cloud)
36182- [GitHub Actions](https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions)
36183- [Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes)
36184- [SPIFFE](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe)
36185
36186Decode a sample token locally and record its `iss`, `aud`, `sub`, and any other
36187claims you plan to trust. Decoding does not verify the signature. Do not paste a
36188production token into a website or write it to logs.
36189
36190#### Connect the workload
36191
36192An administrator creates the provider and federation rule before starting
36193Codex.
36194
361951. Open [Workload identity](https://admin.openai.com/workload-identity) in the
36196 OpenAI Admin Portal, then select **Connect workload**.
361972. Reuse a provider configured for Codex, or create one. Provider presets fill
36198 in common settings for GitHub Actions, Microsoft Entra ID, Google Cloud,
36199 AWS, Kubernetes, SPIFFE, and custom OIDC providers.
362003. Select **Codex** and the managed workspace the workload may use.
362014. Add the narrowest conditions that identify the workload. Match a subject,
36202 exact claims, a CEL condition, or a combination. Add accepted audiences to
36203 restrict which tokens the rule accepts. Every configured matcher must pass.
362045. Map the rule to one existing ChatGPT user or service account, or create one
36205 during setup.
362066. Review the provider, conditions, workspace, principal, scopes, and access
36207 token lifetime. Select **Connect workload**, then **Download config**.
36208
36209The downloaded file contains a non-secret federation rule ID and the path where
36210Codex will read the identity token. It does not contain a credential.
36211
36212To automate setup, use the [workload identity Admin
36213API](https://developers.openai.com/api/docs/guides/workload-identity-federation/admin-api). For matcher
36214behavior and examples, see [Federation rule
36215reference](https://developers.openai.com/api/docs/guides/workload-identity-federation/federation-rules).
36216
36217#### Configure the Codex process
36218
36219The process that starts Codex requires these two workload identity variables:
36220
36221```bash
36222export OPENAI_FEDERATION_RULE_ID="idpm_..."
36223export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"
36224```
36225
36226`OPENAI_FEDERATION_RULE_ID` is not a secret. The token file is. Use an absolute
36227path in a dedicated directory, such as `/var/run/secrets/openai.com`, owned by
36228the workload account with mode `0700`. Only trusted host processes should write
36229there. Keep the directory outside repositories and other paths available to
36230Codex tools. Keep credentials out of logs, shell history, and build artifacts.
36231
36232#### Add audit attribution
36233
36234When runtime instances share a federation rule, you can identify each instance
36235in token-issuance audit events. Set the optional
36236`OPENAI_WORKLOAD_IDENTITY_CONTEXT` variable to a JSON object encoded as a
36237string:
36238
36239```bash
36240export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
36241 "instance_id": "runner-42",
36242 "display_name": "payments-prod",
36243 "labels": {
36244 "environment": "production",
36245 "region": "us-west-2"
36246 }
36247}'
36248```
36249
36250The object requires `instance_id`. It can also contain `display_name` and up to
36251eight labels. The encoded object can be up to 1,024 bytes. `instance_id` and
36252`display_name` can be up to 128 characters. Label keys can be up to 64
36253characters, and label values can be up to 256 characters.
36254
36255Identifiers must start with an ASCII letter or number. Values can then contain
36256letters, numbers, `.`, `_`, `:`, `/`, `@`, and `-`. Label keys support letters,
36257numbers, `.`, `_`, and `-`.
36258
36259OpenAI treats this context as client-reported audit attribution, not as verified
36260workload identity. It does not affect authentication, authorization, rule
36261matching, scopes, rate limits, revocation, feature gates, or metrics. Do not put
36262credentials, secrets, personal data, prompts, model output, or other Customer
36263Content in it.
36264
36265For valid context, OpenAI derives a stable attribution ID scoped to the tenant,
36266provider, federation rule, and `instance_id`. For attribution, the access token
36267contains the ID but not the context. The successful token-issuance audit event
36268contains the ID and the normalized context. Context that exceeds a limit or
36269violates this schema makes the exchange fail with `invalid_grant`.
36270
36271Codex reads the context when the process starts and does not pass it, the rule
36272ID, or the token-file path to model-controlled shells, hooks, or MCP servers.
36273Restart Codex after changing the context.
36274
36275#### Protect and rotate the token file
36276
36277For managed Linux, macOS, and WSL deployments, add the entire token directory to
36278[`permissions.filesystem.deny_read`](https://learn.chatgpt.com/docs/enterprise/managed-configuration#enforce-deny-read-requirements)
36279in managed requirements:
36280
36281```toml
36282[permissions.filesystem]
36283deny_read = ["/var/run/secrets/openai.com"]
36284```
36285
36286This blocks model-controlled commands from reading the active token or a
36287temporary replacement while the Codex host process can still use the token for
36288exchange. For projected-token volumes, deny the entire token mount and any
36289backing or resolved target paths outside it. File modes and environment-variable
36290scrubbing alone do not protect credentials from another process running as the
36291same user. On native Windows, use the elevated sandbox described above.
36292
36293For token sources that do not project a file, have a trusted host process write
36294each replacement inside that protected directory and rename it into place. An
36295atomic rename prevents Codex from reading a partial token. For example, adapt
36296this host-owned refresh script to your provider's token command. Provision the
36297directory before running the script:
36298
36299```bash
36300set -eu
36301TOKEN_DIR="/var/run/secrets/openai.com"
36302TOKEN_FILE="$TOKEN_DIR/identity-token"
36303umask 077
36304TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
36305trap 'rm -f -- "$TOKEN_TEMP"' EXIT
36306trap 'exit 1' HUP INT TERM
36307your-identity-provider-command > "$TOKEN_TEMP"
36308test -s "$TOKEN_TEMP"
36309mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"
36310```
36311
36312Run the refresh process outside any shell or tool that Codex can control. Keep
36313the read denial in place during refresh and cleanup. Even if a forced stop
36314leaves a temporary file behind, that file must remain inside the denied
36315directory. Do not put workload identity settings in `config.toml`.
36316
36317#### Verify the connection
36318
36319Load the downloaded environment and inspect the selected authentication method:
36320
36321```bash
36322. ./workload-identity-idpm_example.env
36323codex login status
36324```
36325
36326In PowerShell:
36327
36328```powershell
36329$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
36330$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
36331codex login status
36332```
36333
36334A successful check prints `Logged in using workload identity`. This confirms
36335that Codex exchanged a token through the configured federation rule. The command
36336does not print the resolved workspace, principal, or rule. Confirm those values
36337in the Admin Portal before you start the workload. If Codex reports another
36338authentication method, the two required WIF variables did not reach the process.
36339
36340If the provider uses **Prevent assertion replay** and the assertion has a `jti`
36341claim, this check consumes that `jti`. Write a newly issued assertion with a new
36342`jti` before starting another Codex process.
36343
36344Run a small request from the same environment:
36345
36346```bash
36347codex exec "Reply with only: workload identity is working"
36348```
36349
36350Codex exchanges the upstream token and keeps the OpenAI access token in memory.
36351It does not write either credential to `auth.json`, the system keyring, or
36352`config.toml`.
36353
36354#### Keep the token current
36355
36356Refresh the identity-token file before the upstream token expires. Codex rereads
36357the file when it needs another OpenAI access token. The OpenAI token expires at
36358the earlier of the upstream token's expiry or the federation rule's lifetime,
36359and never lasts longer than one hour.
36360
36361When an administrator turns on replay protection, each upstream JWT must have a
36362unique `jti`. Write a newly issued assertion with a new `jti` before each
36363exchange, including refreshes in a long-running process. Assertions without
36364`jti` do not receive replay protection.
36365
36366Codex shares one in-memory exchange session inside each host process. Concurrent
36367requests in that process reuse a valid OpenAI access token and share one refresh
36368when it expires. Separate processes perform separate exchanges, so they need
36369assertions that the provider permits them to use.
36370
36371#### Credential precedence
36372
36373The two required workload identity variables take precedence over every other
36374credential source:
36375
363761. If either `OPENAI_FEDERATION_RULE_ID` or
36377 `OPENAI_IDENTITY_TOKEN_FILE` is present, Codex selects workload identity.
363782. If only one required variable is present, Codex returns an error. It does not
36379 fall back to an API key, access token, or stored login.
363803. `OPENAI_WORKLOAD_IDENTITY_CONTEXT` alone does not select workload identity.
363814. When neither required WIF variable is present, Codex applies the normal
36382 credential rules for that surface. For surfaces that allow API key
36383 authentication, `CODEX_API_KEY` takes precedence on `codex exec`,
36384 `codex review`, the TypeScript SDK, and `codex exec-server --remote`. Other
36385 surfaces can use `CODEX_ACCESS_TOKEN` or a stored login.
36386
36387An SDK `apiKey` option becomes `CODEX_API_KEY`, but WIF still takes precedence
36388when either required WIF variable is present. Omit the option when using WIF so
36389the workload does not carry an unused long-lived credential.
36390
36391To move an existing workload without downtime, configure WIF while its current
36392credential is still available. Start a new process with both required WIF
36393variables; WIF takes precedence even if the old credential is still present.
36394After the workload succeeds with WIF, remove the old credential from its runtime
36395and secrets store, then revoke it. Before revocation, you can roll back by
36396removing both required WIF variables and starting a new process.
36397
36398#### Supported Codex surfaces
36399
36400Configure workload identity on the machine that owns the Codex process.
36401
36402| Surface | Support and host boundary |
36403| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
36404| Interactive `codex`, `resume`, and `fork` | Supported. Start the CLI in the configured environment. |
36405| `codex exec`, `exec resume`, and `codex review` | Supported. Either required WIF variable makes WIF take precedence. |
36406| TypeScript SDK | Supported. The parent process supplies the required WIF variables and any optional attribution context. |
36407| `codex app-server` | Supported. Configure WIF on the app-server host, not on a remote client. |
36408| `codex exec-server --remote` | Supported for authentication to the remote environment registry. Configure WIF on the exec-server host. |
36409| Local exec-server process operations | Do not use WIF authentication. They run through the local exec-server protocol. |
36410| `codex mcp-server` | Not supported. |
36411
36412Remote app-server and exec-server clients never send the upstream identity
36413token over their protocols.
36414
36415#### Change or remove access
36416
36417Changes to a rule's subjects, audiences, claims, CEL condition, scopes, or token
36418lifetime apply to new exchanges. A token issued before the change can remain
36419valid until its lifetime ends.
36420
36421Disable a provider or rule to stop access immediately. Disablement blocks new
36422exchanges and revokes OpenAI access tokens already issued through that resource.
36423Archiving has the same access effect and cannot be undone. Changing provider
36424trust also revokes issued tokens before the new trust takes effect.
36425
36426#### Audit changes
36427
36428Provider and federation rule creation, updates, and archival generate audit
36429events. Use the [Compliance API and audit event
36430guidance](https://learn.chatgpt.com/docs/enterprise/compliance-api) to export the events your workspace
36431supports. Correlate them with your identity provider's issuance logs, and do not
36432record upstream assertions or OpenAI access tokens in either system.
36433
36434When the process supplies `OPENAI_WORKLOAD_IDENTITY_CONTEXT`, successful
36435token-issuance audit events also contain the stable attribution ID and
36436normalized context described above.
36437
36438#### Troubleshoot
36439
36440| Symptom | Check |
36441| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
36442| Codex reports incomplete workload identity configuration | Set both required variables in the same process and use an absolute token-file path. |
36443| Codex reports that its login policy does not permit workload identity | Allow ChatGPT authentication in the effective policy and include the rule's workspace in its permitted workspaces. |
36444| Codex reports another credential | Load both required WIF variables into the Codex process, then start a new process and rerun `codex login status`. |
36445| OpenAI rejects workload context | Check its JSON shape, size, allowed characters, and field limits. Remove sensitive or Customer Content. |
36446| OpenAI rejects the token | Compare `iss`, `aud`, expiry, signature key, and assertion lifetime with the provider configuration. |
36447| The rule does not match | Confirm the client uses the intended rule ID and that every subject, audience, exact-claim, and CEL check passes. |
36448| OpenAI rejects the principal | Confirm the user or service account is active and is an active member of the selected workspace. |
36449| OpenAI rejects a repeated assertion | Get a new JWT with a new `jti`; do not retry the same replay-protected assertion. |
36450| A long-running process stops refreshing | Confirm the host refresh process is still replacing the token file before expiry. |
36451
36452For provider verification, limits, and CEL details, see the [federation rule
36453reference](https://developers.openai.com/api/docs/guides/workload-identity-federation/federation-rules).
36454
35558### Workspace analytics36455### Workspace analytics
35559 36456
35560Source: [Workspace analytics](https://learn.chatgpt.com/docs/enterprise/workspace-analytics.md)36457Source: [Workspace analytics](https://learn.chatgpt.com/docs/enterprise/workspace-analytics.md)
35617 36514
35618Source: [Workspace model availability](https://learn.chatgpt.com/docs/enterprise/workspace-model-availability.md)36515Source: [Workspace model availability](https://learn.chatgpt.com/docs/enterprise/workspace-model-availability.md)
35619 36516
35620Model availability depends on the product surface and authentication boundary.36517The models available to someone depend on the product surface and how they
35621A ChatGPT workspace model setting isn't a universal model switch for Codex in36518signed in. A model setting in your ChatGPT workspace doesn't automatically
35622the ChatGPT desktop app, Codex CLI, IDE extension, Codex cloud, or Platform API.36519apply to Codex in the ChatGPT desktop app, Codex CLI, the IDE extension, Codex
36520cloud, or the OpenAI API.
35623 36521
35624For the complete administration model, see36522For the complete administration model, see
35625[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).36523[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).
35638effect for Codex in the ChatGPT desktop app, Codex CLI, IDE extension, Codex36536effect for Codex in the ChatGPT desktop app, Codex CLI, IDE extension, Codex
35639cloud, and the API Platform.36537cloud, and the API Platform.
35640 36538
36539#### Set a clear starting experience for employees
36540
36541Review [Models settings](https://help.openai.com/en/articles/8411955) for your
36542workspace before inviting a pilot group. Workspace owners and admins can
36543configure separate starting defaults for Chat and for Work and Codex. Where
36544supported, choose a starting model, reasoning level, speed, and new-chat
36545behavior for Chat, Work, and local Codex surfaces.
36546
36547Treat these choices as defaults, not permissions. Available models still depend
36548on the member's seat, role, workspace or API identity, enforced workspace
36549requirements, and the specific surface they're using. Starting defaults don't
36550grant access to unavailable models or override those requirements. Codex cloud
36551doesn't support changing its default model.
36552
36553Fast mode availability depends on the workspace, product surface, and any
36554enforced `features.fast_mode` setting in
36555[`requirements.toml`](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).
36556This setting can pin Fast mode on or off for managed local Codex clients; it
36557isn't a starting default and can't override workspace or product availability.
36558
35641#### Prepare for the GPT-5.4 retirement36559#### Prepare for the GPT-5.4 retirement
35642 36560
35643On August 31, 2026, GPT-5.4 and GPT-5.4 mini retire from Codex for users signed36561On August 31, 2026, GPT-5.4 and GPT-5.4 mini retire from Codex for users signed
35714 36632
35715- [Authentication overview](https://learn.chatgpt.com/docs/auth): Compare sign-in methods, credential storage, and enforcement controls.36633- [Authentication overview](https://learn.chatgpt.com/docs/auth): Compare sign-in methods, credential storage, and enforcement controls.
35716 36634
36635- [Workload identity](https://learn.chatgpt.com/docs/enterprise/workload-identity): Let trusted workloads use Codex without long-lived credentials.
36636
35717- [Personal Access Tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens): Create and manage tokens for programmatic access.36637- [Personal Access Tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens): Create and manage tokens for programmatic access.
35718 36638
35719- [Service accounts](https://learn.chatgpt.com/docs/enterprise/service-accounts): Create and manage workspace identities for automated workflows.36639- [Service accounts](https://learn.chatgpt.com/docs/enterprise/service-accounts): Create and manage workspace identities for automated workflows.
