OpenAI - Codex Docs Changes 2026-05-07 20:02 UTC → 2026-05-14 07:00 UTC

121approvals_reviewer = "auto_review"121approvals_reviewer = "auto_review"

122```122```

123 123 

124For the full reviewer lifecycle, trigger conditions, configuration precedence,

125and failure behavior, see

126[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

127 

124The reviewer evaluates only actions that already need approval, such as sandbox128The reviewer evaluates only actions that already need approval, such as sandbox

125escalations, network requests, `request_permissions` prompts, or side-effecting129escalations, blocked network requests, `request_permissions` prompts, or

126app and MCP tool calls. Actions that stay inside the sandbox continue without an130side-effecting app and MCP tool calls. Actions that stay inside the sandbox

127extra review step.131continue without an extra review step.

128 132 

129The reviewer policy checks for data exfiltration, credential probing, persistent133The reviewer policy checks for data exfiltration, credential probing, persistent

130security weakening, and destructive actions. Low-risk and medium-risk actions134security weakening, and destructive actions. Low-risk and medium-risk actions

131can proceed when policy allows them. The policy denies critical-risk actions.135can proceed when policy allows them. The policy denies critical-risk actions.

132High-risk actions require enough user authorization and no matching deny rule.136High-risk actions require enough user authorization and no matching deny rule.

133Timeouts, parse failures, and review errors fail closed.137Prompt-build, review-session, and parse failures fail closed. Timeouts are

138surfaced separately, but the action still does not run.

134 139 

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)140The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

136is in the open-source Codex repository. Enterprises can replace its141is in the open-source Codex repository. Enterprises can replace its

139take precedence. For setup details, see144take precedence. For setup details, see

140[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).145[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

141 146 

142In the Codex app, these reviews appear as automatic review items with a status such147In the Codex app, these reviews appear as automatic review items with a status

143as Reviewing, Approved, Denied, Stopped, or Timed out. They can also include a148such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also

144risk level for the reviewed request.149include a risk level and user-authorization assessment for the reviewed

150request.

145 151 

146Automatic review uses extra model calls, so it can add to Codex usage. Admins152Automatic review uses extra model calls, so it can add to Codex usage. Admins

147can constrain it with `allowed_approvals_reviewers`.153can constrain it with `allowed_approvals_reviewers`.

148 154 

149### Common sandbox and approval combinations155### Common sandbox and approval combinations

150 156 

151| Intent | Flags | Effect |157| Intent | Flags / config | Effect |

152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |158| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

153| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |159| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

154| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |160| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

155| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |161| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |

156| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |162| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

163| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |

157| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | <ElevatedRiskBadge /> No sandbox; no approvals _(not recommended)_ |164| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | <ElevatedRiskBadge /> No sandbox; no approvals _(not recommended)_ |

158 165 

159For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.166For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

28 28 

291. Open Codex and go to **Plugins**.291. Open Codex and go to **Plugins**.

302. Add the **Chrome** plugin.302. Add the **Chrome** plugin.

313. Follow the setup flow. It guides you through installing or connecting the313. Follow the setup flow. It guides you through installing the [Codex Chrome

32 Chrome extension and approving Chrome's permission prompts.32 extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg)

33 and approving Chrome's permission prompts.

334. Open Chrome and confirm the Codex extension shows **Connected**.344. Open Chrome and confirm the Codex extension shows **Connected**.

34 35 

35After the plugin setup is complete, start a new Codex thread. Codex can suggest36After the plugin setup is complete, start a new Codex thread. Codex can suggest

126the composer or chat input. That selector lets you rely on Codex's default126the composer or chat input. That selector lets you rely on Codex's default

127permissions, switch to full access, or use your custom configuration.127permissions, switch to full access, or use your custom configuration.

128 128 

129<div class="not-prose max-w-[22rem] mr-auto mb-6">129<PermissionModeSelectorDemo client:load />

130 <img src="https://developers.openai.com/images/codex/app/permissions-selector-light.webp"

131 alt="Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)"

132 class="block h-auto w-full mx-0!"

133 />

134</div>

135 130 

136In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)131In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)

137to switch modes during a session.132to switch modes during a session.

142configuration. Codex stores those defaults in `config.toml`, its local settings137configuration. Codex stores those defaults in `config.toml`, its local settings

143file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the138file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the

144[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for139[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for

145`sandbox_mode`, `approval_policy`, and140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and

146`sandbox_workspace_write.writable_roots`. Use those settings to decide how much141`sandbox_workspace_write.writable_roots`. Use those settings to decide how much

147autonomy Codex gets by default, which directories it can write to, and when it142autonomy Codex gets by default, which directories it can write to, when it

148should pause for approval.143should pause for approval, and who reviews eligible approval requests.

149 144 

150At a high level, the common sandbox modes are:145At a high level, the common sandbox modes are:

151 146 

166 needs to go beyond that boundary.161 needs to go beyond that boundary.

167- `never`: Codex doesn't stop for approval prompts.162- `never`: Codex doesn't stop for approval prompts.

168 163 

164When approvals are interactive, you can also choose who reviews them with

165`approvals_reviewer`:

166 

167- `user`: approval prompts surface to the user. This is the default.

168- `auto_review`: eligible approval prompts go to a reviewer agent (see

169 [Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review)).

170 

169Full access means using `sandbox_mode = "danger-full-access"` together with171Full access means using `sandbox_mode = "danger-full-access"` together with

170`approval_policy = "never"`. By contrast, the lower-risk local automation172`approval_policy = "never"`. By contrast, the lower-risk local automation

171preset is `sandbox_mode = "workspace-write"` together with173preset is `sandbox_mode = "workspace-write"` together with

172`approval_policy = "on-request"`, or the matching CLI flags174`approval_policy = "on-request"`, or the matching CLI flags

173`--sandbox workspace-write --ask-for-approval on-request`.175`--sandbox workspace-write --ask-for-approval on-request`. You can then keep

176`approvals_reviewer = "user"` for manual approvals or set

177`approvals_reviewer = "auto_review"` for automatic approval review.

174 178 

175If you need Codex to work across more than one directory, writable roots let179If you need Codex to work across more than one directory, writable roots let

176you extend the places it can modify without removing the sandbox entirely. If180you extend the places it can modify without removing the sandbox entirely. If

193[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the197[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the

194IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).198IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).

195 199 

196Automatic review, when available, doesn't change the sandbox boundary. It200Automatic review, when available, does not change the sandbox boundary. It is

197reviews approval requests, such as sandbox escalations or network access, while201one possible `approvals_reviewer` for approval requests at that boundary, such

198actions already allowed inside the sandbox run without extra review. See202as sandbox escalations, blocked network access, or side-effecting tool calls

199[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)203that still need approval. Actions already allowed inside the sandbox run

200for the policy behavior.204without extra review. For the reviewer lifecycle, trigger types, denial

205semantics, and configuration details, see

206[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

201 207 

202Platform details live in the platform-specific docs. For native Windows setup,208Platform details live in the platform-specific docs. For native Windows setup,

203behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin209behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin

1# Auto-review

2 

3Auto-review replaces manual approval at the sandbox boundary with a separate

4reviewer agent. The main Codex agent still runs inside the same sandbox, with

5the same approval policy and the same network and filesystem limits. The

6difference is who reviews eligible escalation requests.

7 

8Auto-review only applies when approvals are interactive. In practice, that

9 means `approval_policy = "on-request"` or a granular approval policy that

10 still surfaces the relevant prompt category. With `approval_policy = "never"`,

11 there is nothing to review.

12 

13## How auto-review works

14 

15At a high level, the flow is:

16 

171. The main agent works inside `read-only` or `workspace-write`.

182. When it needs to cross the sandbox boundary, it requests approval.

193. If `approvals_reviewer = "auto_review"`, Codex routes that approval request

20 to a separate reviewer agent instead of stopping for a person.

214. The reviewer decides whether the action should run and returns a rationale.

225. If the action is approved, execution continues. If it is denied, the main

23 agent is instructed to find a materially safer path or stop and ask the

24 user.

25 

26Auto-review is a reviewer swap, not a permission grant. It does not expand

27`writable_roots`, enable network access, or weaken protected paths. It only

28changes how Codex handles actions that already need approval.

29 

30## When it triggers

31 

32Auto-review evaluates approval requests that would otherwise pause for a human.

33These include:

34 

35- Shell or exec tool calls that request escalated sandbox permissions.

36- Network requests blocked by the current sandbox or policy.

37- File edits outside the allowed writable roots.

38- MCP or app tool calls that require approval based on their tool annotations

39 or configured approval mode.

40- Browser Use access to a new website or domain.

41 

42Auto-review does not run for routine actions already allowed inside the

43sandbox. If a command can run under the active `sandbox_mode`, or a tool call

44stays within the allowed policy, the main agent continues without review.

45 

46Computer Use is a separate case. App approvals for Computer Use still surface

47directly to the user, so Auto-review does not replace those app-level prompts.

48 

49## What auto-review blocks

50 

51At a high level, Auto-review is designed to block actions such as:

52 

53- sending private data, secrets, or credentials to untrusted destinations

54- probing for credentials, tokens, cookies, or session material

55- broad or persistent security weakening

56- destructive actions with significant risk of irreversible damage

57 

58The exact policy lives in the open-source Codex repository:

59[policy_template.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy_template.md)

60and

61[policy.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md).

62That policy can be customized per enterprise with `guardian_policy_config` or

63per user with local [`[auto_review].policy`](/codex/config-advanced#approval-policies-and-sandbox-modes).

64 

65## What the reviewer sees

66 

67The reviewer is itself a Codex agent with a narrower job than the main agent:

68decide whether a specific boundary-crossing action should run.

69 

70The reviewer sees a compact transcript plus the exact approval request. That

71typically includes user messages, surfaced assistant updates, relevant tool

72calls and tool outputs, and the action now being proposed for approval. It can

73also perform read-only checks to gather missing context, but it does so rarely.

74 

75Hidden assistant reasoning is not included. Auto-review sees retained

76conversation items and tool evidence, not private chain-of-thought.

77 

78## Denials and failure behavior

79 

80An explicit denial is not treated like an ordinary sandbox error. Codex returns

81the review rationale to the main agent and adds a stronger instruction:

82 

83- Do not pursue the same outcome via workaround, indirect execution, or policy

84 circumvention.

85- Continue only with a materially safer alternative.

86- Otherwise, stop and ask the user.

87 

88Codex also applies a rejection circuit breaker per turn. In the current

89open-source implementation, Auto-review interrupts the turn after `3`

90consecutive denials or `10` denials within a rolling window of the last `50`

91reviews in the same turn.

92 

93Any non-denial resets the consecutive-denial counter. When the breaker trips,

94Codex emits a warning and aborts the current turn with an interrupt rather than

95letting the agent loop on more escalation attempts.

96 

97Timeouts are surfaced separately from explicit denials, and the main agent is

98informed that a timeout alone is not proof that the action is unsafe.

99 

100There is also an explicit override path for denied actions. In the current

101open-source TUI, run `/approve` to open the **Auto-review Denials** picker, then

102select one recent denied action to approve for one retry. Codex records up to 10

103recent denials per thread. That approval is narrow: it applies to the exact

104denied action, not similar future actions; it is recorded for one retry in the

105same context; and the retry still goes through Auto-review. Under the hood,

106Codex injects a developer-scoped approval marker for that exact action. The

107reviewer then sees that explicit user override as context, but it still follows

108policy and can deny again if policy says the user cannot overwrite that class of

109denial.

110 

111## Configuration

112 

113For setup details, see

114[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

115 

116The default reviewer policy is in the open-source Codex repository:

117[core/src/guardian/policy.md](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md).

118Enterprises can replace its tenant-specific section with

119`guardian_policy_config` in managed requirements. Individual users can also set

120a local

121[`[auto_review].policy`](/codex/config-advanced#approval-policies-and-sandbox-modes)

122in their `config.toml`, but managed requirements take precedence:

123 

124```toml

125[auto_review]

126policy = """

127YOUR POLICY GOES HERE

128"""

129```

130 

131To customize the policy, copy the whole default policy wording first, then

132iterate based on your individual risk profile.

133 

134## Reduce review volume without weakening security

135 

136Auto-review works best when the sandbox already covers your common safe

137workflows. If too many mundane actions need review, fix the boundary first

138instead of teaching the reviewer to approve noisy escalations forever.

139 

140In practice, the highest-leverage changes are:

141 

142- Add narrow

143 [`writable_roots`](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes)

144 for scratch directories or neighboring repos you intentionally use.

145- Add narrowly scoped [prefix rules](https://developers.openai.com/codex/rules). Prefer precise command

146 prefixes such as `["cargo", "test"]` or `["pnpm", "run", "lint"]` over broad

147 patterns such as `["python"]` or `["curl"]`. Broad rules often erase the very

148 boundary Auto-review is meant to guard.

149 

150Auto-review session transcripts are retained under `~/.codex/sessions` by

151default, so you can ask Codex to analyze past traffic there before changing

152policy or permissions.

153 

154## Limits

155 

156Auto-review improves the default operating point for long-running agentic work,

157but it is not a deterministic security guarantee.

158 

159- It only evaluates actions that ask to cross a boundary.

160- It can still make mistakes, especially in adversarial or unusual contexts.

161- It should complement, not replace, good sandbox design, monitoring, and

162 organization-specific policy.

163 

164For the research rationale and published evaluation results, see the

165[Alignment Research post on Auto-review](https://alignment.openai.com/auto-review/).

66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup

67that balances intelligence, speed, and price for the task. It may favor67that balances intelligence, speed, and price for the task. It may favor

68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for

69more demanding reasoning when that model is available. When you want finer69more demanding reasoning. When you want finer control, steer that choice in

70control, steer that choice in your prompt or set `model` and70your prompt or set `model` and

71`model_reasoning_effort` directly in the agent file.71`model_reasoning_effort` directly in the agent file.

72 72 

73For most tasks in Codex, start with `gpt-5.5` when it is available. Continue73For most tasks in Codex, start with `gpt-5.5`. Use `gpt-5.4-mini` when you

74 using `gpt-5.4` during the rollout if `gpt-5.5` is not yet available. Use74 want a faster, lower-cost option for lighter subagent work. If you have

75 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter subagent75 ChatGPT Pro and want near-instant text-only iteration, `gpt-5.3-codex-spark`

76 work. If you have ChatGPT Pro and want near-instant text-only iteration,76 remains available in research preview.

77 `gpt-5.3-codex-spark` remains available in research preview.

78 77 

79### Model choice78### Model choice

80 79 

81- **`gpt-5.5`**: Start here for demanding agents when it is available. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.80- **`gpt-5.5`**: Start here for demanding agents. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

82- **`gpt-5.4`**: Use this when `gpt-5.5` is not yet available or when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.81- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

83- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.82- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

84- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.83- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

85 84 

170| Key | Default | Maturity | Description |170| Key | Default | Maturity | Description |

171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

172| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |172| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

173| `codex_git_commit` | false | Experimental | Enable Codex-generated git commits and commit attribution trailers |

173| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |174| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

174| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |175| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

175| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |176| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

208 key: "commit_attribution",208 key: "commit_attribution",

209 type: "string",209 type: "string",

210 description:210 description:

211 "Override the commit co-author trailer text. Set an empty string to disable automatic attribution.",211 'Commit co-author trailer used when `[features].codex_git_commit` is enabled. Defaults to `Codex <noreply@openai.com>`; set `""` to disable.',

212 },212 },

213 {213 {

214 key: "model_instructions_file",214 key: "model_instructions_file",

330 description:330 description:

331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",

332 },332 },

333 {

334 key: "features.codex_git_commit",

335 type: "boolean",

336 description:

337 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",

338 },

333 {339 {

334 key: "hooks",340 key: "hooks",

335 type: "table",341 type: "table",

83# Inline override for the history compaction prompt. Default: unset.83# Inline override for the history compaction prompt. Default: unset.

84# compact_prompt = ""84# compact_prompt = ""

85 85 

86# Override the default commit co-author trailer. Set to "" to disable it.86# Override the default commit co-author trailer. This only takes effect when

87# [features].codex_git_commit is enabled. When enabled and unset, Codex uses

88# "Codex <noreply@openai.com>". Set to "" to disable it.

87# commit_attribution = "Jane Doe <jane@example.com>"89# commit_attribution = "Jane Doe <jane@example.com>"

88 90 

89# Override built-in base instructions with a file path. Default: unset.91# Override built-in base instructions with a file path. Default: unset.

398# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.400# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.

399# shell_tool = true401# shell_tool = true

400# apps = false402# apps = false

403# codex_git_commit = false

401# codex_hooks = false404# codex_hooks = false

402# unified_exec = true405# unified_exec = true

403# shell_snapshot = true406# shell_snapshot = true

15## Analytics Dashboard15## Analytics Dashboard

16 16 

17<div class="max-w-1xl mx-auto">17<div class="max-w-1xl mx-auto">

18 <img src="https://developers.openai.com/images/codex/enterprise/analytics.png"18 <img src="https://developers.openai.com/images/codex/enterprise/analytics-dashboard.png"

19 alt="Codex analytics dashboard"19 alt="Codex analytics dashboard"

20 class="block w-full mx-auto rounded-lg"20 class="block w-full mx-auto rounded-lg !border-0"

21 />21 />

22</div>22</div>

23 23 

24### Dashboards24### Dashboard views

25 25 

26The [analytics dashboard](https://chatgpt.com/codex/settings/analytics) allows ChatGPT workspace administrators to track feature adoption.26The [analytics dashboard](https://chatgpt.com/codex/cloud/settings/analytics#usage) allows ChatGPT workspace administrators and analytics viewers to track Codex adoption, usage, and Code Review feedback. Usage data can lag by up to 12 hours.

27 27 

28Codex provides the following dashboards:28Codex provides date-range controls for daily and weekly views. Key charts include:

29 29 

30- Daily users by product (CLI, IDE, cloud, Code Review)30- Active users by product surface, including CLI, IDE extension, cloud, desktop, and Code Review

31- Daily code review users31- Workspace and personal usage breakdowns, including credit and token usage by product surface

32- Daily code reviews32- Product activity for threads and turns by client

33- Code reviews by priority level33- User ranking table, with filters for client and sort options such as credits, threads, turns, text tokens, and current streak

34- Daily code reviews by feedback sentiment34- Code Review activity, including PRs reviewed, issues by priority, comments, replies, reactions, and feedback sentiment

35- Daily cloud tasks35- Skill invocations and agent identity usage when your workspace has those features

36- Daily cloud users

37- Daily VS Code extension users

38- Daily CLI users

39 36 

40### Data export37### Data export

41 38 

42Administrators can also export Codex analytics data in CSV or JSON format. Codex provides the following export options:39Administrators can also export Codex analytics data in CSV or JSON format. Codex provides the following export options:

43 40 

44- Code review users and reviews (Daily unique users and total reviews completed in Code Review)41- Workspace usage, including daily active users, threads, turns, and credits by surface

45- Code review findings and feedback (Daily counts of comments, reactions, replies, and priority-level findings)42- Usage per user, including daily threads, turns, and credits across surfaces, with optional email addresses when allowed

46- cloud users and tasks (daily unique cloud users and tasks completed)43- Code Review details, including daily comments, reactions, replies, and priority-level findings

47- CLI and VS Code users (Daily unique users for the Codex CLI and VS Code extension)

48- Sessions and messages per user (Daily session starts and user message counts for each Codex user across surfaces)

49 44 

50## Analytics API45## Analytics API

51 46 

52Use the [Analytics API](https://chatgpt.com/codex/settings/apireference) when you want to automate reporting, build internal dashboards, or join Codex metrics with your existing engineering data.47Use the [Analytics API](https://chatgpt.com/codex/cloud/settings/apireference) when you want to automate reporting, build internal dashboards, or join Codex metrics with your existing engineering data.

53 48 

54### What it measures49### What it measures

55 50 

56The Analytics API provides daily, time-series metrics for a workspace, with optional per-user breakdowns and per-client usage.51The enterprise Analytics API returns daily or weekly UTC buckets for a workspace. It supports workspace-level and per-user usage, per-client breakdowns, Code Review throughput, Code Review comment priority, and user engagement with Code Review comments.

57 52 

58### Endpoints53### Endpoints

59 54 

60#### Daily usage and adoption55The base URL is `https://api.chatgpt.com/v1/analytics/codex`. All endpoints return paginated `page` objects with `has_more` and `next_page`.

61 56 

62- Daily totals for threads, turns, and credits57Use `start_time` for the inclusive Unix timestamp at the beginning of the reporting window, `end_time` for the exclusive Unix timestamp at the end of the reporting window, `group_by` for `day` or `week` buckets, `limit` for page size, and `page` to continue from a previous response. Requests can look back up to 90 days.

63- Breakdown by client surface58 

64- Optional per-user reporting for adoption and power-user analysis59#### Usage

60 

61`GET /workspaces/{workspace_id}/usage`

62 

63- Returns totals for threads, turns, credits, and per-client usage in daily or weekly buckets.

64- Omit `group` to return per-user rows.

65- Set `group=workspace` to return workspace-wide rows.

66- Includes text input, cached input, and output token fields.

65 67 

66#### Code review activity68#### Code review activity

67 69 

68- Pull request reviews completed by Codex70`GET /workspaces/{workspace_id}/code_reviews`

69- Total comments generated by Codex71 

70- Severity breakdown of comments72- Returns pull request reviews completed by Codex.

73- Returns total comments generated by Codex.

74- Breaks comments down by P0, P1, and P2 priority.

71 75 

72#### User engagement with code review76#### User engagement with code review

73 77 

74- Replies to Codex comments78`GET /workspaces/{workspace_id}/code_review_responses`

75- Reactions, including upvotes and downvotes79 

76- Engagement breakdowns for how teams respond to Codex feedback80- Returns replies and reactions to Codex comments.

81- Breaks reactions down into positive, negative, and other reactions.

82- Counts comments that received reactions, replies, or either form of engagement.

77 83 

78### How it works84### How it works

79 85 

80Analytics is daily and time-windowed. Results are time-ordered and returned in pages with cursor-based pagination. You can query by workspace and optionally group by user or aggregate at the workspace level.86Analytics uses time windows and supports day or week grouping. Results are time-ordered and returned in pages with cursor-based pagination. Use an API key scoped to `codex.enterprise.analytics.read`.

81 87 

82### Common use cases88### Common use cases

83 89 

37 value: false,37 value: false,

38 },38 },

39 { title: "ChatGPT Credits", value: true },39 { title: "ChatGPT Credits", value: true },

40 { title: "API Access", value: false },40 { title: "API Access", value: true },

41 ],41 ],

42 }}42 }}

43 />43 />

205For most tasks in Codex, start with `gpt-5.5` when it appears in your model205For most tasks in Codex, start with `gpt-5.5` when it appears in your model

206 picker. It is strongest for complex coding, computer use, knowledge work, and206 picker. It is strongest for complex coding, computer use, knowledge work, and

207 research workflows. GPT-5.5 is currently available in Codex when you sign in207 research workflows. GPT-5.5 is currently available in Codex when you sign in

208 with ChatGPT; it isn't available with API-key authentication. During the208 with ChatGPT or API-key authentication. Use `gpt-5.4-mini` when you want a

209 rollout, continue using `gpt-5.4` if `gpt-5.5` is not yet available. Use209 faster, lower-cost option for lighter coding tasks or subagents. The

210 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter coding210 `gpt-5.3-codex-spark` model is available in research preview for ChatGPT Pro

211 tasks or subagents. The `gpt-5.3-codex-spark` model is available in research211 subscribers and is optimized for near-instant, real-time coding iteration.

212 preview for ChatGPT Pro subscribers and is optimized for near-instant,

213 real-time coding iteration.

214 212 

215## Alternative models213## Alternative models

216 214