OpenAI - Codex Docs Changes 2026-03-08 00:35 UTC → 2026-03-11 00:31 UTC

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 

28winget install Codex -s msstore28winget install Codex -s msstore

29```29```

30 30 

31## Native sandbox

32 

33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.

34 

35Running Codex in full access mode means Codex is not limited to your project

36 directory and might perform unintentional destructive actions that can lead to

37 data loss. Keep sandbox boundaries in place and use [rules](https://developers.openai.com/codex/rules) for

38 targeted exceptions, or set your [approval policy to

39 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

40 Codex attempt to solve problems without asking for escalated permissions,

41 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

42 

31## Customize for your dev setup43## Customize for your dev setup

32 44 

33### Preferred editor45### Preferred editor

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

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |16| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

294 294 

295Details295Details

296 296 

297Maximum number of agent threads that can be open concurrently.297Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

298 298 

299Key299Key

300 300 

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.

18 21 

19## Local vs. cloud setup22## 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 23 

32- Workspace owner with access to ChatGPT Enterprise24During 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 25 

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

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

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

37 29 

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

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

40- Both local + cloud

41 31 

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

33- **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.

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

43 35 

44- Codex local supports ChatGPT sign-in or API keys. Confirm MFA/SSO requirements and any managed login restrictions in authentication36You 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 37 

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

48 39 

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

50 41 

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

52 43 

53### Codex local44### Codex local

54 45 

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

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

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

49 

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

56 51 

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

60 55 

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

62 57 

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/).58Allow 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 59 

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

66 61 

82 77 

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

84 79 

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 completion80#### Enable Codex Slack app to post answers on task completion

92 81 

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

98 87 

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

100 89 

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

102 91 

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

104 93 

106 95 

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

108 97 

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

99 

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

110 101 

111### What RBAC lets you do102### What RBAC lets you do

112 103 

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

114 105 

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

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

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

109- Automatically sync users into Groups via SCIM

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

119 111 

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

113 

114### Create a Codex Admin group

115 

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

117 

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

119 

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

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

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

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

124 

125Use 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.

126 

127Recommended rollout pattern:

128 

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

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

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

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

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

121 134 

122### Important behavior to plan for135This 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 136 

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

125 138 

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.139Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

127 140 

128For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).141Use 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 142 

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

131 144 

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

133 146 

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

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

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

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

135 151 

136- **Requirements** (`requirements.toml`): Admin-enforced constraints users cannot override152These 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 153 

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

155 

156Use 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.

157 

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

159 

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

161 

162```toml

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

164allowed_sandbox_modes = ["workspace-write"]

165allowed_approval_policies = ["on-request"]

166```

167 

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

169 

170```toml

171[rules]

172prefix_rules = [

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

174]

175```

176 

177You 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).

178 

179### Checking user policies

180 

181Use 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.

182 

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

184 

185If 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).

186 

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

140 188 

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.189Teams 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 190 

191You 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.

192 

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

194 

143| Type | Path | Use it to |195| Type | Path | Use it to |

144| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |196| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

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

148 200 

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

150 202 

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

152 204 

153Define a baseline for your pilot:205This 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 206 

169### Connect Codex cloud to repositories207### Connect Codex cloud to repositories

170 208 

1711. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**2091. 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 ChatGPT2102. 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 Connector2113. Install or connect the ChatGPT GitHub Connector

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

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

176 214 

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

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

217 repositories in Codex cloud.

218 

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

178 220 

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.221Codex 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 222 

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

182 224 

183Configure connector / IP allow lists if required by your network policy with these [egress IP ranges](https://openai.com/chatgpt-agents.json).225If 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 226 

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

186 228 

188 230 

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

190 232 

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.233You 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).

234 

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

236 

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

238 

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

240 requests automatically for connected repositories.

241 

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

243 

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

245 Codex review.

246 

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

248 

249### Configure Codex security

192 250 

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).251Codex Security helps engineering and security teams find, confirm, and remediate likely vulnerabilities in connected GitHub repositories.

194 252 

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

196 254 

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.255- scans connected repositories commit by commit

256- ranks likely findings and confirms them when possible

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

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

259 

260For 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).

261 

262Integration 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).

263 

264## Step 6: Set up governance and observability

265 

266Codex 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 267 

199### Codex governance typically uses268### Codex governance typically uses

200 269 

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

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

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

204 273 

205### Recommended minimum setup274### Recommended baseline setup

206 275 

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

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

209- Define a review cadence278- Define a review cadence

210- Decide what success looks like279- Decide what success looks like

211 280 

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

282 

283To set up the Analytics API key:

284 

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

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

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

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

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

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

2917. 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.

292 

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

294 

295To use the Analytics API key:

296 

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

2982. 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.

2993. Choose the endpoint you want to query:

300 

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

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

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

304 

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

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

307 

308Example curl command to retrieve workspace usage:

309 

310```bash

311curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \

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

313```

314 

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

316 

317### Compliance API setup steps

318 

319To set up the Compliance API key:

320 

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

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

3233. 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.

3244. Choose All permissions.

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

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

327 

328- the last 4 digits of the API key

329- the key name

