OpenAI - Codex Docs Changes 2026-03-09 00:34 UTC → 2026-03-16 18:25 UTC

10 10 

11For a high-level explanation of how sandboxing works across the Codex app, IDE11For a high-level explanation of how sandboxing works across the Codex app, IDE

12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).

13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

13 14 

14## Sandbox and approvals15## Sandbox and approvals

15 16 

41- Find and fix bugs in my codebase with minimal, high-confidence changes.41- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 42 

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

44 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

44 45 

45---46---

46 47 

2 2 

3Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can combine automations with [skills](https://developers.openai.com/codex/skills) for more complex tasks.3Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can combine automations with [skills](https://developers.openai.com/codex/skills) for more complex tasks.

4 4 

5Automations run locally in the Codex app. The app needs to be running, and the5Automations run in the background in the Codex app. The app needs to be

6selected project needs to be available on disk.6running, and the selected project needs to be available on disk.

7 7 

8In Git repositories, each automation run starts in a new8In Git repositories, you can choose whether an automation runs in your local

9[worktree](https://developers.openai.com/codex/app/worktrees) so it doesn’t interfere with your main9project or on a new [worktree](https://developers.openai.com/codex/app/worktrees). Both options run in the

10checkout. In non-version-controlled projects, automations run directly in the10background. Worktrees keep automation changes separate from unfinished local

11work, while running in your local project can modify files you are still

12working on. In non-version-controlled projects, automations run directly in the

11project directory.13project directory.

12 14 

13![Automation creation form with schedule and prompt fields](/images/codex/app/create-automation-light.webp)15You can also leave the model and reasoning effort on their default settings, or

16choose them explicitly if you want more control over how the automation runs.

17 

18![Automation creation form with schedule and prompt fields](/images/codex/app/codex-automations-light.webp)

14 19 

15## Managing tasks20## Managing tasks

16 21 

18 23 

19The "Triage" section acts as your inbox. Automation runs with findings show up there, and you can filter your inbox to show all automation runs or only unread ones.24The "Triage" section acts as your inbox. Automation runs with findings show up there, and you can filter your inbox to show all automation runs or only unread ones.

20 25 

21When an automation runs in a Git repository, Codex uses a dedicated background [worktree](https://developers.openai.com/codex/app/features#worktree-support). In non-version-controlled projects, automations run directly in the project directory. Consider using Git to enable running on background worktrees. You can have the same automation run on multiple projects.26For Git repositories, each automation can run either in your local project or

27on a dedicated background [worktree](https://developers.openai.com/codex/app/features#worktree-support). Use

28worktrees when you want to isolate automation changes from unfinished local

29work. Use local mode when you want the automation to work directly in your main

30checkout, keeping in mind that it can modify files you are actively editing.

31In non-version-controlled projects, automations run directly in the project

32directory. You can have the same automation run on multiple projects.

22 33 

23Automations use your default sandbox settings. In read-only mode, tool calls fail if they require modifying files, network access, or working with apps on your computer. With full access enabled, background automations carry elevated risk. You can adjust sandbox settings in [Settings](https://developers.openai.com/codex/app/settings) and selectively allowlist commands with [rules](https://developers.openai.com/codex/rules).34Automations use your default sandbox settings. In read-only mode, tool calls fail if they require modifying files, network access, or working with apps on your computer. With full access enabled, background automations carry elevated risk. You can adjust sandbox settings in [Settings](https://developers.openai.com/codex/app/settings) and selectively allowlist commands with [rules](https://developers.openai.com/codex/rules).

24 35 

30first. This helps you confirm:41first. This helps you confirm:

31 42 

32- The prompt is clear and scoped correctly.43- The prompt is clear and scoped correctly.

33- The selected model and tools behave as expected.44- The selected or default model, reasoning effort, and tools behave as expected.

34- The resulting diff is reviewable.45- The resulting diff is reviewable.

35 46 

36When you start scheduling runs, review the first few outputs closely and adjust47When you start scheduling runs, review the first few outputs closely and adjust

38 49 

39## Worktree cleanup for automations50## Worktree cleanup for automations

40 51 

41For Git repositories, automations run in worktrees. Frequent schedules can52If you choose worktrees for Git repositories, frequent schedules can create

42create many worktrees over time. Archive automation runs you no longer need,53many worktrees over time. Archive automation runs you no longer need, and avoid

43and avoid pinning runs unless you intend to keep their worktrees.54pinning runs unless you intend to keep their worktrees.

44 55 

45## Permissions and security model56## Permissions and security model

46 57 

48| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |48| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |

49| `/status` | Show the thread ID, context usage, and rate limits. |49| `/status` | Show the thread ID, context usage, and rate limits. |

50 50 

51## Deeplinks

52 

53The Codex app registers the `codex://` URL scheme so links can open specific parts of the app directly.

54 

55| Deeplink | Opens | Supported query parameters |

56| --- | --- | --- |

57| `codex://settings` | Settings. | None. |

58| `codex://skills` | Skills. | None. |

59| `codex://automations` | Inbox in automation create mode. | None. |

60| `codex://threads/<thread-id>` | A local thread. `<thread-id>` must be a UUID. | None. |

61| `codex://new` | A new thread. | Optional: `prompt`, `originUrl`, `path`. |

62 

63For new-thread deeplinks:

64 

65- `prompt` prefills the composer.

66- `path` must be an absolute path to a local directory and, when valid, makes that directory the active workspace for the new thread.

67- `originUrl` tries to match one of your current workspace roots by Git remote URL. If both `path` and `originUrl` are present, Codex resolves `path` first.

68 

51## See also69## See also

52 70 

53- [Features](https://developers.openai.com/codex/app/features)71- [Features](https://developers.openai.com/codex/app/features)

85pressing <kbd>Cmd</kbd>+<kbd>J</kbd>.85pressing <kbd>Cmd</kbd>+<kbd>J</kbd>.

86 86 

87Use the terminal to validate changes, run scripts, and perform Git operations87Use the terminal to validate changes, run scripts, and perform Git operations

88without leaving the app.88without leaving the app. Codex can also read the current terminal output, so

89it can check the status of a running development server or refer back to a

90failed build while it works with you.

89 91 

90Common tasks include:92Common tasks include:

91 93 

10require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts or prevent sleep while a10require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts or prevent sleep while a

11thread runs.11thread runs.

12 12 

13## Appearance

14 

15Pick a theme, decide whether the window is solid, and adjust UI or code fonts. Font

16choices apply across the app, including the diff review panel and terminal.

17 

18## Notifications13## Notifications

19 14 

20Choose when turn completion notifications appear, and whether the app should prompt for15Choose when turn completion notifications appear, and whether the app should prompt for

27options. See [Codex security](https://developers.openai.com/codex/agent-approvals-security) and22options. See [Codex security](https://developers.openai.com/codex/agent-approvals-security) and

28[config basics](https://developers.openai.com/codex/config-basic) for more detail.23[config basics](https://developers.openai.com/codex/config-basic) for more detail.

29 24 

25## Appearance

26 

27In **Settings**, you can change the Codex app appearance by choosing a base theme,

28adjusting accent, background, and foreground colors, and changing the UI and code

29fonts. You can also share your custom theme with friends.

30 

31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)

32 

30## Git33## Git

31 34 

32Use Git settings to standardize branch naming and choose whether Codex uses force35Use Git settings to standardize branch naming and choose whether Codex uses force

47experimental. For the best Windows experience, use Codex in a WSL workspace47experimental. For the best Windows experience, use Codex in a WSL workspace

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).

49 49 

50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

51 

50---52---

51 53 

52## Work with the Codex CLI54## Work with the Codex CLI

1# Codex Meetups1# Codex Meetups

2 2 

3Mar 123Mar 17

4 4 

5![Stylized city cover for Orlando](https://developers.openai.com/codex/meetups/orlando.webp)5![Stylized city cover for San Francisco](https://developers.openai.com/codex/meetups/san-francisco.webp)

6 6 

7UpcomingMar 127UpcomingMar 17

8 8 

9Orlando, FL, USA9San Francisco, California, USA

10 10 

11### Orlando11### Community Hackathon - San Francisco

12 12 

13March 12, 202613March 17, 2026

14 14 

15Hosted by [Leonard](https://www.linkedin.com/in/lgofman/), [Michael](https://www.linkedin.com/in/michael-rusudev/), and [Carlos](https://www.linkedin.com/in/cataladev/)15Hosted by [Adam Chan](https://x.com/itsajchan)

16 16 

17[Register now](https://luma.com/39y2dvwx)[Share city](https://developers.openai.com/codex/community/meetups?city=Orlando)17[Register now (opens in a new tab)](https://luma.com/openclaw-hack-night-mar17-2026)[Share city](https://developers.openai.com/codex/community/meetups?city=San%20Francisco)

1# Admin Setup1# Admin Setup

2 2 

3![Codex enterprise admin toggle](/images/codex/codex_enterprise_admin.png)

4 

3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.5This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.

4 6 

5Use this page as the step-by-step rollout guide. It focuses on setup order and decision points. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).7Use this page as the step-by-step rollout guide. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

6 8 

7## Enterprise-grade security and privacy9## Enterprise-grade security and privacy

8 10 

9Codex supports ChatGPT Enterprise security features, including:11Codex supports ChatGPT Enterprise security features, including:

10 12 

11- No training on enterprise data13- No training on enterprise data

12- Zero data retention for the App, CLI, and IDE (code remains in developer environment)14- Zero data retention for the App, CLI, and IDE (code stays in the developer environment)

13- Residency and retention that follow ChatGPT Enterprise policies15- Residency and retention that follow ChatGPT Enterprise policies

14- Granular user access controls16- Granular user access controls

15- Data encryption at rest (AES-256) and in transit (TLS 1.2+)17- Data encryption at rest (AES-256) and in transit (TLS 1.2+)

18- Audit logging via the ChatGPT Compliance API

16 19 

17For security controls and runtime protections, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.20For security controls and runtime protections, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.

21For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

18 22 

19## Local vs. cloud setup23## Pre-requisites: Determine owners and rollout strategy

20 

21Codex operates in two environments: local and cloud.

22 

231. **Codex local** includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.

242. **Codex cloud** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

25 

26You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

27 

28## Step 0: Owners and rollout decision

29 

30Ensure you have the following owners:

31 24 

32- Workspace owner with access to ChatGPT Enterprise25During your rollout, team members may support different aspects of integrating Codex into your organization. Ensure you have the following owners:

33- IT management owner for managed configuration

34- Governance owner for analytics / compliance review

35 26 

36A rollout decision:27- **ChatGPT Enterprise workspace owner:** required to configure Codex settings in your workspace.

28- **Security owner:** determines agent permissions settings for Codex.

29- **Analytics owner:** integrates analytics and compliance APIs into your data pipelines.

37 30 

38- Codex local only (Codex app, CLI, and IDE extension)31Decide which Codex surfaces you will use:

39- Codex cloud only (Codex web, GitHub code review)

40- Both local + cloud

41 32 

42Review [authentication](https://developers.openai.com/codex/auth) before rollout:33- **Codex local:** includes the Codex app, CLI, and IDE extension. The agent runs on the developer's computer in a sandbox.

34- **Codex cloud:** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

35- **Both:** use local + cloud together.

43 36 

44- Codex local supports ChatGPT sign-in or API keys. Confirm MFA/SSO requirements and any managed login restrictions in authentication37You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

45- Codex cloud requires ChatGPT sign-in

46 38 

47## Step 1: Enable workspace toggles39## Step 1: Enable Codex in your workspace

48 40 

49Turn on only the Codex features you plan to roll out in this phase.41You configure access to Codex in ChatGPT Enterprise workspace settings.

50 42 

51Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).43Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

52 44 

53### Codex local45### Codex local

54 46 

47Codex local is enabled by default for new ChatGPT Enterprise workspaces. If

48 you are not a ChatGPT workspace owner, you can test whether you have access by

49 [installing Codex](https://developers.openai.com/codex/quickstart) and logging in with your work email.

50 

55Turn on **Allow members to use Codex Local**.51Turn on **Allow members to use Codex Local**.

56 52 

57This enables use of the Codex app, CLI, and IDE extension for allowed users.53This enables use of the Codex app, CLI, and IDE extension for allowed users.

60 56 

61#### Enable device code authentication for Codex CLI57#### Enable device code authentication for Codex CLI

62 58 

63Allow developers to sign in with device codes when using Codex CLI in a non-interactive environment. More details in [authentication](https://developers.openai.com/codex/auth/).59Allow developers to sign in with a device code when using Codex CLI in a non-interactive environment (for example, a remote development box). More details are in [authentication](https://developers.openai.com/codex/auth/).

64 60 

65![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)61![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)

66 62 

82 78 

83Note that it may take up to 10 minutes for Codex to appear in ChatGPT.79Note that it may take up to 10 minutes for Codex to appear in ChatGPT.

84 80 

85#### Allow members to administer Codex

86 

87Allows users to view overall Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics), access [cloud-managed requirements](https://chatgpt.com/codex/settings/managed-configs), and manage Cloud environments (edit and delete).

88 

89Codex cloud not required.

90 

91#### Enable Codex Slack app to post answers on task completion81#### Enable Codex Slack app to post answers on task completion

92 82 

93Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.83Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.

98 88 

99By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.89By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.

100 90 

101This setting enables users to use an allowlist for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.91This setting lets users use an allowlist for common software dependency domains, add domains and trusted sites, and specify allowed HTTP methods.

102 92 

103For security implications of internet access and runtime controls, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).93For security implications of internet access and runtime controls, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

104 94 

106 96 

107## Step 2: Set up custom roles (RBAC)97## Step 2: Set up custom roles (RBAC)

108 98 

109Use RBAC to control which users or groups can access Codex local and Codex cloud.99Use RBAC to control granular permissions for access Codex local and Codex cloud.

100 

101![Codex cloud toggle](/images/codex/enterprise/rbac_custom_roles.png)

110 102 

111### What RBAC lets you do103### What RBAC lets you do

112 104 

113Workspace Owners can use RBAC in ChatGPT admin settings to:105Workspace Owners can use RBAC in ChatGPT admin settings to:

114 106 

115- Set a default role for users who are not assigned any custom role107- Set a default role for users who aren't assigned any custom role

116- Create custom roles with granular permissions108- Create custom roles with granular permissions

117- Assign one or more custom roles to Groups (including SCIM-synced groups)109- Assign one or more custom roles to Groups

110- Automatically sync users into Groups via SCIM

118- Manage roles centrally from the Custom Roles tab111- Manage roles centrally from the Custom Roles tab

119 112 

120Users can inherit multiple roles, and permissions resolve to the maximum allowed across those roles.113Users can inherit more than one role, and permissions resolve to the most permissive (least restrictive) access across those roles.

114 

115### Create a Codex Admin group

116 

117Set up a dedicated "Codex Admin" group rather than granting Codex administration to a broad audience.

118 

119The **Allow members to administer Codex** toggle grants the Codex Admin role. Codex Admins can:

120 

121- View Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics)

122- Open the Codex [Policies page](https://chatgpt.com/codex/settings/policies) to manage cloud-managed `requirements.toml` policies

123- Assign those managed policies to user groups or configure a default fallback policy

124- Manage Codex cloud environments, including editing and deleting environments

125 

126Use this role for the small set of admins who own Codex rollout, policy management, and governance. It's not required for general Codex users. You don't need Codex cloud to enable this toggle.

127 

128Recommended rollout pattern:

129 

130- Create a "Codex Users" group for people who should use Codex

131- Create a separate "Codex Admin" group for the smaller set of people who should manage Codex settings and policies

132- Assign the custom role with **Allow members to administer Codex** enabled only to the "Codex Admin" group

133- Keep membership in the "Codex Admin" group limited to workspace owners or designated platform, IT, and governance operators

134- If you use SCIM, back the "Codex Admin" group with your identity provider so membership changes are auditable and centrally managed

121 135 

122### Important behavior to plan for136This separation makes it easier to roll out Codex while keeping analytics, environment management, and policy deployment limited to trusted admins. For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).

123 137 

124Users in any custom role group do not use the workspace default permissions.138## Step 3: Configure Codex local requirements

125 139 

126If you are gradually rolling out Codex, one suggestion is to have a “Codex Users” group and a second “Codex Admin” group that has the “Allow members to administer Codex” toggle enabled.140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

127 141 

128For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.

129 143 

130## Step 3: Configure Codex local managed settings144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

131 145 

132For Codex local, set an admin-approved baseline for local behavior before broader rollout.146Recommended setup:

133 147 

134### Use managed configuration for two different goals1481. Create a baseline policy for most users, then create stricter or more permissive variants only where needed.

1492. Assign each managed policy to a specific user group, and configure a default fallback policy for everyone else.

1503. Order group rules with care. If a user matches more than one group-specific rule, the first matching rule applies.

1514. Treat each policy as a complete profile for that group. Codex doesn't fill missing fields from later matching group rules.

135 152 

136- **Requirements** (`requirements.toml`): Admin-enforced constraints users cannot override153These cloud-managed policies apply across Codex local surfaces when users sign in with ChatGPT, including the Codex app, CLI, and IDE extension.

137- **Managed defaults** (`managed_config.toml`): Starting values applied when Codex launches

138 154 

139### Team Config155### Example requirements.toml policies

156 

157Use cloud-managed `requirements.toml` policies to enforce the guardrails you want for each group. The snippets below are examples you can adapt, not required settings.

158 

159![Example managed requirements policy](/images/codex/enterprise/example_policy.png)

160 

161Example: limit web search, sandbox mode, and approvals for a standard local rollout:

162 

163```toml

164allowed_web_search_modes = ["disabled", "cached"]

165allowed_sandbox_modes = ["workspace-write"]

166allowed_approval_policies = ["on-request"]

167```

168 

169Example: add a restrictive command rule when you want admins to block or gate specific commands:

170 

171```toml

172[rules]

173prefix_rules = [

174 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating remote history." },

175]

176```

177 

178You can use either example on its own or combine them in a single managed policy for a group. For exact keys, precedence, and more examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

179 

180### Checking user policies

181 

182Use the policy lookup tools at the end of the workflow to confirm which managed policy applies to a user. You can check policy assignment by group or by entering a user email.

183 

184![Policy lookup by group or user email](/images/codex/enterprise/policy_lookup.png)

185 

186If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

187 

188## Step 4: Standardize local configuration with Team Config

140 189 

141Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.190Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.

142 191 

192You can check Team Config settings into the repository under the `.codex` directory. Codex automatically picks up Team Config settings when a user opens that repository.

193 

194Start with Team Config for your highest-traffic repositories so teams get consistent behavior in the places they use Codex most.

195 

143| Type | Path | Use it to |196| Type | Path | Use it to |

144| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |197| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

145| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |198| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |

148 201 

149For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).202For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).

150 203 

151### Recommended first decisions for local rollout204## Step 5: Configure Codex cloud usage (if enabled)

152 205 

153Define a baseline for your pilot:206This step covers repository and environment setup after you enable the Codex cloud workspace toggle.

154 

155- Approval policy posture

156- Sandbox mode posture

157- Web search posture

158- MCP / connectors policy

159- Local logging and telemetry posture

160 

161For exact keys, precedence, MDM deployment, and examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

162 

163If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

164 

165## Step 4: Configure Codex cloud usage (if enabled)

166 

167This step covers repository and environment setup after the Codex cloud workspace toggle is enabled.

168 207 

169### Connect Codex cloud to repositories208### Connect Codex cloud to repositories

170 209 

1711. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**2101. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**

1722. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT2112. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT

1733. Install or authorize the ChatGPT GitHub Connector2123. Install or connect the ChatGPT GitHub Connector

1744. Choose an installation target for the ChatGPT Connector (typically your main organization)2134. Choose an installation target for the ChatGPT Connector (typically your main organization)

1755. Allow the repositories you want to connect to Codex2145. Allow the repositories you want to connect to Codex

176 215 

216For GitHub Enterprise Managed Users (EMU), an organization owner must install

217 the Codex GitHub App for the organization before users can connect

218 repositories in Codex cloud.

219 

177For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).220For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).

178 221 

179Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.222Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.

180 223 

181### Configure IP addresses (as needed)224### Configure IP addresses

182 225 

183Configure connector / IP allow lists if required by your network policy with these [egress IP ranges](https://openai.com/chatgpt-agents.json).226If your GitHub organization controls the IP addresses that apps use to connect, make sure to include these [egress IP ranges](https://openai.com/chatgpt-agents.json).

184 227 

185These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.228These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.

186 229 

188 231 

189To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).232To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).

190 233 

191Code review can be configured at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details on [GitHub](https://developers.openai.com/codex/integrations/github) integration page.234You can configure code review at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details are on the [GitHub integration page](https://developers.openai.com/codex/integrations/github).

235 

236Use the overview page to confirm your workspace has code review turned on and to see the available review controls.

237 

238![Code review settings overview](/images/codex/enterprise/code_review_settings_overview.png)

239 

240 Use the auto review settings to decide whether Codex should review pull

241 requests automatically for connected repositories.

242 

243![Automatic code review settings](/images/codex/enterprise/auto_code_review_settings.png)

244 

245 Use review triggers to control which pull request events should start a

246 Codex review.

247 

248![Code review trigger settings](/images/codex/enterprise/review_triggers.png)

249 

250### Configure Codex security

192 251 

193Additional integration docs for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).252Codex Security helps engineering and security teams find, confirm, and remediate likely vulnerabilities in connected GitHub repositories.

194 253 

195## Step 5: Set up governance and observability254At a high level, Codex Security:

196 255 

197Codex gives enterprise teams several options for visibility into adoption and impact. Set up governance early so your team can monitor adoption, investigate issues, and support compliance workflows.256- scans connected repositories commit by commit

257- ranks likely findings and confirms them when possible

258- shows structured findings with evidence, criticality, and suggested remediation

259- lets teams refine a repository threat model to improve prioritization and review quality

260 

261For setup, scan creation, findings review, and threat model guidance, see [Codex Security setup](https://developers.openai.com/codex/security/setup). For a product overview, see [Codex Security](https://developers.openai.com/codex/security).

262 

263Integration docs are also available for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).

264 

265## Step 6: Set up governance and observability

266 

267Codex gives enterprise teams options for visibility into adoption and impact. Set up governance early so your team can track adoption, investigate issues, and support compliance workflows.

198 268 

199### Codex governance typically uses269### Codex governance typically uses

200 270 

201- Analytics Dashboard for quick, self-serve visibility271- Analytics Dashboard for quick, self-serve visibility

202- Analytics API for programmatic reporting and BI integration272- Analytics API for programmatic reporting and business intelligence integration

203- Compliance API for audit and investigation workflows273- Compliance API for audit and investigation workflows

204 274 

205### Recommended minimum setup275### Recommended baseline setup

206 276 

207- Assign an owner for adoption reporting277- Assign an owner for adoption reporting

208- Assign an owner for audit and compliance review278- Assign an owner for audit and compliance review

209- Define a review cadence279- Define a review cadence

210- Decide what success looks like280- Decide what success looks like

211 281 

212For details and examples, see [Governance](https://developers.openai.com/codex/enterprise/governance).282### Analytics API setup steps

283 

284To set up the Analytics API key:

285 

2861. Sign in to the [OpenAI API Platform Portal](https://platform.openai.com) as an owner or admin, and select the correct organization.

2872. Go to the [API keys page](https://platform.openai.com/settings/organization/api-keys).

2883. Create a new secret key dedicated to Codex Analytics, and give it a descriptive name such as Codex Analytics API.

2894. Select the appropriate project for your organization. If you only have one project, the default project is fine.

2905. Set the key permissions to Read only, since this API only retrieves analytics data.

2916. Copy the key value and store it securely, because you can only view it once.

2927. Email [support@openai.com](mailto:support@openai.com) to have that key scoped to `codex.enterprise.analytics.read` only. Wait for OpenAI to confirm your API key has Codex Analytics API access.

293 

294![Codex analytics key creation](/images/codex/codex_analytics_key.png)

295 

296To use the Analytics API key:

297 

2981. Find your `workspace_id` in the [ChatGPT Admin console](https://chatgpt.com/admin) under Workspace details.

2992. Call the Analytics API at `https://api.chatgpt.com/v1/analytics/codex` using your Platform API key, and include your `workspace_id` in the path.

3003. Choose the endpoint you want to query:

301 

302- /workspaces/`{workspace_id}`/usage

303- /workspaces/`{workspace_id}`/code_reviews

304- /workspaces/`{workspace_id}`/code_review_responses

305 

3064. Set a reporting date range with `start_time` and `end_time` if needed.

3075. Retrieve the next page of results with `next_page` if the response spans more than one page.

308 

309Example curl command to retrieve workspace usage:

310 

311```bash

312curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \

313 "https://api.chatgpt.com/v1/analytics/codex/workspaces/WORKSPACE_ID/usage"

314```

315 

316For more details on the Analytics API, see [Analytics API](https://developers.openai.com/codex/enterprise/governance#analytics-api).

317 

318### Compliance API setup steps

319 

320To set up the Compliance API key:

321 

3221. Sign in to the [OpenAI API Platform Portal](https://platform.openai.com) as an owner or admin, and select the correct organization.

3232. Go to the [API keys page](https://platform.openai.com/settings/organization/api-keys).

3243. Create a new secret key dedicated to Compliance API and select the appropriate project for your organization. If you only have one project, the default project is fine.

3254. Choose All permissions.

3265. Copy the key value and store it securely, because you can only view it once.

3276. Send an email to [support@openai.com](mailto:support@openai.com) with:

328 

329- the last 4 digits of the API key

330- the key name

331- the created-by name

332- the scope needed: `read`, `delete`, or both

333 

3347. Wait for OpenAI to confirm your API key has Compliance API access.

335 

336To use the Compliance API key:

337 

3381. Find your `workspace_id` in the [ChatGPT Admin console](https://chatgpt.com/admin) under Workspace details.

3392. Use the Compliance API at `https://api.chatgpt.com/v1/`

3403. Pass your Compliance API key in the Authorization header as a Bearer token.

3414. For Codex-related compliance data, use these endpoints:

342 

343- /compliance/workspaces/`{workspace_id}`/logs

344- /compliance/workspaces/`{workspace_id}`/logs/`{log_file_id}`

345- /compliance/workspaces/`{workspace_id}`/codex_tasks

346- /compliance/workspaces/`{workspace_id}`/codex_environments

347 

3485. For most Codex compliance integrations, start with the logs endpoint and request Codex event types such as CODEX_LOG or CODEX_SECURITY_LOG.

3496. Use /logs to list available Codex compliance log files, then /logs/`{log_file_id}` to download a specific file.

350 

351Example curl command to list compliance log files:

352 

353```bash

354curl -L -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

355 "https://api.chatgpt.com/v1/compliance/workspaces/WORKSPACE_ID/logs?event_type=CODEX_LOG&after=2026-03-01T00:00:00Z"

356```

357 

358Example curl command to list Codex tasks:

359 

360```bash

361curl -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

362 "https://api.chatgpt.com/v1/compliance/workspaces/WORKSPACE_ID/codex_tasks"

363```

364 

365For more details on the Compliance API, see [Compliance API](https://developers.openai.com/codex/enterprise/governance#compliance-api).

213 366 

214## Step 6: Confirm and validate setup367## Step 7: Confirm and verify setup

215 368 

216### What to verify369### What to verify

217 370 

219- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)372- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)

220- MFA and SSO requirements match your enterprise security policy373- MFA and SSO requirements match your enterprise security policy

221- RBAC and workspace toggles produce the expected access behavior374- RBAC and workspace toggles produce the expected access behavior

222- Managed configuration is applied for users375- Managed configuration applies for users

223- Governance data is visible for admins376- Governance data is visible for admins

224 377 

225For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).378For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).

226 379 

227Once your team is confident with setup, you can confidently roll Codex out to additional teams and organizations.380Once your team is confident with setup, you can roll Codex out to more teams and organizations.

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers can be enabled). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced requirement, Codex falls back to a requirements-compatible value and notifies the user. If an `mcp_servers` allowlist is configured, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11 

12Requirements can also be used to constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note features are generally not security-sensitive, but enterprises have the option of pinning values, if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).

15 15 

16### Locations and precedence16### Locations and precedence

17 17 

18Requirements layers are applied in this order (earlier wins per field):18Codex applies requirements layers in this order (earlier wins per field):

19 19 

201. Cloud-managed requirements (ChatGPT Business or Enterprise)201. Cloud-managed requirements (ChatGPT Business or Enterprise)

212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`

223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)

23 23 

24Across layers, requirements are merged per field: if an earlier layer sets a field (including an empty list), later layers do not override that field, but lower layers can still fill fields that remain unset.24Across layers, Codex merges requirements per field: if an earlier layer sets a field (including an empty list), later layers don't override that field, but lower layers can still fill fields that remain unset.

25 25 

26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

27 27 

53 53 

54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.

55 55 

56If a user matches multiple group-specific rules, the first matching rule applies. Codex does not fill unset requirement fields from later matching group rules.56If a user matches more than one group-specific rule, the first matching rule applies. Codex doesn't fill unset fields from later matching group rules.

57 57 

58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and does not fill `allowed_approval_policies` from the later rule.58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and doesn't fill `allowed_approval_policies` from the later rule.

59 59 

60#### How Codex applies cloud-managed requirements locally60#### How Codex applies cloud-managed requirements locally

61 61 

62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, invalid, or does not match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, corrupted, or doesn't match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.

63 63 

64After cache resolution, managed requirements are enforced as part of the normal requirements layering described above.64After cache resolution, Codex enforces managed requirements as part of the normal requirements layering described above.

65 65 

66### Example requirements.toml66### Example requirements.toml

67 67 

78allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed78allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

79```79```

80 80 

81`allowed_web_search_modes = []` effectively allows only `"disabled"`.81`allowed_web_search_modes = []` allows only `"disabled"`.

82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

83 83 

84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):

89unified_exec = false89unified_exec = false

90```90```

91 91 

92Use the canonical feature keys from `config.toml`’s `[features]` table. Codex normalizes the effective feature set to satisfy these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 93 

94### Enforce command rules from requirements94### Enforce command rules from requirements

95 95 

64To see all available commands and bind them as keyboard shortcuts, select the settings icon in the Codex chat and select **Keyboard shortcuts**.64To see all available commands and bind them as keyboard shortcuts, select the settings icon in the Codex chat and select **Keyboard shortcuts**.

65You can also refer to the [Codex IDE extension commands](https://developers.openai.com/codex/ide/commands) page.65You can also refer to the [Codex IDE extension commands](https://developers.openai.com/codex/ide/commands) page.

66For a list of supported slash commands, see [Codex IDE extension slash commands](https://developers.openai.com/codex/ide/slash-commands).66For a list of supported slash commands, see [Codex IDE extension slash commands](https://developers.openai.com/codex/ide/slash-commands).

67If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

67 68 

68---69---

69 70 

1# Best practices

2 

3If you’re new to Codex or coding agents in general, this guide will help you get better results faster. It covers the core habits that make Codex more effective across the [CLI](https://developers.openai.com/codex/cli), [IDE extension](https://developers.openai.com/codex/ide), and the [Codex app](https://developers.openai.com/codex/app), from prompting and planning to validation, MCP, skills, and automations.

4 

5Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time.

6 

7A useful way to think about this: start with the right task context, use `AGENTS.md` for durable guidance, configure Codex to match your workflow, connect external systems with MCP, turn repeated work into skills, and automate stable workflows.

8 

9## Strong first use: Context and prompts

10 

11Codex is already strong enough to be useful even when your prompt isn't perfect. You can often hand it a hard problem with minimal setup and still get a strong result. Clear [prompting](https://developers.openai.com/codex/prompting) isn't required to get value, but it does make results more reliable, especially in larger codebases or higher-stakes tasks.

12 

13If you work in a large or complex repository, the biggest unlock is giving Codex the right task context and a clear structure for what you want done.

14 

15A good default is to include four things in your prompt:

16 

17- **Goal:** What are you trying to change or build?

18- **Context:** Which files, folders, docs, examples, or errors matter for this task? You can @ mention certain files as context.

19- **Constraints:** What standards, architecture, safety requirements, or conventions should Codex follow?

20- **Done when:** What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?

21 

22This helps Codex stay scoped, make fewer assumptions, and produce work that's easier to review.

23 

24Choose a reasoning level based on how hard the task is and test what works best for your workflow. Different users and tasks work best with different settings.

25 

26- Low for faster, well-scoped tasks

27- Medium or High for more complex changes or debugging

28- Extra High for long, agentic, reasoning-heavy tasks

29 

30To provide context faster, try using speech dictation inside the Codex app to

31 dictate what you want Codex to do rather than typing it.

32 

33## Plan first for difficult tasks

34 

35If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.

36 

37A few approaches work well:

38 

39**Use Plan mode:** For most users, this is the easiest and most effective option. Plan mode lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation. Toggle with `/plan` or <kbd>Shift</kbd>+<kbd>Tab</kbd>.

40 

41**Ask Codex to interview you:** If you have a rough idea of what you want but aren't sure how to describe it well, ask Codex to question you first. Tell it to challenge your assumptions and turn the fuzzy idea into something concrete before writing code.

42 

43**Use a PLANS.md template:** For more advanced workflows, you can configure Codex to follow a `PLANS.md` or execution-plan template for longer-running or multi-step work. For more detail, see the [execution plans guide](https://developers.openai.com/cookbook/articles/codex_exec_plans).

44 

45## Make guidance reusable with `AGENTS.md`

46 

47Once a prompting pattern works, the next step is to stop repeating it manually. That's where [AGENTS.md](https://developers.openai.com/codex/guides/agents-md) comes in.

48 

49Think of `AGENTS.md` as an open-format README for agents. It loads into context automatically and is the best place to encode how you and your team want Codex to work in a repository.

50 

51A good `AGENTS.md` covers:

52 

53- repo layout and important directories

54- How to run the project

55- Build, test, and lint commands

56- Engineering conventions and PR expectations

57- Constraints and do-not rules

58- What done means and how to verify work

59 

60The `/init` slash command in the CLI is the quick-start command to scaffold a starter `AGENTS.md` in the current directory. It's a great starting point, but you should edit the result to match how your team actually builds, tests, reviews, and ships code.

61 

62You can create `AGENTS.md` files at different levels: a global `AGENTS.md` for personal defaults that sits in `~/.codex`, a repo-level file for shared standards, and more specific files in subdirectories for local rules. If there’s a more specific file closer to your current directory, that guidance wins.

63 

64Keep it practical. A short, accurate `AGENTS.md` is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.

65 

66If `AGENTS.md` starts getting too large, keep the main file concise and reference task-specific markdown files for things like planning, code review, or architecture.

67 

68When Codex makes the same mistake twice, ask it for a retrospective and update

69 `AGENTS.md`. Guidance stays practical and based on real friction.

70 

71## Configure Codex for consistency

72 

73Configuration is one of the main ways to make Codex behave more consistently across sessions and surfaces. For example, you can set defaults for model choice, reasoning effort, sandbox mode, approval policy, profiles, and MCP setup.

74 

75A good starting pattern is:

76 

77- Keep personal defaults in `~/.codex/config.toml` (Settings → Configuration → Open config.toml from the Codex app)

78- Keep repo-specific behavior in `.codex/config.toml`

79- Use command-line overrides only for one-off situations (if you use the CLI)

80 

81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and experimental features. You can edit it directly or ask Codex to update it for you.

82 

83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

84 

85If you're new to coding agents, start with the default permissions. Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear.

86 

87Note that the CLI, IDE, and Codex app all share the same configuration layers. Learn more on the [sample configuration](https://developers.openai.com/codex/config-sample) page.

88 

89Configure Codex for your real environment early. Many quality issues are

90 really setup issues, like the wrong working directory, missing write access,

91 wrong model defaults, or missing tools and connectors.

92 

93## Improve reliability with testing and review

94 

95Don't stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.

96 

97Codex can do this loop for you, but only if it knows what “good” looks like. That guidance can come from either the prompt or `AGENTS.md`.

98 

99That can include:

100 

101- Writing or updating tests for the change

102- Running the right test suites

103- Checking lint, formatting, or type checks

104- Confirming the final behavior matches the request

105- Reviewing the diff for bugs, regressions, or risky patterns

106 

107Toggle the diff panel in the Codex app to directly [review

108 changes](https://developers.openai.com/codex/app/review) locally. Click on a specific row to provide

109 feedback that gets fed as context to the next Codex turn.

110 

111A useful option here is the slash command `/review`, which gives you a few ways to review code:

112 

113- Review against a base branch for PR-style review

114- Review uncommitted changes

115- Review a commit

116- Use custom review instructions

117 

118If you and your team have a `code_review.md` file and reference it from `AGENTS.md`, Codex can follow that guidance during review as well. This is a strong pattern for teams that want review behavior to stay consistent across repositories and contributors.

119 

120Codex shouldn't just generate code. With the right instructions, it can also help **test it, check it, and review it**.

121 

122If you use GitHub Cloud, you can set up Codex to run [code reviews for your PRs](https://developers.openai.com/codex/integrations/github). At OpenAI, Codex reviews 100% of PRs. You can enable automatic reviews or have Codex reactively review when you @Codex.

123 

124## Use MCPs for external context

125 

126Use MCPs when the context Codex needs lives outside the repo. It lets Codex connect to the tools and systems you already use, so you don't have to keep copying and pasting live information into prompts.

127 

128[Model Context Protocol](https://developers.openai.com/codex/mcp), or MCP, is an open standard for connecting Codex to external tools and systems.

129 

130Use MCP when:

131 

132- The needed context lives outside the repo

133- The data changes frequently

134- You want Codex to use a tool rather than rely on pasted instructions

135- You need a repeatable integration across users or projects

136 

137Codex supports both STDIO and Streamable HTTP servers with OAuth.

138 

139In the Codex App, head to Settings → MCP servers to see custom and recommended servers. Often, Codex can help you install the needed servers. All you need to do is ask. You can also use the `codex mcp add` command in the CLI to add your custom servers with a name, URL, and other details.

140 

141Add tools only when they unlock a real workflow. Do not start by wiring in

142 every tool you use. Start with one or two tools that clearly remove a manual

143 loop you already do often, then expand from there.

144 

145## Turn repeatable work into skills

146 

147Once a workflow becomes repeatable, stop relying on long prompts or repeated back-and-forth. Use a [Skill](https://developers.openai.com/codex/skills) to package the instructions in a SKILL.md file, context, and supporting logic Codex should apply consistently. Skills work across the CLI, IDE extension, and Codex app.

148 

149Keep each skill scoped to one job. Start with 2 to 3 concrete use cases, define clear inputs and outputs, and write the description so it says what the skill does and when to use it. Include the kinds of trigger phrases a user would actually say.

150 

151Don't try to cover every edge case up front. Start with one representative task, get it working well, then turn that workflow into a skill and improve from there. Include scripts or extra assets only when they improve reliability.

152 

153A good rule of thumb: if you keep reusing the same prompt or correcting the same workflow, it should probably become a skill.

154 

155Skills are especially useful for recurring jobs like:

156 

157- Log triage

158- Release note drafting

159- PR review against a checklist

160- Migration planning

161- Telemetry or incident summaries

162- Standard debugging flows

163 

164The `$skill-creator` skill is the best place to start to scaffold the first version of a skill and to use the `$skill-installer` skill to install it locally. One of the most important parts of a skill is the description. It should say what the skill does and when to use it.

165 

166Personal skills are stored in `$HOME/.agents/skills`, and shared team skills

167 can be checked into `.agents/skills` inside a repository. This is especially

168 helpful for onboarding new teammates.

169 

170## Use automations for repeated work

171 

172Once a workflow is stable, you can schedule Codex to run it in the background for you. In the Codex app, [automations](https://developers.openai.com/codex/app/automations) let you choose the project, prompt, cadence, and execution environment for a recurring task.

173 

174Once a task becomes repetitive for you, you can create an automation in the Automations tab on the Codex app. You can choose which project it runs in, the prompt it runs (you can invoke skills), and the cadence it will run. You can also choose whether the automation runs in a dedicated git worktree or in your local environment. Learn more about [git worktrees](https://developers.openai.com/codex/app/worktrees).

175 

176Good candidates include:

177 

178- Summarizing recent commits

179- Scanning for likely bugs

180- Drafting release notes

181- Checking CI failures

182- Producing standup summaries

183- Running repeatable analysis workflows on a schedule

184 

185A useful rule is that skills define the method, automations define the schedule. If a workflow still needs a lot of steering, turn it into a skill first. Once it's predictable, automation becomes a force multiplier.

186 

187Use automations for reflection and maintenance, not just execution. Review

188 recent sessions, summarize repeated friction, and improve prompts,

189 instructions, or workflow setup over time.

190 

191## Organize long-running work with session controls

192 

193Codex sessions aren't just chat history. They're working threads that accumulate context, decisions, and actions over time, so managing them well has a big impact on quality.

194 

195The Codex app UI makes thread management easiest because you can pin threads and create worktrees. If you are using the CLI, these [slash commands](https://developers.openai.com/codex/cli/slash-commands) are especially useful:

196 

197- `/experimental` to toggle experimental features and add to your `config.toml`

198- `/resume` to resume a saved conversation

199- `/fork` to create a new thread while preserving the original transcript

200- `/compact` when the thread is getting long and you want a summarized version of earlier context. Note that Codex does automatically compact conversations for you

201- `/agent` when you are running parallel agents and want to switch between the active agent thread

202- `/theme` to choose a syntax highlighting theme

203- `/apps` to use ChatGPT apps directly in Codex

204- `/status` to inspect the current session state

205 

206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.

207 

208Use Codex’s [multi-agent](https://developers.openai.com/codex/concepts/multi-agents) workflows to offload

209bounded work from the main thread. Keep the main agent focused on the core

210problem, and use subagents for tasks like exploration, tests, or triage.

211 

212## Common mistakes

213 

214A few common mistakes to avoid when first using Codex:

215 

216- Overloading the prompt with durable rules instead of moving them into `AGENTS.md` or a skill

217- Not letting the agent see its work by not giving details on how to best run build and test commands

218- Skipping planning on multi-step and complex tasks

219- Giving Codex full permission to your computer before you understand the workflow

220- Running live threads on the same files without using git worktrees

221- Turning a recurring task into an automation before it's reliable manually

222- Treating Codex like something you have to watch step by step instead of using it in parallel with your own work

223- Using one thread per project instead of one thread per task. This leads to bloated context and worse results over time

41- Find and fix bugs in my codebase with minimal, high-confidence changes.40- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 41 

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).42 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

43 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

44 44 

45 [Learn more about the Codex app](https://developers.openai.com/codex/app)45 [Learn more about the Codex app](https://developers.openai.com/codex/app)

46 46 

694. Use Git checkpoints694. Use Git checkpoints

70 70 

71 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.71 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.

72 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

72 73 

73 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)74 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)

74 75 

1004. Use Git checkpoints1014. Use Git checkpoints

101 102 

102 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.103 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.

104 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

103 105 

104[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)106[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)

105 107