OpenAI - Codex Docs Changes

agent-approvals-security.md +123 −9

Details

41network_access = true41network_access = true

42```42```

43 43

44### Network isolation

46Network access is controlled through destination rules that apply to scripts,

47programs, and subprocesses spawned by commands. When command network access is

48already enabled, turn on the `network_proxy` feature to constrain that traffic

49to the network policy you configure.

51```toml

52[features.network_proxy]

53enabled = true

54domains = { "api.openai.com" = "allow", "example.com" = "deny" }

55```

57For a one-off CLI session, use the boolean shorthand when you only need the

58toggle, and the table form when you also set policy options:

60```bash

61codex \

62 -c 'features.network_proxy=true' \

63 -c 'sandbox_workspace_write.network_access=true'

65codex \

66 -c 'features.network_proxy.enabled=true' \

67 -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \

68 -c 'sandbox_workspace_write.network_access=true'

69```

71The feature changes how enabled network access is enforced; it does not grant

72network access by itself. Use `sandbox_workspace_write.network_access` with

73`workspace-write` config to decide whether commands have network access at all:

75- Network off + `network_proxy` on: network stays off, and the feature does nothing.

76- Network on + `network_proxy` off: network stays on with unrestricted direct

77 outbound access.

78- Network on + `network_proxy` on: network stays on, and outbound traffic is

79 constrained by the configured network policy.

81Admin-managed `experimental_network` requirements are separate from the user

82feature toggle. They can configure and start sandboxed networking without

83`features.network_proxy`, but they do not turn on network access when the active

84sandbox keeps it off. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-network-access-requirements)

85for the administrator-side `requirements.toml` shape.

87#### Network policy

89Domain rules are allowlist-first:

91- Exact hosts match only themselves.

92- `*.example.com` matches subdomains such as `api.example.com`, but not

93 `example.com`.

94- `**.example.com` matches both the apex and subdomains.

95- A global `*` allow rule matches any public host that is not denied. Treat `*`

96 as broad network access and prefer scoped rules when you can.

97- `deny` always wins over `allow`, and global `*` is only valid for allow rules.

99#### Local and private destinations

100

101By default, `allow_local_binding = false` blocks loopback, link-local, and

102private destinations:

103

104- Specific exceptions: add an exact local IP literal or `localhost` allow rule

105 when a command needs one local target.

106- Broader access: set `allow_local_binding = true` only when you intentionally

107 want wider local/private reach.

108- Wildcards: wildcard rules do not count as explicit local exceptions.

109- Resolved addresses: hostnames that resolve to local/private IPs stay blocked

110 even if they match the allowlist.

111

112#### DNS rebinding protections

113

114Before allowing a hostname, Codex performs a best-effort DNS and IP

115classification check:

116

117- Lookups that fail or time out are blocked.

118- Hostnames that resolve to non-public addresses are blocked.

119- The check reduces DNS rebinding risk, but it does not eliminate it. Preventing

120 rebinding completely would require pinning resolved IPs through the transport

121 layer.

122

123If hostile DNS is in scope, enforce egress controls at a lower layer too.

124

125#### Dangerous settings

126

127Two settings deliberately widen the trust boundary:

128

129- `dangerously_allow_non_loopback_proxy = true` can expose proxy listeners beyond

130 loopback.

131- `dangerously_allow_all_unix_sockets = true` bypasses the Unix socket allowlist.

132

133Use them only in tightly controlled environments. When Unix socket proxying is

134enabled, listeners stay loopback-only even if non-loopback binding was requested,

135so sandboxed networking does not become a remote bridge into local daemons.

136

137`network_proxy` is off by default. When you enable it:

138

139| Setting | Default | Behavior |

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

141| `enabled` | `false` | Starts sandboxed networking only when command network access is already on. |

142| `domains` | unset | Uses allowlist behavior, so no external destinations are allowed until you add `allow` rules. Supports exact hosts, scoped wildcards, and global `*` allow rules; `deny` always wins. |

143| `unix_sockets` | unset | No Unix socket destinations are allowed until you add explicit `allow` rules. |

144| `allow_local_binding` | `false` | Blocks local and private-network destinations unless you add an exact local IP literal or `localhost` allow rule, or explicitly opt into broader local/private access. |

145| `enable_socks5` | `true` | Exposes SOCKS5 support when policy allows it. |

146| `enable_socks5_udp` | `true` | Allows UDP over SOCKS5 when SOCKS5 is available. |

147| `allow_upstream_proxy` | `true` | Lets sandboxed networking honor an upstream proxy from the environment. |

148| `dangerously_allow_non_loopback_proxy` | `false` | Keeps listener endpoints on loopback unless you deliberately expose them beyond localhost. |

149| `dangerously_allow_all_unix_sockets` | `false` | Keeps Unix socket access allowlist-based unless you deliberately bypass that protection. |

150

44You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:151You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:

45 152

46```toml153```toml

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

122```229```

123 230

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

232and failure behavior, see

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

234

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

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

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

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

128 239

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

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

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

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

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

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

134 246

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)247The [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 its248is in the open-source Codex repository. Enterprises can replace its

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

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

141 253

142In the Codex app, these reviews appear as automatic review items with a status such254In 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 a255such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also

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

257request.

145 258

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

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

148 261

149### Common sandbox and approval combinations262### Common sandbox and approval combinations

150 263

152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |265| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

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

158 272

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.273For 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.

app.md +15 −0

Details

139 139

140Keep parallel code changes isolated with built-in Git worktree support.140Keep parallel code changes isolated with built-in Git worktree support.

141 141

142 </BentoContent>

143 <BentoContent href="/codex/remote-connections">

144

145### Remote connections

146

147Use the ChatGPT mobile app to start, steer, approve, and review Codex work on a

148connected host.

149

142 </BentoContent>150 </BentoContent>

143 <BentoContent href="/codex/app/computer-use">151 <BentoContent href="/codex/app/computer-use">

144 152

167 175

168Open rendered pages, leave comments, or let Codex operate local browser flows.176Open rendered pages, leave comments, or let Codex operate local browser flows.

169 177

178 </BentoContent>

179 <BentoContent href="/codex/app/chrome-extension">

180

181### Chrome extension

182

183Add the Chrome plugin so Codex can use Chrome for signed-in browser tasks while you manage website approvals.

184

170 </BentoContent>185 </BentoContent>

171 <BentoContent href="/codex/app/features#image-generation">186 <BentoContent href="/codex/app/features#image-generation">

172 187

app-server.md +140 −18

Details

12Supported transports:12Supported transports:

13 13

14- `stdio` (`--listen stdio://`, default): newline-delimited JSON (JSONL).14- `stdio` (`--listen stdio://`, default): newline-delimited JSON (JSONL).

~~15- `websocket` (`--listen ws://IP:PORT`, experimental and unsupported): one JSON-RPC message per WebSocket text frame.~~15- `websocket` (`--listen ws://IP:PORT`, experimental and unsupported): one

16 JSON-RPC message per WebSocket text frame.

17- Unix socket (`--listen unix://` or `--listen unix://PATH`): WebSocket

18 connections over Codex's default app-server control socket or a custom Unix

19 socket path, using the standard HTTP Upgrade handshake.

16- `off` (`--listen off`): don't expose a local transport.20- `off` (`--listen off`): don't expose a local transport.

17 21

~~18When you run with `--listen ws://IP:PORT`, the same listener also serves basic HTTP health probes:~~22When you run with `--listen ws://IP:PORT`, the same listener also serves basic

23HTTP health probes:

19 24

20- `GET /readyz` returns `200 OK` once the listener accepts new connections.25- `GET /readyz` returns `200 OK` once the listener accepts new connections.

~~21- `GET /healthz` returns `200 OK` when the request doesn't include an `Origin` header.~~26- `GET /healthz` returns `200 OK` when the request doesn't include an `Origin`

27 header.

22- Requests with an `Origin` header are rejected with `403 Forbidden`.28- Requests with an `Origin` header are rejected with `403 Forbidden`.

23 29

24WebSocket transport is experimental and unsupported. Loopback listeners such as `ws://127.0.0.1:PORT` are appropriate for localhost and SSH port-forwarding workflows. Non-loopback WebSocket listeners currently allow unauthenticated connections by default during rollout, so configure WebSocket auth before exposing one remotely.30WebSocket transport is experimental and unsupported. Local listeners such as

31`ws://127.0.0.1:PORT` are appropriate for localhost and SSH port-forwarding

32workflows. Non-loopback WebSocket listeners currently allow unauthenticated

33connections by default during rollout, so configure WebSocket auth before

34exposing one remotely.

25 35

26Supported WebSocket auth flags:36Supported WebSocket auth flags:

27 37

29- `--ws-auth capability-token --ws-token-sha256 HEX`39- `--ws-auth capability-token --ws-token-sha256 HEX`

30- `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`40- `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`

31 41

32For signed bearer tokens, you can also set `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`. Clients present the credential as `Authorization: Bearer <token>` during the WebSocket handshake, and app-server enforces auth before JSON-RPC `initialize`.42For signed bearer tokens, you can also set `--ws-issuer`, `--ws-audience`, and

43`--ws-max-clock-skew-seconds`. Clients present the credential as

44`Authorization: Bearer <token>` during the WebSocket handshake, and app-server

45enforces auth before JSON-RPC `initialize`.

33 46

34Prefer `--ws-token-file` over passing raw bearer tokens on the command line. Use `--ws-token-sha256` only when the client keeps the raw high-entropy token in a separate local secret store; the hash is only a verifier, and clients still need the original token.47Prefer `--ws-token-file` over passing raw bearer tokens on the command line. Use

48`--ws-token-sha256` only when the client keeps the raw high-entropy token in a

49separate local secret store; the hash is only a verifier, and clients still need

50the original token.

35 51

36In WebSocket mode, app-server uses bounded queues. When request ingress is full, the server rejects new requests with JSON-RPC error code `-32001` and message `"Server overloaded; retry later."` Clients should retry with an exponentially increasing delay and jitter.52In WebSocket mode, app-server uses bounded queues. When request ingress is full,

53the server rejects new requests with JSON-RPC error code `-32001` and message

54`"Server overloaded; retry later."` Clients should retry with an exponentially

55increasing delay and jitter.

37 56

38## Message schema57## Message schema

39 58

68 87

69## Getting started88## Getting started

70 89

~~711. Start the server with `codex app-server` (default stdio transport) or `codex app-server --listen ws://127.0.0.1:4500` (experimental WebSocket transport).~~901. Start the server with `codex app-server` (default stdio transport),

91 `codex app-server --listen ws://127.0.0.1:4500` (TCP WebSocket), or

92 `codex app-server --listen unix://` (default Unix socket).

722. Connect a client over the selected transport, then send `initialize` followed by the `initialized` notification.932. Connect a client over the selected transport, then send `initialize` followed by the `initialized` notification.

733. Start a thread and a turn, then keep reading notifications from the active transport stream.943. Start a thread and a turn, then keep reading notifications from the active transport stream.

74 95

216 237

217- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.238- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.

218- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.239- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

219- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.240- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread. Returned threads include `forkedFromId` when available.

220- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.241- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.

221- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filters. Returned `thread` objects include runtime `status`.242- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filters. Returned `thread` objects include runtime `status`.

222- `thread/turns/list` - page through a stored thread's turn history without resuming it.243- `thread/turns/list` - page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.

244- `thread/turns/items/list` - reserved for paged turn-item loading; currently returns unsupported.

223- `thread/loaded/list` - list the thread ids currently loaded in memory.245- `thread/loaded/list` - list the thread ids currently loaded in memory.

224- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.246- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.

225- `thread/goal/set` - set the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/updated`.247- `thread/goal/set` - set the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/updated`.

244- `command/exec/resize` - resize a running PTY-backed `command/exec` session.266- `command/exec/resize` - resize a running PTY-backed `command/exec` session.

245- `command/exec/terminate` - stop a running `command/exec` session.267- `command/exec/terminate` - stop a running `command/exec` session.

246- `command/exec/outputDelta` (notify) - emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.268- `command/exec/outputDelta` (notify) - emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.

269- `process/spawn` - start an explicit process session outside Codex's sandbox (experimental; requires `capabilities.experimentalApi`).

270- `process/writeStdin` - write stdin bytes to a running `process/spawn` session or close stdin (experimental).

271- `process/resizePty` - resize a running PTY-backed process session (experimental).

272- `process/kill` - terminate a running process session (experimental).

273- `process/outputDelta` and `process/exited` (notify) - emitted for streaming process output and process exit status (experimental).

247- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.274- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.

248- `modelProvider/capabilities/read` - read provider capability bounds for model/provider combinations (experimental; requires `capabilities.experimentalApi`).275- `modelProvider/capabilities/read` - read provider capability bounds for model/provider combinations (experimental; requires `capabilities.experimentalApi`).

249- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.276- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

250- `experimentalFeature/enablement/set` - patch in-memory runtime enablement for supported feature keys such as `apps` and `plugins`.277- `experimentalFeature/enablement/set` - patch in-memory runtime settings for supported feature keys such as `apps` and `plugins`.

251- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).278- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

252- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).279- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

253- `skills/changed` (notify) - emitted when watched local skill files change.280- `skills/changed` (notify) - emitted when watched local skill files change.

351## Threads378## Threads

352 379

353- `thread/read` reads a stored thread without subscribing to it; set `includeTurns` to include turns.380- `thread/read` reads a stored thread without subscribing to it; set `includeTurns` to include turns.

354- `thread/turns/list` pages through a stored thread's turn history without resuming it.381- `thread/turns/list` pages through a stored thread's turn history without

382 resuming it. Use `itemsView` to choose whether turn items are omitted,

383 summarized, or fully loaded.

355- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filtering.384- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filtering.

356- `thread/loaded/list` returns the thread IDs currently in memory.385- `thread/loaded/list` returns the thread IDs currently in memory.

357- `thread/archive` moves the thread's persisted JSONL log into the archived directory.386- `thread/archive` moves the thread's persisted JSONL log into the archived directory.

378{ "id": 10, "result": {407{ "id": 10, "result": {

379 "thread": {408 "thread": {

380 "id": "thr_123",409 "id": "thr_123",

410 "sessionId": "thr_123",

381 "preview": "",411 "preview": "",

382 "ephemeral": false,412 "ephemeral": false,

383 "modelProvider": "openai",413 "modelProvider": "openai",

389 419

390`serviceName` is optional. Set it when you want app-server to tag thread-level metrics with your integration's service name.420`serviceName` is optional. Set it when you want app-server to tag thread-level metrics with your integration's service name.

391 421

422`thread.sessionId` identifies the current live session tree root. Root threads

423use their own thread id as the session id; forked threads keep the session id

424of the root they came from. Clients should read the session id from

425`thread.sessionId` instead of deriving it from the thread id.

426

392To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:427To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:

393 428

394```json429```json

407 442

408If you resume with a different model than the one recorded in the rollout, Codex emits a warning and applies a one-time model-switch instruction on the next turn.443If you resume with a different model than the one recorded in the rollout, Codex emits a warning and applies a one-time model-switch instruction on the next turn.

409 444

445### Manage a thread goal

446

447`thread/goal/set`, `thread/goal/get`, and `thread/goal/clear` are experimental

448and require `capabilities.experimentalApi = true` plus the `goals` feature. Use

449them for the same persisted goal state surfaced by `/goal` in the TUI.

450

451```json

452{ "method": "thread/goal/set", "id": 13, "params": {

453 "threadId": "thr_123",

454 "objective": "Finish the migration and keep tests green",

455 "status": "active",

456 "tokenBudget": 40000

457} }

458{ "id": 13, "result": { "goal": {

459 "threadId": "thr_123",

460 "objective": "Finish the migration and keep tests green",

461 "status": "active",

462 "tokenBudget": 40000,

463 "tokensUsed": 0,

464 "timeUsedSeconds": 0

465} } }

466{ "method": "thread/goal/updated", "params": {

467 "threadId": "thr_123",

468 "goal": {

469 "threadId": "thr_123",

470 "objective": "Finish the migration and keep tests green",

471 "status": "active",

472 "tokenBudget": 40000,

473 "tokensUsed": 0,

474 "timeUsedSeconds": 0

475 }

476} }

477```

478

479Goal objectives must be non-empty and at most 4,000 characters. Supplying a new

480objective replaces the goal and resets usage accounting. Supplying the current

481non-terminal objective, or omitting `objective`, updates status or token budget

482while preserving usage history.

483

410To branch from a stored session, call `thread/fork` with the `thread.id`. This creates a new thread id and emits a `thread/started` notification for it:484To branch from a stored session, call `thread/fork` with the `thread.id`. This creates a new thread id and emits a `thread/started` notification for it:

411 485

412```json486```json

413{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123" } }487{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123" } }

414{ "id": 12, "result": { "thread": { "id": "thr_456" } } }488{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }

415{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }489{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

416```490```

417 491

435 509

436Use `thread/turns/list` to page a stored thread's turn history without resuming it. Results default to newest-first so clients can fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.510Use `thread/turns/list` to page a stored thread's turn history without resuming it. Results default to newest-first so clients can fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.

437 511

512`itemsView` controls how much turn-item data the response includes:

513

514- `notLoaded` omits items.

515- `summary` returns summarized item data and is the default when omitted.

516- `full` returns full item data.

517

438```json518```json

439{ "method": "thread/turns/list", "id": 20, "params": {519{ "method": "thread/turns/list", "id": 20, "params": {

440 "threadId": "thr_123",520 "threadId": "thr_123",

441 "limit": 50,521 "limit": 50,

442 "sortDirection": "desc"522 "sortDirection": "desc",

523 "itemsView": "summary"

443} }524} }

444{ "id": 20, "result": {525{ "id": 20, "result": {

445 "data": [],526 "data": [],

448} }529} }

449```530```

450 531

532`thread/turns/items/list` is reserved for paged turn-item loading, but the

533current server returns an unsupported-method error.

534

451### List threads (with pagination & filters)535### List threads (with pagination & filters)

452 536

453`thread/list` lets you render a history UI. Results default to newest-first by `createdAt`. Filters apply before pagination. Pass any combination of:537`thread/list` lets you render a history UI. Results default to newest-first by `createdAt`. Filters apply before pagination. Pass any combination of:

825 909

826Use this notification to render the reviewer output in your client.910Use this notification to render the reviewer output in your client.

827 911

912## Process execution

913

914`process/*` is an experimental, explicit process-control API. It requires

915`capabilities.experimentalApi = true` and runs outside Codex's sandbox. Use it

916only when your client intentionally exposes local process control without a

917sandbox.

918

919Start a process with `process/spawn` and provide a `processHandle`, then use

920that handle for stdin, resize, and kill requests. Output streams through

921`process/outputDelta` notifications and completion streams through

922`process/exited`.

923

924```json

925{ "method": "process/spawn", "id": 48, "params": {

926 "command": ["python3", "-m", "pytest", "-q"],

927 "processHandle": "pytest-1",

928 "cwd": "/Users/me/project",

929 "tty": true

930} }

931{ "id": 48, "result": {} }

932{ "method": "process/outputDelta", "params": {

933 "processHandle": "pytest-1",

934 "stream": "stdout",

935 "deltaBase64": "Li4u"

936} }

937{ "method": "process/exited", "params": {

938 "processHandle": "pytest-1",

939 "exitCode": 0

940} }

941```

942

943Use `process/writeStdin` with `deltaBase64`, `closeStdin`, or both to send

944input. Use `process/resizePty` for PTY resize events and `process/kill` to

945terminate a running process.

946

828## Command execution947## Command execution

829 948

830`command/exec` runs a single command (`argv` array) under the server sandbox without creating a thread.949`command/exec` runs a single command (`argv` array) under the server sandbox without creating a thread.

990- `item/reasoning/summaryPartAdded` - marks a boundary between reasoning summary sections.1109- `item/reasoning/summaryPartAdded` - marks a boundary between reasoning summary sections.

991- `item/reasoning/textDelta` - streams raw reasoning text (when supported by the model).1110- `item/reasoning/textDelta` - streams raw reasoning text (when supported by the model).

992- `item/commandExecution/outputDelta` - streams stdout/stderr for a command; append deltas in order.1111- `item/commandExecution/outputDelta` - streams stdout/stderr for a command; append deltas in order.

993- `item/fileChange/outputDelta` - contains the tool call response of the underlying `apply_patch` tool call.1112- `item/fileChange/outputDelta` - deprecated compatibility notification for legacy `apply_patch` text output. Current app-server versions no longer emit it; use `fileChange` items and `turn/diff/updated` instead.

994 1113

995## Errors1114## Errors

996 1115

1050 1169

1051`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.1170`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.

1052 1171

1172Dynamic tool names and namespace names must follow Responses API naming

1173constraints. Avoid reserved namespace names used by built-in Codex tools.

1174

1053When a dynamic tool is invoked during a turn, app-server emits:1175When a dynamic tool is invoked during a turn, app-server emits:

1054 1176

10551. `item/started` with `item.type = "dynamicToolCall"`, `status = "inProgress"`, plus `tool` and `arguments`.11771. `item/started` with `item.type = "dynamicToolCall"`, `status = "inProgress"`, plus `tool` and `arguments`.

1662- `usedPercent` is current usage within the quota window.1784- `usedPercent` is current usage within the quota window.

1663- `windowDurationMins` is the quota window length.1785- `windowDurationMins` is the quota window length.

1664- `resetsAt` is a Unix timestamp (seconds) for the next reset.1786- `resetsAt` is a Unix timestamp (seconds) for the next reset.

1665- `planType` is included when the backend returns the ChatGPT plan associated with a bucket.1787- `planType` is included when the server returns the ChatGPT plan associated with a bucket.

1666- `credits` is included when the backend returns remaining workspace credit details.1788- `credits` is included when the server returns remaining workspace credit details.

1667- `rateLimitReachedType` identifies the backend-classified limit state when one has been reached.1789- `rateLimitReachedType` identifies the server-classified limit state when one has been reached.

1668 1790

1669### 7) Notify a workspace owner about a limit1791### 7) Notify a workspace owner about a limit

1670 1792

app/browser.md +5 −1

Details

6 6

7Use it for local development servers, file-backed previews, and public pages7Use it for local development servers, file-backed previews, and public pages

8that don't require sign-in. For anything that depends on login state or browser8that don't require sign-in. For anything that depends on login state or browser

~~9extensions, use your regular browser.~~9extensions, use your regular browser or the

10[Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension).

10 11

11Open the in-app browser from the toolbar, by clicking a URL, by navigating12Open the in-app browser from the toolbar, by clicking a URL, by navigating

12manually in the browser, or by pressing <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>13manually in the browser, or by pressing <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>

48the allowed list means Codex asks again before using it; removing a site from the49the allowed list means Codex asks again before using it; removing a site from the

49blocked list means Codex can ask again instead of treating it as blocked.50blocked list means Codex can ask again instead of treating it as blocked.

50 51

52For signed-in websites in Chrome, see

53[Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension).

51## Preview a page55## Preview a page

52 56

531. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).571. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).

app/chrome-extension.md +172 −0 added

Details

1# Codex Chrome extension

3The Codex Chrome extension lets Codex use Chrome for browser tasks that need

4your signed-in browser state. Use it when Codex needs to read or act on sites

5such as LinkedIn, Salesforce, Gmail, or internal tools.

7For local development servers, file-backed previews, and public pages that do

8not require sign-in, use the [in-app browser](https://developers.openai.com/codex/app/browser) first. The

9in-app browser keeps preview and verification work inside Codex without using

10your Chrome profile.

12Codex can also switch between tools as a task requires, using plugins when a

13dedicated integration is available, Chrome when it needs logged-in browser

14context, and the in-app browser for localhost.

16<div className="not-prose my-4">

17 <Alert

18 client:load

19 color="warning"

20 variant="soft"

21 description="Treat page content as untrusted context, and review the website before allowing Codex to continue."

22 />

23</div>

25## Set up Chrome from Plugins

27Set up the extension from Codex:

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

302. Add the **Chrome** plugin.

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

32 extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg)

33 and approving Chrome's permission prompts.

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

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

37Chrome when a task needs a signed-in website. You can also invoke it directly in

38a prompt:

40```text

41@Chrome open Salesforce and update the account from these call notes.

42```

44If Chrome isn't already open, Codex can open it. Chrome browser tasks run in

45Chrome tab groups so the work for a thread stays grouped together.

47## Control website access

49By default, Codex asks before it interacts with each new website. Codex bases

50the prompt on the website host, such as `example.com`.

52When Codex asks to use a website, you can choose the option that matches the

53task and your risk tolerance:

55- Allow the website for the current chat.

56- Always allow the host so Codex can use that website again without asking.

57- Decline the website.

59### Manage the allowlist and blocklist

61In Computer Use settings, you can manage an allowlist and blocklist for

62domains. The allowlist contains domains Codex can use without asking again. The

63blocklist contains domains Codex shouldn't use.

65Removing a domain from the allowlist means Codex asks again before using it.

66Removing a domain from the blocklist means Codex can ask again instead of

67treating the domain as blocked.

69#### Always allow browser content <ElevatedRiskBadge class="ml-2" />

71If you turn on always allow browser content, Codex no longer asks for

72confirmation before using websites.

74#### Browser history <ElevatedRiskBadge class="ml-2" />

76Browser history can include sensitive telemetry, internal URLs, search terms,

77and activity from Chrome sessions on signed-in devices. If you allow Codex to

78access browser history, relevant history entries can become part of the context

79Codex uses for the task. Malicious or misleading page content can increase the

80risk that Codex copies this data somewhere unintended.

82Codex asks when it wants to use browser history. Codex scopes history access to

83the request, and history doesn't have an always-allow option.

85## Data and security

87### Chrome extension permissions

89Chrome asks you to accept extension permissions when you install the extension.

90The permission prompt may include:

92- Access the page debugger

93- Read and change all your data on all websites

94- Read and change your browsing history on all your signed-in devices

95- Display notifications

96- Read and change your bookmarks

97- Manage your downloads

98- Communicate with cooperating native applications

99- View and manage your tab groups

100

101These Chrome permissions make the extension capable of operating browser

102workflows. Codex still uses its own confirmations, settings, allowlists, and

103blocklists before using websites or browser history during a task.

104

105### Memories

106

107Browser use follows your Codex Memories setting. If Memories is on, Codex can

108use relevant saved memories while working in Chrome. If Memories is off, browser

109use doesn't use memories.

110

111### What OpenAI stores from browsing

112

113OpenAI doesn't store a separate complete record of your Chrome actions from the

114extension. OpenAI stores browser activity only when it becomes part of the Codex

115context, such as text Codex reads from a page, screenshots, tool calls,

116summaries, messages, or other content included in the thread.

117

118Your ChatGPT and Codex data controls apply to content processed in context.

119Avoid sending secrets or highly sensitive data through browser tasks unless

120they're required and you are present to review each prompt.

121

122## Troubleshooting

123

124If Codex can't connect to Chrome, first confirm the website Codex is trying to

125access isn't in the blocklist in Settings. If the website isn't blocked, work

126through these checks:

127

1281. Open the Codex extension from the Chrome toolbar or Chrome's extensions

129 menu. Make sure it shows **Connected**. If it shows disconnected or mentions

130 a missing native host, remove and re-add the Chrome plugin from **Plugins**

131 in Codex, then follow the setup flow again.

1322. In Codex, open **Plugins** and confirm that the Chrome plugin is on. If the

133 plugin is off, turn it on and try the task again.

1343. Make sure you are using the same Chrome profile where the Codex extension is

135 installed. If you use more than one Chrome profile, install and enable the

136 extension in the active profile.

1374. Start a new Codex thread and try the Chrome task again. This can clear a

138 thread-specific connection state.

1395. Restart Chrome and Codex, then try again. If the extension still doesn't

140 connect, uninstall the Codex Chrome extension, remove and re-add the Chrome

141 plugin from **Plugins**, and follow the setup flow again.

1426. If the extension shows **Connected** but Codex still can't use Chrome, run

143 `/feedback` in the Codex app and include the thread ID when you contact

144 support.

145

146<CodexScreenshot

147 alt="Codex Chrome extension showing connected status"

148 lightSrc="/images/codex/app/chrome-connected-light.png"

149 darkSrc="/images/codex/app/chrome-connected-dark.png"

150 maxHeight="300px"

151 class="mt-4"

152/>

153

154### Upload Files

155

156If a Chrome task needs to upload a file from your computer, allow the Codex

157extension to access file URLs in Chrome:

158

1591. In Chrome, open the extensions icon in the toolbar, then click **Manage

160 Extensions**.

1612. On the Codex extension card, click **Details**.

1623. Turn on **Allow access to file URLs**.

163

164After you change the setting, start the Chrome task again.

165

166<CodexScreenshot

167 alt="Chrome extension settings showing Allow access to file URLs enabled for Codex"

168 lightSrc="/images/codex/app/chrome-file-url-access-light.webp"

169 darkSrc="/images/codex/app/chrome-file-url-access-dark.webp"

170 maxHeight="420px"

171 class="mt-4"

172/>

app/computer-use.md +1 −1

Details

49 49

50## Start a computer use task50## Start a computer use task

51 51

~~52Mention `@Computer Use` or `@AppName` in your prompt, or ask Codex to use~~52Mention `@Computer` or `@AppName` in your prompt, or ask Codex to use

53computer use. Describe the exact app, window, or flow Codex should operate.53computer use. Describe the exact app, window, or flow Codex should operate.

54 54

55```text55```text

app/settings.md +5 −4

Details

85 85

86## Browser use86## Browser use

87 87

~~88Use these settings to install or enable the bundled Browser plugin and manage~~88Use these settings to install or enable the bundled Browser plugin, set up the

~~89allowed and blocked websites. Codex asks before using a website unless you've~~89[Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension), and manage allowlisted

~~90allowed it. Removing a site from the blocked list lets Codex ask~~90and blocklisted websites. Codex asks before using a website unless you've

~~91again before using it in the browser.~~91allowlisted it. Removing a site from the blocklist lets Codex ask again before

92using it in the browser.

92 93

93See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and94See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and

94browser use workflows.95browser use workflows.

auth.md +23 −2

Details

20 20

21When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.21When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.

22 22

23If your environment already provides a ChatGPT access token, the CLI can read

24it from stdin:

26```shell

27printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

28```

23### Sign in with an API key30### Sign in with an API key

24 31

25You can also sign in to the Codex app, CLI, or IDE Extension with an API key. Get your API key from the [OpenAI dashboard](https://platform.openai.com/api-keys).32You can also sign in to the Codex app, CLI, or IDE Extension with an API key. Get your API key from the [OpenAI dashboard](https://platform.openai.com/api-keys).

30available only when you sign in with ChatGPT. If you sign in with an API key,37available only when you sign in with ChatGPT. If you sign in with an API key,

31Codex uses standard API pricing instead.38Codex uses standard API pricing instead.

32 39

~~33Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Don't expose Codex execution in untrusted or public environments.~~40We recommend API key authentication for programmatic Codex CLI workflows, such

41as CI/CD jobs. Don't expose Codex execution in untrusted or public environments.

43### Use Codex access tokens for enterprise automation

45In ChatGPT Enterprise workspaces, admins can allow permitted members to create

46Codex access tokens for trusted, non-interactive Codex local workflows. Use an

47access token when automation needs ChatGPT workspace access, ChatGPT-managed

48Codex entitlements, or enterprise workspace controls without a browser sign-in.

50Access tokens are intended for trusted scripts, schedulers, and private CI

51runners. For general OpenAI API calls, continue to use Platform API keys.

53For setup steps, permissions, rotation, and revocation guidance, see

54[Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

34 55

35## Secure your Codex cloud account56## Secure your Codex cloud account

36 57

102If your network uses a corporate TLS proxy or private root CA, set123If your network uses a corporate TLS proxy or private root CA, set

103`CODEX_CA_CERTIFICATE` to a PEM bundle before logging in. When124`CODEX_CA_CERTIFICATE` to a PEM bundle before logging in. When

104`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. The same125`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. The same

105custom CA settings apply to login, normal HTTPS requests, and secure websocket126custom CA settings apply to login, normal HTTPS requests, and secure WebSocket

106connections.127connections.

107 128

108```shell129```shell

cli/features.md +32 −38

Details

48 48

49## Connect the TUI to a remote app server49## Connect the TUI to a remote app server

50 50

51Remote TUI mode lets you run the Codex app server on one machine and use the Codex terminal UI from another machine. This is useful when the code, credentials, or execution environment live on a remote host, but you want the local interactive TUI experience.51Remote TUI mode lets you run the Codex app server on one machine and use the

52 52Codex terminal UI from another machine. Start the app server with a WebSocket

~~53Start the app server on the machine that should own the workspace and run commands:~~53listener:

54 54

55```bash55```bash

56codex app-server --listen ws://127.0.0.1:450056codex app-server --listen ws://127.0.0.1:4500

57```57```

58 58

~~59Then connect from the machine running the TUI:~~59Then connect the TUI to that endpoint:

60 60

61```bash61```bash

62codex --remote ws://127.0.0.1:450062codex --remote ws://127.0.0.1:4500

63```63```

64 64

~~65For access from another machine, bind the app server to a reachable interface, for example:~~65For access from another machine, bind the app server to a reachable interface

66 66and configure WebSocket auth before remote use:

~~67```bash~~

~~68codex app-server --listen ws://0.0.0.0:4500~~

~~69```~~

71`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses only. For plain WebSocket connections, prefer local-host addresses or SSH port forwarding. If you expose the listener beyond the local host, configure authentication before real remote use and put authenticated non-local connections behind TLS.

~~73Codex supports these WebSocket authentication modes for remote TUI connections:~~

75- **No WebSocket auth**: Best for local-host listeners or SSH port-forwarded connections. Codex can start non-local listeners without auth, but logs a warning and the startup banner reminds you to configure auth before real remote use.

76- **Capability token**: Store a shared token in a file on the app-server host, start the server with `--ws-auth capability-token --ws-token-file /abs/path/to/token`, then set the same token in an environment variable on the TUI host and pass `--remote-auth-token-env <ENV_VAR>`.

77- **Signed bearer token**: Store an HMAC shared secret in a file on the app-server host, start the server with `--ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret`, and have the TUI send a signed JWT bearer token through `--remote-auth-token-env <ENV_VAR>`. The shared secret must be at least 32 bytes. Signed tokens use HS256 and must include `exp`; Codex also validates `nbf`, `iss`, and `aud` when those claims or server options are present.

~~79To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:~~

80 67

81```bash68```bash

~~82TOKEN_FILE="$HOME/.codex/codex-app-server-token"~~69TOKEN_FILE="$HOME/.codex/app-server-token"

~~83install -d -m 700 "$(dirname "$TOKEN_FILE")"~~

84openssl rand -base64 32 > "$TOKEN_FILE"70openssl rand -base64 32 > "$TOKEN_FILE"

85chmod 600 "$TOKEN_FILE"71chmod 600 "$TOKEN_FILE"

72codex app-server --listen ws://0.0.0.0:4500 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"

86```73```

87 74

~~88Treat the token file like a password, and regenerate it if it leaks.~~75`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses.

76Plain WebSocket connections are appropriate for localhost and SSH

77port-forwarding workflows. For non-local clients, use WebSocket auth and put the

78connection behind TLS.

80Codex supports these WebSocket authentication modes:

82- Capability token: start the server with `--ws-auth capability-token` and

83 either `--ws-token-file /absolute/path` or `--ws-token-sha256 HEX`.

84- Signed bearer token: start the server with

85 `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`, plus

86 optional `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`.

89 87

~~90Then start the app server with that token file. For example, with a capability token behind a TLS proxy:~~88The TUI sends the remote auth token as an `Authorization: Bearer <token>` header

89during the WebSocket handshake. Codex only accepts remote auth tokens over

90`wss://` URLs or loopback `ws://` URLs.

91 91

92```bash92```bash

~~93# Remote host~~93export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"

~~94TOKEN_FILE="$HOME/.codex/codex-app-server-token"~~94codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

~~95codex app-server \~~

~~96 --listen ws://0.0.0.0:4500 \~~

~~97 --ws-auth capability-token \~~

~~98 --ws-token-file "$TOKEN_FILE"~~

100# TUI host

101export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"

102codex --remote wss://codex-devbox.example.com:4500 \

103 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

104```95```

105 96

106The TUI sends remote auth tokens as `Authorization: Bearer <token>` during the WebSocket handshake. Codex only sends those tokens over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`, so put non-local remote listeners behind TLS if clients need to authenticate over the network.97For SSH remote projects in the Codex app, use

98[Remote connections](https://developers.openai.com/codex/remote-connections). For managed remote-control

99clients, `codex remote-control` starts an app-server process with

100remote-control support enabled.

107 101

108## Models and reasoning102## Models and reasoning

109 103

110For most tasks in Codex, `gpt-5.5` is the recommended model when it is104For most tasks in Codex, `gpt-5.5` is the recommended model when it's

111available. It is OpenAI's newest frontier model for complex coding, computer105available. It's OpenAI's newest frontier model for complex coding, computer

112use, knowledge work, and research workflows, with stronger planning, tool use,106use, knowledge work, and research workflows, with stronger planning, tool use,

113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,107and follow-through on multi-step tasks. If `gpt-5.5` isn't yet available,

114continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have108continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

115access to the GPT-5.3-Codex-Spark model in research preview.109access to the GPT-5.3-Codex-Spark model in research preview.

116 110

cli/reference.md +34 −7

Details

122 href: "/codex/cli/reference#codex-app-server",122 href: "/codex/cli/reference#codex-app-server",

123 type: "experimental",123 type: "experimental",

124 description:124 description:

125 "Launch the Codex app server for local development or debugging.",125 "Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.",

126 },

127 {

128 key: "codex remote-control",

129 href: "/codex/cli/reference#codex-remote-control",

130 type: "experimental",

131 description:

132 "Ensure the local app-server daemon is running with remote-control support enabled.",

126 },133 },

127 {134 {

128 key: "codex app",135 key: "codex app",

192 href: "/codex/cli/reference#codex-login",199 href: "/codex/cli/reference#codex-login",

193 type: "stable",200 type: "stable",

194 description:201 description:

195 "Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.",202 "Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.",

196 },203 },

197 {204 {

198 key: "codex logout",205 key: "codex logout",

375export const appServerOptions = [382export const appServerOptions = [

376 {383 {

377 key: "--listen",384 key: "--listen",

379 defaultValue: "stdio://",386 defaultValue: "stdio://",

380 description:387 description:

381 "Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.",388 "Transport listener URL. Use `stdio://` for JSONL, `ws://IP:PORT` for a TCP WebSocket endpoint, `unix://` for the default Unix socket, `unix://PATH` for a custom Unix socket, or `off` to disable the local transport.",

382 },389 },

383 {390 {

384 key: "--ws-auth",391 key: "--ws-auth",

417 description:424 description:

418 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",425 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",

419 },426 },

427 {

428 key: "--analytics-default-enabled",

429 type: "boolean",

430 defaultValue: "false",

431 description:

432 "Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.",

433 },

420];434];

421 435

422export const appOptions = [436export const appOptions = [

583 description:597 description:

584 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",598 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",

585 },599 },

600 {

601 key: "--with-access-token",

602 type: "boolean",

603 description:

604 "Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).",

605 },

586 {606 {

587 key: "--device-auth",607 key: "--device-auth",

588 type: "boolean",608 type: "boolean",

893 913

894Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.914Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

895 915

896Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.916Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication.

897 917

898### `codex app-server`918### `codex app-server`

899 919

901 921

902<ConfigTable client:load options={appServerOptions} />922<ConfigTable client:load options={appServerOptions} />

903 923

904`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.924`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. Use `--listen unix://` to accept WebSocket handshakes on Codex's default Unix socket, or `--listen unix:///absolute/path.sock` to choose a socket path. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

925

926### `codex remote-control`

927

928Ensure the app-server daemon is running with remote-control support enabled.

929Managed remote-control clients and SSH remote workflows use this command; it's

930not a replacement for `codex app-server --listen` when you are building a local

931protocol client.

905 932

906### `codex app`933### `codex app`

907 934

983 1010

984### `codex login`1011### `codex login`

985 1012

986Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.1013Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.

987 1014

988<ConfigTable client:load options={loginOptions} />1015<ConfigTable client:load options={loginOptions} />

989 1016

cli/slash-commands.md +112 −5

Details

9 9

10- Find the right built-in slash command for a task10- Find the right built-in slash command for a task

11- Steer an active session with commands like `/model`, `/fast`,11- Steer an active session with commands like `/model`, `/fast`,

~~12 `/personality`, `/permissions`, `/agent`, and `/status`~~12 `/personality`, `/permissions`, `/approve`, `/raw`, `/agent`, and `/status`

13 13

14## Built-in slash commands14## Built-in slash commands

15 15

25| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |25| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

26| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |26| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |

27| [`/ide`](#include-ide-context-with-ide) | Include open files, current selection, and other IDE context. | Pull editor context into the next prompt without re-explaining what's open in your IDE. |

28| [`/keymap`](#remap-tui-shortcuts-with-keymap) | Remap TUI keyboard shortcuts. | Inspect and persist custom shortcut bindings in `config.toml`. |

29| [`/vim`](#toggle-vim-mode-with-vim) | Toggle Vim mode for the composer. | Switch between Vim normal/insert behavior and the default composer editing mode. |

27| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |30| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |

30| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |33| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

34| [`/hooks`](#review-hooks-with-hooks) | Review lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |

31| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |35| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |

32| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |36| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

33| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |37| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

41| [`/approve`](#approve-an-auto-review-denial-with-approve) | Approve one retry of a recent auto review denial. | Retry a command or action that the auto reviewer denied. |

42| [`/memories`](#configure-memories-with-memories) | Configure memory use and generation. | Turn memory injection or memory generation on or off without leaving the TUI. |

43| [`/skills`](#use-skills-with-skills) | Browse and use skills. | Improve task-specific behavior by selecting a relevant local skill. |

44| [`/hooks`](#view-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect hook configuration loaded into the current session. |

38| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |46| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

40| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |48| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |

42| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |50| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |

43| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for supported models. | Turn Fast mode on or off, or check whether the current thread is using it. |51| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model's Fast tier on or off, or check whether the thread is using it. |

44| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |52| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |

53| [`/goal`](#set-or-view-an-experimental-task-goal-with-goal) | Set, pause, resume, view, or clear a task goal. | Give Codex a persistent target to track while a larger task runs. Requires `features.goals`. |

45| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |54| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

46| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |55| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

48| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |57| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |

59| [`/raw`](#toggle-raw-scrollback-with-raw) | Toggle raw scrollback mode. | Make terminal selection and copying less formatted while reviewing long output. |

50| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |60| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |

51| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |61| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |

55| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |65| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |

56| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |66| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |

57| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |67| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |

59 69

60`/quit` and `/exit` both exit the CLI. Use them only after you have saved or70`/quit` and `/exit` both exit the CLI. Use them only after you have saved or

61committed any important work.71committed any important work.

62 72

~~63The `/approvals` command still works as an alias, but it no longer appears in the slash popup list.~~73Use `/permissions` to adjust what Codex can do without asking first. Use

74`/approve` only when you need to retry a recent action that automatic review

75denied.

64 76

65## Control your session with slash commands77## Control your session with slash commands

66 78

791. Type `/fast on`, `/fast off`, or `/fast status`.911. Type `/fast on`, `/fast off`, or `/fast status`.

802. If you want the setting to persist, confirm the update when Codex offers to save it.922. If you want the setting to persist, confirm the update when Codex offers to save it.

81 93

~~82Expected: Codex reports whether Fast mode is on or off for the current thread. In the TUI footer, you can also show a Fast mode status-line item with `/statusline`.~~94Expected: Codex reports whether the current model's Fast service tier is on or

95off for the current thread. In the TUI footer, you can also show a Fast mode

96status-line item with `/statusline`.

98Fast tier commands are catalog-driven. If the current model doesn't advertise a

99Fast tier, Codex won't show `/fast`.

83 100

84### Set a communication style with `/personality`101### Set a communication style with `/personality`

85 102

108 125

109While a task is already running, `/plan` is temporarily unavailable.126While a task is already running, `/plan` is temporarily unavailable.

110 127

128### Set an experimental goal with `/goal`

129

130`/goal` is experimental and only available when `features.goals` is enabled. To enable it, open `/experimental` or add `goals = true` under `[features]` in `config.toml`.

131

1321. Type `/goal <objective>` to set the goal, for example `/goal Finish the migration and keep tests green`.

1332. Type `/goal` to view the current goal.

1343. Use `/goal pause`, `/goal resume`, or `/goal clear` to pause, resume, or remove it.

135

136Expected: Codex keeps the goal attached to the active thread while work continues.

137

138Goal objectives must be non-empty and at most 4,000 characters. For longer

139instructions, put the details in a file and point the goal at that file.

140

111### Toggle experimental features with `/experimental`141### Toggle experimental features with `/experimental`

112 142

1131. Type `/experimental` and press Enter.1431. Type `/experimental` and press Enter.

115 145

116Expected: Codex saves your feature choices to config and applies them on restart.146Expected: Codex saves your feature choices to config and applies them on restart.

117 147

148### Approve an auto review denial with `/approve`

149

150Use `/approve` when the automatic reviewer denied a recent action and you want

151Codex to retry it once.

152

1531. Type `/approve`.

1542. Confirm the retry when Codex shows the relevant denied action.

155

156Expected: Codex retries that denied action once under the current session

157policy.

158

159### Configure memories with `/memories`

160

1611. Type `/memories`.

1622. Choose whether Codex should use existing memories, generate new memories, or

163 keep memory behavior disabled.

164

165Expected: Codex updates the relevant memory settings for future sessions.

166

167### Use skills with `/skills`

168

1691. Type `/skills`.

1702. Pick the skill you want Codex to apply.

171

172Expected: Codex inserts the selected skill context so the next request follows

173that skill's instructions.

174

175### View lifecycle hooks with `/hooks`

176

1771. Type `/hooks`.

1782. Review the loaded lifecycle hook configuration.

179

180Expected: Codex shows the hooks that can run in the current session.

181

118### Clear the terminal and start a new chat with `/clear`182### Clear the terminal and start a new chat with `/clear`

119 183

1201. Type `/clear` and press Enter.1841. Type `/clear` and press Enter.

136Expected: Codex announces the updated policy. Future actions respect the200Expected: Codex announces the updated policy. Future actions respect the

137updated approval mode until you change it again.201updated approval mode until you change it again.

138 202

203### Include IDE context with `/ide`

204

2051. Type `/ide`.

2062. Add optional inline text if you want to explain what Codex should do with the

207 current IDE selection or open files.

208

209Expected: Codex includes available IDE context in the next prompt.

210

211### Toggle Vim mode with `/vim`

212

2131. Type `/vim`.

2142. Continue editing in the composer.

215

216Expected: Codex toggles composer Vim mode for the current session. To make Vim

217mode the default for new sessions, set `tui.vim_mode_default = true` in

218`config.toml`.

219

139### Copy the latest response with `/copy`220### Copy the latest response with `/copy`

140 221

1411. Type `/copy` and press Enter.2221. Type `/copy` and press Enter.

149You can also press <kbd>Ctrl</kbd>+<kbd>O</kbd> from the main TUI to copy the230You can also press <kbd>Ctrl</kbd>+<kbd>O</kbd> from the main TUI to copy the

150latest completed response without opening the slash command menu.231latest completed response without opening the slash command menu.

151 232

233### Toggle raw scrollback with `/raw`

234

2351. Type `/raw`, `/raw on`, or `/raw off`.

236

237Expected: Codex toggles raw scrollback mode, which makes terminal selection and

238copying more direct. You can also use the default <kbd>Alt</kbd>+<kbd>R</kbd>

239binding or persist the default with `tui.raw_output_mode = true`.

240

152### Grant sandbox read access with `/sandbox-add-read-dir`241### Grant sandbox read access with `/sandbox-add-read-dir`

153 242

154This command is available only when running the CLI natively on Windows.243This command is available only when running the CLI natively on Windows.

202Available title items include app name, project, spinner, status, thread, git291Available title items include app name, project, spinner, status, thread, git

203branch, model, and task progress.292branch, model, and task progress.

204 293

294### Choose a syntax theme with `/theme`

295

2961. Type `/theme`.

2972. Preview a theme from the picker, then confirm.

298

299Expected: Codex updates syntax highlighting and persists the choice to

300`tui.theme` in `config.toml`.

301

205### Remap TUI shortcuts with `/keymap`302### Remap TUI shortcuts with `/keymap`

206 303

207Use `/keymap` to inspect, update, and persist keyboard shortcut bindings for the TUI.304Use `/keymap` to inspect, update, and persist keyboard shortcut bindings for the TUI.

338discoverable plugins that your configuration allows, and installed plugin state.435discoverable plugins that your configuration allows, and installed plugin state.

339Press <kbd>Space</kbd> on an installed plugin to toggle its enabled state.436Press <kbd>Space</kbd> on an installed plugin to toggle its enabled state.

340 437

438### Review hooks with `/hooks`

439

4401. Type `/hooks`.

4412. Choose a hook event to inspect the matching handlers.

4423. Trust, disable, or re-enable non-managed hooks as needed.

443

444Expected: Codex opens the hook browser so you can review configured lifecycle

445hooks. Managed hooks appear as managed and can't be disabled from the user hook

446browser.

447

341### Switch agent threads with `/agent`448### Switch agent threads with `/agent`

342 449

3431. Type `/agent` and press Enter.4501. Type `/agent` and press Enter.

concepts/sandboxing.md +21 −15

Details

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

concepts/sandboxing/auto-review.md +165 −0 added

Details

1# Auto-review

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.

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.

13## How auto-review works

15At a high level, the flow is:

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.

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.

30## When it triggers

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

33These include:

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.

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.

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.

49## What auto-review blocks

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

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

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

65## What the reviewer sees

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

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

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.

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

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

78## Denials and failure behavior

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:

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.

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.

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.

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.

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/).

concepts/subagents.md +8 −9

Details

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 finer~~69more demanding reasoning. When you want finer control, steer that choice in

~~70control, steer that choice in your prompt or set `model` and~~70your 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. Continue~~73For 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. Use~~74 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 subagent~~75 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

config-advanced.md +13 −12

Details

88 88

89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

90 90

~~91## Hooks (experimental)~~91Project config files can't override settings that redirect credentials, change

92provider auth, or run machine-local notification/telemetry commands.

93Codex ignores the following keys in project-local `.codex/config.toml` and

94prints a startup warning when it sees them: `openai_base_url`,

95`chatgpt_base_url`, `model_provider`, `model_providers`, `notify`, `profile`,

96`profiles`, `experimental_realtime_ws_base_url`, and `otel`. Set those keys in

97your user-level `~/.codex/config.toml` instead.

99## Hooks

92 100

93Codex can also load lifecycle hooks from either `hooks.json` files or inline101Codex can also load lifecycle hooks from either `hooks.json` files or inline

94`[hooks]` tables in `config.toml` files that sit next to active config layers.102`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 103

~~96In practice, the two most useful locations are:~~104In practice, the four most useful locations are:

97 105

98- `~/.codex/hooks.json`106- `~/.codex/hooks.json`

99- `~/.codex/config.toml`107- `~/.codex/config.toml`

103Project-local hooks load only when the project `.codex/` layer is trusted.111Project-local hooks load only when the project `.codex/` layer is trusted.

104User-level hooks remain independent of project trust.112User-level hooks remain independent of project trust.

105 113

106Turn hooks on with:

~~107~~

108```toml

109[features]

110codex_hooks = true

111```

~~112~~

113Inline TOML hooks use the same event structure as `hooks.json`:114Inline TOML hooks use the same event structure as `hooks.json`:

114 115

115```toml116```toml

config-basic.md +5 −3

Details

168### Supported features168### Supported features

169 169

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

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

189 191

190Omit feature keys to keep their defaults.192Omit feature keys to keep their defaults.

191 193

192For the current lifecycle hooks MVP, see [Hooks](https://developers.openai.com/codex/hooks).194For lifecycle hook configuration, see [Hooks](https://developers.openai.com/codex/hooks).

193 195

194### Enabling features196### Enabling features

195 197

config-reference.md +238 −22

Details

6 6

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8

9Project-scoped config can't override machine-local provider, auth,

10notification, profile, or telemetry routing keys. Codex ignores

11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,

12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and

13`otel` when they appear in a project-local `.codex/config.toml`; put those in

14user-level config instead.

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).16For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 17

11<ConfigTable18<ConfigTable

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

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

210 description:217 description:

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

212 },219 },

213 {220 {

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

224 },231 },

225 {232 {

226 key: "service_tier",233 key: "service_tier",

227 type: "flex | fast",234 type: "string",

228 description: "Preferred service tier for new turns.",235 description:

236 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",

229 },237 },

230 {238 {

231 key: "experimental_compact_prompt_file",239 key: "experimental_compact_prompt_file",

325 description: "Enable ChatGPT Apps/connectors support (experimental).",333 description: "Enable ChatGPT Apps/connectors support (experimental).",

326 },334 },

327 {335 {

328 key: "features.codex_hooks",336 key: "features.hooks",

337 type: "boolean",

338 description:

339 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.",

340 },

341 {

342 key: "features.codex_git_commit",

329 type: "boolean",343 type: "boolean",

330 description:344 description:

331 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.",345 "Enable Codex-generated git commits. When enabled, Codex uses `commit_attribution` to append a `Co-authored-by:` trailer to generated commit messages.",

332 },346 },

333 {347 {

334 key: "hooks",348 key: "hooks",

336 description:350 description:

337 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",351 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",

338 },352 },

353 {

354 key: "features.plugin_hooks",

355 type: "boolean",

356 description:

357 "Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.",

358 },

339 {359 {

340 key: "features.memories",360 key: "features.memories",

341 type: "boolean",361 type: "boolean",

428 description:448 description:

429 "Deny list applied after `enabled_tools` for the MCP server.",449 "Deny list applied after `enabled_tools` for the MCP server.",

430 },450 },

451 {

452 key: "mcp_servers.<id>.default_tools_approval_mode",

453 type: "auto | prompt | approve",

454 description:

455 "Default approval behavior for MCP tools on this server unless a per-tool override exists.",

456 },

457 {

458 key: "mcp_servers.<id>.tools.<tool>.approval_mode",

459 type: "auto | prompt | approve",

460 description:

461 "Per-tool approval behavior override for one MCP tool on this server.",

462 },

431 {463 {

432 key: "mcp_servers.<id>.scopes",464 key: "mcp_servers.<id>.scopes",

433 type: "array<string>",465 type: "array<string>",

575 description:607 description:

576 "Enable personality selection controls (stable; on by default).",608 "Enable personality selection controls (stable; on by default).",

577 },609 },

610 {

611 key: "features.network_proxy",

612 type: "boolean | table",

613 description:

614 "Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default).",

615 },

616 {

617 key: "features.network_proxy.enabled",

618 type: "boolean",

619 description: "Enable sandboxed networking. Defaults to `false`.",

620 },

621 {

622 key: "features.network_proxy.domains",

623 type: "map<string, allow | deny>",

624 description:

625 "Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add `allow` rules. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. Add `deny` rules for blocked destinations; `deny` wins on conflicts.",

626 },

627 {

628 key: "features.network_proxy.unix_sockets",

629 type: "map<string, allow | none>",

630 description:

631 "Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.",

632 },

633 {

634 key: "features.network_proxy.allow_local_binding",

635 type: "boolean",

636 description:

637 "Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.",

638 },

639 {

640 key: "features.network_proxy.enable_socks5",

641 type: "boolean",

642 description: "Expose SOCKS5 support. Defaults to `true`.",

643 },

644 {

645 key: "features.network_proxy.enable_socks5_udp",

646 type: "boolean",

647 description: "Allow UDP over SOCKS5. Defaults to `true`.",

648 },

649 {

650 key: "features.network_proxy.allow_upstream_proxy",

651 type: "boolean",

652 description:

653 "Allow chaining through an upstream proxy from the environment. Defaults to `true`.",

654 },

655 {

656 key: "features.network_proxy.dangerously_allow_non_loopback_proxy",

657 type: "boolean",

658 description:

659 "Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.",

660 },

661 {

662 key: "features.network_proxy.dangerously_allow_all_unix_sockets",

663 type: "boolean",

664 description:

665 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.",

666 },

667 {

668 key: "features.network_proxy.proxy_url",

669 type: "string",

670 description:

671 'HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.',

672 },

673 {

674 key: "features.network_proxy.socks_url",

675 type: "string",

676 description:

677 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.',

678 },

578 {679 {

579 key: "features.web_search",680 key: "features.web_search",

580 type: "boolean",681 type: "boolean",

615 key: "features.fast_mode",716 key: "features.fast_mode",

616 type: "boolean",717 type: "boolean",

617 description:718 description:

618 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).',719 "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).",

619 },720 },

620 {721 {

621 key: "features.prevent_idle_sleep",722 key: "features.prevent_idle_sleep",

852 },953 },

853 {954 {

854 key: "profiles.<name>.service_tier",955 key: "profiles.<name>.service_tier",

855 type: "flex | fast",956 type: "string",

856 description: "Profile-scoped service tier preference for new turns.",957 description: "Profile-scoped service tier preference for new turns.",

857 },958 },

858 {959 {

1066 description:1167 description:

1067 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",1168 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",

1068 },1169 },

1170 {

1171 key: "tui.vim_mode_default",

1172 type: "boolean",

1173 description:

1174 "Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`.",

1175 },

1176 {

1177 key: "tui.raw_output_mode",

1178 type: "boolean",

1179 description:

1180 "Start the TUI in raw scrollback mode for copy-friendly terminal selection (default: false). You can toggle it with `/raw` or the default `alt-r` key binding.",

1181 },

1069 {1182 {

1070 key: "tui.show_tooltips",1183 key: "tui.show_tooltips",

1071 type: "boolean",1184 type: "boolean",

1100 key: "tui.keymap.<context>.<action> = []",1213 key: "tui.keymap.<context>.<action> = []",

1101 type: "empty array",1214 type: "empty array",

1102 description:1215 description:

1103 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.",1216 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.",

1217 },

1218 {

1219 key: "plugins.<plugin>.mcp_servers.<server>.enabled",

1220 type: "boolean",

1221 description:

1222 "Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.",

1223 },

1224 {

1225 key: "plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode",

1226 type: "auto | prompt | approve",

1227 description:

1228 "Default approval behavior for tools on a plugin-provided MCP server.",

1229 },

1230 {

1231 key: "plugins.<plugin>.mcp_servers.<server>.enabled_tools",

1232 type: "array<string>",

1233 description:

1234 "Allow list of tools exposed from a plugin-provided MCP server.",

1235 },

1236 {

1237 key: "plugins.<plugin>.mcp_servers.<server>.disabled_tools",

1238 type: "array<string>",

1239 description:

1240 "Deny list applied after `enabled_tools` for a plugin-provided MCP server.",

1241 },

1242 {

1243 key: "plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode",

1244 type: "auto | prompt | approve",

1245 description:

1246 "Per-tool approval behavior override for a plugin-provided MCP tool.",

1104 },1247 },

1105 {1248 {

1106 key: "tui.model_availability_nux.<model>",1249 key: "tui.model_availability_nux.<model>",

1219 key: "permissions.<name>.network.proxy_url",1362 key: "permissions.<name>.network.proxy_url",

1220 type: "string",1363 type: "string",

1221 description:1364 description:

1222 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.",1365 "HTTP listener URL used when this permissions profile enables sandboxed networking.",

1223 },1366 },

1224 {1367 {

1225 key: "permissions.<name>.network.enable_socks5",1368 key: "permissions.<name>.network.enable_socks5",

1226 type: "boolean",1369 type: "boolean",

1227 description:1370 description:

1228 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.",1371 "Expose SOCKS5 support when this permissions profile enables sandboxed networking.",

1229 },1372 },

1230 {1373 {

1231 key: "permissions.<name>.network.socks_url",1374 key: "permissions.<name>.network.socks_url",

1241 key: "permissions.<name>.network.allow_upstream_proxy",1384 key: "permissions.<name>.network.allow_upstream_proxy",

1242 type: "boolean",1385 type: "boolean",

1243 description:1386 description:

1244 "Allow the managed proxy to chain to another upstream proxy.",1387 "Allow sandboxed networking to chain through another upstream proxy.",

1245 },1388 },

1246 {1389 {

1247 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",1390 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",

1248 type: "boolean",1391 type: "boolean",

1249 description:1392 description:

1250 "Permit non-loopback bind addresses for the managed proxy listener.",1393 "Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost.",

1251 },1394 },

1252 {1395 {

1253 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",1396 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",

1254 type: "boolean",1397 type: "boolean",

1255 description:1398 description:

1256 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.",1399 "Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments.",

1257 },

1258 {

1259 key: "permissions.<name>.network.mode",

1260 type: "limited | full",

1261 description: "Network proxy mode used for subprocess traffic.",

1262 },1400 },

1263 {1401 {

1264 key: "permissions.<name>.network.domains",1402 key: "permissions.<name>.network.domains",

1265 type: "map<string, allow | deny>",1403 type: "map<string, allow | deny>",

1266 description:1404 description:

1267 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.",1405 "Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts.",

1268 },1406 },

1269 {1407 {

1270 key: "permissions.<name>.network.unix_sockets",1408 key: "permissions.<name>.network.unix_sockets",

1271 type: "map<string, allow | none>",1409 type: "map<string, allow | none>",

1272 description:1410 description:

1273 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.",1411 "Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values.",

1274 },1412 },

1275 {1413 {

1276 key: "permissions.<name>.network.allow_local_binding",1414 key: "permissions.<name>.network.allow_local_binding",

1277 type: "boolean",1415 type: "boolean",

1278 description:1416 description:

1279 "Permit local bind/listen operations through the managed proxy.",1417 "Permit broader local/private-network access through sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",

1280 },1418 },

1281 {1419 {

1282 key: "projects.<path>.trust_level",1420 key: "projects.<path>.trust_level",

1429 description:1567 description:

1430 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",1568 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",

1431 },1569 },

1570 {

1571 key: "experimental_network",

1572 type: "table",

1573 description:

1574 "Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag.",

1575 },

1576 {

1577 key: "experimental_network.enabled",

1578 type: "boolean",

1579 description:

1580 "Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.",

1581 },

1582 {

1583 key: "experimental_network.http_port",

1584 type: "integer",

1585 description:

1586 "Loopback HTTP listener port to use for `[experimental_network]` requirements.",

1587 },

1588 {

1589 key: "experimental_network.socks_port",

1590 type: "integer",

1591 description:

1592 "Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.",

1593 },

1594 {

1595 key: "experimental_network.allow_upstream_proxy",

1596 type: "boolean",

1597 description:

1598 "Allow sandboxed networking to chain through an upstream proxy from the environment.",

1599 },

1600 {

1601 key: "experimental_network.dangerously_allow_non_loopback_proxy",

1602 type: "boolean",

1603 description:

1604 "Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.",

1605 },

1606 {

1607 key: "experimental_network.dangerously_allow_all_unix_sockets",

1608 type: "boolean",

1609 description:

1610 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.",

1611 },

1612 {

1613 key: "experimental_network.domains",

1614 type: "map<string, allow | deny>",

1615 description:

1616 "Map-shaped administrator domain policy for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. `deny` wins on conflicts. Do not combine this with `experimental_network.allowed_domains` or `experimental_network.denied_domains`.",

1617 },

1618 {

1619 key: "experimental_network.allowed_domains",

1620 type: "array<string>",

1621 description:

1622 "List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",

1623 },

1624 {

1625 key: "experimental_network.denied_domains",

1626 type: "array<string>",

1627 description:

1628 "List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",

1629 },

1630 {

1631 key: "experimental_network.managed_allowed_domains_only",

1632 type: "boolean",

1633 description:

1634 "When `true`, only administrator-managed allow rules remain effective while sandboxed networking requirements are active; user allowlist additions are ignored. Without managed allow rules, user-added domain allow rules do not remain effective.",

1635 },

1636 {

1637 key: "experimental_network.unix_sockets",

1638 type: "map<string, allow | none>",

1639 description:

1640 "Administrator-managed Unix socket policy for sandboxed networking.",

1641 },

1642 {

1643 key: "experimental_network.allow_local_binding",

1644 type: "boolean",

1645 description:

1646 "Permit broader local/private-network access for sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",

1647 },

1432 {1648 {

1433 key: "hooks",1649 key: "hooks",

1434 type: "table",1650 type: "table",

1451 key: "hooks.<Event>",1667 key: "hooks.<Event>",

1452 type: "array<table>",1668 type: "array<table>",

1453 description:1669 description:

1454 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",1670 "Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",

1455 },1671 },

1456 {1672 {

1457 key: "hooks.<Event>[].hooks",1673 key: "hooks.<Event>[].hooks",

config-sample.md +22 −7

Details

42# Default OSS provider for --oss sessions. When unset, Codex prompts. Default: unset.42# Default OSS provider for --oss sessions. When unset, Codex prompts. Default: unset.

43# oss_provider = "ollama"43# oss_provider = "ollama"

44 44

~~45# Preferred service tier. `fast` is honored only when enabled in [features].~~45# Preferred service tier. Built-in examples: fast | flex; model catalogs can add more.

~~46# service_tier = "flex" # fast | flex~~46# service_tier = "flex"

47 47

48# Optional manual model metadata. When unset, Codex uses model or preset defaults.48# Optional manual model metadata. When unset, Codex uses model or preset defaults.

49# model_context_window = 128000 # tokens; default: auto for model49# model_context_window = 128000 # tokens; default: auto for model

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.

286experimental_use_profile = false288experimental_use_profile = false

287 289

288################################################################################290################################################################################

289# Managed network proxy settings291# Sandboxed networking settings

290################################################################################292################################################################################

291 293

294# Enable the feature before configuring sandboxed networking rules.

295# [features.network_proxy]

296# enabled = true

297# domains = { "api.openai.com" = "allow", "example.com" = "deny" }

298#

299# Exact hosts match only themselves.

300# "*.example.com" matches subdomains only; "**.example.com" matches the apex plus subdomains.

301# "*" allows any public host that is not denied, so prefer scoped rules when possible.

302# `allow_local_binding = false` blocks loopback and private destinations by default.

303# Add an exact local IP literal or `localhost` allow rule for one target, or set it to true only when broader local access is required.

304#

292# Set `default_permissions = "workspace"` before enabling this profile.305# Set `default_permissions = "workspace"` before enabling this profile.

293# [permissions.workspace.network]306# [permissions.workspace.network]

294# enabled = true307# enabled = true

301# dangerously_allow_non_loopback_proxy = false314# dangerously_allow_non_loopback_proxy = false

302# dangerously_allow_non_loopback_admin = false315# dangerously_allow_non_loopback_admin = false

303# dangerously_allow_all_unix_sockets = false316# dangerously_allow_all_unix_sockets = false

304# mode = "limited" # limited | full

305# allow_local_binding = false317# allow_local_binding = false

306#318#

307# [permissions.workspace.network.domains]319# [permissions.workspace.network.domains]

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

399# shell_tool = true411# shell_tool = true

400# apps = false412# apps = false

401# codex_hooks = false413# hooks = false

414# plugin_hooks = false # Default off; set true to opt into plugin-bundled hooks.

415# codex_git_commit = false

402# unified_exec = true416# unified_exec = true

403# shell_snapshot = true417# shell_snapshot = true

404# multi_agent = true418# multi_agent = true

405# personality = true419# personality = true

420# network_proxy = false

406# fast_mode = true421# fast_mode = true

407# enable_request_compression = true422# enable_request_compression = true

408# skill_mcp_dependency_install = true423# skill_mcp_dependency_install = true

577# model_provider = "openai"592# model_provider = "openai"

578# approval_policy = "on-request"593# approval_policy = "on-request"

579# sandbox_mode = "read-only"594# sandbox_mode = "read-only"

580# service_tier = "flex"595# service_tier = "flex" # or another supported service tier id

581# oss_provider = "ollama"596# oss_provider = "ollama"

582# model_reasoning_effort = "medium"597# model_reasoning_effort = "medium"

583# plan_mode_reasoning_effort = "high"598# plan_mode_reasoning_effort = "high"

enterprise/access-tokens.md +144 −0 added

Details

1# Access tokens

3Codex access tokens let trusted automation run Codex local with a ChatGPT workspace identity. Use them when a script, scheduled job, or CI runner needs repeatable, non-interactive Codex access.

5Codex access tokens are currently supported for ChatGPT Business and

6 Enterprise workspaces.

8Access tokens are created in the ChatGPT admin console at [Access tokens](https://chatgpt.com/admin/access-tokens). They are tied to the ChatGPT user and workspace that create them, and Codex uses them as agent identities for programmatic local workflows.

10If a Platform API key works for your automation, keep using API key auth. Use

11 Codex access tokens when the workflow specifically needs ChatGPT workspace

12 access, ChatGPT-managed Codex entitlements, or enterprise workspace controls.

14## How access tokens work

16Use an access token when Codex needs to run without a user completing a browser sign-in. The token represents the ChatGPT workspace user who created it, so runs can use that user's Codex access and appear in workspace governance data.

18Codex checks the token when a run starts and ties the run to that workspace identity. Treat the token like any other automation secret: store it in a secret manager, keep it out of logs, and rotate it regularly.

20Use access tokens for:

22- `codex exec` jobs that run from trusted automation.

23- Local scripts that need repeatable, non-interactive Codex runs.

24- Enterprise workflows where usage should be associated with a ChatGPT workspace user instead of an API organization key.

26Main risks to avoid:

28- **Leaked secrets:** anyone with the token can start Codex runs as the token creator. Store tokens in a secret manager, keep them out of logs, and rotate them regularly.

29- **Untrusted runners:** public CI, forked pull requests, or shared machines can expose tokens to people outside your workspace. Use access tokens only on trusted runners.

30- **Shared identities:** one person's token reused across unrelated teams makes ownership and audit trails harder to interpret. Create tokens for a specific workflow owner.

31- **Stale credentials:** long-lived tokens can remain active after the workflow changes. Prefer finite expirations and revoke tokens that are no longer used.

32- **Wrong credential type:** access tokens are for Codex local workflows. Use Platform API keys for general OpenAI API calls.

34## Enable access token creation

36Use the Codex Local controls in workspace settings to turn on access token creation for allowed members.

38<CodexScreenshot

39 alt="Access token access permission in ChatGPT workspace RBAC settings"

40 lightSrc="/images/codex/enterprise/rbac_access_token_access_permission.png"

41 darkSrc="/images/codex/enterprise/rbac_access_token_access_permission_dark.png"

42 maxWidth={847}

43 variant="no-wallpaper"

44/>

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

472. In the Codex Local section, make sure **Allow members to use Codex Local** is turned on.

483. Turn on **Allow members to use Codex access tokens** if all allowed members should be able to create access tokens.

494. If you use custom roles for a narrower rollout, assign the access token permission only to groups that need to create tokens.

51Keep access token creation limited to people or service owners who understand where the token will be stored, which automation will use it, and how it will be rotated.

53## Create an access token

55Use the Access tokens page to name the token and choose when it expires.

571. Go to [Access tokens](https://chatgpt.com/admin/access-tokens).

582. Select **Create**.

60<CodexScreenshot

61 alt="Access tokens page with the Create button"

62 lightSrc="/images/codex/enterprise/access_token_create_header.png"

63 darkSrc="/images/codex/enterprise/access_token_create_header_dark.png"

64 maxWidth={942}

65 variant="no-wallpaper"

66/>

683. Enter a descriptive name, such as `release-ci` or `nightly-docs-check`.

70<CodexScreenshot

71 alt="Create access token modal with fields for name and expiration"

72 lightSrc="/images/codex/enterprise/access_token_creation_modal.png"

73 darkSrc="/images/codex/enterprise/access_token_creation_modal_dark.png"

74 maxWidth={544}

75 variant="no-wallpaper"

76/>

784. Choose an expiration. Prefer a finite expiration such as 7, 30, 60, or 90 days. If you choose **No expiration**, rotate the token on a regular schedule.

795. Select **Create**.

806. Copy the generated access token immediately. You cannot view it again after you close the modal.

817. Store the token in your secret manager or CI secret store.

83The shortest custom expiration is one day. Revoked and expired tokens cannot be used to start new Codex runs.

85## Use an access token with Codex CLI

87For ephemeral automation, store the token in `CODEX_ACCESS_TOKEN` and run Codex normally:

89```bash

90export CODEX_ACCESS_TOKEN="<access-token>"

91codex exec --json "review this repository and summarize the top risks"

92```

94For a persistent local login, pipe the token to `codex login --with-access-token`:

96```bash

97printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token

98codex exec "summarize the last release diff"

99```

100

101`codex login --with-access-token` stores an agent identity credential in Codex auth storage. If you prefer not to persist credentials on the machine, use the `CODEX_ACCESS_TOKEN` environment variable instead.

102

103## Rotate or revoke a token

104

105Rotate access tokens the same way you rotate other automation secrets:

106

1071. Create a replacement token.

1082. Update the secret in the runner, scheduler, or secret manager.

1093. Run a smoke test with the new token.

1104. Revoke the old token from [Access tokens](https://chatgpt.com/admin/access-tokens).

111

112From the Access tokens page, workspace owners and admins can revoke any workspace token. Members with access token permission can revoke only the tokens they created.

113

114## Permission model

115

116Access token permissions are separate from the general Codex local permission. A member can have access to the Codex app, CLI, or IDE extension without being allowed to create access tokens.

117

119| ------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- | -------------------------------------- |

120| Open [Access tokens](https://chatgpt.com/admin/access-tokens) | Yes | Yes | No |

121| Create access tokens | Yes, for their own ChatGPT workspace identity | Yes, for their own ChatGPT workspace identity | No |

122| List access tokens | Workspace list, including who created each token | Only tokens they created | No |

124| Grant or remove access token permission | Yes | No | No |

125| Manage other Codex enterprise settings | Yes, based on admin role and Codex admin permissions | No, unless separately granted | No |

126

127In short: workspace owners and admins manage access at the workspace level. Members need the access token permission to create and manage their own tokens, but the permission does not grant admin rights or access to other members' tokens.

128

129## Troubleshooting

130

131### The access tokens page returns 404 or forbidden

132

133Ask a workspace owner or admin to confirm that Codex access tokens are enabled and that your role includes the access token permission.

134

135### `codex login --with-access-token` fails

136

137Confirm that you copied the generated access token, not a browser session token or Platform API key. Also confirm that the token has not expired or been revoked.

138

139## Related docs

140

141- [Authentication](https://developers.openai.com/codex/auth)

142- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)

143- [Admin setup](https://developers.openai.com/codex/enterprise/admin-setup)

144- [Governance](https://developers.openai.com/codex/enterprise/governance)

enterprise/admin-setup.md +22 −4

Details

11 11

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

13 13

14Use 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).14Use this page as the step-by-step rollout guide. For detailed policy, configuration, automation, 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), [Access tokens](https://developers.openai.com/codex/enterprise/access-tokens), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

15 15

16## Enterprise-grade security and privacy16## Enterprise-grade security and privacy

17 17

59 59

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

61 61

~~62If this toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”~~62If members need programmatic Codex local workflows, also turn on **Allow members to use Codex access tokens** or grant the access token permission through a custom role. For setup and permission details, see [Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

64If the Codex Local toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”

63 65

64#### Enable device code authentication for Codex CLI66#### Enable device code authentication for Codex CLI

65 67

161 163

162Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).164Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

163 165

164Use 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. To disable Browser Use, the in-app browser, or Computer Use, see [Pin feature flags](https://developers.openai.com/codex/enterprise/managed-configuration#pin-feature-flags).166Use 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, network access requirements, MCP server allowlists, feature pins, and restrictive command rules. To disable Browser Use, the in-app browser, or Computer Use, see [Pin feature flags](https://developers.openai.com/codex/enterprise/managed-configuration#pin-feature-flags).

165 167

166<div class="max-w-1xl mx-auto py-1">168<div class="max-w-1xl mx-auto py-1">

167 <img src="https://developers.openai.com/images/codex/enterprise/policies_and_configurations_page.png"169 <img src="https://developers.openai.com/images/codex/enterprise/policies_and_configurations_page.png"

207computer_use = false209computer_use = false

208```210```

209 211

212Example: define administrator-owned network requirements:

213

214```toml

215experimental_network.enabled = true

216experimental_network.dangerously_allow_all_unix_sockets = true

217experimental_network.allow_local_binding = true

218experimental_network.allowed_domains = [

219 "api.openai.com",

220 "*.example.com",

221]

222experimental_network.denied_domains = [

223 "blocked.example.com",

224 "*.exfil.example.com",

225]

226```

227

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

211 229

212```toml230```toml

216]234]

217```235```

218 236

219You 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).237You can use any 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).

220 238

221### Checking user policies239### Checking user policies

222 240

enterprise/governance.md +39 −32

Details

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### Dashboards~~24### 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 users~~31- Workspace and personal usage breakdowns, including credit and token usage by product surface

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

~~33- Code reviews by priority level~~33- 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 sentiment~~34- Code Review activity, including PRs reviewed, issues by priority, comments, replies, reactions, and feedback sentiment

~~35- Daily cloud tasks~~35- Skill invocations, agent identity usage, and access token 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 adoption~~55The 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 credits~~57Use `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 surface~~58

~~64- Optional per-user reporting for adoption and power-user analysis~~59#### Usage

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

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 Codex~~70`GET /workspaces/{workspace_id}/code_reviews`

~~69- Total comments generated by Codex~~71

~~70- Severity breakdown of comments~~72- 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 comments~~78`GET /workspaces/{workspace_id}/code_review_responses`

~~75- Reactions, including upvotes and downvotes~~79

~~76- Engagement breakdowns for how teams respond to Codex feedback~~80- 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

109Use record metadata to answer questions like:115Use record metadata to answer questions like:

110 116

111- Who ran a task117- Who ran a task

118- Who created or revoked an access token

112- When it ran119- When it ran

113- Which model was used120- Which model was used

114- How much content was processed121- How much content was processed

enterprise/managed-configuration.md +38 −4

Details

76 76

77Use `[[remote_sandbox_config]]` when one managed policy should apply different77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter78sandbox requirements on different hosts. For example, you can keep a stricter

~~79default for laptops while allowing workspace writes on matching devboxes or CI~~79default for laptops while allowing workspace writes on matching dev boxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 81

82```toml82```toml

94 94

95The first matching `[[remote_sandbox_config]]` entry wins within the same95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level96requirements source. If no entry matches, Codex keeps the top-level

~~97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't~~97`allowed_sandbox_modes`. Host name matching is for policy selection only; don't

98treat it as authenticated device proof.98treat it as authenticated device proof.

99 99

100You can also constrain web search mode:100You can also constrain web search mode:

106`allowed_web_search_modes = []` allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.

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

108 108

109### Configure network access requirements

110

111Use `[experimental_network]` in `requirements.toml` when administrators should

112define network access requirements centrally. These requirements are separate

113from the user `features.network_proxy` toggle: they can configure sandboxed

114networking without that feature flag, but they do not grant command network

115access when the active sandbox keeps networking off.

116

117```toml

118experimental_network.enabled = true

119experimental_network.dangerously_allow_all_unix_sockets = true

120experimental_network.allow_local_binding = true

121experimental_network.allowed_domains = [

122 "api.openai.com",

123 "*.example.com",

124]

125experimental_network.denied_domains = [

126 "blocked.example.com",

127 "*.exfil.example.com",

128]

129```

130

131Use `experimental_network.managed_allowed_domains_only = true` only when you

132also define administrator-owned `allowed_domains` and want that allowlist to be

133exclusive. If it is `true` without managed allow rules, user-added domain allow

134rules do not remain effective.

135

136The domain syntax, local/private destination rules, deny-over-allow behavior,

137and DNS rebinding limitations are the same as the sandboxed networking behavior

138described in [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security#network-isolation).

139

109### Pin feature flags140### Pin feature flags

110 141

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

129- `in_app_browser = false` disables the in-app browser pane.160- `in_app_browser = false` disables the in-app browser pane.

130- `browser_use = false` disables Browser Use and Browser Agent availability.161- `browser_use = false` disables Browser Use and Browser Agent availability.

131- `computer_use = false` disables Computer Use availability and related162- `computer_use = false` disables Computer Use availability and related

132 install or enablement flows.163 install or setup flows.

133 164

134If omitted, these features are allowed by policy, subject to normal client,165If omitted, these features are allowed by policy, subject to normal client,

135platform, and rollout availability.166platform, and rollout availability.

187directory where your MDM or endpoint-management tooling installs the referenced218directory where your MDM or endpoint-management tooling installs the referenced

188scripts.219scripts.

189 220

221To enforce managed hooks even for users who disabled hooks locally, pin

222`[features].hooks = true` alongside `[hooks]`.

223

190```toml224```toml

191[features]225[features]

192codex_hooks = true226hooks = true

193 227

194[hooks]228[hooks]

195managed_dir = "/enterprise/hooks"229managed_dir = "/enterprise/hooks"

hooks.md +117 −25

Details

9- Run a custom validation check when a conversation turn stops, enforcing standards9- Run a custom validation check when a conversation turn stops, enforcing standards

10- Customize prompting when in a certain directory10- Customize prompting when in a certain directory

11 11

~~12Hooks are behind a feature flag in `config.toml`:~~12Hooks are enabled by default. If you need to turn them off in `config.toml`,

13set:

13 14

14```toml15```toml

15[features]16[features]

~~16codex_hooks = true~~17hooks = false

17```18```

18 19

20Use `hooks` as the canonical feature key. `codex_hooks` still works as a

21deprecated alias.

23Admins can force hooks off the same way in `requirements.toml` with

24`[features].hooks = false`.

19Runtime behavior to keep in mind:26Runtime behavior to keep in mind:

20 27

21- Matching hooks from multiple files all run.28- Matching hooks from multiple files all run.

22- Multiple matching command hooks for the same event are launched concurrently,29- Multiple matching command hooks for the same event are launched concurrently,

23 so one hook cannot prevent another matching hook from starting.30 so one hook cannot prevent another matching hook from starting.

31- Non-managed command hooks must be reviewed and trusted before they run.

24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and32- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

25 `Stop` run at turn scope.33 `Stop` run at turn scope.

26 34

44- `<repo>/.codex/config.toml`52- `<repo>/.codex/config.toml`

45 53

46If more than one hook source exists, Codex loads all matching hooks.54If more than one hook source exists, Codex loads all matching hooks.

~~47Higher-precedence config layers do not replace lower-precedence hooks.~~55Higher-precedence config layers don't replace lower-precedence hooks.

48If a single layer contains both `hooks.json` and inline `[hooks]`, Codex56If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

49merges them and warns at startup. Prefer one representation per layer.57merges them and warns at startup. Prefer one representation per layer.

50 58

59Plugin hooks are off by default in this release. If

60`[features].plugin_hooks = true`, Codex can also discover hooks bundled with

61enabled plugins. Otherwise, enabled plugins won't run bundled hooks.

51Project-local hooks load only when the project `.codex/` layer is trusted. In63Project-local hooks load only when the project `.codex/` layer is trusted. In

52untrusted projects, Codex still loads user and system hooks from their own64untrusted projects, Codex still loads user and system hooks from their own

53active config layers.65active config layers.

54 66

67## Review and manage hooks

69Codex lists configured hooks before deciding which ones can run. Use `/hooks`

70in the CLI to inspect hook sources, review new or changed hooks, trust hooks, or

71disable individual non-managed hooks. If hooks need review at startup, Codex

72prints a warning that tells you to open `/hooks`.

74Managed hooks from system, MDM, cloud, or `requirements.toml` sources are marked

75as managed, trusted by policy, and can't be disabled from the user hook browser.

55## Config shape77## Config shape

56 78

57Hooks are organized in three levels:79Hooks are organized in three levels:

141- `timeout` is in seconds.163- `timeout` is in seconds.

142- If `timeout` is omitted, Codex uses `600` seconds.164- If `timeout` is omitted, Codex uses `600` seconds.

143- `statusMessage` is optional.165- `statusMessage` is optional.

166- `async` is parsed, but async command hooks aren't supported yet. Codex skips

167 handlers with `async: true`.

168- Only `type: "command"` handlers run today. `prompt` and `agent` handlers are

169 parsed but skipped.

144- Commands run with the session `cwd` as their working directory.170- Commands run with the session `cwd` as their working directory.

145- For repo-local hooks, prefer resolving from the git root instead of using a171- For repo-local hooks, prefer resolving from the git root instead of using a

146 relative path such as `.codex/hooks/...`. Codex may be started from a172 relative path such as `.codex/hooks/...`. Codex may be started from a

149Equivalent inline TOML in `config.toml`:175Equivalent inline TOML in `config.toml`:

150 176

151```toml177```toml

152[features]

153codex_hooks = true

~~154~~

155[[hooks.PreToolUse]]178[[hooks.PreToolUse]]

156matcher = "^Bash$"179matcher = "^Bash$"

157 180

176Enterprise-managed requirements can also define hooks inline under `[hooks]`.199Enterprise-managed requirements can also define hooks inline under `[hooks]`.

177This is useful when admins want to enforce the hook configuration while200This is useful when admins want to enforce the hook configuration while

178delivering the actual scripts through MDM or another device-management system.201delivering the actual scripts through MDM or another device-management system.

202To enforce managed hooks even for users who disabled hooks locally, pin

203`[features].hooks = true` in `requirements.toml` alongside `[hooks]`.

179 204

180```toml205```toml

181[features]206[features]

182codex_hooks = true207hooks = true

183 208

184[hooks]209[hooks]

185managed_dir = "/enterprise/hooks"210managed_dir = "/enterprise/hooks"

199 224

200- `managed_dir` is used on macOS and Linux.225- `managed_dir` is used on macOS and Linux.

201- `windows_managed_dir` is used on Windows.226- `windows_managed_dir` is used on Windows.

202- Codex does not distribute the scripts in `managed_dir`; your enterprise227- Codex doesn't distribute the scripts in `managed_dir`; your enterprise

203 tooling must install and update them separately.228 tooling must install and update them separately.

204- Managed hook commands should use absolute script paths under the configured229- Managed hook commands should use absolute script paths under the configured

205 managed directory.230 managed directory.

206 231

232## Plugin-bundled hooks

233

234Plugin-bundled hooks are opt-in for this release. When

235`[features].plugin_hooks = true` and a plugin is enabled, Codex can load

236lifecycle hooks from that plugin alongside user, project, and managed hooks.

237

238```toml

239[features]

240plugin_hooks = true

241```

242

243By default, Codex looks for `hooks/hooks.json` inside the plugin root. A plugin

244manifest can override that default with a `hooks` entry in

245`.codex-plugin/plugin.json`. The manifest entry can be a `./`-prefixed path, an

246array of `./`-prefixed paths, an inline hooks object, or an array of inline

247hooks objects.

248

249```json

250{

251 "name": "repo-policy",

252 "hooks": "./hooks/hooks.json"

253}

254```

255

256Manifest hook paths are resolved relative to the plugin root and must stay

257inside that root. If a manifest defines `hooks`, Codex uses those manifest

258entries instead of the default `hooks/hooks.json`.

259

260Plugin hook commands receive these environment variables:

261

262- `PLUGIN_ROOT` is a Codex-specific extension that points to the installed

263 plugin root.

264- `PLUGIN_DATA` is a Codex-specific extension that points to the plugin's

265 writable data directory.

266- Codex also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for

267 compatibility with existing plugin hooks.

268

269Plugin hooks use the same event schema as other hooks. They are non-managed

270hooks, so they require trust review before they run.

271

207## Matcher patterns272## Matcher patterns

208 273

209The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,274The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,

223 288

224\*For `apply_patch`, matchers can also use `Edit` or `Write`.289\*For `apply_patch`, `matcher` values can also use `Edit` or `Write`.

225 290

226Examples:291Examples:

227 292

245| `cwd` | `string` | Working directory for the session |310| `cwd` | `string` | Working directory for the session |

313

314Turn-scoped hooks list `turn_id` as a Codex-specific extension in their

315event-specific tables.

316

317`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,

318`UserPromptSubmit`, and `Stop` also include `permission_mode`, which describes

319the current permission mode as `default`, `acceptEdits`, `plan`, `dontAsk`, or

320`bypassPermissions`.

248 321

249Turn-scoped hooks list `turn_id` in their event-specific tables.322`transcript_path` points to a conversation transcript for convenience, but the

323transcript format is not a stable interface for hooks and may change over time.

250 324

251If you need the full wire format, see [Schemas](#schemas).325If you need the full wire format, see [Schemas](#schemas).

252 326

288Fields in addition to [Common input fields](#common-input-fields):362Fields in addition to [Common input fields](#common-input-fields):

289 363

291| -------- | -------- | ---------------------------------------------- |365| -------- | -------- | -------------------------------------------------------- |

293 367

294Plain text on `stdout` is added as extra developer context.368Plain text on `stdout` is added as extra developer context.

295 369

310### PreToolUse384### PreToolUse

311 385

312`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,386`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

313and MCP tool calls. It is still a guardrail rather than a complete enforcement387and MCP tool calls. It's still a guardrail rather than a complete enforcement

314boundary because Codex can often perform equivalent work through another388boundary because Codex can often perform equivalent work through another

315supported tool path.389supported tool path.

316 390

320 `WebSearch` or other non-shell, non-MCP tool calls.394 `WebSearch` or other non-shell, non-MCP tool calls.

321 395

322`matcher` is applied to `tool_name` and matcher aliases. For file edits through396`matcher` is applied to `tool_name` and matcher aliases. For file edits through

323`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input397`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input

324still reports `tool_name: "apply_patch"`.398still reports `tool_name: "apply_patch"`.

325 399

326Fields in addition to [Common input fields](#common-input-fields):400Fields in addition to [Common input fields](#common-input-fields):

327 401

329| ------------- | ------------ | --------------------------------------------------------------------------------------------------------- |403| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |

334 408

335Plain text on `stdout` is ignored.409Plain text on `stdout` is ignored.

336 410

337JSON on `stdout` can use `systemMessage` and can block a Bash command with this411JSON on `stdout` can use `systemMessage`. To deny a supported tool call, return

338hook-specific shape:412this hook-specific shape:

339 413

340```json414```json

341{415{

358 432

359You can also use exit code `2` and write the blocking reason to `stderr`.433You can also use exit code `2` and write the blocking reason to `stderr`.

360 434

361`permissionDecision: "allow"` and `"ask"`, legacy `decision: "approve"`,435To add model-visible context without blocking, return

362`updatedInput`, `additionalContext`, `continue: false`, `stopReason`, and436`hookSpecificOutput.additionalContext`:

363`suppressOutput` are parsed but not supported yet, so they fail open.437

438```json

439{

440 "hookSpecificOutput": {

441 "hookEventName": "PreToolUse",

442 "additionalContext": "The pending command touches generated files."

443 }

444}

445```

446

447`permissionDecision: "ask"`, legacy `decision: "approve"`, `updatedInput`,

448`continue: false`, `stopReason`, and `suppressOutput` are parsed but not

449supported yet, so they fail open.

364 450

365### PermissionRequest451### PermissionRequest

366 452

384 470

385Plain text on `stdout` is ignored.471Plain text on `stdout` is ignored.

386 472

473Some tool inputs may include a human-readable description, but don't rely on a

474`tool_input.description` field for every tool.

475

387To approve the request, return:476To approve the request, return:

388 477

389```json478```json

432 `WebSearch` or other non-shell, non-MCP tool calls.521 `WebSearch` or other non-shell, non-MCP tool calls.

433 522

434`matcher` is applied to `tool_name` and matcher aliases. For file edits through523`matcher` is applied to `tool_name` and matcher aliases. For file edits through

435`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input524`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input

436still reports `tool_name: "apply_patch"`.525still reports `tool_name: "apply_patch"`.

437 526

438Fields in addition to [Common input fields](#common-input-fields):527Fields in addition to [Common input fields](#common-input-fields):

439 528

441| --------------- | ------------ | --------------------------------------------------------------------------------------------------------- |530| --------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |

447 536

448Plain text on `stdout` is ignored.537Plain text on `stdout` is ignored.

549 638

550## Schemas639## Schemas

551 640

641The linked `main` branch schemas may include hook fields that are not in the

642 current release. Use this page as the release behavior reference.

643

552If you need the exact current wire format, see the generated schemas in the644If you need the exact current wire format, see the generated schemas in the

553[Codex GitHub repository](https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated).645[Codex GitHub repository](https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated).

mcp.md +25 −0

Details

86- `required` (optional): Set `true` to make startup fail if this enabled server can't initialize.86- `required` (optional): Set `true` to make startup fail if this enabled server can't initialize.

87- `enabled_tools` (optional): Tool allow list.87- `enabled_tools` (optional): Tool allow list.

88- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).88- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).

89- `default_tools_approval_mode` (optional): Default approval behavior for

90 tools from this server. Supported values are `auto`, `prompt`, and

91 `approve`.

92- `tools.<tool>.approval_mode` (optional): Per-tool approval behavior override.

89 93

90If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.94If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.

91 95

125url = "http://localhost:3000/mcp"129url = "http://localhost:3000/mcp"

126enabled_tools = ["open", "screenshot"]130enabled_tools = ["open", "screenshot"]

127disabled_tools = ["screenshot"] # applied after enabled_tools131disabled_tools = ["screenshot"] # applied after enabled_tools

132default_tools_approval_mode = "prompt"

128startup_timeout_sec = 20133startup_timeout_sec = 20

129tool_timeout_sec = 45134tool_timeout_sec = 45

130enabled = true135enabled = true

136

137[mcp_servers.chrome_devtools.tools.open]

138approval_mode = "approve"

139```

140

141### Plugin-provided MCP servers

142

143Installed plugins can bundle MCP servers in their plugin manifest. Those

144servers are launched from the plugin, so user config doesn't set their

145transport command. User config can still control on/off state and tool policy

146under `plugins.<plugin>.mcp_servers.<server>`.

147

148```toml

149[plugins."sample@test".mcp_servers.sample]

150enabled = true

151default_tools_approval_mode = "prompt"

152enabled_tools = ["read", "search"]

153

154[plugins."sample@test".mcp_servers.sample.tools.search]

155approval_mode = "approve"

131```156```

132 157

133## Examples of useful MCP servers158## Examples of useful MCP servers

models.md +5 −7

Details

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

plugins/build.md +92 −25

Details

4plugins in Codex, see [Plugins](https://developers.openai.com/codex/plugins). If you are still iterating on4plugins in Codex, see [Plugins](https://developers.openai.com/codex/plugins). If you are still iterating on

5one repo or one personal workflow, start with a local skill. Build a plugin5one repo or one personal workflow, start with a local skill. Build a plugin

6when you want to share that workflow across teams, bundle app integrations or6when you want to share that workflow across teams, bundle app integrations or

~~7MCP config, or publish a stable package.~~7MCP config, package lifecycle hooks, or publish a stable package.

8 8

9## Create a plugin with `$plugin-creator`9## Create a plugin with `$plugin-creator`

10 10

320 320

321- the curated marketplace that powers the official Plugin Directory321- the curated marketplace that powers the official Plugin Directory

322- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`322- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`

323- a Claude-style marketplace at `$REPO_ROOT/.claude-plugin/marketplace.json`323- a legacy-compatible marketplace at `$REPO_ROOT/.claude-plugin/marketplace.json`

324- a personal marketplace at `~/.agents/plugins/marketplace.json`324- a personal marketplace at `~/.agents/plugins/marketplace.json`

325 325

326You can install any plugin exposed through a marketplace. Codex installs326You can install any plugin exposed through a marketplace. Codex installs

337### Plugin structure337### Plugin structure

338 338

339Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include339Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include

340a `skills/` directory, an `.app.json` file that points at one or more apps or340a `skills/` directory, a `hooks/` directory for lifecycle hooks, an `.app.json`

341connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,341file that points at one or more apps or connectors, an `.mcp.json` file that

342and assets used to present the plugin across supported surfaces.342configures MCP servers, and assets used to present the plugin across supported

343surfaces.

343 344

344<FileTree345<FileTree

345 class="mt-4"346 class="mt-4"

374 },375 },

375 ],376 ],

376 },377 },

377 {

378 name: ".app.json",

379 comment: "Optional: app or connector mappings",

380 },

381 {

382 name: ".mcp.json",

383 comment: "Optional: MCP server configuration",

384 },

385 {378 {

386 name: "hooks/",379 name: "hooks/",

387 open: true,380 open: true,

388 children: [381 children: [

389 {382 {

390 name: "hooks.json",383 name: "hooks.json",

391 comment: "Optional: lifecycle configuration",384 comment: "Optional: lifecycle hooks",

392 },385 },

393 ],386 ],

394 },387 },

388 {

389 name: ".app.json",

390 comment: "Optional: app or connector mappings",

391 },

392 {

393 name: ".mcp.json",

394 comment: "Optional: MCP server configuration",

395 },

395 {396 {

396 name: "assets/",397 name: "assets/",

397 comment: "Optional: icons, logos, screenshots",398 comment: "Optional: icons, logos, screenshots",

401 ]}402 ]}

402/>403/>

403 404

404Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,405Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `hooks/`,

405`.mcp.json`, `.app.json`, and lifecycle config files at the plugin root.406`assets/`, `.mcp.json`, and `.app.json` at the plugin root.

406 407

407Published plugins typically use a richer manifest than the minimal example that408Published plugins typically use a richer manifest than the minimal example that

408appears in quick-start scaffolds. The manifest has three jobs:409appears in quick-start scaffolds. The manifest has three jobs:

409 410

410- Identify the plugin.411- Identify the plugin.

411- Point to bundled components such as skills, apps, or MCP servers.412- Point to bundled components such as skills, apps, MCP servers, or hooks.

412- Provide install-surface metadata such as descriptions, icons, and legal413- Provide install-surface metadata such as descriptions, icons, and legal

413 links.414 links.

414 415

486- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under487- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under

487 `./assets/` when possible.488 `./assets/` when possible.

488- Use `skills` for bundled skill folders, `apps` for `.app.json`,489- Use `skills` for bundled skill folders, `apps` for `.app.json`,

489 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle config.490 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle hooks.

490- If you omit `hooks` and the plugin includes `./hooks/hooks.json`, Codex loads491- Plugin hooks are off by default in this release; bundled hooks won't run

491 that default lifecycle config automatically.492 unless `[features].plugin_hooks = true`.

493- When plugin hooks are enabled, omit `hooks` to use the default

494 `./hooks/hooks.json` file when present.

492 495

493### Bundled MCP servers and lifecycle config496### Bundled MCP servers and lifecycle hooks

494 497

495`mcpServers` can point to an `.mcp.json` file that contains either a direct498`mcpServers` can point to an `.mcp.json` file that contains either a direct

496server map or a wrapped `mcp_servers` object.499server map or a wrapped `mcp_servers` object.

519}522}

520```523```

521 524

522`hooks` can point to one lifecycle JSON file, an array of lifecycle JSON files,525After installation, users can enable or disable a bundled MCP server and tune

523an inline lifecycle object, or an array of inline lifecycle objects. File paths526tool approval policy from their Codex config without editing the plugin. Use

524must follow the same `./`-prefixed plugin-root path rules as other manifest527`plugins.<plugin>.mcp_servers.<server>` for plugin-scoped MCP server policy:

525paths. If you omit the manifest field, Codex still checks `./hooks/hooks.json`.528

529```toml

530[plugins."my-plugin".mcp_servers.docs]

531enabled = true

532default_tools_approval_mode = "prompt"

533enabled_tools = ["search"]

534

535[plugins."my-plugin".mcp_servers.docs.tools.search]

536approval_mode = "approve"

537```

538

539Plugin hooks are off by default in this release. When

540`[features].plugin_hooks = true` and your plugin is enabled, Codex can load

541lifecycle hooks from your plugin alongside user, project, and managed hooks.

542

543```toml

544[features]

545plugin_hooks = true

546```

547

548The default plugin hook file is `hooks/hooks.json`:

549

550```json

551{

552 "hooks": {

553 "SessionStart": [

554 {

555 "hooks": [

556 {

557 "type": "command",

558 "command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",

559 "statusMessage": "Loading plugin context"

560 }

561 ]

562 }

563 ]

564 }

565}

566```

567

568If you define `hooks` in `.codex-plugin/plugin.json`, Codex uses that manifest

569entry instead of the default `hooks/hooks.json`. The manifest field can be a

570single path, an array of paths, an inline hooks object, or an array of inline

571hooks objects.

572

573```json

574{

575 "name": "repo-policy",

576 "hooks": ["./hooks/session.json", "./hooks/tools.json"]

577}

578```

579

580Hook paths follow the same manifest path rules as `skills`, `apps`, and

581`mcpServers`: start with `./`, resolve relative to the plugin root, and stay

582inside the plugin root.

583

584Plugin hook commands receive the Codex-specific environment variables

585`PLUGIN_ROOT` and `PLUGIN_DATA`. `PLUGIN_ROOT` points to the installed plugin

586root, and `PLUGIN_DATA` points to the plugin's writable data directory. Codex

587also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for compatibility with

588existing plugin hooks.

589

590Plugin hooks use the same event schema as regular hooks. See

591[Hooks](https://developers.openai.com/codex/hooks) for supported events, inputs, outputs, trust review, and

592current limitations.

526 593

527### Publish official public plugins594### Publish official public plugins

528 595

remote-connections.md +227 −34

Details

1# Remote connections1# Remote connections

2 2

~~3SSH remote connections are currently in alpha. To enable them today, set~~3import {

~~4 `remote_connections = true` in the `[features]` table in~~4 Desktop,

~~5 `~/.codex/config.toml`. Availability, setup flows, and supported environments~~5 Storage,

~~6 may change as the feature improves.~~6 Terminal,

7} from "@components/react/oai/platform/ui/Icon.react";

7 8

~~8Remote connections let Codex work with projects that live on another~~9Remote connections let you use Codex from another device or another machine.

~~9SSH-accessible machine. Use them when the codebase, credentials, services, or~~10Use Codex in the ChatGPT mobile app to work with Codex on a connected Mac,

~~10build environment you need are available on that host instead of your local~~11continue work from another Codex App device, or connect the Codex App to

~~11machine.~~12projects on an SSH host.

14Remote access uses the connected host's projects, threads, files, credentials,

15permissions, plugins, Computer Use, browser setup, and local tools.

17## What you can do remotely

19- Start new threads in projects on the host, or continue existing ones.

20- Send follow-up instructions, answer questions, and steer active work.

21- Approve commands and other actions.

22- Review outputs, diffs, test results, terminal output, and screenshots.

23- Get notified when Codex completes a task or needs your attention.

24- Switch between connected hosts and threads.

26The next sections cover using Codex in the ChatGPT mobile app to control a Codex

27App host. To connect Codex to a project on an SSH host, see

28[connect to an SSH host](#connect-to-an-ssh-host).

30<div class="not-prose my-6 max-w-4xl rounded-xl bg-[url('/images/codex/codex-wallpaper-1.webp')] bg-cover bg-center p-4 md:p-8">

31 <CodexScreenshot

32 alt="Codex mobile setup screen alongside the ChatGPT mobile Codex project list"

33 lightSrc="/images/codex/app/mobile-setup-light.webp"

34 darkSrc="/images/codex/app/mobile-setup-dark.webp"

35 variant="no-wallpaper"

36 maxHeight="none"

37 maxWidth="420px"

38 />

39</div>

41## Before you set up mobile access

43Make sure you have:

45- Codex access in the ChatGPT account and workspace you want to use.

46- The latest ChatGPT mobile app on an iOS or Android device. If you do not see

47 Codex in the ChatGPT mobile app, update ChatGPT first.

48- The latest Codex App for macOS running on a Mac host that is awake, online,

49 and signed in to the same account and workspace. Mobile setup starts from the

50 Codex App; you cannot set it up from the Codex CLI or IDE Extension.

51- Any required multi-factor authentication, SSO, or passkey configuration for

52 that account or workspace.

54If you use Codex through a ChatGPT workspace, your admin may need to enable

55Remote Control access before you can connect from your phone.

57## Set up mobile access

59Start in the Codex App on the host you want to connect. The setup flow enables

60remote access for that host, then shows a QR code you can scan from your phone.

62<WorkflowSteps variant="headings">

641. Start Codex mobile setup.

66 Open Codex on the host and select **Set up Codex mobile** in the

67 sidebar.

692. Scan the QR code.

71 Use your phone to scan the QR code shown by Codex. The code opens ChatGPT so

72 you can finish connecting the mobile app to the host.

743. Finish setup in ChatGPT.

76 ChatGPT opens the Codex mobile setup flow. Confirm the same ChatGPT account

77 and workspace, then complete any required multi-factor authentication, SSO,

78 or passkey steps. After setup succeeds, the host appears in Codex on your

79 phone.

814. Review host settings.

83 In Codex on the host, use **Settings > Connections** to manage connected

84 devices. You can also choose whether to keep the computer awake, enable

85 Computer Use, or install the Chrome extension.

87</WorkflowSteps>

89<div class="not-prose my-6 max-w-4xl">

90 <CodexScreenshot

91 alt="Connections settings showing devices that can control this Mac and remote access settings"

92 lightSrc="/images/codex/app/mobile-control-this-mac-framed-light.webp"

93 darkSrc="/images/codex/app/mobile-control-this-mac-framed-dark.webp"

94 maxHeight="480px"

95 class="p-3 sm:p-4"

96 imageClass="rounded-xl"

97 />

98</div>

100## Choose what to connect

101

102Start with the Mac laptop or desktop where you already use Codex. Add an

103always-on Mac or SSH host when you need continuous access or a different

104environment.

105

106### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Desktop width={17} height={17} /></span><span>Your Mac laptop or desktop</span></span>

107

108Connect the Mac where you already run Codex day to day. This gives remote access

109to the same projects, threads, credentials, plugins, and local setup you already

110use.

111

112If that Mac sleeps, loses network access, or closes Codex, remote access stops

113until it is available again. If you use this computer as your host device, keep

114it plugged in and turn on **Keep this Mac awake** in the host's connection

115settings.

116

117On a Mac laptop, remote access can stay available with the lid open while the

118computer is plugged in. With the lid closed, connect an external display as

119well. Choosing **Sleep** still stops remote access.

120

121### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Storage width={17} height={17} /></span><span>A dedicated always-on Mac</span></span>

122

123Use a dedicated always-on Mac when you want Codex to stay reachable for

124longer-running work.

125

126Install the projects, credentials, plugins, MCP servers, and tools Codex should

127use on that machine.

128

129### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Terminal width={17} height={17} /></span><span>A remote development environment</span></span>

130

131Use an SSH host or managed devbox when the project already lives in a remote

132environment. Connect the Codex App host to that environment first; your phone

133still connects to the Codex App host, and Codex works in the remote environment

134with its dependencies, security policies, and compute resources.

135

136For SSH setup details, see [connect to an SSH host](#connect-to-an-ssh-host).

137

138For browser or desktop tasks on an always-on Mac or remote host, enable

139 Computer Use and install the Chrome extension on that host.

140

141## What comes from the connected host

142

143Your phone sends prompts, approvals, and follow-up messages to Codex. The

144connected host provides the environment Codex uses.

145

146That means:

147

148- Repository files and local documents come from the connected host.

149- Shell commands run on that host or remote environment.

150- Any plugin installed on that host is available when you use Codex remotely.

151- MCP servers, skills, browser access, and Computer Use come from that host's

152 configuration.

153- Signed-in websites and desktop apps are available only when the host can

154 access them.

155- Sandboxing, security controls, and action approvals still apply to the

156 connected session.

157

158Codex uses a secure relay layer to keep trusted machines reachable across your

159authorized ChatGPT devices without exposing them directly to the public

160internet.

161

162## Pick up work from another device

163

164You can continue work from another signed-in Codex App device. For example, if

165your laptop is unavailable, you can start a thread from your phone on an

166always-on host, then later open Codex on your laptop and continue that same

167thread there.

168

169In Codex on the laptop, use **Settings > Connections > Control other devices**

170to add the other host. A device can allow remote access and control another

171device at the same time.

172

173<div class="not-prose my-6 max-w-4xl">

174 <CodexScreenshot

175 alt="Connections settings showing another device available under Control other devices"

176 lightSrc="/images/codex/app/mobile-control-other-devices-framed-light.webp"

177 darkSrc="/images/codex/app/mobile-control-other-devices-framed-dark.webp"

178 maxHeight="360px"

179 class="p-3 sm:p-4"

180 imageClass="rounded-xl"

181 />

182</div>

183

184## Connect to an SSH host

185

186In the Codex App, add remote projects from an SSH host and run threads against

187the remote filesystem and shell. Remote project threads run commands, read

188files, and write changes on the remote host.

12 189

13Keep the remote host configured with the same security expectations you use for190Keep the remote host configured with the same security expectations you use for

14normal SSH access: trusted keys, least-privilege accounts, and no191normal SSH access: trusted keys, least-privilege accounts, and no

15unauthenticated public listeners.192unauthenticated public listeners.

16 193

~~17## Codex app~~

~~19In the Codex app, add remote projects from an SSH host and run threads against~~

~~20the remote filesystem and shell.~~

22<WorkflowSteps variant="headings">194<WorkflowSteps variant="headings">

23 195

241. Add the host to your SSH config so Codex can auto-discover it.1961. Add the host to your SSH config so Codex can auto-discover it.

33 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with205 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with

34 OpenSSH, and ignores pattern-only hosts.206 OpenSSH, and ignores pattern-only hosts.

35 207

~~362. Confirm you can SSH to the host from the machine running the Codex app.~~2082. Confirm you can SSH to the host from the machine running the Codex App.

37 209

38 ```bash210 ```bash

39 ssh devbox211 ssh devbox

45 user's login shell. Make sure the `codex` command is available on the217 user's login shell. Make sure the `codex` command is available on the

46 remote host's `PATH` in that shell.218 remote host's `PATH` in that shell.

47 219

~~484. In the Codex app, open **Settings > Connections**, add or enable the SSH host,~~2204. In the Codex App, open **Settings > Connections**, add or enable the SSH

~~49 then choose a remote project folder.~~221 host, then choose a remote project folder.

50 222

51</WorkflowSteps>223</WorkflowSteps>

52 224

~~53If remote connections don't appear yet, enable the alpha feature flag in~~

~~54`~/.codex/config.toml`:~~

~~56```toml~~

~~57[features]~~

~~58remote_connections = true~~

~~59```~~

~~61Remote project threads run commands, read files, and write changes on the~~

~~62remote host.~~

64<CodexScreenshot225<CodexScreenshot

65 alt="Codex app settings showing SSH remote connections"226 alt="Codex app settings showing SSH remote connections"

66 lightSrc="/images/codex/app/remote-connections-light.webp"227 lightSrc="/images/codex/app/remote-connections-light.webp"

67 darkSrc="/images/codex/app/remote-connections-dark.webp"228 darkSrc="/images/codex/app/remote-connections-dark.webp"

68 maxHeight="420px"229 maxHeight="420px"

~~69 variant="no-wallpaper"~~230 class="p-3 sm:p-4"

231 imageClass="rounded-xl"

70/>232/>

71 233

72## Authentication and network exposure234## Authentication and network exposure

73 235

~~74Use SSH port forwarding with local-host WebSocket listeners. Don't expose an~~236Remote connections use SSH to start and manage the remote Codex app server.

~~75unauthenticated app-server listener on a shared or public network.~~237Don't expose app-server transports directly on a shared or public network.

238

239If you need to reach a remote machine outside your current network, use a VPN

240or mesh networking tool instead of exposing the app server directly to the

241internet.

242

243## Troubleshooting

244

245### You do not see the host on your phone

246

247Confirm that the Codex App is running on the host, **Allow other devices to

248connect** is enabled, and the same ChatGPT account and workspace are selected on

249both devices.

250

251### The approval request does not appear

252

253Open Codex in the ChatGPT mobile app. Confirm that the phone and host use the

254same ChatGPT account and workspace, then scan the QR code again or restart setup

255from the host. If you use a ChatGPT workspace, ask your admin to confirm that

256Remote Control access is enabled.

257

258### The remote session disconnects

259

260Check whether the host went to sleep, lost network access, or closed Codex.

261Keep the host awake and connected while Codex works.

262

263### Authentication blocks setup

76 264

~~77If you need to reach a remote machine outside your current network, use a VPN or~~265Complete the account or workspace authentication prompt shown during setup. If

~~78mesh networking tool such as Tailscale instead of exposing the app server~~266your organization requires SSO, multi-factor authentication, or a passkey,

~~79directly to the internet.~~267finish that flow before trying again. If setup still fails, ask your workspace

268admin to confirm that Remote Control access is enabled.

80 269

81## See also270## See also

82 271

~~83- [Codex app settings](https://developers.openai.com/codex/app/settings)~~272- [Codex App](https://developers.openai.com/codex/app)

273- [Codex App features](https://developers.openai.com/codex/app/features)

274- [Codex App settings](https://developers.openai.com/codex/app/settings)

275- [Computer Use](https://developers.openai.com/codex/app/computer-use)

276- [Chrome extension](https://developers.openai.com/codex/app/chrome-extension)

84- [Command line options](https://developers.openai.com/codex/cli/reference)277- [Command line options](https://developers.openai.com/codex/cli/reference)

85- [Authentication](https://developers.openai.com/codex/auth)278- [Authentication](https://developers.openai.com/codex/auth)

subagents.md +1 −1

Details

60 60

61Codex also reapplies the parent turn's live runtime overrides when it spawns a61Codex also reapplies the parent turn's live runtime overrides when it spawns a

62child. That includes sandbox and approval choices you set interactively during62child. That includes sandbox and approval choices you set interactively during

~~63the session, such as `/approvals` changes or `--yolo`, even if the selected~~63the session, such as `/permissions` changes or `--yolo`, even if the selected

64custom agent file sets different defaults.64custom agent file sets different defaults.

65 65

66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.

use-cases/ai-app-evals.md +123 −0 added

Details

1---

2name: Add evals to your AI application

3tagline: Use Codex to turn expected behavior into a Promptfoo eval suite.

4summary: Ask Codex to inspect your AI application, identify the behavior you

5 want to evaluate, and add a runnable Promptfoo eval suite.

6skills:

7 - token: promptfoo

8 url: https://github.com/promptfoo/promptfoo/tree/main/plugins/promptfoo

9 description: Plugin that includes `$promptfoo-evals` and

10 `$promptfoo-provider-setup` for creating, connecting, running, and QAing

11 eval suites.

12bestFor:

13 - AI applications that already have prompts, model calls, tools, retrieval,

14 agents, or product requirements but no repeatable eval suite.

15 - Teams preparing a model, prompt, retrieval, or agent change and wanting

16 regression tests before the pull request merges.

17 - Quality reviews where repeated manual checks should become committed eval

18 cases.

19starterPrompt:

20 title: Add Evals Before You Change Behavior

21 body: >-

22 Use $promptfoo-evals to add a Promptfoo eval suite for this AI application.

23 If there is not already a working Promptfoo provider or target adapter, use

24 $promptfoo-provider-setup first.

27 Behavior to evaluate: [support answer quality / tool-call correctness /

28 retrieval grounding / business rules / agent task completion]

31 Before editing:

33 - Inspect the app path users hit and any existing evals or tests.

35 - Propose the smallest useful eval plan: target adapter, seed cases,

36 assertions, files, commands, and required env vars or local services.

38 - Do not change production prompts, model settings, or app behavior until

39 the baseline eval exists and has been run.

42 Requirements:

44 - Exercise the application path users hit when possible, not only the raw

45 model prompt.

47 - Keep fixtures free of secrets, customer data, and sensitive personal data.

49 - Add a local eval command such as `npm run evals` or document the exact

50 command to run.

53 Finish with:

55 - Files changed

57 - Eval commands run

59 - Passing and failing cases

61 - Recommended next evals to add

62 suggestedEffort: medium

63relatedLinks:

64 - label: Promptfoo configuration

65 url: https://www.promptfoo.dev/docs/configuration/guide/

66 - label: Evaluation best practices

67 url: /api/docs/guides/evaluation-best-practices

68---

70## Introduction

72When you are building an AI application, or making changes to an existing one, you want to make sure it behaves as expected. Evals are a way to systematically test a set of scenarios and catch regressions before they ship.

74You can use Promptfoo to run evals on your AI application, and Codex to help you create and maintain the evals.

76## How to use

78Use Codex with the Promptfoo plugin's `$promptfoo-evals` skill to turn one AI app behavior into a repeatable eval suite. When the app does not already have a working Promptfoo target, `$promptfoo-provider-setup` helps connect the suite to the application path you want to test.

80Codex can inspect the app, propose high-signal cases, add the Promptfoo config and test data, run the suite locally, and give you a command to keep using.

82This use case works best when the behavior is concrete: support answer quality, retrieval grounding, classifier labels, tool calls, JSON shape, business rules, or prompt and model migration confidence.

84A strong first pass should be reviewable code and test data: a `promptfooconfig.yaml` or equivalent config, a small `evals/` directory, test cases, any target adapter needed to call the app, and a local command such as `npm run evals`.

86## Choose what to evaluate

88Start with one user-visible promise. Avoid asking Codex to evaluate the entire AI system in one pass. A smaller suite is easier to trust, review, and keep running.

90Good first targets include:

92- **Correctness:** classification, extraction, summarization, routing, or transformation.

93- **Grounding:** answers that should stay tied to retrieved documents or cited sources.

94- **Tool use:** choosing the right tool, passing valid arguments, and handling tool errors.

95- **Format or business rules:** JSON schemas, field names, business-rule limits, or UI-facing copy contracts.

96- **Prompt or model migration:** making sure a new prompt, model, system message, or retrieval setting does not break important cases.

98Start from product requirements, bug reports, support escalations, or sanitized examples your team is comfortable committing to the repo.

100## Ask for an eval plan

101

102Codex should inspect before it edits. Ask for a plan that names the target path, fixtures, assertions, adapter, and commands. This gives you a chance to catch the wrong target or weak test cases before files are added.

103

104Review the plan before implementation. It should name the app path or endpoint Promptfoo will call, the first seed cases, the assertions, the files Codex will create, the local command, and any required secrets or services. If the plan tests the raw model instead of the application path users hit, ask Codex whether that is intentional.

105

106## Implement, run, and iterate

107

108Once the plan is correct, ask Codex to implement it. The first implementation should be boring: config, cases, fixtures, a target adapter if needed, a command, and proof that the command ran.

109

110A small app-backed suite might look like this:

111

112```text

113evals/

114 promptfooconfig.yaml

115 tests/

116 cases.yaml

117 providers/

118 provider.js # only if the built-in provider cannot call the app directly

119```

120

121Run the suite before changing behavior. The baseline tells you whether the app already fails the cases, whether the assertions need tuning, or whether the target adapter is wrong. Tune assertions when they are too brittle or vague, but keep real product failures visible.

122

123After the first run, use the suite to compare app changes before they ship. Add new cases whenever a bug, launch requirement, or product review shows behavior you want to keep stable. Once the local command is stable, ask Codex to add it to CI or your release checklist.

use-cases/budget-vs-actuals-review.md +60 −0 added

Details

1---

2name: Review budget vs. actuals

3tagline: Turn plan, actuals, and close notes into a variance workbook.

4summary: Give Codex a budget, actuals export, and close notes, then ask it to

5 map actuals to plan, calculate variances, flag reconciliation issues, and

6 separate supported explanations from open finance questions.

7skills:

8 - token: $spreadsheets

9 description: Inspect spreadsheet inputs, clean and map rows, create variance

10 tables, and produce reviewable workbook outputs.

11bestFor:

12 - Month-end reviews that compare budget plans with actual spend exports.

13 - Finance teams preparing leadership commentary from GL, spend, or department

14 actuals.

15 - Workbooks where category mapping, tie-outs, and unsupported explanations

16 need review.

17starterPrompt:

18 title: Review budget vs. actuals

19 body: >-

20 Use $spreadsheets to update the budget vs. actuals review from the attached

21 files.

24 Compare actuals to plan, map actuals to the right budget categories,

25 summarize the major variances, and prepare a clean review view as an

26 editable .xlsx workbook.

29 Preserve the raw inputs, use formulas for dollar and percentage variance

30 calculations, and flag categories that do not map cleanly instead of forcing

31 a match. Use account type to determine favorable or unfavorable variance:

32 revenue above plan is favorable, while expense above plan is unfavorable.

33 suggestedEffort: medium

34relatedLinks:

35 - label: Agent skills

36 url: /codex/skills

37---

39## Introduction

41If you're working on a budget and want to review the variances or inspect any issues, Codex can help you create a fully functional review workbook you can work with.

43Attach the budget plan, actuals export, and close notes, then ask Codex for an editable review workbook. Codex can preserve the raw inputs, map actuals to plan, calculate variances, and create a summary view you can inspect in the thread.

45## Create the review workbook

491. Attach the budget plan, actuals export, and close notes, or provide exact file references along with the source.

502. Run the starter prompt and ask for an editable `.xlsx` workbook.

513. Open the workbook in Codex. Expand it into the full-screen view to inspect the raw inputs, mappings, variance formulas, and summary tab.

524. Continue in the same thread to fix category mappings, add department cuts, or draft the finance summary.

56If the source files are in a connected app, mention the exact files or folder. Avoid asking Codex to search a broad Drive or workspace when the review should use specific finance sources. When the workbook appears in the thread, open it in Codex and expand it full-screen to review the raw inputs, mappings, variance formulas, and summary tab before asking for revisions.

58## Check the variances

60Before sharing the workbook, ask Codex to audit the categories, formulas, and variance explanations.

use-cases/cash-flow-forecast.md +62 −0 added

Details

1---

2name: Forecast cash flow

3tagline: Find the liquidity low point in an editable forecast workbook.

4summary: Give Codex cash-flow inputs and model constraints, then ask it to

5 create an editable workbook that preserves the source cadence, flags

6 safety-balance breaches, and shows which assumptions drive cash pressure.

7skills:

8 - token: $spreadsheets

9 description: Build editable forecast workbooks, wire formulas to assumptions,

10 and add checks for scenarios and input gaps.

11bestFor:

12 - Finance and operations teams building a 13-week or monthly cash forecast.

13 - Forecasts that need receipts, payroll, vendor payments, and working-capital

14 assumptions in one workbook.

15 - Teams reviewing runway, safety-balance breaches, and scenario drivers before

16 a planning meeting.

17starterPrompt:

18 title: Forecast cash flow

19 body: >-

20 Use $spreadsheets to build an editable cash-flow forecast workbook from the

21 attached source files.

24 Use beginning cash, expected receipts, payroll, vendor payments, debt, tax,

25 capex, working-capital items, and timing assumptions where available.

26 Preserve the source cadence, whether weekly or monthly.

29 Include a summary view that flags the liquidity low point, the minimum

30 ending cash balance, and any breach of the safety cash threshold. Use

31 formulas so I can change assumptions later, and call out missing timing

32 assumptions before using placeholders.

33 suggestedEffort: medium

34relatedLinks:

35 - label: Agent skills

36 url: /codex/skills

37---

39## Introduction

41When you are building a cash-flow forecast, you want to make sure it is accurate and reflects the reality of your business. You can use Codex to help you create a forecast workbook that you can inspect and revise in Codex. Attach the cash-flow inputs, operating assumptions, and model constraints. You can also use file references when the inputs live in Google Drive or another connected source.

43## Make the forecast

471. Attach the cash-flow inputs, operating assumptions, and model constraints.

482. Run the starter prompt and ask for an editable `.xlsx` workbook.

493. Open the workbook in Codex. Expand it into the full-screen view to inspect assumptions, formulas, scenarios, and the summary tab.

504. Continue in the same thread to change collections, payroll, vendor payment, growth, or safety-balance assumptions.

54When the workbook appears in the thread, open it in Codex and expand it full-screen. Review the timing assumptions, formulas, scenarios, and summary tab, then ask Codex to revise the same workbook from there.

56## Review cash pressure

58Before using the forecast, ask Codex to identify the low point, tie the workbook back to the source inputs, and list assumptions that need review.

60## Run a scenario

62After reviewing the workbook in Codex, use follow-up prompts to change one scenario driver at a time.

use-cases/code-migrations.md +7 −1

Details

55relatedLinks:55relatedLinks:

56 - label: Modernizing your Codebase with Codex56 - label: Modernizing your Codebase with Codex

57 url: /cookbook/examples/codex/code_modernization57 url: /cookbook/examples/codex/code_modernization

58 - label: Follow a goal

59 url: /codex/use-cases/follow-goals

58 - label: Worktrees in the Codex app60 - label: Worktrees in the Codex app

59 url: /codex/app/worktrees61 url: /codex/app/worktrees

60---62---

61 63

62## Introduction64## Introduction

63 65

64When you are moving from one stack to another, you can leverage codex to map and execute a controlled migration: routing, data models, configuration, auth, background jobs, build tooling, deployment, tests, or even the language and framework conventions themselves.66When you are moving from one stack to another, you can leverage Codex to map and execute a controlled migration: routing, data models, configuration, auth, background jobs, build tooling, deployment, tests, or even the language and framework conventions themselves.

65 67

66Codex is useful here because it can inventory the legacy system, map old concepts to new ones, and land the change in checkpoints instead of one giant rewrite. That matters when you are moving off a legacy framework, porting to a new runtime, or incrementally replacing one stack with another while the product still has to keep working.68Codex is useful here because it can inventory the legacy system, map old concepts to new ones, and land the change in checkpoints instead of one giant rewrite. That matters when you are moving off a legacy framework, porting to a new runtime, or incrementally replacing one stack with another while the product still has to keep working.

67 69

82 84

83In our [code modernization cookbook](https://developers.openai.com/cookbook/examples/codex/code_modernization), we introduce ExecPlans: documents that let Codex keep an overview of the cleanup, spell out the intended end state, and log validation after each pass.85In our [code modernization cookbook](https://developers.openai.com/cookbook/examples/codex/code_modernization), we introduce ExecPlans: documents that let Codex keep an overview of the cleanup, spell out the intended end state, and log validation after each pass.

84When you ask Codex to run a complex migration, ask it to create an ExecPlan for each part of the system to make sure every decision and tech stack choice is recorded and can be reviewed later.86When you ask Codex to run a complex migration, ask it to create an ExecPlan for each part of the system to make sure every decision and tech stack choice is recorded and can be reviewed later.

88## Combine with a goal

90For long-running migration slices, use a [goal](https://developers.openai.com/codex/use-cases/follow-goals) to guide Codex through the work. Set the goal with a clear end state, parity checks, rollback expectations, and a stopping condition.

use-cases/collections/production-systems.md +6 −0

Details

26 26

27- https://developers.openai.com/codex/use-cases/reusable-codex-skills27- https://developers.openai.com/codex/use-cases/reusable-codex-skills

28 28

29## Keep documentation current

31Ask Codex to compare source changes with existing docs, update the smallest useful docs surface, and verify the changes.

33- https://developers.openai.com/codex/use-cases/update-documentation

29## Maintain system health35## Maintain system health

30 36

31Let Codex pick up feature requests and bug fixes automatically by using it from Slack and connecting it to your alerting, issue tracking, and daily bug sweeps.37Let Codex pick up feature requests and bug fixes automatically by using it from Slack and connecting it to your alerting, issue tracking, and daily bug sweeps.

use-cases/collections/web-development.md +6 −0

Details

5Codex works great with existing design systems, taking into account constraints and visual inputs to produce a responsive UI.5Codex works great with existing design systems, taking into account constraints and visual inputs to produce a responsive UI.

6These use cases are helpful when you are building web apps and need to iterate on frontend designs.6These use cases are helpful when you are building web apps and need to iterate on frontend designs.

7 7

8## Get from idea to prototype

10Use Codex to turn a rough idea into a visual direction and implement a first prototype.

12- https://developers.openai.com/codex/use-cases/idea-to-proof-of-concept

8## Build from Figma14## Build from Figma

9 15

10Use Codex to pull design context from Figma and turn it into code that follows the repo's components, styling, and design system.16Use Codex to pull design context from Figma and turn it into code that follows the repo's components, styling, and design system.

use-cases/complete-tasks-from-messages.md +2 −2

Details

9starterPrompt:9starterPrompt:

10 title: Finish One Task From a Message Thread10 title: Finish One Task From a Message Thread

11 body: >-11 body: >-

~~12 @Computer Use Look at my messages from [person].~~12 @Computer Look at my messages from [person].

13 13

14 14

15 Then:15 Then:

45 45

46For example:46For example:

47 47

~~48- `@Computer Use Look at my messages from [person]. Check my availability, find 2 dinner options in Hayes Valley, and draft a reply in the same thread. Check in with me before completing booking.`~~48- `@Computer Look at my messages from [person]. Check my availability, find 2 dinner options in Hayes Valley, and draft a reply in the same thread. Check in with me before completing booking.`

49 49

50## Practical tips50## Practical tips

51 51

use-cases/dcf-model.md +70 −0 added

Details

1---

2name: Model a DCF valuation

3tagline: Turn financial inputs into an editable valuation workbook.

4summary: Attach historical financials, valuation assumptions, and modeling

5 notes, then ask Codex for an editable DCF workbook you can inspect and revise

6 in Codex.

7skills:

8 - token: $spreadsheets

9 description: Create editable spreadsheet workbooks from attached inputs,

10 formulas, and assumptions.

11bestFor:

12 - Analysts turning historical financials and assumptions into a DCF workbook.

13 - Finance teams that want to inspect and iterate on the workbook in Codex.

14 - Teams preparing a valuation model from source files.

15starterPrompt:

16 title: Model a DCF valuation

17 body: >-

18 Use $spreadsheets to build a DCF workbook for the company in the attached

19 source files.

22 Include explicit operating drivers for revenue growth, margins, capex, and

23 working capital. Calculate unlevered free cash flow, WACC, terminal value,

24 and enterprise value. If capital structure and diluted share count are

25 provided, bridge to implied equity value and implied equity value per share.

28 Use any assumptions included in the source files. If an assumption is

29 missing, add a clearly labeled placeholder in the assumptions tab instead of

30 hiding it in a formula. If full balance sheet or cash-flow statement inputs

31 are missing, create the operating forecast needed for unlevered free cash

32 flow and flag the missing statement inputs.

35 Generate the result as an editable .xlsx workbook.

36 suggestedEffort: medium

37relatedLinks:

38 - label: Agent skills

39 url: /codex/skills

40 - label: File inputs

41 url: /api/docs/guides/file-inputs

42---

44## Introduction

46Codex can help you create a fully functional DCF workbook that you can inspect and revise.

48It can use multiple files as context, including the historical financials, valuation assumptions, and any modeling notes.

49You can provide these files directly, or use file references when the inputs live in Google Drive or another connected source. If so, provide the exact file references, as it will be more effective than asking Codex to search through all of your files.

51## Create the workbook

551. Attach the historical financials, valuation assumptions, and any modeling notes, or provide exact file references along with the source.

562. Run the starter prompt and ask for an editable `.xlsx` workbook.

573. Open the generated workbook in Codex. Expand it into the full-screen view to inspect the model tabs, formulas, assumptions, and valuation summary.

584. Continue in the same thread to check formula links, change assumptions, add scenarios, or tighten the model.

62When the workbook appears in the thread, open it in Codex and expand it full-screen. Review the source inputs, forecast drivers, valuation outputs, and sensitivity tables, then ask Codex to revise the same workbook from there.

64## Check the valuation

66Before using the workbook, ask Codex to review the model like a finance teammate would: source tie-outs, formulas, hardcoded assumptions, and valuation outputs.

68## Revise one assumption

70After reviewing the workbook in Codex, ask for targeted revisions in the same thread. Change one driver at a time so the impact is easy to inspect.

use-cases/draft-prds-from-sources.md +88 −0 added

Details

1---

2name: Draft PRDs from internal context

3tagline: Create product requirements documents from Linear, Slack, source

4 documents, and meeting notes.

5summary: Use Codex with the $documents skill and connected apps such as Linear,

6 Slack, Notion or Google Drive to create a reviewable PRD with the expected

7 sections, a timeline, decisions, open questions, and a source appendix.

8skills:

9 - token: $documents

10 description: Create, edit, and verify a DOCX when the PRD should become a

11 polished file instead of chat text.

12 - token: slack

13 url: https://github.com/openai/plugins/tree/main/plugins/slack

14 description: Read product discussions, launch threads, decision notes, and

15 follow-up questions from approved channels or thread links.

16 - token: linear

17 url: https://github.com/openai/plugins/tree/main/plugins/linear

18 description: Read projects, issues, priorities, acceptance criteria, and open

19 work that should shape the PRD.

20 - token: google-drive

21 url: https://github.com/openai/plugins/tree/main/plugins/google-drive

22 description: Read planning docs, research notes, specs, exported meeting notes,

23 and source folders.

24 - token: notion

25 url: https://github.com/openai/plugins/tree/main/plugins/notion

26 description: Read roadmap pages, project notes, meeting notes, and team wikis

27 that should shape the PRD.

28bestFor:

29 - Product teams turning planning context into a PRD, proposal, launch brief,

30 or decision memo.

31 - PMs who need to draft a PRD quickly after aligning with the team in internal

32 discussions.

33starterPrompt:

34 title: Draft the PRD

35 body: >-

36 Use $documents to create a PRD for [feature or product area] from @linear

37 [project or milestone], @slack [channel or thread], and @google-drive or

38 @notion [planning docs, research notes, meeting notes, or source folder].

41 Include the problem, users, goals/non-goals, requirements, UX, technical

42 considerations, metrics, launch plan, risks, open questions, decisions,

43 timeline, and source appendix.

46 Cite the sources behind requirement-level claims. If sources disagree, call

47 out the conflict instead of choosing silently. Draft only. Do not post,

48 update Linear, or share the document until I approve it.

49 suggestedEffort: medium

50relatedLinks:

51 - label: Codex plugins

52 url: /codex/plugins

53 - label: Agent skills

54 url: /codex/skills

55 - label: Codex app

56 url: /codex/app

57---

59## Introduction

61Before working on a new product or feature, it's common to draft a product requirements document (PRD) to align on the scope and requirements. Most often than not, the context needed to write that PRD is already available in the team's internal systems: tickets on Linear, discussions on Slack, drafts in Notion or Google Drive, etc. Codex can gather this context and draft a PRD that you can review and iterate on, while keeping the source trail visible.

63## Choose the sources

65Start with the sources you want Codex to use: the Linear project, the Slack planning channel or thread, and any Drive docs, Notion pages, meeting notes, or local files that should be cited in the PRD.

66You should also clearly outline the PRD sections you expect, such as the problem, users, requirements, UX, tech, launch plan, timeline, or decisions.

701. Start with `$documents` when the output should be a real DOCX.

712. Name the sources directly: the Linear project or milestone, the Slack channel or thread, and the docs or notes Codex should cite.

723. Give Codex the PRD section contract.

734. Review the source appendix first, then the requirements and open questions.

745. Use the same thread to resolve gaps, tighten scope, and prepare the handoff.

78## Refine in the same thread

80Use the starter prompt on this page for the first draft. If something is missing, point Codex at the missing source instead of starting over.

82## Check the source trail

84Before sharing the PRD, ask Codex to list the claims with weak or missing support, the unresolved questions, and the decisions it treated as confirmed. If the source appendix does not make those easy to audit, keep refining the same thread before exporting or posting anything.

86### Suggested prompt

88**Check the Source Trail**

use-cases/follow-goals.md +80 −0 added

Details

1---

2name: Follow a goal

3tagline: Give Codex a durable objective for long-running work.

4summary: Use `/goal` when a task needs Codex to keep working across turns toward

5 a verifiable stopping condition.

6bestFor:

7 - Long-running coding work with a clear success condition and validation loop.

8 - Code migrations, large refactors, deployment retry loops, experiments,

9 games, and side projects where Codex can keep making scoped progress.

10 - Teams that need to run long experiments with clear success criteria.

11starterPrompt:

12 title: Set a Long-Running Goal

13 body: /goal Complete [objective] without stopping until [verifiable end state].

14relatedLinks:

15 - label: "`/goal` in CLI slash commands"

16 url: /codex/cli/slash-commands#set-an-experimental-goal-with-goal

17 - label: Codex workflows

18 url: /codex/workflows

19 - label: Run code migrations

20 url: /codex/use-cases/code-migrations

21 - label: Iterate on difficult problems

22 url: /codex/use-cases/iterate-on-difficult-problems

23---

25## Introduction

27Use `/goal` when you want Codex to keep working toward one durable objective instead of stopping after one normal turn. It is useful for work that has a clear target, a validation loop, and enough room for Codex to make progress without asking you to steer every step. When you use `/goal`, Codex can work independently for multiple hours without needing your input.

29`/goal` is an experimental Codex CLI feature. Enable it from `/experimental`, or add `goals = true` under `[features]` in `config.toml`. Then set a goal with `/goal <objective>`, check the current goal with `/goal`, and use `/goal pause`, `/goal resume`, or `/goal clear` when you need to control the run.

31## Choose the right work

33A good goal is bigger than one prompt but smaller than an open-ended backlog. It should define what Codex should achieve, what it should not change, how it should validate progress, and when it should stop.

35This works well for:

37- code migration where the target stack, parity checks, and constraints are clear

38- large refactors where Codex can run tests after each checkpoint

39- experiments, games, or prototypes where Codex can keep improving a working artifact

41Avoid using a goal for a loose list of unrelated work.

43## Set up the loop

471. Name one objective and one stopping condition.

482. Point Codex at the files, docs, issue, logs, or plan it must read first.

493. Define the commands or artifacts that prove progress.

504. Tell Codex to work in checkpoints and keep a short progress log.

515. Use `/goal` to inspect status while it runs.

526. Pause, resume, or clear the goal when the run is done, blocked, or changing direction.

56The important part is the contract. Codex should know what "done" means before it starts. If the goal is a migration, "done" might mean the new path passes contract tests and the legacy path still has a rollback. If the goal is a game or prototype, "done" might mean the app builds, launches, and matches the input reference or expected behavior.

58Ask Codex to help: start by having a conversation about what you want to

59 build, then ask it to directly set a goal and start working.

61## Let Codex work independently

63During a goal, ask for compact progress reports that make the run easy to trust. A useful status update names the current checkpoint, what was verified, what remains, and whether Codex is blocked.

64If the status becomes vague, tighten the goal rather than adding more ad hoc instructions. Tell Codex exactly which checkpoint matters next, which command proves it, and what should cause it to pause.

66When Codex follows a goal, it can work independently for many hours without you having to check in. It will stop running when it is fairly confident it has reached the stopping condition, so you should think of `/goal` as a background task you don't need to monitor.

68## Example goals

70### Migrations

72Whether you're migrating games to a new stack, mobile apps to a new platform, or a codebase to a new framework, you can use `/goal` to have Codex run the migration:

74### Prototype creation

76Whether you're creating a new app from scratch, a new game, or a new feature, you can use `/goal` to have Codex complete a polished first version. You can use a PLAN.md file to guide the creation of the first version, describing precisely what you want to build.

78### Prompt optimization

80When you have an eval suite, you can use `/goal` to optimize prompts against the eval results. Codex can inspect failures, update the prompt, rerun the evals, and keep iterating until the score improves or it reaches your stopping condition.

use-cases/idea-to-proof-of-concept.md +76 −0 added

Details

1---

2name: Get from idea to proof of concept

3tagline: Explore the concept visually with ImageGen and build a first version of

4 your idea.

5summary: Use Codex with ImageGen to turn a rough idea into a visual direction,

6 implement the smallest useful prototype, and verify it in a browser.

7skills:

8 - token: $imagegen

9 description: Generate visual concepts, UI mockups, asset directions, and

10 variants with `gpt-image-2` before Codex implements the selected

11 direction.

12 - token: $playwright

13 url: https://github.com/openai/skills/tree/main/skills/.curated/playwright-interactive

14 description: Open the running app in a real browser, inspect the changed route,

15 and verify each small UI adjustment before the next iteration.

16 - token: build-web-apps

17 url: https://github.com/openai/plugins/tree/main/plugins/build-web-apps

18 description: Use the concept-first workflow for new web apps, dashboards, sites,

19 and frontend prototypes, then verify the implementation in the browser.

20 - token: game-studio

21 url: https://github.com/openai/plugins/tree/main/plugins/game-studio

22 description: Use Game Studio when the proof of concept is a browser game and

23 needs a playable loop, asset workflow, HUD, engine choice, and playtest

24 pass.

25bestFor:

26 - Early product ideas where a working prototype will answer more than a

27 written plan.

28 - Web apps, dashboards, and tools that need visual exploration before

29 implementation.

30 - Teams that want to validate a product idea with a working prototype before

31 investing further.

32starterPrompt:

33 title: Build the Proof of Concept

34 body: >-

35 Use ImageGen to generate a high quality UI mockup for the following idea,

36 then use the [Build Web Apps plugin/Game studio plugin] to implement it:

39 [describe the idea, target user, and the main workflow]

40 suggestedEffort: high

41relatedLinks:

42 - label: Image generation guide

43 url: /api/docs/guides/image-generation

44 - label: Codex plugins

45 url: /codex/plugins

46---

48## Start with a visual direction

50GPT Image 2 is great at generating high quality UI mockups. Instead of starting from scratch when exploring new ideas, you can leverage image generation to get a visual direction.

52You can do this in two ways:

54- Iterate on the visual direction using the ImageGen skill, and once you are satisfied with the proposed UI, you can ask Codex to build a prototype matching the visuals. In that case, make sure to copy the final image you want to implement in a new turn rather than continuing the conversation directly – Codex will do better when it can reference a user attachment.

55- Use a plugin and simply describe your idea: the plugin will generate the visual direction for you and handle next steps.

57## Leverage a plugin

59If you do not need to iterate on the visual direction before starting the implementation, you can use a plugin and describe your idea.

61Use the [Build Web Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-web-apps)

62for web apps, dashboards, creative websites, and frontend-heavy tools. Its

63workflow pushes Codex to generate a design first, match it in code, and use the

64browser to compare the result back to the concept.

66Use the [Game Studio plugin](https://github.com/openai/plugins/tree/main/plugins/game-studio)

67when the proof of concept is a browser game. That path should define the player

68verbs, first playable loop, engine, asset workflow, HUD, controls, and browser

69test before expanding the game.

71## Iteration workflow

73A good proof of concept is scoped to an MVP that can be implemented quickly and validated with the team.

74If you want to make sure the MVP is working as expected, you can use Playwright interactive to let Codex verify its work.

76Once you have a first version working, you can iterate on it by asking for scoped changes in the same conversation:

use-cases/qa-your-app-with-computer-use.md +3 −3

Details

10starterPrompt:10starterPrompt:

11 title: Run a Structured QA Pass11 title: Run a Structured QA Pass

12 body: |-12 body: |-

~~13 @Computer Use Test my app in [environment].~~13 @Computer Test my app in [environment].

14 14

15 Test these flows:15 Test these flows:

16 - [hero use case 1]16 - [hero use case 1]

46 46

47You can keep this broad:47You can keep this broad:

48 48

~~49- `@Computer Use Test my app. Find any major issues and give me a report.`~~49- `@Computer Test my app. Find any major issues and give me a report.`

50 50

51Or make it more explicit:51Or make it more explicit:

52 52

~~53- `@Computer Use Test my app in staging. Cover signup, invite a teammate, and upgrade billing. Log every bug with repro steps, expected result, actual result, and severity.`~~53- `@Computer Test my app in staging. Cover signup, invite a teammate, and upgrade billing. Log every bug with repro steps, expected result, actual result, and severity.`

54 54

55If you already maintain a test-plan file in the repo, attach it to the thread or point Codex at it so the QA pass follows your existing flows.55If you already maintain a test-plan file in the repo, attach it to the thread or point Codex at it so the QA pass follows your existing flows.

56 56

use-cases/react-native-expo-apps.md +105 −0 added

Details

1---

2name: Build React Native apps with Expo

3tagline: Go from a mobile-app idea to a working Expo app with the dedicated plugin.

4summary: Use Codex with the Expo plugin to scaffold React Native apps, stay

5 inside Expo Router and Expo-native package conventions, test quickly with Expo

6 Go, and move to dev clients or EAS builds only when the app needs them.

7skills:

8 - token: expo

9 url: https://docs.expo.dev/skills/

10 description: Use Expo-authored skills for Expo Router UI, native-feeling

11 components, data fetching, dev clients, deployment, upgrades, modules, and

12 Codex Run action wiring.

13bestFor:

14 - Developers who want to prototype or ship a React Native app with Expo before

15 reaching for native IDE workflows.

16 - Expo Router projects where Codex should follow Expo conventions for routing,

17 UI, package installs, builds, and deployment.

18 - Developers that need to migrate a web app to a mobile app.

19starterPrompt:

20 title: Build the Expo App

21 body: >-

22 Use the Expo plugin to build a React Native app with Expo for this idea:

25 [describe the app idea, target users, and the main workflow]

28 Requirements:

30 - Start with Expo Router and Expo-native project conventions.

32 - Try `npx expo start` and Expo Go first before creating a custom build.

34 - Use `npx expo install` for Expo packages so dependencies stay compatible.

36 - Use native-feeling UI patterns for navigation, forms, lists, empty states,

37 and loading states.

40 Deliver:

42 - the working app slice

44 - the run command

46 - the verification path you used, including Expo Go, device, simulator, dev

47 client, or EAS

48 suggestedEffort: medium

49relatedLinks:

50 - label: Expo plugin

51 url: https://docs.expo.dev/skills/

52 - label: Expo MCP Server setup

53 url: https://docs.expo.dev/eas/ai/mcp/

54techStack:

55 - need: Mobile framework

56 goodDefault: "[Expo](https://expo.dev/) and [React Native](https://reactnative.dev/)"

57 why: Expo gives Codex a managed React Native path with fast iteration,

58 compatible packages, and deployment tooling.

59 - need: Routing

60 goodDefault: "[Expo Router](https://docs.expo.dev/router/introduction/)"

61 why: Expo Router keeps navigation file-based and predictable, which helps Codex

62 add screens and flows without inventing a custom routing layer.

63---

65## Start with Expo Go

67Expo is a strong default when you want Codex to move from a mobile-app idea to a

68tested React Native app. The useful loop is `expo start` first, Expo Go

69on a device next, and then a dev client or EAS build only when the app needs

70custom native code, store distribution, or a capability that Expo Go can't run.

72That keeps Codex focused on the app workflow instead of spending the first pass

73on native IDE setup, simulator setup, provisioning, or build configuration.

75## Use the Expo plugin

77Expo published an [Expo plugin](https://docs.expo.dev/skills/) that gives Codex Expo-native guidance for Expo Router, native UI, forms,

78navigation, animations, data fetching, NativeWind setup, Expo modules, dev

79clients, deployment, upgrades, and Codex Run action wiring.

81Use it when Codex is building new Expo screens, adding packages, wiring API

82calls, preparing a dev client, or getting an app ready for TestFlight, App

83Store, Play Store, or EAS Hosting.

85Optionally, add the [Expo MCP Server](https://docs.expo.dev/eas/ai/mcp/) when the task needs current

86Expo documentation lookup, compatible package installation, EAS build and

87workflow operations, screenshots, simulator interaction, React Native DevTools,

88or TestFlight data.

90## Iteration process

941. Ask Codex to inspect the repo and confirm whether it is a new Expo app or an

95 existing Expo project.

962. Start with Expo Router and Expo Go, and use `npx expo install` when adding

97 Expo packages.

983. Ask Codex to build one complete workflow with native-feeling navigation,

99 loading states, empty states, and error states.

1004. Verify on the fastest available path, such as Expo Go on a device or a

101 simulator, then move to a dev client or EAS only when needed.

102

103

104

105## Suggested follow-up prompt

use-cases/slack-action-triage.md +123 −0 added

Details

1---

2name: Prioritize Slack action items

3tagline: Turn Slack threads and DMs into a ranked queue of next steps.

4summary: Use Codex with Slack and the tools where work happens to find direct

5 asks, implicit follow-ups, resolved items, and the highest-impact next actions

6 before drafting replies or handoffs.

7skills:

8 - token: slack

9 url: https://github.com/openai/plugins/tree/main/plugins/slack

10 description: Search DMs, channels, thread replies, mentions, and shared context

11 before deciding what still needs attention.

12 - token: gmail

13 url: https://github.com/openai/plugins/tree/main/plugins/gmail

14 description: Cross-check email when a Slack thread refers to an outreach, intro,

15 or sent follow-up.

16 - token: google-drive

17 url: https://github.com/openai/plugins/tree/main/plugins/google-drive

18 description: Read linked docs, decks, sheets, or source material when the Slack

19 thread depends on an artifact.

20 - token: google-calendar

21 url: https://github.com/openai/plugins/tree/main/plugins/google-calendar

22 description: Check event timing when a thread depends on a meeting, launch,

23 webinar, or deadline.

24bestFor:

25 - People who get work through Slack and need Codex to separate live asks from

26 already-handled chatter.

27 - Launch, community, support, product, and operations workstreams where

28 context is split across DMs, channels, and threads.

29 - Teams that want a ranked action queue before drafting replies, handoffs,

30 docs changes, or follow-up tasks.

31starterPrompt:

32 title: Find What Needs Attention in Slack

33 body: >-

34 Can you check @slack for messages to me about [workstream] from [time

35 window] and return a ranked action queue?

38 Look across DMs, group DMs, channel mentions, and threads.

41 For each item, include:

43 - source link or thread

45 - what is being asked

47 - whether it needs my reply, a person or lead, a docs or code change, or

48 just a decision

50 - why it matters

52 - the recommended next step

55 Before calling anything unresolved, read the latest thread replies and skip

56 items that were already handled.

59 Do not post messages directly but suggest drafts for my review.

60 suggestedEffort: low

61relatedLinks:

62 - label: Codex plugins

63 url: /codex/plugins

64 - label: Use Codex in Slack

65 url: /codex/integrations/slack

66 - label: Codex automations

67 url: /codex/app/automations

68---

70## Find the work hidden in Slack

72Slack is often where a request starts, but not where the full context lives. A teammate might ask for a reply in a DM, clarify the real action in a thread, link a doc in a channel, and resolve the issue later without mentioning you again.

74Use this workflow when you want Codex to read the Slack context, check whether the ask is still live, and return the few items that actually need your attention. The goal is to get a ranked action queue: what needs a reply, a decision, a person to contact, a doc update, or a handoff.

76## Run the triage pass

801. Give Codex a time window, workstream, person, channel, or topic.

812. Ask it to search DMs, group DMs, channel mentions, and relevant thread replies.

823. Have Codex read the latest thread tail before calling an item unresolved.

834. Ask for a ranked queue sorted by urgency and impact.

845. Ask Codex to draft the reply, handoff, or follow-up task.

88After trying this and tweaking the flow to match your needs, you can turn it into a [thread automation](https://developers.openai.com/codex/app/automations#thread-automations) by asking Codex to do the same thing on a schedule.

90## Ask for the right output

92A useful triage result should explain why each item is still live. It should also skip old asks that someone answered later in the thread.

94You should expect to see something like this:

98<p>

99 <strong>Top action item:</strong> Priya is asking for concrete customer

100 examples, not just more ideas.

101 </p>

102 <p>

103 <strong>Why it matters:</strong> the launch update needs real people the

104 team can contact this week.

105 </p>

106 <p>

107 <strong>Evidence:</strong> the original channel message asked for use cases,

108 but the thread later says "please DM me if you have leads."

109 </p>

110 <p>

111 <strong>Next step:</strong> reply with two named leads, or say you can be

112 the example if that is more useful.

113 </p>

114

115

116

117Good output makes the distinction explicit: an idea is different from a lead, a live ask is different from an FYI, and a request you already answered shouldn't stay in the queue.

118

119If you get too much noise or too few actionable items, tweak the prompt and if needed, mention specific slack channels you want Codex to pay attention to.

120

121## Draft the follow-up

122

123Once the queue is right, keep the action in the same thread. Ask Codex to draft a reply or handoff from the evidence it already gathered:

use-cases/update-documentation.md +104 −0 added

Details

1---

2name: Keep documentation up-to-date

3tagline: Use code and other sources to automate docs updates.

4summary: Use Codex to compare source code changes, public docs, release notes,

5 and PR context, then draft focused documentation updates with verification

6 steps before publishing.

7skills:

8 - token: github

9 url: https://github.com/openai/plugins/tree/main/plugins/github

10 description: Read issues, pull requests, comments, review threads, and failed

11 checks when GitHub is part of your bug intake.

12bestFor:

13 - Developer docs, READMEs, runbooks, examples, and migration notes that need

14 to track behavior that changes frequently.

15 - Teams that maintain documentation for a technical product.

16starterPrompt:

17 title: Update Docs From Source Changes

18 body: >-

19 Update the [product/feature] documentation based on the following sources:

21 - the changed source files in [this repo/source linked repo]

23 - the existing docs pages that mention a new behavior

25 - any linked issue, PR, release note, or public reference I provide below

28 Then:

30 - identify what is user-facing

32 - update only the docs that need to change

34 - keep unpublished roadmap, private customer details, and internal-only

35 context out of public docs

37 - preserve the existing docs structure, terminology, and cross-links

39 - run the docs checks that fit the change

42 Before finalizing, summarize what changed, what you verified, and any claims

43 you could not prove from trusted sources.

46 [link release notes or other references here]

47relatedLinks:

48 - label: Workflows

49 url: /codex/workflows

50---

52## Introduction

54Documentation is easiest to keep current when it is updated alongside source changes, not weeks later. Codex can inspect changed code, tests, release notes, linked issues, and pull request context, then draft a scoped docs update that matches the existing structure.

56Use this workflow for developer docs, README updates, changelog drafts, migration notes, runbooks, or anything else that needs to track behavior that changes frequently.

58## How to use

621. Start from the change you need to document.

64 Share the branch, pull request, commit, issue, or files. If the docs are public, say explicitly that unpublished roadmap, private customer details, and internal-only context should stay out.

662. Ask Codex to map the affected docs.

68 Have it search existing docs for feature names, config keys, commands, examples, and related terms before drafting.

703. Update the smallest useful docs surface.

72 Codex should preserve the current page structure, terminology, cross-links, and frontmatter. It should avoid broad rewrites when a precise note, example, or section update is enough.

744. Verify the changes.

76 Ask Codex to run formatting and docs checks that fit the repo, then summarize the evidence behind each user-facing claim.

78## What to give Codex

80| Source | Why it helps |

81| ------------------------------------ | -------------------------------------------------------------------------- |

82| Changed code and tests | Lets Codex analyze actual behavior to draft focused documentation updates. |

83| Public release notes or product docs | Helps Codex match public terminology, availability, and feature status. |

84| Pull request or issue context | Explains why the change happened and which user-facing behavior matters. |

85| Local docs checks | Gives Codex a concrete definition of done before the docs are published. |

87Adding more context such as public release notes lets Codex avoid including private context or updates that are not yet public.

89## Make the workflow repeatable

91For a repo-wide convention, add documentation expectations to [AGENTS.md](https://developers.openai.com/codex/guides/agents-md). For example:

93```md

94## Documentation

96- When user-facing behavior changes, check whether docs, examples, or changelogs need updates.

97- Public docs must only include public information or behavior visible in this repo.

98- Preserve existing terminology and frontmatter.

99- Run the docs formatting and build checks before final handoff.

100```

101

102If the process has more steps, turn it into a [skill](https://developers.openai.com/codex/skills) so future Codex threads can follow the same source-checking, drafting, and verification loop. See [Save workflows as skills](https://developers.openai.com/codex/use-cases/reusable-codex-skills) that shares more details on this pattern.

103

104You can also turn this workflow into a [thread automation](https://developers.openai.com/codex/app/automations#thread-automations) by asking Codex to run it on a schedule, asking to fetch all the recent PRs from GitHub to automatically keep docs up-to-date, for example on a weekly basis:

use-cases/use-your-computer-with-codex.md +5 −5

Details

10starterPrompt:10starterPrompt:

11 title: Hand Off One Computer Task11 title: Hand Off One Computer Task

12 body: >-12 body: >-

~~13 @Computer Use [do the task you want completed across your Mac]~~13 @Computer [do the task you want completed across your Mac]

14 14

15 15

16 For example:16 For example:

40## How to use40## How to use

41 41

421. Install the [Computer Use plugin](https://developers.openai.com/codex/app/computer-use).421. Install the [Computer Use plugin](https://developers.openai.com/codex/app/computer-use).

~~432. Start your request with `@Computer Use`, or mention a specific app such as `@Slack` or `@Messages`.~~432. Start your request with `@Computer`, or mention a specific app such as `@Slack` or `@Messages`.

443. Describe the task and the outcome you want.443. Describe the task and the outcome you want.

454. Approve access when Codex needs it, then let it continue the task in the background.454. Approve access when Codex needs it, then let it continue the task in the background.

46 46

48 48

49For example:49For example:

50 50

~~51- `@Computer Use Play some music to help me focus.`~~51- `@Computer Play some music to help me focus.`

~~52- `@Computer Use Help me add my interview notes from Notes to Ashby.`~~52- `@Computer Help me add my interview notes from Notes to Ashby.`

~~53- `@Computer Use Go through my Slack and add reminders for everything I need to do by end of day.`~~53- `@Computer Go through my Slack and add reminders for everything I need to do by end of day.`

54 54

55## Practical tips55## Practical tips

56 56

use-cases/user-stories-to-ui-mocks.md +79 −0 added

Details

1---

2name: Turn user stories into UI mocks

3tagline: Convert product feedback, issue threads, and design context into

4 mockups your team can react to and implement.

5summary: Use Codex to gather product feedback from Slack, Linear, Google Drive,

6 normalize it into user stories and constraints, then generate UI mockups with

7 ImageGen. When the direction is chosen, turn the mock into a working

8 prototype.

9skills:

10 - token: slack

11 url: https://github.com/openai/plugins/tree/main/plugins/slack

12 description: Search approved feedback channels and threads for user stories,

13 pain points, quotes, and open questions.

14 - token: linear

15 url: https://github.com/openai/plugins/tree/main/plugins/linear

16 description: Pull feature requests, bug reports, labels, priorities, and project

17 context into the mock brief.

18 - token: google-drive

19 url: https://github.com/openai/plugins/tree/main/plugins/google-drive

20 description: Read research notes, call summaries, docs, sheets, and slides that

21 contain product feedback or design requirements.

22 - token: figma

23 url: https://github.com/openai/plugins/tree/main/plugins/figma

24 description: Fetch design context, screenshots, and design-system references so

25 mocks do not drift away from the product's visual language.

26 - token: $imagegen

27 description: Generate UI mockups, variations, and visual truth from the

28 synthesized stories and design constraints.

29 - token: build-web-apps

30 url: https://github.com/openai/plugins/tree/main/plugins/build-web-apps

31 description: Turn the selected mock into a working web prototype and verify the

32 implementation against the mock.

33bestFor:

34 - Product teams turning scattered feedback into a visual direction for a

35 feature.

36 - Design and engineering teams that want mockups grounded in source material

37 before building.

38 - Teams who want to iterate fast based on user feedback.

39starterPrompt:

40 title: Create Mocks from User Stories

41 body: >-

42 Turn this [user story/set of user feedbacks] into a UI mock for a feature

43 that would solve the problem, using these sources as context:

45 - @slack [channels or thread links]

47 - @linear [issue links, project, team, or view]

49 - @google-drive [research notes, survey export, doc, sheet, or slide deck]

52 Do that while respecting the current design system and existing UI [provide

53 Figma file or screenshot as reference].

54 suggestedEffort: medium

55relatedLinks:

56 - label: Codex plugins

57 url: /codex/plugins

58---

60## Introduction

62Product teams often collect feedback from various sources, such as Slack threads, Linear issues, Google Drive docs or sheets, or customer-call notes. Sometimes, they have clear user stories illustrating a problem they want to solve, and sometimes, the context lives in those sources.

64Codex can gather this context and turn it into a UI mock for a feature that would solve the problem, and once validated, can be implemented into the product.

66## Generate visual truth

68If you have a clear user story, you can start with that. If not, you can have a discussion with Codex first, gathering context from different sources and synthesizing it into a user story.

70Then, you can ask Codex to use ImageGen to create a few mock directions. The mocks should preserve the product's information architecture and design-system constraints.

72If helpful, you can provide screenshots of the current UI or a Figma file as reference.

74Do this until you are satisfied with the mock. The more scoped the changes are, the more likely Codex is to generate a mock that can be implemented directly.

76## Move from mock to prototype

78Use the final mock image that you want Codex to implement. Re-attach this image in a new turn rather than continuing the conversation directly.

79You can then ask Codex to implement the mock – optionally using the [Build Web Apps plugin](https://developers.openai.com/codex/plugins/build-web-apps) if you're building a web app – to turn it into a working prototype:

use-cases/verified-operations-workflows.md +91 −0 added

Details

1---

2name: Run verified operations

3tagline: Run repeatable workflows and verify the result.

4summary: Use Codex to normalize inputs, run approved scripts or APIs, retry

5 bounded failures, and verify the result from logs or artifacts before

6 reporting back.

7bestFor:

8 - Operations tasks with structured inputs, explicit approval, and a result

9 that should be auditable.

10 - Repeated workflows such as access updates, invite batches, quota changes,

11 customer setup tasks, routing checks, and migration follow-ups.

12 - Teams that need Codex to run a narrow scope and report exactly what

13 succeeded, failed, or needs a human decision.

14starterPrompt:

15 title: Run an Approved Workflow

16 body: >-

17 I need to run this workflow:

20 Goal: [what should happen]

22 Inputs: [CSV, Google Sheet, list, ticket, or file path]

24 Approval or policy source: [Slack thread, doc, ticket, or none]

26 Runner: [script, API, CLI, skill, or manual app workflow]

28 Verification artifact: [result CSV, log, dashboard, screenshot, or other

29 proof]

32 Please:

34 - inspect the inputs and ask only for missing required fields

36 - normalize dates, amounts, owners, and IDs before running the workflow

38 - run a dry run first when the workflow supports it

40 - run only the approved scope

42 - record one success or failure row per item

44 - retry transient failures once without restarting successful rows

46 - summarize totals, failures, retries, and verification artifacts

49 Pause before irreversible actions or scope changes.

50 suggestedEffort: medium

51relatedLinks:

52 - label: Codex plugins

53 url: /codex/plugins

54 - label: Codex automations

55 url: /codex/app/automations

56 - label: Agent skills

57 url: /codex/skills

58---

60## Run operations you can audit

62If you have repeatable operations you need to run regularly, such as giving access to a user, applying a batch update, or calling a script with different parameters for example, you can use Codex to automate it and give you an auditable output.

64Use this workflow when Codex should run a repeatable operation and show you what happened with an artifact that counts as verification.

66## Describe the task and inputs

701. Give Codex the input table, files, tickets, or other list it should batch run the process on.

712. Point it to the approval source or policy that defines the allowed scope, if applicable.

723. Tell Codex which script, API, skill, CLI, or app workflow should do the work.

734. Optionally, ask for a dry run when the workflow supports one.

745. Ask Codex to run the batch operation and record one success or failure row per item.

78Keep the scope narrow, and add instructions for Codex to run the operation only when it has all the required inputs.

79If a row is missing a required field, Codex should flag that row instead of guessing.

81Connect the tools you use to run the operation with [plugins](https://developers.openai.com/codex/plugins), for example your ticketing system or your spreadsheet with list items.

83## Require proof to verify the result

85A useful operations run includes an artifact that you or a teammate can inspect, such as a result CSV, a log file, a dashboard link, a screenshot, a PR check, or any other proof that the operation was successful. When using the Codex app, you can inspect this [artifact](https://developers.openai.com/codex/app/artifacts) directly in the artifact viewer after the run to verify the result.

87## Turn the run into a reusable workflow

89After the first successful run, ask Codex to capture the repeatable parts. For common workflows, this can become a [skill](https://developers.openai.com/codex/skills), or an [automation](https://developers.openai.com/codex/app/automations) that runs on a schedule.

91For scheduled operations, use an automation only after the manual run produces reliable output. Keep sensitive actions that might affect access or data permanently draft-only unless you explicitly want Codex to take them.

OpenAI - Codex Docs Changes 2026-05-05 23:00 UTC → 2026-05-18 22:01 UTC