330- the created-by name

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

332 

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

334 

335To use the Compliance API key:

336 

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

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

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

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

341 

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

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

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

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

346 

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

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

349 

350Example curl command to list compliance log files:

351 

352```bash

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

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

355```

356 

357Example curl command to list Codex tasks:

358 

359```bash

360curl -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

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

362```

363 

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

213 365 

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

215 367 

216### What to verify368### What to verify

217 369 

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

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

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

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

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

224 376 

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

226 378 

227Once your team is confident with setup, you can confidently roll Codex out to additional teams and organizations.379Once 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

31 31 

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 33 

34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, tuned for waiting and repeated status checks.

35 35 

36To see it in action, try the following prompt on your project:36To see it in action, try the following prompt on your project:

37 37 

53 53 

54## Process CSV batches with sub-agents54## Process CSV batches with sub-agents

55 55 

56Use `spawn_agents_on_csv` when you have many similar tasks that can be expressed as one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.56Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.

57 57 

58This works well for repeated audits such as:58This works well for repeated audits such as:

59 59 

69- `output_schema` when each worker should return a JSON object with a fixed shape69- `output_schema` when each worker should return a JSON object with a fixed shape

70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 71 

72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, that row is marked as failed in the exported CSV.72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.

73 73 

74Example prompt:74Example prompt:

75 75 

101shows the source thread label, and you can press `o` to open that thread before101shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.102you approve, reject, or answer the request.

103 103 

104In non-interactive flows, or whenever a run cannot surface a fresh approval,104In non-interactive flows, or whenever a run can’t surface a fresh approval,

105an action that needs new approval fails and the error is surfaced back to the105an action that needs new approval fails and Codex surfaces the error back to the

106parent workflow.106parent workflow.

107 107 

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a108Codex also reapplies the parent turn’s live runtime overrides when it spawns a

116 116 

117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

118 118 

119Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.

120 120 

121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a

122role-specific config file (`config_file`) when Codex spawns an agent with that role.122role-specific config file (`config_file`) when Codex spawns an agent with that role.

132 132 

133- `model` and `model_reasoning_effort` to select a specific model for your agent role133- `model` and `model_reasoning_effort` to select a specific model for your agent role

134- `sandbox_mode` to mark an agent as `read-only`134- `sandbox_mode` to mark an agent as `read-only`

135- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them

136 136 

137### Schema137### Schema

138 138 

139| Field | Type | Required | Purpose |139| Field | Type | Required | Purpose |

140| --- | --- | --- | --- |140| --- | --- | --- | --- |

141| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |141| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

142| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |142| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |

143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

144| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |144| `[agents.<name>]` | table | No | Role declaration. `<name>` becomes the `agent_type` when spawning an agent. |

145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |

146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

147 147 

148**Notes:**148**Notes:**

149 149 

150- Unknown fields in `[agents.<name>]` are rejected.150- Codex rejects unknown fields in `[agents.<name>]`.

151- `agents.max_threads` defaults to `6` when you leave it unset.

151- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.152- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

152- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.153- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

153- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.

154- `agents.<name>.config_file` is validated at config load time and must point to an existing file.155- Codex validates `agents.<name>.config_file` at config load time, and it must point to an existing file.

155- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

156- If Codex can’t load a role config file, agent spawns can fail until you fix the file.157- If Codex can’t load a role config file, agent spawns can fail until you fix the file.

157- Any configuration not set by the agent role will be inherited from the parent session.158- The agent inherits any configuration that the role doesn’t set from the parent session.

158 159 

159### Example agent roles160### Example agent roles

160 161 

236Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.237Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

237```238```

238 239 

239#### Example 2: frontend integration debugging team240#### Example 2: Frontend integration debugging team

240 241 

241This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.242This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

242 243 

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 

26 26 

27## Access and prerequisites27## Access and prerequisites

28 28 

29Codex Security works with connected GitHub repositories through Codex cloud. OpenAI manages access. If you need access or a repository isn’t visible, contact your OpenAI account team and confirm the repository is available through your Codex cloud workspace.29Codex Security works with connected GitHub repositories through Codex Web. OpenAI manages access. If you need access or a repository isn't visible, contact your OpenAI account team and confirm the repository is available through your Codex Web workspace.

30 30 

31## Related docs31## Related docs

32 32 

27- Runs commands as a dedicated Windows Sandbox User.27- Runs commands as a dedicated Windows Sandbox User.

28- Limits network access by installing Windows Firewall rules.28- Limits network access by installing Windows Firewall rules.

29 29 

30### Sandbox permissions

31 

32Running Codex in full access mode means Codex is not limited to your project

33 directory and might perform unintentional destructive actions that can lead to

34 data loss. For safer automation, keep sandbox boundaries in place and use

35 [rules](https://developers.openai.com/codex/rules) for specific exceptions, or set your [approval policy to

36 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

37 Codex attempt to solve problems without asking for escalated permissions,

38 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

39 

30### Grant sandbox read access40### Grant sandbox read access

31 41 

32When a command fails because the Windows sandbox can't read a directory, use:42When a command fails because the Windows sandbox can't read a directory, use: