OpenAI - Codex Docs Changes

agent-approvals-security.md +254 −0 added

Details

1# Agent approvals & security

3Codex helps protect your code and data and reduces the risk of misuse.

5This page covers how to operate Codex safely, including sandboxing, approvals,

6 and network access. If you are looking for Codex Security, the product for

7 scanning connected GitHub repositories, see [Codex Security](https://developers.openai.com/codex/security).

9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

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

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

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

15## Sandbox and approvals

17Codex security controls come from two layers that work together:

19- **Sandbox mode**: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.

20- **Approval policy**: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).

22Codex uses different sandbox modes depending on where you run it:

24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

27In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.

29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

31Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

33## Network access [Elevated Risk](https://help.openai.com/articles/20001061)

35For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.

37For the Codex app, CLI, or IDE Extension, the default `workspace-write` sandbox mode keeps network access turned off unless you enable it in your configuration:

39```toml

40[sandbox_workspace_write]

41network_access = true

42```

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:

46```toml

47web_search = "cached" # default

48# web_search = "disabled"

49# web_search = "live" # same as --search

50```

52Use caution when enabling network access or web search in Codex. Prompt injection can cause the agent to fetch and follow untrusted instructions.

54## Defaults and recommendations

56- On launch, Codex detects whether the folder is version-controlled and recommends:

57 - Version-controlled folders: `Auto` (workspace write + on-request approvals)

58 - Non-version-controlled folders: `read-only`

59- Depending on your setup, Codex may also start in `read-only` until you explicitly trust the working directory (for example, via an onboarding prompt or `/permissions`).

60- The workspace includes the current directory and temporary directories like `/tmp`. Use the `/status` command to see which directories are in the workspace.

61- To accept the defaults, run `codex`.

62- You can set these explicitly:

63 - `codex --sandbox workspace-write --ask-for-approval on-request`

64 - `codex --sandbox read-only --ask-for-approval on-request`

66### Protected paths in writable roots

68In the default `workspace-write` sandbox policy, writable roots still include protected paths:

70- `<writable_root>/.git` is protected as read-only whether it appears as a directory or file.

71- If `<writable_root>/.git` is a pointer file (`gitdir: ...`), the resolved Git directory path is also protected as read-only.

72- `<writable_root>/.agents` is protected as read-only when it exists as a directory.

73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

74- Protection is recursive, so everything under those paths is read-only.

76### Run without approval prompts

78You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

80This option works with all `--sandbox` modes, so you still control Codex's level of autonomy. Codex makes a best effort within the constraints you set.

82If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

84For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.

86### Common sandbox and approval combinations

88| Intent | Flags | Effect |

89| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

90| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

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

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

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

94| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |

96`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.

98With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

100#### Configuration in `config.toml`

101

102For the broader configuration workflow, see [Config basics](https://developers.openai.com/codex/config-basic), [Advanced Config](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://developers.openai.com/codex/config-reference).

103

104```toml

105# Always ask for approval mode

106approval_policy = "untrusted"

107sandbox_mode = "read-only"

108allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

109

110# Optional: Allow network in workspace-write mode

111[sandbox_workspace_write]

112network_access = true

113

114# Optional: granular approval prompt auto-rejection

115# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

116```

117

118You can also save presets as profiles, then select them with `codex --profile <name>`:

119

120```toml

121[profiles.full_auto]

122approval_policy = "on-request"

123sandbox_mode = "workspace-write"

124

125[profiles.readonly_quiet]

126approval_policy = "never"

127sandbox_mode = "read-only"

128```

129

130### Test the sandbox locally

131

132To see what happens when a command runs under the Codex sandbox, use these Codex CLI commands:

133

134```bash

135# macOS

136codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

137# Linux

138codex sandbox linux [--full-auto] [COMMAND]...

139```

140

141The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

142

143## OS-level sandbox

144

145Codex enforces the sandbox differently depending on your OS:

146

147- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

148- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.

149- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

150

151If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:

152

153```json

154{

155 "chatgpt.runCodexInWindowsSubsystemForLinux": true

156}

157```

158

159This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).

160

161When running natively on Windows, configure the native sandbox mode in `config.toml`:

162

163```toml

164[windows]

165sandbox = "unelevated" # or "elevated"

166```

167

168See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

169

170When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.

171

172In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

173

174## Version control

175

176Codex works best with a version control workflow:

177

178- Work on a feature branch and keep `git status` clean before delegating. This keeps Codex patches easier to isolate and revert.

179- Prefer patch-based workflows (for example, `git diff`/`git apply`) over editing tracked files directly. Commit frequently so you can roll back in small increments.

180- Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

181

182## Monitoring and telemetry

183

184Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

185

186### Overview

187

188- Codex turns off OTel export by default to keep local runs self-contained.

189- When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.

190- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

191

192### Enable OTel (opt-in)

193

194Add an `[otel]` block to your Codex configuration (typically `~/.codex/config.toml`), choosing an exporter and whether to log prompt text.

195

196```toml

197[otel]

198environment = "staging" # dev | staging | prod

199exporter = "none" # none | otlp-http | otlp-grpc

200log_user_prompt = false # redact prompt text unless policy allows

201```

202

203- `exporter = "none"` leaves instrumentation active but doesn't send data anywhere.

204- To send events to your own collector, pick one of:

205

206```toml

207[otel]

208exporter = { otlp-http = {

209 endpoint = "https://otel.example.com/v1/logs",

210 protocol = "binary",

211 headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }

212}}

213```

214

215```toml

216[otel]

217exporter = { otlp-grpc = {

218 endpoint = "https://otel.example.com:4317",

219 headers = { "x-otlp-meta" = "abc123" }

220}}

221```

222

223Codex batches events and flushes them on shutdown. Codex exports only telemetry produced by its OTel module.

224

225### Event categories

226

227Representative event types include:

228

229- `codex.conversation_starts` (model, reasoning settings, sandbox/approval policy)

230- `codex.api_request` (attempt, status/success, duration, and error details)

231- `codex.sse_event` (stream event kind, success/failure, duration, plus token counts on `response.completed`)

232- `codex.websocket_request` and `codex.websocket_event` (request duration plus per-message kind/success/error)

233- `codex.user_prompt` (length; content redacted unless explicitly enabled)

234- `codex.tool_decision` (approved/denied, source: configuration vs. user)

235- `codex.tool_result` (duration, success, output snippet)

236

237Associated OTel metrics (counter plus duration histogram pairs) include `codex.api_request`, `codex.sse_event`, `codex.websocket.request`, `codex.websocket.event`, and `codex.tool.call` (with corresponding `.duration_ms` instruments).

238

239For the full event catalog and configuration reference, see the [Codex configuration documentation on GitHub](https://github.com/openai/codex/blob/main/docs/config.md#otel).

240

241### Security and privacy guidance

242

243- Keep `log_user_prompt = false` unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.

244- Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.

245- Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.

246- Review local data retention settings (for example, `history.persistence` / `history.max_bytes`) if you don't want Codex to save session transcripts under `CODEX_HOME`. See [Advanced Config](https://developers.openai.com/codex/config-advanced#history-persistence) and [Configuration Reference](https://developers.openai.com/codex/config-reference).

247- If you run the CLI with network access turned off, OTel export can't reach your collector. To export, allow network access in `workspace-write` mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.

248- Review events periodically for approval/sandbox changes and unexpected tool executions.

249

250OTel is optional and designed to complement, not replace, the sandbox and approval protections described above.

251

252## Managed configuration

253

254Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.

app.md +5 −2

Details

4 4

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).

6 6

7![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)9![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)

8 10

9## Getting started11## Getting started

12 14

131. Download and install the Codex app151. Download and install the Codex app

14 16

~~15 The Codex app is currently only available for macOS.~~17 Download the Codex app for Windows or macOS.

16 18

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

18 20

~~19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)~~21 [Get notified for Linux](https://openai.com/form/codex-app/)

202. Open Codex and sign in222. Open Codex and sign in

21 23

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

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

40 42

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

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

42 45

43---46---

44 47

app-server.md +282 −27

Details

116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.

117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.

118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.

119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `thread/archived`, `thread/unarchived`, `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.

120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.

121 121

122## Initialization122## Initialization

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

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

203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.

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

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

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

207- `thread/archive` - move a thread’s log file into the archived directory; returns `{}` on success.207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

208- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread`.208- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.

209- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

210- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.211- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

210- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.212- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

211- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."213- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

223- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.225- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.

224- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.226- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

225- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).227- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).

226- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id).228- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

229- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

227- `config/read` - fetch the effective configuration on disk after resolving configuration layering.230- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

231- `externalAgentConfig/detect` - detect migratable external-agent artifacts with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

232- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).

228- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.233- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

229- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.234- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

230- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists and residency requirements (or `null` if you haven’t set any up).235- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

231 236

232## Models237## Models

233 238

239{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }244{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }

240{ "id": 6, "result": {245{ "id": 6, "result": {

241 "data": [{246 "data": [{

242 "id": "gpt-5.2-codex",247 "id": "gpt-5.4",

243 "model": "gpt-5.2-codex",248 "model": "gpt-5.4",

244 "upgrade": "gpt-5.3-codex",249 "displayName": "GPT-5.4",

245 "displayName": "GPT-5.2 Codex",

246 "hidden": false,250 "hidden": false,

247 "defaultReasoningEffort": "medium",251 "defaultReasoningEffort": "medium",

248 "reasoningEffort": [{252 "supportedReasoningEfforts": [{

249 "effort": "low",253 "reasoningEffort": "low",

250 "description": "Lower latency"254 "description": "Lower latency"

251 }],255 }],

252 "inputModalities": ["text", "image"],256 "inputModalities": ["text", "image"],

259 263

260Each model entry can include:264Each model entry can include:

261 265

262- `reasoningEffort` - supported effort options for the model.266- `supportedReasoningEfforts` - supported effort options for the model.

263- `defaultReasoningEffort` - suggested default effort for clients.267- `defaultReasoningEffort` - suggested default effort for clients.

264- `upgrade` - optional recommended upgrade model id for migration prompts in clients.268- `upgrade` - optional recommended upgrade model id for migration prompts in clients.

269- `upgradeInfo` - optional upgrade metadata for migration prompts in clients.

265- `hidden` - whether the model is hidden from the default picker list.270- `hidden` - whether the model is hidden from the default picker list.

266- `inputModalities` - supported input types for the model (for example `text`, `image`).271- `inputModalities` - supported input types for the model (for example `text`, `image`).

267- `supportsPersonality` - whether the model supports personality-specific instructions such as `/personality`.272- `supportsPersonality` - whether the model supports personality-specific instructions such as `/personality`.

299- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.304- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.

300- `thread/loaded/list` returns the thread IDs currently in memory.305- `thread/loaded/list` returns the thread IDs currently in memory.

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

307- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed`.

302- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.308- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.

303- `thread/compact/start` triggers compaction and returns `{}` immediately.309- `thread/compact/start` triggers compaction and returns `{}` immediately.

304- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.310- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.

313 "cwd": "/Users/me/project",319 "cwd": "/Users/me/project",

314 "approvalPolicy": "never",320 "approvalPolicy": "never",

315 "sandbox": "workspaceWrite",321 "sandbox": "workspaceWrite",

316 "personality": "friendly"322 "personality": "friendly",

323 "serviceName": "my_app_server_client"

317} }324} }

318{ "id": 10, "result": {325{ "id": 10, "result": {

319 "thread": {326 "thread": {

320 "id": "thr_123",327 "id": "thr_123",

321 "preview": "",328 "preview": "",

329 "ephemeral": false,

322 "modelProvider": "openai",330 "modelProvider": "openai",

323 "createdAt": 1730910000331 "createdAt": 1730910000

324 }332 }

326{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }334{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

327```335```

328 336

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

338

329To 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`:339To 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`:

330 340

331```json341```json

333 "threadId": "thr_123",343 "threadId": "thr_123",

334 "personality": "friendly"344 "personality": "friendly"

335} }345} }

336{ "id": 11, "result": { "thread": { "id": "thr_123" } } }346{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

337```347```

338 348

339Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.349Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.

352{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }362{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

353```363```

354 364

365When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.

366

355### Read a stored thread (without resuming)367### Read a stored thread (without resuming)

356 368

357Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.369Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.

358 370

359- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.371- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.

372- Returned `thread` objects include runtime `status` (`notLoaded`, `idle`, `systemError`, or `active` with `activeFlags`).

360 373

361```json374```json

362{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }375{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }

363{ "id": 19, "result": { "thread": { "id": "thr_123", "turns": [] } } }376{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

364```377```

365 378

366Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.379Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.

400} }413} }

401{ "id": 20, "result": {414{ "id": 20, "result": {

402 "data": [415 "data": [

403 { "id": "thr_a", "preview": "Create a TUI", "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111 },416 { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },

404 { "id": "thr_b", "preview": "Fix tests", "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000 }417 { "id": "thr_b", "preview": "Fix tests", "ephemeral": true, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }

405 ],418 ],

406 "nextCursor": "opaque-token-or-null"419 "nextCursor": "opaque-token-or-null"

407} }420} }

409 422

410When `nextCursor` is `null`, you have reached the final page.423When `nextCursor` is `null`, you have reached the final page.

411 424

425### Track thread status changes

426

427`thread/status/changed` is emitted whenever a loaded thread's runtime status changes. The payload includes `threadId` and the new `status`.

428

429```json

430{

431 "method": "thread/status/changed",

432 "params": {

433 "threadId": "thr_123",

434 "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }

435 }

436}

437```

438

412### List loaded threads439### List loaded threads

413 440

414`thread/loaded/list` returns thread IDs currently loaded in memory.441`thread/loaded/list` returns thread IDs currently loaded in memory.

418{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }445{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

419```446```

420 447

448### Unsubscribe from a loaded thread

449

450`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:

451

452- `unsubscribed` when the connection was subscribed and is now removed.

453- `notSubscribed` when the connection was not subscribed to that thread.

454- `notLoaded` when the thread is not loaded.

455

456If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.

457

458```json

459{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }

460{ "id": 22, "result": { "status": "unsubscribed" } }

461{ "method": "thread/status/changed", "params": {

462 "threadId": "thr_123",

463 "status": { "type": "notLoaded" }

464} }

465{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

466```

467

421### Archive a thread468### Archive a thread

422 469

423Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.470Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.

425```json472```json

426{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }473{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }

427{ "id": 22, "result": {} }474{ "id": 22, "result": {} }

475{ "method": "thread/archived", "params": { "threadId": "thr_b" } }

428```476```

429 477

430Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.478Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.

435 483

436```json484```json

437{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }485{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }

438{ "id": 24, "result": { "thread": { "id": "thr_b" } } }486{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }

487{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

439```488```

440 489

441### Trigger thread compaction490### Trigger thread compaction

449{ "id": 25, "result": {} }498{ "id": 25, "result": {} }

450```499```

451 500

501### Roll back recent turns

502

503Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.

504

505```json

506{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }

507{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

508```

509

452## Turns510## Turns

453 511

454The `input` field accepts a list of items:512The `input` field accepts a list of items:

478}536}

479```537```

480 538

539On macOS, `includePlatformDefaults: true` appends a curated platform-default Seatbelt policy for restricted-read sessions. This improves tool compatibility without broadly allowing all of `/System`.

540

481Examples:541Examples:

482 542

483```json543```json

654- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).714- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).

655- When omitted, `timeoutMs` falls back to the server default.715- When omitted, `timeoutMs` falls back to the server default.

656 716

717### Read admin requirements (`configRequirements/read`)

718

719Use `configRequirements/read` to inspect the effective admin requirements loaded from `requirements.toml` and/or MDM.

720

721```json

722{ "method": "configRequirements/read", "id": 52, "params": {} }

723{ "id": 52, "result": {

724 "requirements": {

725 "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],

726 "allowedSandboxModes": ["readOnly", "workspaceWrite"],

727 "featureRequirements": {

728 "personality": true,

729 "unified_exec": false

730 },

731 "network": {

732 "enabled": true,

733 "allowedDomains": ["api.openai.com"],

734 "allowUnixSockets": ["/tmp/example.sock"],

735 "dangerouslyAllowAllUnixSockets": false

736 }

737 }

738} }

739```

740

741`result.requirements` is `null` when no requirements are configured. See the docs on [`requirements.toml`](https://developers.openai.com/codex/config-reference#requirementstoml) for details on supported keys and values.

742

743### Windows sandbox setup (`windowsSandbox/setupStart`)

744

745Custom Windows clients can trigger sandbox setup asynchronously instead of blocking on startup checks.

746

747```json

748{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }

749{ "id": 53, "result": { "started": true } }

750```

751

752App-server starts setup in the background and later emits a completion notification:

753

754```json

755{

756 "method": "windowsSandbox/setupCompleted",

757 "params": { "mode": "elevated", "success": true, "error": null }

758}

759```

760

761Modes:

762

763- `elevated` - run the elevated Windows sandbox setup path.

764- `unelevated` - run the legacy setup/preflight path.

765

657## Events766## Events

658 767

659Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `turn/*`, and `item/*` notifications.768Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `thread/status/changed`, `turn/*`, `item/*`, and `serverRequest/resolved` notifications.

660 769

661### Notification opt-out770### Notification opt-out

662 771

674- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.783- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.

675- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.784- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.

676 785

786### Windows sandbox setup events

787

788- `windowsSandbox/setupCompleted` - `{ mode, success, error }` emitted after a `windowsSandbox/setupStart` request finishes.

789

677### Turn events790### Turn events

678 791

679- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.792- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.

689`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:802`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:

690 803

691- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).804- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).

692- `agentMessage` - `{id, text}` containing the accumulated agent reply.805- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).

693- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.806- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.

694- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.807- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.

695- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.808- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.

696- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.809- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.

697- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.810- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.

811- `dynamicToolCall` - `{id, tool, arguments, status, contentItems?, success?, durationMs?}` for client-executed dynamic tool invocations.

698- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.812- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.

699- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.813- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.

700- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.814- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.

751Order of messages:865Order of messages:

752 866

7531. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.8671. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.

7542. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, and optional `proposedExecpolicyAmendment`.8682. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, optional `networkApprovalContext`, and optional `availableDecisions`. When `initialize.params.capabilities.experimentalApi = true`, the payload can also include experimental `additionalPermissions` describing requested per-command sandbox access. Any filesystem paths inside `additionalPermissions` are absolute on the wire.

7553. Client responds with one of the command execution approval decisions above.8693. Client responds with one of the command execution approval decisions above.

7564. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.8704. `serverRequest/resolved` confirms that the pending request has been answered or cleared.

8715. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.

872

873When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.

874

875Codex groups concurrent network approval prompts by destination (`host`, protocol, and port). The app-server may therefore send one prompt that unblocks multiple queued requests to the same destination, while different ports on the same host are treated separately.

757 876

758### File change approvals877### File change approvals

759 878

7621. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.8811. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.

7632. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.8822. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.

7643. Client responds with one of the file change approval decisions above.8833. Client responds with one of the file change approval decisions above.

7654. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.8844. `serverRequest/resolved` confirms that the pending request has been answered or cleared.

8855. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.

886

887### `tool/requestUserInput`

888

889When the client responds to `item/tool/requestUserInput`, app-server emits `serverRequest/resolved` with `{ threadId, requestId }`. If the pending request is cleared by turn start, turn completion, or turn interruption before the client answers, the server emits the same notification for that cleanup.

890

891### Dynamic tool calls (experimental)

892

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

894

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

896

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

8982. `item/tool/call` as a server request to the client.

8993. The client response payload with returned content items.

9004. `item/completed` with `item.type = "dynamicToolCall"`, the final `status`, and any returned `contentItems` or `success` value.

766 901

767### MCP tool-call approvals (apps)902### MCP tool-call approvals (apps)

768 903

769App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.904App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. Destructive tool annotations always trigger approval even when the tool also advertises less-privileged hints. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.

770 905

771## Skills906## Skills

772 907

863 998

864## Apps (connectors)999## Apps (connectors)

865 1000

866Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state.1001Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state. App entries can also include optional `branding`, `appMetadata`, and `labels` fields.

867 1002

868```json1003```json

869{ "method": "app/list", "id": 50, "params": {1004{ "method": "app/list", "id": 50, "params": {

879 "name": "Demo App",1014 "name": "Demo App",

880 "description": "Example connector for documentation.",1015 "description": "Example connector for documentation.",

881 "logoUrl": "https://example.com/demo-app.png",1016 "logoUrl": "https://example.com/demo-app.png",

1017 "logoUrlDark": null,

1018 "distributionChannel": null,

1019 "branding": null,

1020 "appMetadata": null,

1021 "labels": null,

882 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",1022 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

883 "isAccessible": true,1023 "isAccessible": true,

884 "isEnabled": true1024 "isEnabled": true

904 "name": "Demo App",1044 "name": "Demo App",

905 "description": "Example connector for documentation.",1045 "description": "Example connector for documentation.",

906 "logoUrl": "https://example.com/demo-app.png",1046 "logoUrl": "https://example.com/demo-app.png",

1047 "logoUrlDark": null,

1048 "distributionChannel": null,

1049 "branding": null,

1050 "appMetadata": null,

1051 "labels": null,

907 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",1052 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

908 "isAccessible": true,1053 "isAccessible": true,

909 "isEnabled": true1054 "isEnabled": true

936}1081}

937```1082```

938 1083

1084### Config RPC examples for app settings

1085

1086Use `config/read`, `config/value/write`, and `config/batchWrite` to inspect or update app controls in `config.toml`.

1087

1088Read the effective app config shape (including `_default` and per-tool overrides):

1089

1090```json

1091{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }

1092{ "id": 60, "result": {

1093 "config": {

1094 "apps": {

1095 "_default": {

1096 "enabled": true,

1097 "destructive_enabled": true,

1098 "open_world_enabled": true

1099 },

1100 "google_drive": {

1101 "enabled": true,

1102 "destructive_enabled": false,

1103 "default_tools_approval_mode": "prompt",

1104 "tools": {

1105 "files/delete": { "enabled": false, "approval_mode": "approve" }

1106 }

1107 }

1108 }

1109 }

1110} }

1111```

1112

1113Update a single app setting:

1114

1115```json

1116{

1117 "method": "config/value/write",

1118 "id": 61,

1119 "params": {

1120 "keyPath": "apps.google_drive.default_tools_approval_mode",

1121 "value": "prompt",

1122 "mergeStrategy": "replace"

1123 }

1124}

1125```

1126

1127Apply multiple app edits atomically:

1128

1129```json

1130{

1131 "method": "config/batchWrite",

1132 "id": 62,

1133 "params": {

1134 "edits": [

1135 {

1136 "keyPath": "apps._default.destructive_enabled",

1137 "value": false,

1138 "mergeStrategy": "upsert"

1139 },

1140 {

1141 "keyPath": "apps.google_drive.tools.files/delete.approval_mode",

1142 "value": "approve",

1143 "mergeStrategy": "upsert"

1144 }

1145 ]

1146 }

1147}

1148```

1149

1150### Detect and import external agent config

1151

1152Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.

1153

1154Detection example:

1155

1156```json

1157{ "method": "externalAgentConfig/detect", "id": 63, "params": {

1158 "includeHome": true,

1159 "cwds": ["/Users/me/project"]

1160} }

1161{ "id": 63, "result": {

1162 "items": [

1163 {

1164 "itemType": "AGENTS_MD",

1165 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",

1166 "cwd": "/Users/me/project"

1167 },

1168 {

1169 "itemType": "SKILLS",

1170 "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",

1171 "cwd": null

1172 }

1173 ]

1174} }

1175```

1176

1177Import example:

1178

1179```json

1180{ "method": "externalAgentConfig/import", "id": 64, "params": {

1181 "migrationItems": [

1182 {

1183 "itemType": "AGENTS_MD",

1184 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",

1185 "cwd": "/Users/me/project"

1186 }

1187 ]

1188} }

1189{ "id": 64, "result": {} }

1190```

1191

1192Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports do not overwrite existing skill directories.

1193

939## Auth endpoints1194## Auth endpoints

940 1195

941The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.1196The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.

app/automations.md +24 −13

Details

2 2

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

4 4

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

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

7 7

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

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

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

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

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

11project directory.13project directory.

12 14

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

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

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

14 19

15## Managing tasks20## Managing tasks

16 21

18 23

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

20 25

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

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

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

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

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

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

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

22 33

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

24 35

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

31 42

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

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

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

35 46

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

38 49

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

40 51

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

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

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

44 55

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

46 57

62 73

63If you are in a managed environment, admins can restrict these behaviors using74If you are in a managed environment, admins can restrict these behaviors using

64admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See75admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See

~~65[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~76[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

66 77

67Automations use `approval_policy = "never"` when your organization policy78Automations use `approval_policy = "never"` when your organization policy

68allows it. If `approval_policy = "never"` is disallowed by admin requirements,79allows it. If `approval_policy = "never"` is disallowed by admin requirements,

app/commands.md +18 −0

Details

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

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

50 50

51## Deeplinks

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

55| Deeplink | Opens | Supported query parameters |

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

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

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

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

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

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

63For new-thread deeplinks:

65- `prompt` prefills the composer.

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

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

51## See also69## See also

52 70

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

app/features.md +18 −4

Details

14session in a specific directory.14session in a specific directory.

15 15

16If you work in a single repository with two or more apps or packages, split16If you work in a single repository with two or more apps or packages, split

~~17distinct projects into separate app projects so the [sandbox](https://developers.openai.com/codex/security)~~17distinct projects into separate app projects so the [sandbox](https://developers.openai.com/codex/agent-approvals-security)

18only includes the files for that project.18only includes the files for that project.

19 19

20![Codex app showing multiple projects in the sidebar and threads in the main pane](/images/codex/app/multitask-light.webp)20![Codex app showing multiple projects in the sidebar and threads in the main pane](/images/codex/app/multitask-light.webp)

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

86 86

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

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

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

90failed build while it works with you.

89 91

90Common tasks include:92Common tasks include:

91 93

101 103

102![Integrated terminal drawer open beneath a Codex thread](/images/codex/app/integrated-terminal-light.webp)104![Integrated terminal drawer open beneath a Codex thread](/images/codex/app/integrated-terminal-light.webp)

103 105

106## Native Windows sandbox

107

108On Windows, Codex can run natively in PowerShell with a native Windows sandbox

109instead of requiring WSL or a virtual machine. This lets you stay in

110Windows-native workflows while keeping bounded permissions in place.

111

112[Learn more about Windows setup and sandboxing](https://developers.openai.com/codex/app/windows).

113

114![Codex app Windows sandbox setup prompt above the message composer](/images/codex/windows/windows-sandbox-setup.webp)

115

104## Voice dictation116## Voice dictation

105 117

106Use your voice to prompt Codex. Hold <kbd>Ctrl</kbd>+<kbd>M</kbd> while the composer is visible and start talking. Your voice will be transcribed. Edit the transcribed prompt or hit send to have Codex start work.118Use your voice to prompt Codex. Hold <kbd>Ctrl</kbd>+<kbd>M</kbd> while the composer is visible and start talking. Your voice will be transcribed. Edit the transcribed prompt or hit send to have Codex start work.

152opening separate projects or using worktrees rather than asking Codex to roam164opening separate projects or using worktrees rather than asking Codex to roam

153outside the project root.165outside the project root.

154 166

155For details on how Codex handles sandboxing, check out the [security documentation](https://developers.openai.com/codex/security).167For a high-level overview, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For

168configuration details, see the

169[agent approvals & security documentation](https://developers.openai.com/codex/agent-approvals-security).

156 170

157## MCP support171## MCP support

158 172

165 179

166Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex180Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex

167enables web search by default and serves results from a web search cache. If you configure your181enables web search by default and serves results from a web search cache. If you configure your

168sandbox for [full access](https://developers.openai.com/codex/security), web search defaults to live results. See182sandbox for [full access](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. See

169[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the183[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the

170most recent data.184most recent data.

171 185

app/settings.md +9 −6

Details

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

11thread runs.11thread runs.

12 12

~~13## Appearance~~

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

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

18## Notifications13## Notifications

19 14

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

24 19

25Codex agents in the app inherit the same configuration as the IDE and CLI extension.20Codex agents in the app inherit the same configuration as the IDE and CLI extension.

26Use the in-app controls for common settings, or edit `config.toml` for advanced21Use the in-app controls for common settings, or edit `config.toml` for advanced

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

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

29 24

25## Appearance

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

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

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

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

30## Git33## Git

31 34

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

app/troubleshooting.md +4 −2

Details

32### Only some threads appear in the sidebar32### Only some threads appear in the sidebar

33 33

34The sidebar allows filtering of threads depending on the state of a project. If34The sidebar allows filtering of threads depending on the state of a project. If

~~35you’re missing threads, check whether you have any filters applied by clicking~~35you're missing threads, click the filter icon next to the **Threads** label and

~~36the filter icon next to the **Threads** label.~~36switch to Chronological. If you still don't see the thread, open

37[Settings](codex://settings) and check the archived chats or archived threads

38section.

37 39

38### Code doesn't run on a worktree40### Code doesn't run on a worktree

39 41

app/windows.md +214 −0 added

Details

1# Windows

3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl).

9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

11## Download and update the Codex app

13Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).

16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

18To update the app, open the Microsoft Store, go to **Downloads**, and click

19**Check for updates**. The Store installs the latest version afterward.

21For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.

24If you prefer a command-line install path, or need an alternative to opening

25the Microsoft Store UI, run:

27```powershell

28winget install Codex -s msstore

29```

31## Native sandbox

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

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

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

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

38 targeted exceptions, or set your [approval policy to

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

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

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

43## Customize for your dev setup

45### Preferred editor

47Choose a default app for **Open**, such as Visual Studio, VS Code, or another

48editor. You can override that choice per project. If you already picked a

49different app from the **Open** menu for a project, that project-specific

50choice takes precedence.

52![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)

54### Integrated terminal

56You can also choose the default integrated terminal. Depending on what you have

57installed, options include:

59- PowerShell

60- Command Prompt

61- Git Bash

62- WSL

64This change applies only to new terminal sessions. If you already have an

65integrated terminal open, restart the app or start a new thread before

66expecting the new default terminal to appear.

68![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)

70## Windows Subsystem for Linux (WSL)

72By default, the Codex app uses the Windows-native agent. That means the agent

73runs commands in PowerShell. The app can still work with projects that live in

74Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.

76If you want to add a project from the WSL filesystem, click **Add new project**

77or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

78Explorer window. From there, choose your Linux distribution and the folder you

79want to open.

81If you plan to keep using the Windows-native agent, prefer storing projects on

82your Windows filesystem and accessing them from WSL through

83`/mnt/<drive>/...`. This setup is more reliable than opening projects

84directly from the WSL filesystem.

86If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,

87switch the agent from Windows native to WSL, and **restart the app**. The

88change doesn't take effect until you restart. Your projects should remain in

89place after restart.

91![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

93You configure the integrated terminal independently from the agent. See

94[Customize for your dev setup](#customize-for-your-dev-setup) for the

95terminal options. You can keep the agent in WSL and still use PowerShell in the

96terminal, or use WSL for both, depending on your workflow.

98## Useful developer tools

100Codex works best when a few common developer tools are already installed:

101

102- **Git**: Powers the review panel in the Codex app and lets you inspect or

103 revert changes.

104- **Node.js**: A common tool that the agent uses to perform tasks more

105 efficiently.

106- **Python**: A common tool that the agent uses to perform tasks more

107 efficiently.

108- **.NET SDK**: Useful when you want to build native Windows apps.

109- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.

110

111Install them with the default Windows package manager `winget` by pasting this

112into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or

113asking Codex to install them:

114

115```powershell

116winget install --id Git.Git

117winget install --id OpenJS.NodeJS.LTS

118winget install --id Python.Python.3.14

119winget install --id Microsoft.DotNet.SDK.10

120winget install --id GitHub.cli

121```

122

123After installing GitHub CLI, run `gh auth login` to enable GitHub features in

124the app.

125

126If you need a different Python or .NET version, change the package IDs to the

127version you want.

128

129## Troubleshooting and FAQ

130

131### Run commands with elevated permissions

132

133If you need Codex to run commands with elevated permissions, start the Codex app

134itself as an administrator. After installation, open the Start menu, find

135Codex, and choose Run as administrator. The Codex agent inherits that

136permission level.

137

138### PowerShell execution policy blocks commands

139

140If you have never used tools such as Node.js or `npm` in PowerShell before, the

141Codex agent or integrated terminal may hit execution policy errors.

142

143This can also happen if Codex creates PowerShell scripts for you. In that case,

144you may need a less restrictive execution policy before PowerShell will run

145them.

146

147An error may look something like this:

148

149```text

150npm.ps1 cannot be loaded because running scripts is disabled on this system.

151```

152

153A common fix is to set the execution policy to `RemoteSigned`:

154

155```powershell

156Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

157```

158

159For details and other options, check Microsoft's

160[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)

161before changing the policy.

162

163### Local environment scripts on Windows

164

165If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform

166commands such as `npm` scripts, you can keep one shared setup script or

167set of actions for every platform.

168

169If you need Windows-specific behavior, create Windows-specific setup scripts or

170Windows-specific actions.

171

172Actions run in the environment used by your integrated terminal. See

173[Customize for your dev setup](#customize-for-your-dev-setup).

174

175Local setup scripts run in the agent environment: WSL if the agent uses WSL,

176and PowerShell otherwise.

177

178### Share config, auth, and sessions with WSL

179

180The Windows app uses the same Codex home directory as native Codex on Windows:

181`%USERPROFILE%\.codex`.

182

183If you also run the Codex CLI inside WSL, the CLI uses the Linux home

184directory by default, so it does not automatically share configuration, cached

185auth, or session history with the Windows app.

186

187To share them, use one of these approaches:

188

189- Sync WSL `~/.codex` with `%USERPROFILE%\.codex` on your file system.

190- Point WSL at the Windows Codex home directory by setting `CODEX_HOME`:

191

192```bash

193export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

194```

195

196If you want that setting in every shell, add it to your WSL shell profile, such

197as `~/.bashrc` or `~/.zshrc`.

198

199### Git features are unavailable

200

201If you don't have Git installed natively on Windows, the app can't use some

202features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.

203

204### Git isn't detected for projects opened from `\\wsl$`

205

206For now, if you want to use the Windows-native agent with a project that is

207also accessible from WSL, the most reliable workaround is to store the project

208on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.

209

210### Cmder is not listed in the open dialog

211

212If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the

213Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart

214Codex or reboot.

app/worktrees.md +45 −43

Details

1# Worktrees1# Worktrees

2 2

3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don’t conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually.3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually, and use Handoff to move a thread between Local and Worktree.

4 4

5## What's a worktree5## What's a worktree

6 6

10 10

11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.

12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.

13- **Handoff**: The flow that moves a thread between Local and Worktree. Codex handles the Git operations required to move your work safely between them.

13 14

14## Why use a worktree15## Why use a worktree

15 16

~~161. Work in parallel with Codex without breaking each other as you work.~~171. Work in parallel with Codex without disturbing your current Local setup.

~~172. Start a thread unrelated to your current work~~182. Queue up background work while you stay focused on the foreground.

~~18 - Staging area to queue up work you want Codex to start but aren’t ready to test yet.~~193. Move a thread into Local later when you're ready to inspect, test, or collaborate more directly.

19 20

20## Getting started21## Getting started

21 22

313. Submit your prompt323. Submit your prompt

32 33

33 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a ["detached HEAD"](https://git-scm.com/docs/git-checkout#_detached_head).34 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a ["detached HEAD"](https://git-scm.com/docs/git-checkout#_detached_head).

~~344. Verify your changes~~354. Choose where to keep working

35 36

~~36 When you’re ready, follow one of the paths [below](#verifying-and-pushing-workflow-changes)~~37 When you’re ready, you can either keep working directly on the worktree or hand the thread off to your local checkout. Handing off to or from local will move your thread *and* code so you can continue in the other checkout.

~~37 based on your project and flow.~~

38 38

~~39## Verifying and pushing workflow changes~~39## Working between Local and Worktree

40 40

41Worktrees look and feel much like your local checkout. But **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can’t** check it out in your local checkout at the same time, and vice versa.41Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a thread between them.

42 42

~~43Because of this, choose how you want to verify and commit changes Codex made on a worktree:~~43Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.

45In practice, there are two common paths:

44 46

451. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).471. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).

462. [Work in your local checkout](#option-2-working-in-your-local-checkout). Use this when you need to bring changes back into your main checkout, for example because you can run only one instance of your app.482. [Hand the thread off to Local](#option-2-handing-a-thread-off-to-local). Use this when you want to bring the thread into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.

47 49

48### Option 1: Working on the worktree50### Option 1: Working on the worktree

49 51

57 59

58Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.60Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.

59 61

~~60If you plan to keep working on this branch, you can [add it to the sidebar](#adding-a-worktree-to-the-sidebar). Otherwise, archive the thread after you’re done so the worktree can be deleted.~~62### Option 2: Handing a thread off to Local

~~62### Option 2: Working in your local checkout~~

63 63

~~64If you don’t want to verify your changes directly on the worktree and instead check them out on your local checkout, click **Sync with local** in the header of your thread.~~64If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.

65 65

~~66You will be presented with the option of creating a new branch or syncing to an existing branch.~~66This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.

67 67

~~68You can sync with local at any point. To do so, click **Sync with local** in the header again. From here, you can choose which direction to sync (to local or from local) and a sync method:~~68Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

69 69

~~70- **Overwrite**: Makes the destination checkout match the source checkout’s files and commit history.~~70Each thread keeps the same associated worktree over time. If you hand the thread back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.

71- **Apply**: Calculates the source changes since the nearest shared commit and applies that patch onto the destination checkout, preserving destination commit history while bringing over source code changes (not source commits).

72 71

~~73![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-light.webp)~~72![Handoff dialog moving a thread from a worktree to Local](/images/codex/app/handoff-light.webp)

74 73

~~75You can create multiple worktrees and sync them to the same feature branch to split up your work into parallel threads.~~74You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the thread to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.

76 75

77In some cases, changes on your worktree might conflict with changes on your local checkout, for example from testing a previous worktree. In those cases, you can use the **Overwrite local** option to reset the previous changes and cleanly apply your worktree changes.76Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the thread.

78 77

~~79Since this process uses Git operations, any files that are part of the `.gitignore` file won’t be transferred during the sync process.~~78## Advanced details

80 79

~~81## Adding a worktree to the sidebar~~80### Codex-managed and permanent worktrees

82 81

83If you choose option one above (work on the worktree), once you have created a branch on the worktree, an option appears in the header to add the worktree to your sidebar. This promotes the worktree to a permanent home. When you do this, it will never be automatically deleted, and you can even kick off new threads from the same worktree.82By default, threads use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one thread, and Codex returns that thread to the same worktree if you hand it back there later.

84 83

~~85## Advanced details~~84If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees are not automatically deleted, and you can start multiple threads from the same worktree.

86 85

87### How Codex manages worktrees for you86### How Codex manages worktrees for you

88 87

89Codex will create a worktree in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will *not* be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This means you can create several worktrees without polluting your branches.88Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will *not* be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.

90 89

91### Branch limitations90### Branch limitations

92 91

98 97

99To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.98To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.

100 99

101If you plan on checking out the branch locally, try Workflow 2 ([sync with local](#option-2-working-in-your-local-checkout)).100If you plan on checking out the branch locally, use Handoff to move the thread into Local instead of trying to keep the same branch checked out in both places at once.

102 101

103Why this limitation exists102Why this limitation exists

104 103

112 111

113Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.112Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.

114 113

115Worktrees will never be cleaned up if:114By default, Codex keeps your most recent 15 Codex-managed worktrees. You can change this limit or turn off automatic deletion in settings if you prefer to manage disk usage yourself.

116 115

117- A pinned conversation is tied to it116Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:

118- The worktree was added to the sidebar (see above)

119 117

120Worktrees are eligible for cleanup when:118- A pinned conversation is tied to it

119- The thread is still in progress

120- The worktree is a permanent worktree

121 121

122- It’s more than 4 days old122Codex-managed worktrees are deleted automatically when:

123- You have more than 10 worktrees

124 123

125When either of those conditions are met, Codex automatically cleans up a worktree when you archive a thread, or on app startup if it finds a worktree with no associated threads.124- You archive the associated thread

125- Codex needs to delete older worktrees to stay within your configured limit

126 126

127Before cleaning up a worktree, Codex will save a snapshot of the work on it that you can restore at any point in a new worktree. If you open a conversation after its worktree was cleaned up, you’ll see the option to restore it.127Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you'll see the option to restore it.

128 128

129## Frequently asked questions129## Frequently asked questions

130 130

133 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can133 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can

134 manage them consistently.134 manage them consistently.

135 135

136Can I move a session between worktrees?136Can I move a thread between Local and Worktree?

137 137

138Not yet. If you need to change environments, you have to start a new thread in138 Yes. Use **Hand off** in the thread header to move a thread between your local

139the target environment and restate the prompt. You can use the up arrow keys139 checkout and a worktree. Codex handles the Git operations needed to move the

140in the composer to try to recover your prompt.140 thread safely between environments. If you hand a thread back to a worktree

141 later, Codex returns it to the same associated worktree.

141 142

142What happens to threads if a worktree is deleted?143What happens to threads if a worktree is deleted?

143 144

144 Threads can remain in your history even if the underlying worktree directory145 Threads can remain in your history even if the underlying worktree directory

145is cleaned up. However, Codex saves a snapshot of the worktree prior to146 is deleted. For Codex-managed worktrees, Codex saves a snapshot before

146cleaning it up and offers to restore it if you reopen the thread associated147 deleting the worktree and offers to restore it if you reopen the associated

147with it.148 thread. Permanent worktrees are not automatically deleted when you archive

149 their threads.

auth.md +22 −1

Details

9 9

10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.

11 11

12Your sign-in method also determines which admin controls and data-handling policies apply.

14- With sign in with ChatGPT, Codex usage follows your ChatGPT workspace permissions, RBAC, and ChatGPT Enterprise retention and residency settings

15- With an API key, usage follows your API organization's retention and data-sharing settings instead

17For the CLI, Sign in with ChatGPT is the default authentication path when no valid session is available.

12### Sign in with ChatGPT19### Sign in with ChatGPT

13 20

14When 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.

19 26

20OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).

21 28

29Features that rely on ChatGPT credits, such as [fast mode](https://developers.openai.com/codex/speed), are

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

31Codex uses standard API pricing instead.

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.

22## Secure your Codex cloud account35## Secure your Codex cloud account

23 36

24Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).37Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).

43 56

44Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.57Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.

45 58

59For sign in with ChatGPT sessions, Codex refreshes tokens automatically during use before they expire, so active sessions usually continue without requiring another browser login.

46## Credential storage61## Credential storage

47 62

48Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:63Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:

74 89

75If the active credentials don't match the configured restrictions, Codex logs the user out and exits.90If the active credentials don't match the configured restrictions, Codex logs the user out and exits.

76 91

~~77These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/security#managed-configuration).~~92These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

78 93

79## Login on headless devices94## Login on headless devices

80 95

130docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"145docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

131```146```

132 147

148For a more advanced version of this same pattern on trusted CI/CD runners, see

149[Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).

150That guide explains how to let Codex refresh `auth.json` during normal runs and

151then keep the updated file for the next job. API keys are still the recommended

152default for automation.

153

133### Fallback: Forward the localhost callback over SSH154### Fallback: Forward the localhost callback over SSH

134 155

135If you can forward ports between your local machine and the remote host, you can use the standard browser-based flow by tunneling Codex's local callback server (default `localhost:1455`).156If you can forward ports between your local machine and the remote host, you can use the standard browser-based flow by tunneling Codex's local callback server (default `localhost:1455`).

auth/ci-cd-auth.md +277 −0 added

Details

1# Maintain Codex account auth in CI/CD (advanced)

3This guide shows how to keep ChatGPT-managed Codex auth working on a trusted

4CI/CD runner without calling the OAuth token endpoint yourself.

6The right way to authenticate automation is with an API key. Use this guide

7only if you specifically need to run the workflow as your Codex account.

9The pattern is:

111. Create `auth.json` once on a trusted machine with `codex login`.

122. Put that file on the runner.

133. Run Codex normally.

144. Let Codex refresh the session when it becomes stale.

155. Keep the refreshed `auth.json` for the next run.

17This is an advanced workflow for enterprise and other trusted private

18automation. API keys are still the recommended option for most CI/CD jobs.

20Treat `~/.codex/auth.json` like a password: it contains access tokens. Don't

21 commit it, paste it into tickets, or share it in chat. Do not use this

22 workflow for public or open-source repositories.

24## Why this works

26Codex already knows how to refresh a ChatGPT-managed session.

28As of the current open-source client:

30- Codex loads the local auth cache from `auth.json`

31- if `last_refresh` is older than about 8 days, Codex refreshes the token

32 bundle before the run continues

33- after a successful refresh, Codex writes the new tokens and a new

34 `last_refresh` back to `auth.json`

35- if a request gets a `401`, Codex also has a built-in refresh-and-retry path

37That means the supported CI/CD strategy is not "call the refresh API yourself."

38It is "run Codex and persist the updated `auth.json`."

40## When to use this

42Use this guide only when all of the following are true:

44- you need ChatGPT-managed Codex auth rather than an API key

45- `codex login` cannot run on the remote runner

46- the runner is trusted private infrastructure

47- you can preserve the refreshed `auth.json` between runs

48- only one machine or serialized job stream will use a given `auth.json` copy

50This guide applies to Codex-managed ChatGPT auth (`auth_mode: "chatgpt"`).

52It does not apply to:

54- API key auth

55- external-token host integrations (`auth_mode: "chatgptAuthTokens"`)

56- generic OAuth clients outside Codex

58If your credentials are stored in the OS keyring, switch to file-backed storage

59first. See [Credential storage](https://developers.openai.com/codex/auth#credential-storage).

61## Seed `auth.json` once

63On a trusted machine where browser login is possible:

651. Configure Codex to store credentials in a file:

67```toml

68cli_auth_credentials_store = "file"

69```

712. Run:

73```bash

74codex login

75```

773. Verify the file looks like managed ChatGPT auth:

79```bash

80AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

82jq '{

83 auth_mode,

84 has_tokens: (.tokens != null),

85 has_refresh_token: ((.tokens.refresh_token // "") != ""),

86 last_refresh

87}' "$AUTH_FILE"

88```

90Continue only if:

92- `auth_mode` is `"chatgpt"`

93- `has_refresh_token` is `true`

95Then place the contents of `auth.json` into your CI/CD secret manager or copy

96it to a trusted persistent runner.

98## Recommended pattern: GitHub Actions on a self-hosted runner

100The simplest fully automated setup is a self-hosted GitHub Actions runner with a

101persistent `CODEX_HOME`.

102

103Why this pattern works well:

104

105- the runner can keep `auth.json` on disk between jobs

106- Codex can refresh the file in place

107- later jobs automatically pick up the refreshed tokens

108- you only need the original secret for bootstrap or reseeding

109

110The critical detail is to seed `auth.json` only if it is missing. If you

111rewrite the file from the original secret on every run, you throw away the

112refreshed tokens that Codex just wrote.

113

114Example scheduled workflow:

115

116```yaml

117name: Keep Codex auth fresh

118

119on:

120 schedule:

121 - cron: "0 9 * * 1"

122 workflow_dispatch:

123

124jobs:

125 keep-codex-auth-fresh:

126 runs-on: self-hosted

127 steps:

128 - name: Bootstrap auth.json if needed

129 shell: bash

130 env:

131 CODEX_AUTH_JSON: ${{ secrets.CODEX_AUTH_JSON }}

132 run: |

133 export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

134 mkdir -p "$CODEX_HOME"

135 chmod 700 "$CODEX_HOME"

136

137 if [ ! -f "$CODEX_HOME/auth.json" ]; then

138 printf '%s' "$CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"

139 chmod 600 "$CODEX_HOME/auth.json"

140 fi

141

142 - name: Run Codex

143 shell: bash

144 run: |

145 codex exec --json "Reply with the single word OK." >/dev/null

146```

147

148What this does:

149

150- the first run seeds `auth.json`

151- later runs reuse the same file

152- once the cached session is old enough, Codex refreshes it during the normal

153 `codex exec` step

154- the refreshed file remains on disk for the next workflow run

155

156A weekly schedule is usually enough because Codex treats the session as stale

157after roughly 8 days in the current open-source client.

158

159## Ephemeral runners: restore, run Codex, persist the updated file

160

161If you use GitHub-hosted runners, GitLab shared runners, or any other ephemeral

162environment, the runner filesystem disappears after each job. In that setup,

163you need a round-trip:

164

1651. restore the current `auth.json` from secure storage

1662. run Codex

1673. write the updated `auth.json` back to secure storage

168

169Generic GitHub Actions shape:

170

171```yaml

172name: Run Codex with managed auth

173

174on:

175 workflow_dispatch:

176

177jobs:

178 codex-job:

179 runs-on: ubuntu-latest

180 steps:

181 - name: Restore auth.json

182 shell: bash

183 run: |

184 export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

185 mkdir -p "$CODEX_HOME"

186 chmod 700 "$CODEX_HOME"

187

188 # Replace this with your secret manager or secure storage command.

189 my-secret-cli read codex-auth-json > "$CODEX_HOME/auth.json"

190 chmod 600 "$CODEX_HOME/auth.json"

191

192 - name: Run Codex

193 shell: bash

194 run: |

195 codex exec --json "summarize the failing tests"

196

197 - name: Persist refreshed auth.json

198 if: always()

199 shell: bash

200 run: |

201 # Replace this with your secret manager or secure storage command.

202 my-secret-cli write codex-auth-json < "$CODEX_HOME/auth.json"

203```

204

205The key requirement is that the write-back step stores the refreshed file that

206Codex produced during the run, not the original seed.

207

208## You do not need a separate refresh command

209

210Any normal Codex run can refresh the session.

211

212That means you have two good options:

213

214- let your existing CI/CD Codex job refresh the file naturally

215- add a lightweight scheduled maintenance job, like the GitHub Actions example

216 above, if your real jobs do not run often enough

217

218The first Codex run after the session becomes stale is the one that refreshes

219`auth.json`.

220

221## Operational rules that matter

222

223- Use one `auth.json` per runner or per serialized workflow stream.

224- Do not share the same file across concurrent jobs or multiple machines.

225- Do not overwrite a persistent runner's refreshed file from the original seed

226 on every run.

227- Do not store `auth.json` in the repository, logs, or public artifact storage.

228- Reseed from a trusted machine if built-in refresh stops working.

229

230## What to do when refresh stops working

231

232This flow reduces manual work, but it does not guarantee the same session lasts

233forever.

234

235Reseed the runner with a fresh `auth.json` if:

236

237- Codex starts returning `401` and the runner can no longer refresh

238- the refresh token was revoked or expired

239- another machine or concurrent job rotated the token first

240- your secure-storage round trip failed and an old file was restored

241

242To reseed:

243

2441. Run `codex login` on a trusted machine.

2452. Replace the stored CI/CD copy of `auth.json`.

2463. Let the next runner job continue using Codex's built-in refresh flow.

247

248## Verify that the runner is maintaining the session

249

250Check that the runner still has managed auth tokens and that `last_refresh`

251exists:

252

253```bash

254AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

255

256jq '{

257 auth_mode,

258 last_refresh,

259 has_access_token: ((.tokens.access_token // "") != ""),

260 has_id_token: ((.tokens.id_token // "") != ""),

261 has_refresh_token: ((.tokens.refresh_token // "") != "")

262}' "$AUTH_FILE"

263```

264

265If your runner is persistent, you should see the same file continue to exist

266between runs. If your runner is ephemeral, confirm that your write-back step is

267storing the updated file from the last job.

268

269## Source references

270

271If you want to verify this behavior in the open-source client:

272

273- [`codex-rs/core/src/auth.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/auth.rs)

274 covers stale-token detection, automatic refresh, refresh-on-401 recovery, and

275 persistence of refreshed tokens

276- [`codex-rs/core/src/auth/storage.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/auth/storage.rs)

277 covers file-backed `auth.json` storage

cli.md +6 −4

Details

3Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected directory.3Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected directory.

4It's [open source](https://github.com/openai/codex) and built in Rust for speed and efficiency.4It's [open source](https://github.com/openai/codex) and built in Rust for speed and efficiency.

5 5

~~6Codex is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans. Learn more about [what’s included](https://developers.openai.com/codex/pricing).~~6ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).

7 7

8## CLI setup8## CLI setup

9 9

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

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

49 49

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

50---52---

51 53

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

55 57

56Run `codex` to start an interactive terminal UI (TUI) session.](https://developers.openai.com/codex/cli/features#running-in-interactive-mode)[### Control model and reasoning58Run `codex` to start an interactive terminal UI (TUI) session.](https://developers.openai.com/codex/cli/features#running-in-interactive-mode)[### Control model and reasoning

57 59

~~58Use `/model` to switch between GPT-5.3-Codex and other available models, or adjust reasoning levels.](https://developers.openai.com/codex/cli/features#models-reasoning)[### Image inputs~~60Use `/model` to switch between GPT-5.4, GPT-5.3-Codex, and other available models, or adjust reasoning levels.](https://developers.openai.com/codex/cli/features#models-reasoning)[### Image inputs

59 61

60Attach screenshots or design specs so Codex reads them alongside your prompt.](https://developers.openai.com/codex/cli/features#image-inputs)[### Run local code review62Attach screenshots or design specs so Codex reads them alongside your prompt.](https://developers.openai.com/codex/cli/features#image-inputs)[### Run local code review

61 63

~~62Get your code reviewed by a separate Codex agent before you commit or push your changes.](https://developers.openai.com/codex/cli/features#running-local-code-review)[### Use multi-agent~~64Get your code reviewed by a separate Codex agent before you commit or push your changes.](https://developers.openai.com/codex/cli/features#running-local-code-review)[### Use subagents

63 65

~~64Enable experimental multi-agent collaboration and parallelize complex tasks.](https://developers.openai.com/codex/multi-agent)[### Web search~~66Use subagents to parallelize complex tasks.](https://developers.openai.com/codex/subagents)[### Web search

65 67

66Use Codex to search the web and get up-to-date information for your task.](https://developers.openai.com/codex/cli/features#web-search)[### Codex Cloud tasks68Use Codex to search the web and get up-to-date information for your task.](https://developers.openai.com/codex/cli/features#web-search)[### Codex Cloud tasks

67 69

cli/features.md +19 −6

Details

20 20

21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.

24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.

25- Use `/copy` to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.

23- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

24- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.27- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

25 28

43 46

44## Models and reasoning47## Models and reasoning

45 48

46For most coding tasks in Codex, `gpt-5.3-codex` is the go-to model. It’s available for ChatGPT-authenticated Codex sessions in the Codex app, CLI, IDE extension, and Codex Cloud. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship frontier model, combining frontier coding performance with stronger reasoning, native computer use, and broader professional workflows. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.

47 50

~~48Switch models mid-session with the /model command, or specify one when launching the CLI.~~51Switch models mid-session with the `/model` command, or specify one when launching the CLI.

49 52

50```bash53```bash

~~51codex --model gpt-5.3-codex~~54codex --model gpt-5.4

52```55```

53 56

54[Learn more about the models available in Codex](https://developers.openai.com/codex/models).57[Learn more about the models available in Codex](https://developers.openai.com/codex/models).

65 68

66`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.69`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.

67 70

~~68## Multi-agents (experimental)~~71## Subagents

69 72

70Use Codex multi-agent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Multi-agents](https://developers.openai.com/codex/multi-agent).73Use Codex subagent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Subagents](https://developers.openai.com/codex/subagents).

75Codex only spawns subagents when you explicitly ask it to. Because each

76subagent does its own model and tool work, subagent workflows consume more

77tokens than comparable single-agent runs.

71 78

72## Image inputs79## Image inputs

73 80

83 90

84Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.91Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.

85 92

93## Syntax highlighting and themes

95The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.

97Use `/theme` to open the theme picker, preview themes live, and save your selection to `tui.theme` in `~/.codex/config.toml`. You can also add custom `.tmTheme` files under `$CODEX_HOME/themes` and select them in the picker.

86## Running local code review99## Running local code review

87 100

88Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.101Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.

96 109

97## Web search110## Web search

98 111

99Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. 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](https://developers.openai.com/codex/security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.112Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. 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](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.

100 113

101You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.114You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.

102 115

cli/slash-commands.md +89 −30

Details

1# Slash commands in Codex CLI1# Slash commands in Codex CLI

2 2

3Slash commands give you fast, keyboard-first control over Codex. Type `/` in the composer to open the slash popup, choose a command, and Codex will perform actions such as switching models, adjusting permissions, or summarizing long conversations without leaving the terminal.3Slash commands give you fast, keyboard-first control over Codex. Type `/` in

4the composer to open the slash popup, choose a command, and Codex will perform

5actions such as switching models, adjusting permissions, or summarizing long

6conversations without leaving the terminal.

4 7

5This guide shows you how to:8This guide shows you how to:

6 9

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

~~8- Steer an active session with commands like `/model`, `/personality`, `/permissions`, `/experimental`, `/agent`, and `/status`~~11- Steer an active session with commands like `/model`, `/personality`,

12 `/permissions`, `/experimental`, `/agent`, and `/status`

9 13

10## Built-in slash commands14## Built-in slash commands

11 15

~~12Codex ships with the following commands. Open the slash popup and start typing the command name to filter the list.~~16Codex ships with the following commands. Open the slash popup and start typing

17the command name to filter the list.

13 18

15| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

16| [`/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. |21| [`/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. |

17| [`/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. |22| [`/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. |

25| [`/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 to start over. |

20| [`/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. |26| [`/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. |

27| [`/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. |

25| [`/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. |32| [`/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. |

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

40| [`/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. |47| [`/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. |

41 48

~~42`/quit` and `/exit` both exit the CLI. Use them only after you have saved or committed any important work.~~49`/quit` and `/exit` both exit the CLI. Use them only after you have saved or

50committed any important work.

43 51

44The `/approvals` command still works as an alias, but it no longer appears in the slash popup list.52The `/approvals` command still works as an alias, but it no longer appears in the slash popup list.

45 53

621. In an active conversation, type `/personality` and press Enter.701. In an active conversation, type `/personality` and press Enter.

632. Choose a style from the popup.712. Choose a style from the popup.

64 72

~~65Expected: Codex confirms the new style in the transcript and uses it for later responses in the thread.~~73Expected: Codex confirms the new style in the transcript and uses it for later

74responses in the thread.

66 75

~~67Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none` to disable personality instructions.~~76Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`

77to disable personality instructions.

68 78

69If the active model doesn't support personality-specific instructions, Codex hides this command.79If the active model doesn't support personality-specific instructions, Codex hides this command.

70 80

71### Switch to plan mode with `/plan`81### Switch to plan mode with `/plan`

72 82

~~731. Type `/plan` and press Enter to switch the active conversation into plan mode.~~831. Type `/plan` and press Enter to switch the active conversation into plan

84 mode.

742. Optional: provide inline prompt text (for example, `/plan Propose a migration plan for this service`).852. Optional: provide inline prompt text (for example, `/plan Propose a migration plan for this service`).

753. You can paste content or attach images while using inline `/plan` arguments.863. You can paste content or attach images while using inline `/plan` arguments.

76 87

81### Toggle experimental features with `/experimental`92### Toggle experimental features with `/experimental`

82 93

831. Type `/experimental` and press Enter.941. Type `/experimental` and press Enter.

~~842. Toggle the features you want (for example, **Multi-agents**), then restart Codex.~~952. Toggle the features you want, then restart Codex.

85 96

86Expected: Codex saves your feature choices to config and applies them on restart.97Expected: Codex saves your feature choices to config and applies them on restart.

87 98

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

100

1011. Type `/clear` and press Enter.

102

103Expected: Codex clears the terminal, resets the visible transcript, and starts

104a fresh chat in the same CLI session.

105

106Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new conversation.

107

108<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current

109chat. Codex disables both actions while a task is in progress.

110

88### Update permissions with `/permissions`111### Update permissions with `/permissions`

89 112

901. Type `/permissions` and press Enter.1131. Type `/permissions` and press Enter.

~~912. Select the approval preset that matches your comfort level, for example `Auto` for hands-off runs or `Read Only` to review edits.~~1142. Select the approval preset that matches your comfort level, for example

115 `Auto` for hands-off runs or `Read Only` to review edits.

92 116

~~93Expected: Codex announces the updated policy. Future actions respect the new approval mode until you change it again.~~117Expected: Codex announces the updated policy. Future actions respect the

118updated approval mode until you change it again.

119

120### Copy the latest response with `/copy`

121

1221. Type `/copy` and press Enter.

123

124Expected: Codex copies the latest completed Codex output to your clipboard.

125

126If a turn is still running, `/copy` uses the latest completed output instead of

127the in-progress response. The command is unavailable before the first completed

128Codex output and immediately after a rollback.

94 129

95### Grant sandbox read access with `/sandbox-add-read-dir`130### Grant sandbox read access with `/sandbox-add-read-dir`

96 131

991. Type `/sandbox-add-read-dir C:\absolute\directory\path` and press Enter.1341. Type `/sandbox-add-read-dir C:\absolute\directory\path` and press Enter.

1002. Confirm the path is an existing absolute directory.1352. Confirm the path is an existing absolute directory.

101 136

102Expected: Codex refreshes the Windows sandbox policy and grants read access to that directory for later commands that run in the sandbox.137Expected: Codex refreshes the Windows sandbox policy and grants read access to

138that directory for later commands that run in the sandbox.

103 139

104### Inspect the session with `/status`140### Inspect the session with `/status`

105 141

1061. In any conversation, type `/status`.1421. In any conversation, type `/status`.

1072. Review the output for the active model, approval policy, writable roots, and current token usage.1432. Review the output for the active model, approval policy, writable roots, and current token usage.

108 144

109Expected: You see a summary like what `codex status` prints in the shell, confirming Codex is operating where you expect.145Expected: You see a summary like what `codex status` prints in the shell,

146confirming Codex is operating where you expect.

110 147

111### Inspect config layers with `/debug-config`148### Inspect config layers with `/debug-config`

112 149

1131. Type `/debug-config`.1501. Type `/debug-config`.

1142. Review the output for config layer order (lowest precedence first), on/off state, and policy sources.1512. Review the output for config layer order (lowest precedence first), on/off

152 state, and policy sources.

115 153

116Expected: Codex prints layer diagnostics plus policy details such as `allowed_approval_policies`, `allowed_sandbox_modes`, `mcp_servers`, `rules`, `enforce_residency`, and `experimental_network` when configured.154Expected: Codex prints layer diagnostics plus policy details such as

155`allowed_approval_policies`, `allowed_sandbox_modes`, `mcp_servers`, `rules`,

156`enforce_residency`, and `experimental_network` when configured.

117 157

118Use this output to debug why an effective setting differs from `config.toml`.158Use this output to debug why an effective setting differs from `config.toml`.

119 159

1221. Type `/statusline`.1621. Type `/statusline`.

1232. Use the picker to toggle and reorder items, then confirm.1632. Use the picker to toggle and reorder items, then confirm.

124 164

125Expected: The footer status line updates immediately and persists to `tui.status_line` in `config.toml`.165Expected: The footer status line updates immediately and persists to

166`tui.status_line` in `config.toml`.

126 167

127Available status-line items include model, model+reasoning, context stats, rate limits, git branch, token counters, session id, current directory/project root, and Codex version.168Available status-line items include model, model+reasoning, context stats, rate

169limits, git branch, token counters, session id, current directory/project root,

170and Codex version.

128 171

129### Check background terminals with `/ps`172### Check background terminals with `/ps`

130 173

1311. Type `/ps`.1741. Type `/ps`.

1322. Review the list of background terminals and their status.1752. Review the list of background terminals and their status.

133 176

134Expected: Codex shows each background terminal’s command plus up to three recent, non-empty output lines so you can gauge progress at a glance.177Expected: Codex shows each background terminal's command plus up to three

178recent, non-empty output lines so you can gauge progress at a glance.

135 179

136Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.180Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.

137 181

1401. After a long exchange, type `/compact`.1841. After a long exchange, type `/compact`.

1412. Confirm when Codex offers to summarize the conversation so far.1852. Confirm when Codex offers to summarize the conversation so far.

142 186

143Expected: Codex replaces earlier turns with a concise summary, freeing context while keeping critical details.187Expected: Codex replaces earlier turns with a concise summary, freeing context

188while keeping critical details.

144 189

145### Review changes with `/diff`190### Review changes with `/diff`

146 191

1471. Type `/diff` to inspect the Git diff.1921. Type `/diff` to inspect the Git diff.

1482. Scroll through the output inside the CLI to review edits and added files.1932. Scroll through the output inside the CLI to review edits and added files.

149 194

150Expected: Codex shows changes you’ve staged, changes you haven’t staged yet, and files Git hasn’t started tracking, so you can decide what to keep.195Expected: Codex shows changes you've staged, changes you haven't staged yet,

196and files Git hasn't started tracking, so you can decide what to keep.

151 197

152### Highlight files with `/mention`198### Highlight files with `/mention`

153 199

160 206

1611. Type `/new` and press Enter.2071. Type `/new` and press Enter.

162 208

163Expected: Codex starts a fresh conversation in the same CLI session, so you can switch tasks without leaving your terminal.209Expected: Codex starts a fresh conversation in the same CLI session, so you

210can switch tasks without leaving your terminal.

211

212Unlike `/clear`, `/new` doesn’t clear the current terminal view first.

164 213

165### Resume a saved conversation with `/resume`214### Resume a saved conversation with `/resume`

166 215

1671. Type `/resume` and press Enter.2161. Type `/resume` and press Enter.

1682. Choose the session you want from the saved-session picker.2172. Choose the session you want from the saved-session picker.

169 218

170Expected: Codex reloads the selected conversation’s transcript so you can pick up where you left off, keeping the original history intact.219Expected: Codex reloads the selected conversation's transcript so you can pick

220up where you left off, keeping the original history intact.

171 221

172### Fork the current conversation with `/fork`222### Fork the current conversation with `/fork`

173 223

1741. Type `/fork` and press Enter.2241. Type `/fork` and press Enter.

175 225

176Expected: Codex clones the current conversation into a new thread with a fresh ID, leaving the original transcript untouched so you can explore an alternative approach in parallel.226Expected: Codex clones the current conversation into a new thread with a fresh

227ID, leaving the original transcript untouched so you can explore an alternative

228approach in parallel.

177 229

178If you need to fork a saved session instead of the current one, run `codex fork` in your terminal to open the session picker.230If you need to fork a saved session instead of the current one, run

231`codex fork` in your terminal to open the session picker.

179 232

180### Generate `AGENTS.md` with `/init`233### Generate `AGENTS.md` with `/init`

181 234

1821. Run `/init` in the directory where you want Codex to look for persistent instructions.2351. Run `/init` in the directory where you want Codex to look for persistent instructions.

1832. Review the generated `AGENTS.md`, then edit it to match your repository conventions.2362. Review the generated `AGENTS.md`, then edit it to match your repository conventions.

184 237

185Expected: Codex creates an `AGENTS.md` scaffold you can refine and commit for future sessions.238Expected: Codex creates an `AGENTS.md` scaffold you can refine and commit for

239future sessions.

186 240

187### Ask for a working tree review with `/review`241### Ask for a working tree review with `/review`

188 242

1891. Type `/review`.2431. Type `/review`.

1902. Follow up with `/diff` if you want to inspect the exact file changes.2442. Follow up with `/diff` if you want to inspect the exact file changes.

191 245

192Expected: Codex summarizes issues it finds in your working tree, focusing on behavior changes and missing tests. It uses the current session model unless you set `review_model` in `config.toml`.246Expected: Codex summarizes issues it finds in your working tree, focusing on

247behavior changes and missing tests. It uses the current session model unless

248you set `review_model` in `config.toml`.

193 249

194### List MCP tools with `/mcp`250### List MCP tools with `/mcp`

195 251

2031. Type `/apps`.2591. Type `/apps`.

2042. Pick an app from the list.2602. Pick an app from the list.

205 261

206Expected: Codex inserts the app mention into the composer as `$app-slug`, so you can immediately ask Codex to use it.262Expected: Codex inserts the app mention into the composer as `$app-slug`, so

263you can immediately ask Codex to use it.

207 264

208### Switch agent threads with `/agent`265### Switch agent threads with `/agent`

209 266

2101. Type `/agent` and press Enter.2671. Type `/agent` and press Enter.

2112. Select the thread you want from the picker.2682. Select the thread you want from the picker.

212 269

213Expected: Codex switches the active thread so you can inspect or continue that agent’s work.270Expected: Codex switches the active thread so you can inspect or continue that

271agent's work.

214 272

215### Send feedback with `/feedback`273### Send feedback with `/feedback`

216 274

2171. Type `/feedback` and press Enter.2751. Type `/feedback` and press Enter.

2182. Follow the prompts to include logs or diagnostics.2762. Follow the prompts to include logs or diagnostics.

219 277

220Expected: Codex collects the requested diagnostics and submits them to the maintainers.278Expected: Codex collects the requested diagnostics and submits them to the

279maintainers.

221 280

222### Sign out with `/logout`281### Sign out with `/logout`

223 282

codex.md +5 −1

Details

24 24

25Explore Codex Ambassadors and upcoming community meetups by location.25Explore Codex Ambassadors and upcoming community meetups by location.

26 26

~~27 See community](https://developers.openai.com/codex/community/meetups)~~27 See community](https://developers.openai.com/codex/community/meetups) [### Codex for OSS

29Apply or nominate maintainers for API credits, ChatGPT Pro with Codex, and selective Codex Security access.

31 Learn more](https://developers.openai.com/codex/community/codex-for-oss)

codex-for-oss-terms.md +47 −0 added

Details

1# Codex for Open Source Program Terms

3These Program Terms govern the Codex for Open Source program (the “Program”) offered by OpenAI OpCo, LLC and its affiliates (“OpenAI,” “we,” “our,” or “us”). By submitting an application to the Program or accepting any Program benefit, you agree to these Program Terms.

5These Program Terms supplement, and do not replace, the OpenAI Terms of Use, Privacy Policy, applicable service terms, and OpenAI policies that govern your use of ChatGPT, Codex, the API, and any other OpenAI services made available through the Program. If there is a conflict, these Program Terms control only with respect to the Program.

7## 1. Program Overview

9The Program is designed to support maintainers of important open-source software. Approved applicants may receive one or more of the following benefits, as determined by OpenAI in its sole discretion: (i) a limited-duration ChatGPT Pro benefit that includes Codex access; (ii) API credits for eligible open-source maintainer workflows; and (iii) conditional access to Codex Security for qualified repositories or maintainers. Availability, duration, scope, and timing of any benefit may vary by applicant, repository, or use case.

11## 2. Eligibility and Applications

13To be considered for the Program, applicants must have a valid ChatGPT account and provide accurate and complete information about themselves, their repositories, and their role in maintaining or administering those repositories. OpenAI may consider factors such as repository usage, ecosystem importance, evidence of active maintenance, role or permissions, and Program capacity. Submission of an application does not guarantee selection, funding, or access.

15## 3. Selection and Verification

17OpenAI may approve or deny applications in its sole discretion. OpenAI may request additional information to verify identity, repository affiliation, maintainer status, or repository control, and may condition any benefit on successful verification. OpenAI's decisions are final.

19## 4. Benefits

21Unless OpenAI states otherwise in writing, Program benefits are personal, limited, non-transferable, and have no cash value. Program benefits may not be sold, assigned, sublicensed, exchanged, or shared. If OpenAI provides a redemption code, invitation, or activation flow, the recipient must follow the applicable redemption instructions and any additional redemption terms communicated by OpenAI. Benefits may expire if they are not redeemed or activated within the period specified by OpenAI.

23## 5. Additional Conditions for Codex Security and API Credits

25Codex Security access and API credits are optional, additional Program benefits and may require separate review, additional eligibility checks, and/or additional terms. OpenAI may limit Codex Security access to repositories that the applicant owns, maintains, or is otherwise authorized to administer.

27Applicants may not use the Program, including Codex Security, to scan, probe, test, or review repositories, systems, or codebases that they do not own or lack permission to review. OpenAI may require proof of control or authorization before granting or continuing such access and may limit or revoke access at any time if authorization is unclear or no longer valid.

29## 6. Fraud, Abuse, and Revocation

31OpenAI may reject, suspend, or revoke any Program benefit for any reason in its sole discretion, including without limitation if it reasonably believes that an applicant or recipient: (i) provided false, misleading, or incomplete information; (ii) used multiple identities or accounts to obtain more than one benefit; (iii) transferred, resold, or shared a benefit; (iv) violated OpenAI's terms or policies; (v) used the Program in a harmful, abusive, fraudulent, or unauthorized manner; or (vi) otherwise created legal, security, reputational, or operational risk for OpenAI or others.

33## 7. Submission Similarity; No Exclusivity; No Confidentiality

35The applicant acknowledges that OpenAI may currently or in the future develop, receive, review, fund, support, or work with ideas, projects, repositories, workflows, or proposals that are similar or identical to the applicant's submission. Nothing in these Program Terms prevents OpenAI from independently developing, funding, or supporting any such similar or identical work.

37The applicant further acknowledges that OpenAI assumes no obligation of exclusivity with respect to any submission and that any decision to select, fund, or support a project or maintainer is made in OpenAI's sole discretion.

39Except as described in OpenAI's privacy policy or as required by law, applicants should not submit confidential information in connection with the Program, and OpenAI has no duty to treat application materials as confidential.

41## 8. Program Changes

43OpenAI may modify, pause, limit, or discontinue the Program, its eligibility criteria, or any Program benefit at any time. OpenAI may also update these Program Terms from time to time. Continued participation in the Program after an update constitutes acceptance of the revised Program Terms.

45## 9. Taxes and Local Restrictions

47Recipients are responsible for any taxes, reporting obligations, or local legal requirements that may apply to receipt or use of Program benefits. The Program is void where prohibited or restricted by law.

community/codex-for-oss.md +19 −0 added

Details

1# Codex for Open Source

3Open-source maintainers do critical work, often behind the scenes, to keep the software ecosystem healthy. Over the past year, the Codex Open Source Fund ($1 million) has supported projects that need API credits, including teams using Codex to power GitHub pull request workflows. OpenAI is grateful to the maintainers who keep that work moving.

5The fund now supports eligible maintainers by offering six months of ChatGPT Pro with Codex and conditional access to Codex Security for core maintainers with write access. Developers should code in the tools they prefer, whether that’s Codex, [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), [OpenClaw](https://github.com/openclaw/openclaw), or something else, and this program supports that work.

7## What the program includes

9- Six months of ChatGPT Pro with Codex for day-to-day coding, triage, review, and maintainer workflows

10- Conditional access to Codex Security for repositories that need deeper security coverage

11- API credits through the Codex Open Source Fund for projects that use Codex in pull request review, maintainer automation, release workflows, or other core OSS work

13Given GPT-5.4’s capabilities, the team reviews Codex Security access case by case to ensure these workflows get the care and diligence they require.

15If you’re a core maintainer or run a widely used public project, apply. If your project doesn’t fit the criteria but it plays an important role in the ecosystem, apply anyway and explain why.

17By submitting an application, you agree to the [Codex for Open Source Program Terms](https://developers.openai.com/codex/codex-for-oss-terms).

19[Apply today!](https://openai.com/form/codex-for-oss/)

community/meetups.md +8 −8

Details

1# Codex Meetups1# Codex Meetups

2 2

~~3Mar 12~~3Mar 17

4 4

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

6 6

~~7UpcomingMar 12~~7UpcomingMar 17

8 8

~~9Orlando, FL, USA~~9San Francisco, California, USA

10 10

~~11### Orlando~~11### Community Hackathon - San Francisco

12 12

~~13March 12, 2026~~13March 17, 2026

14 14

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

16 16

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

concepts/customization.md +12 −12

Details

7- **Project guidance (`AGENTS.md`)** for persistent instructions7- **Project guidance (`AGENTS.md`)** for persistent instructions

8- **Skills** for reusable workflows and domain expertise8- **Skills** for reusable workflows and domain expertise

9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems

~~10- **[Multi-agents](https://developers.openai.com/codex/concepts/multi-agents)** for delegating work to specialized sub-agents~~10- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents

11 11

12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.

13 13

19 19

20- Build and test commands20- Build and test commands

21- Review expectations21- Review expectations

~~22- Repo-specific conventions~~22- repo-specific conventions

23- Directory-specific instructions23- Directory-specific instructions

24 24

25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.

44 - AGENTS.md Global (for you as a developer)44 - AGENTS.md Global (for you as a developer)

45- repo-root/45- repo-root/

46 46

~~47 - AGENTS.md Repo-specific (for your team)~~47 - AGENTS.md repo-specific (for your team)

48 48

49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)

50 50

87 87

88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

89 89

91| :----- | :--------------------- | :--------------------------------------------- |91| :----- | :--------------------- | :--------------------------------------------- |

94 94

95Codex uses progressive disclosure for skills:95Codex uses progressive disclosure for skills:

105## MCP105## MCP

106 106

107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.

108It’s especially useful for remotely hosted systems such as Figma, Linear, Jira, GitHub, or internal knowledge services your team depends on.108It's especially useful for remotely hosted systems such as Figma, Linear, GitHub, or internal knowledge services your team depends on.

109 109

110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.

111 111

112A useful mental model:112One way to think about it:

113 113

114- **Host**: Codex114- **Host**: Codex

115- **Client**: the MCP connection inside Codex115- **Client**: the MCP connection inside Codex

129 129

130[Model Context Protocol](https://developers.openai.com/codex/mcp)130[Model Context Protocol](https://developers.openai.com/codex/mcp)

131 131

132## Multi-agents132## Subagents

133 133

134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each sub-agent stays focused and uses the right tools for its job.134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each subagent stays focused and uses the right tools for its job.

135 135

136[Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents)136[Subagent concepts](https://developers.openai.com/codex/concepts/subagents)

137 137

138## Skills + MCP together138## Skills + MCP together

139 139

146 146

1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.

1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.

1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, JIRA, docs servers, design tools).1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).

1504. [Multi-agents](https://developers.openai.com/codex/multi-agent) when you’re ready to delegate noisy or specialized tasks to sub-agents.1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.

concepts/multi-agents.md +0 −53 deleted

File DeletedView Diff

~~1# Multi-agents~~

~~3Codex can run multi-agent workflows by spawning specialized agents in parallel and collecting their results in one response.~~

~~5This page explains the core concepts and tradeoffs. For setup, agent configuration, and examples, see [Multi-agents](https://developers.openai.com/codex/multi-agent).~~

~~7## Why multi-agent workflows help~~

9Even with large context windows, models have limits. If you flood the main conversation (where you’re defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

~~11This is often described as:~~

~~13- **Context pollution**: useful information gets buried under noisy intermediate output.~~

~~14- **Context rot**: performance degrades as the conversation fills up with less relevant details.~~

~~16For background, see Chroma’s writeup on [context rot](https://research.trychroma.com/context-rot).~~

~~18Multi-agent workflows help by moving noisy work off the main thread:~~

~~20- Keep the **main agent** focused on requirements, decisions, and final outputs.~~

~~21- Run specialized **sub-agents** in parallel for exploration, tests, or log analysis.~~

~~22- Return **summaries** from sub-agents instead of raw intermediate output.~~

24As a starting point, use parallel agents for tasks that mostly read (exploration, tests, triage, and summarization). Be more careful with parallel write-heavy workflows, because multiple agents editing code at once can create conflicts and increase coordination overhead.

~~26## Core terms~~

~~28Codex uses a few related terms in multi-agent workflows:~~

~~30- **Multi-agent**: A workflow where Codex runs multiple agents in parallel and combines their results.~~

~~31- **Sub-agent**: A delegated agent that Codex starts to handle a specific task.~~

~~32- **Agent thread**: The CLI thread for an agent, which you can inspect and switch between with `/agent`.~~

~~34## Choosing models and reasoning~~

~~36Different agents benefit from different model and reasoning settings.~~

~~38`gpt-5.3-codex-spark` is available in research preview for ChatGPT Pro~~

~~39subscribers. See [Models](https://developers.openai.com/codex/models) for current availability. If you’re~~

~~40using Codex via the API, use GPT-5.2-Codex today.~~

~~42### Model choice~~

44- **`gpt-5.3-codex`**: Use for agents that need stronger reasoning, such as code review, security analysis, multi-step implementation, or tasks with ambiguous requirements. The main agent and agents that propose or apply edits usually fit here.

45- **`gpt-5.3-codex-spark`**: Use for agents that prioritize speed over depth, such as exploration, read-heavy scans, or quick summarization tasks. Spark works well for parallel workers that return distilled results to the main agent.

~~47### Reasoning effort (`model_reasoning_effort`)~~

~~49- **`high`**: Use when an agent needs to trace complex logic, validate assumptions, or work through edge cases (for example, reviewer or security-focused agents).~~

~~50- **`medium`**: A balanced default for most agents.~~

~~51- **`low`**: Use when the task is straightforward and speed matters most.~~

53Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://developers.openai.com/codex/models), [Config basics](https://developers.openai.com/codex/config-basic), and [Configuration Reference](https://developers.openai.com/codex/config-reference).

concepts/sandboxing.md +102 −0 added

Details

1# Sandboxing – Codex

3Sandboxing is the boundary that lets Codex act autonomously without giving it

4unrestricted access to your machine. When Codex runs local commands in the

5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a

6constrained environment instead of running with full access by default.

8That environment defines what Codex can do on its own, such as which files it

9can modify and whether commands can use the network. When a task stays inside

10those boundaries, Codex can keep moving without stopping for confirmation. When

11it needs to go beyond them, Codex falls back to the approval flow.

13Sandboxing and approvals are different controls that work together. The

14 sandbox defines technical boundaries. The approval policy decides when Codex

15 must stop and ask before crossing them.

17## What the sandbox does

19The sandbox applies to spawned commands, not just to Codex's built-in file

20operations. If Codex runs tools like `git`, package managers, or test runners,

21those commands inherit the same sandbox boundaries.

23Codex uses platform-native enforcement on each OS. The implementation differs

24between macOS, Linux, WSL, and native Windows, but the idea is the same across

25surfaces: give the agent a bounded place to work so routine tasks can run

26autonomously inside clear limits.

28## Why it matters

30Sandboxing reduces approval fatigue. Instead of asking you to confirm every

31low-risk command, Codex can read files, make edits, and run routine project

32commands within the boundary you already approved.

34It also gives you a clearer trust model for agentic work. You are not just

35trusting the agent's intentions; you are trusting that the agent is operating

36inside enforced limits. That makes it easier to let Codex work independently

37while still knowing when it will stop and ask for help.

39## How you control it

41Most people start with the permissions controls in the product.

43In the Codex app and IDE, you choose a mode from the permissions selector under

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

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

47![Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)](/images/codex/app/permissions-selector-light.webp)

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

50to switch modes during a session.

52## Configure defaults

54If you want Codex to start with the same behavior every time, use a custom

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

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

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

58`sandbox_mode`, `approval_policy`, and

59`sandbox_workspace_write.writable_roots`. Use those settings to decide how much

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

61should pause for approval.

63At a high level, the common sandbox modes are:

65- `read-only`: Codex can inspect files, but it cannot edit files or run

66 commands without approval.

67- `workspace-write`: Codex can read files, edit within the workspace, and run

68 routine local commands inside that boundary. This is the default low-friction

69 mode for local work.

70- `danger-full-access`: Codex runs without sandbox restrictions. This removes

71 the filesystem and network boundaries and should be used only when you want

72 Codex to act with full access.

74The common approval policies are:

76- `untrusted`: Codex asks before running commands that are not in its trusted

77 set.

78- `on-request`: Codex works inside the sandbox by default and asks when it

79 needs to go beyond that boundary.

80- `never`: Codex does not stop for approval prompts.

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

83`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local

84automation preset: `sandbox_mode = "workspace-write"` and

85`approval_policy = "on-request"`.

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

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

89you need a broader or narrower trust boundary, adjust the default sandbox mode

90and approval policy instead of relying on ad hoc exceptions.

92When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules

93let you allow, prompt, or forbid command prefixes outside the sandbox, which is

94often a better fit than broadly expanding access. For a higher-level overview

95of approvals and sandbox behavior in the app, see

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

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

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

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

101requirements and organization-level constraints on sandboxing and approvals, see

102[Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

concepts/subagents.md +87 −0 added

Details

1# Subagents

3Codex can run subagent workflows by spawning specialized agents in parallel so

4they can explore, execute, or analyze work concurrently.

6This page explains the core concepts and tradeoffs. For setup, agent configuration, and examples, see [Subagents](https://developers.openai.com/codex/subagents).

8## Why subagent workflows help

10Even with large context windows, models have limits. If you flood the main conversation (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

12This is often described as:

14- **Context pollution**: useful information gets buried under noisy intermediate output.

15- **Context rot**: performance degrades as the conversation fills up with less relevant details.

17For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).

19Subagent workflows help by moving noisy work off the main thread:

21- Keep the **main agent** focused on requirements, decisions, and final outputs.

22- Run specialized **subagents** in parallel for exploration, tests, or log analysis.

23- Return **summaries** from subagents instead of raw intermediate output.

25They can also save time when the work can run independently in parallel, and

26they make larger-shaped tasks more tractable by breaking them into bounded

27pieces. For example, Codex can split analysis of a multi-million-token

28document into smaller problems and return distilled takeaways to the main

29thread.

31As a starting point, use parallel agents for read-heavy tasks such as

32exploration, tests, triage, and summarization. Be more careful with parallel

33write-heavy workflows, because agents editing code at once can create

34conflicts and increase coordination overhead.

36## Core terms

38Codex uses a few related terms in subagent workflows:

40- **Subagent workflow**: A workflow where Codex runs parallel agents and combines their results.

41- **Subagent**: A delegated agent that Codex starts to handle a specific task.

42- **Agent thread**: The CLI thread for an agent, which you can inspect and switch between with `/agent`.

44## Triggering subagent workflows

46Codex doesn't spawn subagents automatically, and it should only use subagents when you

47explicitly ask for subagents or parallel agent work.

49In practice, manual triggering means using direct instructions such as

50"spawn two agents," "delegate this work in parallel," or "use one agent per

51point." Subagent workflows consume more tokens than comparable single-agent runs

52because each subagent does its own model and tool work.

54A good subagent prompt should explain how to divide the work, whether Codex

55should wait for all agents before continuing, and what summary or output to

56return.

58```text

59Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

60```

62## Choosing models and reasoning

64Different agents need different model and reasoning settings.

66If 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 favor

68`gpt-5.3-codex-spark` for fast scans or a higher-effort `gpt-5.4`

69configuration for harder reasoning. When you want finer control, steer that

70choice in your prompt or set `model` and `model_reasoning_effort` directly in

71the agent file.

73For most tasks in Codex, start with `gpt-5.4`. Use `gpt-5.3-codex-spark` when

74you want a faster option for lighter subagent work.

76### Model choice

78- **`gpt-5.4`**: Start here for most agents. It combines strong coding, reasoning, tool use, and broader workflows. The main agent and agents that coordinate ambiguous or multi-step work fit here.

79- **`gpt-5.3-codex-spark`**: Use for agents that favor speed over depth, such as exploration, read-heavy scans, or quick summarization tasks. It works well for parallel workers that return distilled results to the main agent.

81### Reasoning effort (`model_reasoning_effort`)

83- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).

84- **`medium`**: A balanced default for most agents.

85- **`low`**: Use when the task is straightforward and speed matters most.

87Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://developers.openai.com/codex/models), [Config basics](https://developers.openai.com/codex/config-basic), and [Configuration Reference](https://developers.openai.com/codex/config-reference).

config-advanced.md +15 −8

Details

2 2

3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).

4 4

5For background on project guidance, reusable capabilities, custom slash commands, multi-agent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).5For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).

6 6

7## Profiles7## Profiles

8 8

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5-codex"

19approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

20 21

21[profiles.deep-review]22[profiles.deep-review]

22model = "gpt-5-pro"23model = "gpt-5-pro"

23model_reasoning_effort = "high"24model_reasoning_effort = "high"

24approval_policy = "never"25approval_policy = "never"

26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

25 27

26[profiles.lightweight]28[profiles.lightweight]

27model = "gpt-4.1"29model = "gpt-4.1"

30 32

31To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.33To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.

32 34

35Profiles can also override `model_catalog_json`. When both the top level and the selected profile set `model_catalog_json`, Codex prefers the profile value.

33## One-off overrides from the CLI37## One-off overrides from the CLI

34 38

35In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:39In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:

41 45

42```shell46```shell

43# Dedicated flag47# Dedicated flag

~~44codex --model gpt-5.2~~48codex --model gpt-5.4

45 49

46# Generic key/value override (value is TOML, not JSON)50# Generic key/value override (value is TOML, not JSON)

~~47codex --config model='"gpt-5.2"'~~51codex --config model='"gpt-5.4"'

48codex --config sandbox_workspace_write.network_access=true52codex --config sandbox_workspace_write.network_access=true

49codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

50```54```

87 91

88## Agent roles (`[agents]` in `config.toml`)92## Agent roles (`[agents]` in `config.toml`)

89 93

~~90For multi-agent role configuration (`[agents]` in `config.toml`), see [Multi-agents](https://developers.openai.com/codex/multi-agent).~~94For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

91 95

92## Project root detection96## Project root detection

93 97

186 190

187Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).191Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

188 192

189For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).193For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [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).

194

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories, such as sandbox approvals, `execpolicy` rule prompts, or MCP input requests (`mcp_elicitations`), while keeping other prompts interactive.

190 196

191```197```

192approval_policy = "untrusted" # Other options: on-request, never198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }

193sandbox_mode = "workspace-write"199sandbox_mode = "workspace-write"

200allow_login_shell = false # Optional hardening: disallow login shells for shell tools

194 201

195[sandbox_workspace_write]202[sandbox_workspace_write]

196exclude_tmpdir_env_var = false # Allow $TMPDIR203exclude_tmpdir_env_var = false # Allow $TMPDIR

199network_access = false # Opt in to outbound network206network_access = false # Opt in to outbound network

200```207```

201 208

202Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/security#managed-configuration).209Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

203 210

204In workspace-write mode, some environments keep `.git/` and `.codex/`211In workspace-write mode, some environments keep `.git/` and `.codex/`

205 read-only even when the rest of the workspace is writable. This is why212 read-only even when the rest of the workspace is writable. This is why

297 304

298For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/security#monitoring-and-telemetry).305For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry).

299 306

300### Metrics307### Metrics

301 308

config-basic.md +17 −11

Details

11The CLI and IDE extension share the same configuration layers. You can use them to:11The CLI and IDE extension share the same configuration layers. You can use them to:

12 12

13- Set the default model and provider.13- Set the default model and provider.

~~14- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/security#sandbox-and-approvals).~~14- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals).

15- Configure [MCP servers](https://developers.openai.com/codex/mcp).15- Configure [MCP servers](https://developers.openai.com/codex/mcp).

16 16

17## Configuration precedence17## Configuration precedence

34On managed machines, your organization may also enforce constraints via34On managed machines, your organization may also enforce constraints via

35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or

36 `sandbox_mode = "danger-full-access"`). See [Managed36 `sandbox_mode = "danger-full-access"`). See [Managed

~~37configuration](https://developers.openai.com/codex/security#managed-configuration) and [Admin-enforced~~37 configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Admin-enforced

~~38requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~38 requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

39 39

40## Common configuration options40## Common configuration options

41 41

46Choose the model Codex uses by default in the CLI and IDE.46Choose the model Codex uses by default in the CLI and IDE.

47 47

48```toml48```toml

~~49model = "gpt-5.2"~~49model = "gpt-5.4"

50```50```

51 51

52#### Approval prompts52#### Approval prompts

57approval_policy = "on-request"57approval_policy = "on-request"

58```58```

59 59

60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations).60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations).

61 61

62#### Sandbox level62#### Sandbox level

63 63

67sandbox_mode = "workspace-write"67sandbox_mode = "workspace-write"

68```68```

69 69

70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [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).

72#### Windows sandbox mode

74When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you don't have administrator permissions or if elevated setup fails.

76```toml

77[windows]

78sandbox = "elevated" # Recommended

79# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

80```

71 81

72#### Web search mode82#### Web search mode

73 83

74Codex enables web search by default for local tasks and serves results from a web search cache. 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](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:84Codex enables web search by default for local tasks and serves results from a web search cache. 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](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

75 85

76- `"cached"` (default) serves results from the web search cache.86- `"cached"` (default) serves results from the web search cache.

77- `"live"` fetches the most recent data from the web (same as `--search`).87- `"live"` fetches the most recent data from the web (same as `--search`).

137 147

138| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

139| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

config-reference.md +1163 −341

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

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/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).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).

10 10

11| Key | Type / Values | Details |11| Key | Type / Values | Details |

12| --- | --- | --- |12| --- | --- | --- |

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

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

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

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

22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

26| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

27| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

29| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

30| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

32| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

34| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

35| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

~~26| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |~~

~~28| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |~~

30| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

61| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

62| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

63| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

69| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

71| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

72| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

73| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

~~56| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |~~

88| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

101| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

103| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

110| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

127| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

162| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

128| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |178| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

179| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

184| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

208| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

211| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

155| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |213| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

216| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

158| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

162| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |222| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

164 225

165Key226Key

166 227

188 249

189Key250Key

190 251

191`agents.max_threads`252`agents.<name>.nickname_candidates`

192 253

193Type / Values254Type / Values

194 255

195`number`256`array<string>`

196 257

197Details258Details

198 259

199Maximum number of agent threads that can be open concurrently.260Optional pool of display nicknames for spawned agents in that role.

200 261

201Key262Key

202 263

203`approval_policy`264`agents.job_max_runtime_seconds`

204 265

205Type / Values266Type / Values

206 267

207`untrusted | on-request | never`268`number`

208 269

209Details270Details

210 271

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.272Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

212 273

213Key274Key

214 275

215`apps.<id>.disabled_reason`276`agents.max_depth`

216 277

217Type / Values278Type / Values

218 279

219`unknown | user`280`number`

220 281

221Details282Details

222 283

223Optional reason attached when an app/connector is disabled.284Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

224 285

225Key286Key

226 287

227`apps.<id>.enabled`288`agents.max_threads`

228 289

229Type / Values290Type / Values

230 291

231`boolean`292`number`

232 293

233Details294Details

234 295

235Enable or disable a specific app/connector by id (default: true).296Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

236 297

237Key298Key

238 299

239`chatgpt_base_url`300`allow_login_shell`

240 301

241Type / Values302Type / Values

242 303

243`string`304`boolean`

244 305

245Details306Details

246 307

247Override the base URL used during the ChatGPT login flow.308Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells.

248 309

249Key310Key

250 311

251`check_for_update_on_startup`312`analytics.enabled`

252 313

253Type / Values314Type / Values

254 315

256 317

257Details318Details

258 319

259Check for Codex updates on startup (set to false only when updates are centrally managed).320Enable or disable analytics for this machine/profile. When unset, the client default applies.

260 321

261Key322Key

262 323

263`cli_auth_credentials_store`324`approval_policy`

264 325

265Type / Values326Type / Values

266 327

267`file | keyring | auto`328`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

268 329

269Details330Details

270 331

271Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).332Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

272 333

273Key334Key

274 335

275`compact_prompt`336`approval_policy.reject.mcp_elicitations`

276 337

277Type / Values338Type / Values

278 339

279`string`340`boolean`

280 341

281Details342Details

282 343

283Inline override for the history compaction prompt.344When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

284 345

285Key346Key

286 347

287`developer_instructions`348`approval_policy.reject.rules`

288 349

289Type / Values350Type / Values

290 351

291`string`352`boolean`

292 353

293Details354Details

294 355

295Additional developer instructions injected into the session (optional).356When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

296 357

297Key358Key

298 359

299`disable_paste_burst`360`approval_policy.reject.sandbox_approval`

300 361

301Type / Values362Type / Values

302 363

304 365

305Details366Details

306 367

307Disable burst-paste detection in the TUI.368When `true`, sandbox escalation approval prompts are auto-rejected.

308 369

309Key370Key

310 371

311`experimental_compact_prompt_file`372`apps._default.destructive_enabled`

312 373

313Type / Values374Type / Values

314 375

315`string (path)`376`boolean`

316 377

317Details378Details

318 379

319Load the compaction prompt override from a file (experimental).380Default allow/deny for app tools with `destructive_hint = true`.

320 381

321Key382Key

322 383

323`experimental_use_freeform_apply_patch`384`apps._default.enabled`

324 385

325Type / Values386Type / Values

326 387

328 389

329Details390Details

330 391

331Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.392Default app enabled state for all apps unless overridden per app.

332 393

333Key394Key

334 395

335`experimental_use_unified_exec_tool`396`apps._default.open_world_enabled`

336 397

337Type / Values398Type / Values

338 399

340 401

341Details402Details

342 403

343Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.404Default allow/deny for app tools with `open_world_hint = true`.

344 405

345Key406Key

346 407

347`features.apply_patch_freeform`408`apps.<id>.default_tools_approval_mode`

348 409

349Type / Values410Type / Values

350 411

351`boolean`412`auto | prompt | approve`

352 413

353Details414Details

354 415

355Expose the freeform `apply_patch` tool (experimental).416Default approval behavior for tools in this app unless a per-tool override exists.

356 417

357Key418Key

358 419

359`features.apps`420`apps.<id>.default_tools_enabled`

360 421

361Type / Values422Type / Values

362 423

364 425

365Details426Details

366 427

367Enable ChatGPT Apps/connectors support (experimental).428Default enabled state for tools in this app unless a per-tool override exists.

368 429

369Key430Key

370 431

371`features.apps_mcp_gateway`432`apps.<id>.destructive_enabled`

372 433

373Type / Values434Type / Values

374 435

376 437

377Details438Details

378 439

379Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).440Allow or block tools in this app that advertise `destructive_hint = true`.

380 441

381Key442Key

382 443

383`features.child_agents_md`444`apps.<id>.enabled`

384 445

385Type / Values446Type / Values

386 447

388 449

389Details450Details

390 451

391Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).452Enable or disable a specific app/connector by id (default: true).

392 453

393Key454Key

394 455

395`features.collaboration_modes`456`apps.<id>.open_world_enabled`

396 457

397Type / Values458Type / Values

398 459

400 461

401Details462Details

402 463

403Enable collaboration modes such as plan mode (stable; on by default).464Allow or block tools in this app that advertise `open_world_hint = true`.

404 465

405Key466Key

406 467

407`features.elevated_windows_sandbox`468`apps.<id>.tools.<tool>.approval_mode`

408 469

409Type / Values470Type / Values

410 471

411`boolean`472`auto | prompt | approve`

412 473

413Details474Details

414 475

415Enable the elevated Windows sandbox pipeline (experimental).476Per-tool approval behavior override for a single app tool.

416 477

417Key478Key

418 479

419`features.experimental_windows_sandbox`480`apps.<id>.tools.<tool>.enabled`

420 481

421Type / Values482Type / Values

422 483

424 485

425Details486Details

426 487

427Run the Windows restricted-token sandbox (experimental).488Per-tool enabled override for an app tool (for example `repos/list`).

428 489

429Key490Key

430 491

431`features.multi_agent`492`background_terminal_max_timeout`

432 493

433Type / Values494Type / Values

434 495

435`boolean`496`number`

436 497

437Details498Details

438 499

439Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).500Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

440 501

441Key502Key

442 503

443`features.personality`504`chatgpt_base_url`

444 505

445Type / Values506Type / Values

446 507

447`boolean`508`string`

448 509

449Details510Details

450 511

451Enable personality selection controls (stable; on by default).512Override the base URL used during the ChatGPT login flow.

452 513

453Key514Key

454 515

455`features.powershell_utf8`516`check_for_update_on_startup`

456 517

457Type / Values518Type / Values

458 519

460 521

461Details522Details

462 523

463Force PowerShell UTF-8 output (defaults to true).524Check for Codex updates on startup (set to false only when updates are centrally managed).

464 525

465Key526Key

466 527

467`features.remote_models`528`cli_auth_credentials_store`

468 529

469Type / Values530Type / Values

470 531

471`boolean`532`file | keyring | auto`

472 533

473Details534Details

474 535

475Refresh remote model list before showing readiness (experimental).536Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).

476 537

477Key538Key

478 539

479`features.request_rule`540`commit_attribution`

480 541

481Type / Values542Type / Values

482 543

483`boolean`544`string`

484 545

485Details546Details

486 547

487Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).548Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

488 549

489Key550Key

490 551

491`features.runtime_metrics`552`compact_prompt`

492 553

493Type / Values554Type / Values

494 555

495`boolean`556`string`

496 557

497Details558Details

498 559

499Show runtime metrics summary in TUI turn separators (experimental).560Inline override for the history compaction prompt.

500 561

501Key562Key

502 563

503`features.search_tool`564`developer_instructions`

504 565

505Type / Values566Type / Values

506 567

507`boolean`568`string`

508 569

509Details570Details

510 571

511Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).572Additional developer instructions injected into the session (optional).

512 573

513Key574Key

514 575

515`features.shell_snapshot`576`disable_paste_burst`

516 577

517Type / Values578Type / Values

518 579

520 581

521Details582Details

522 583

523Snapshot shell environment to speed up repeated commands (beta).584Disable burst-paste detection in the TUI.

524 585

525Key586Key

526 587

527`features.shell_tool`588`experimental_compact_prompt_file`

528 589

529Type / Values590Type / Values

530 591

531`boolean`592`string (path)`

532 593

533Details594Details

534 595

535Enable the default `shell` tool for running commands (stable; on by default).596Load the compaction prompt override from a file (experimental).

536 597

537Key598Key

538 599

539`features.unified_exec`600`experimental_use_unified_exec_tool`

540 601

541Type / Values602Type / Values

542 603

544 605

545Details606Details

546 607

547Use the unified PTY-backed exec tool (beta).608Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

548 609

549Key610Key

550 611

551`features.use_linux_sandbox_bwrap`612`features.apps`

552 613

553Type / Values614Type / Values

554 615

556 617

557Details618Details

558 619

559Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).620Enable ChatGPT Apps/connectors support (experimental).

560 621

561Key622Key

562 623

563`features.web_search`624`features.apps_mcp_gateway`

564 625

565Type / Values626Type / Values

566 627

568 629

569Details630Details

570 631

571Deprecated legacy toggle; prefer the top-level `web_search` setting.632Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

572 633

573Key634Key

574 635

575`features.web_search_cached`636`features.artifact`

576 637

577Type / Values638Type / Values

578 639

580 641

581Details642Details

582 643

583Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.644Enable native artifact tools such as slides and spreadsheets (under development).

584 645

585Key646Key

586 647

587`features.web_search_request`648`features.child_agents_md`

588 649

589Type / Values650Type / Values

590 651

592 653

593Details654Details

594 655

595Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

596 657

597Key658Key

598 659

599`feedback.enabled`660`features.collaboration_modes`

600 661

601Type / Values662Type / Values

602 663

604 665

605Details666Details

606 667

607Enable feedback submission via `/feedback` across Codex surfaces (default: true).668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

608 669

609Key670Key

610 671

611`file_opener`672`features.default_mode_request_user_input`

612 673

613Type / Values674Type / Values

614 675

615`vscode | vscode-insiders | windsurf | cursor | none`676`boolean`

616 677

617Details678Details

618 679

619URI scheme used to open citations from Codex output (default: `vscode`).680Allow `request_user_input` in default collaboration mode (under development; off by default).

620 681

621Key682Key

622 683

623`forced_chatgpt_workspace_id`684`features.elevated_windows_sandbox`

624 685

625Type / Values686Type / Values

626 687

627`string (uuid)`688`boolean`

628 689

629Details690Details

630 691

631Limit ChatGPT logins to a specific workspace identifier.692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

632 693

633Key694Key

634 695

635`forced_login_method`696`features.enable_request_compression`

636 697

637Type / Values698Type / Values

638 699

639`chatgpt | api`700`boolean`

640 701

641Details702Details

642 703

643Restrict Codex to a specific authentication method.704Compress streaming request bodies with zstd when supported (stable; on by default).

644 705

645Key706Key

646 707

647`hide_agent_reasoning`708`features.experimental_windows_sandbox`

648 709

649Type / Values710Type / Values

650 711

652 713

653Details714Details

654 715

655Suppress reasoning events in both the TUI and `codex exec` output.716Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

656 717

657Key718Key

658 719

659`history.max_bytes`720`features.fast_mode`

660 721

661Type / Values722Type / Values

662 723

663`number`724`boolean`

664 725

665Details726Details

666 727

667If set, caps the history file size in bytes by dropping oldest entries.728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

668 729

669Key730Key

670 731

671`history.persistence`732`features.image_detail_original`

672 733

673Type / Values734Type / Values

674 735

675`save-all | none`736`boolean`

676 737

677Details738Details

678 739

679Control whether Codex saves session transcripts to history.jsonl.740Allow image outputs with `detail = "original"` on supported models (under development).

680 741

681Key742Key

682 743

683`include_apply_patch_tool`744`features.image_generation`

684 745

685Type / Values746Type / Values

686 747

688 749

689Details750Details

690 751

691Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.752Enable the built-in image generation tool (under development).

692 753

693Key754Key

694 755

695`instructions`756`features.personality`

696 757

697Type / Values758Type / Values

698 759

699`string`760`boolean`

700 761

701Details762Details

702 763

703Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.764Enable personality selection controls (stable; on by default).

704 765

705Key766Key

706 767

707`log_dir`768`features.powershell_utf8`

708 769

709Type / Values770Type / Values

710 771

711`string (path)`772`boolean`

712 773

713Details774Details

714 775

715Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

716 777

717Key778Key

718 779

719`mcp_oauth_callback_port`780`features.prevent_idle_sleep`

720 781

721Type / Values782Type / Values

722 783

723`integer`784`boolean`

724 785

725Details786Details

726 787

727Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

728 789

729Key790Key

730 791

731`mcp_oauth_credentials_store`792`features.remote_models`

732 793

733Type / Values794Type / Values

734 795

735`auto | file | keyring`796`boolean`

736 797

737Details798Details

738 799

739Preferred store for MCP OAuth credentials.800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

740 801

741Key802Key

742 803

743`mcp_servers.<id>.args`804`features.request_rule`

744 805

745Type / Values806Type / Values

746 807

747`array<string>`808`boolean`

748 809

749Details810Details

750 811

751Arguments passed to the MCP stdio server command.812Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

752 813

753Key814Key

754 815

755`mcp_servers.<id>.bearer_token_env_var`816`features.responses_websockets`

756 817

757Type / Values818Type / Values

758 819

759`string`820`boolean`

760 821

761Details822Details

762 823

763Environment variable sourcing the bearer token for an MCP HTTP server.824Prefer the Responses API WebSocket transport for supported providers (under development).

764 825

765Key826Key

766 827

767`mcp_servers.<id>.command`828`features.responses_websockets_v2`

768 829

769Type / Values830Type / Values

770 831

771`string`832`boolean`

772 833

773Details834Details

774 835

775Launcher command for an MCP stdio server.836Enable Responses API WebSocket v2 mode (under development).

776 837

777Key838Key

778 839

779`mcp_servers.<id>.cwd`840`features.runtime_metrics`

780 841

781Type / Values842Type / Values

782 843

783`string`844`boolean`

784 845

785Details846Details

786 847

787Working directory for the MCP stdio server process.848Show runtime metrics summary in TUI turn separators (experimental).

788 849

789Key850Key

790 851

791`mcp_servers.<id>.disabled_tools`852`features.search_tool`

792 853

793Type / Values854Type / Values

794 855

795`array<string>`856`boolean`

796 857

797Details858Details

798 859

799Deny list applied after `enabled_tools` for the MCP server.860Legacy toggle for an older Apps discovery flow. Current builds do not use it.

800 861

801Key862Key

802 863

803`mcp_servers.<id>.enabled`864`features.shell_snapshot`

804 865

805Type / Values866Type / Values

806 867

808 869

809Details870Details

810 871

811Disable an MCP server without removing its configuration.872Snapshot shell environment to speed up repeated commands (stable; on by default).

812 873

813Key874Key

814 875

815`mcp_servers.<id>.enabled_tools`876`features.shell_tool`

816 877

817Type / Values878Type / Values

818 879

819`array<string>`880`boolean`

820 881

821Details882Details

822 883

823Allow list of tool names exposed by the MCP server.884Enable the default `shell` tool for running commands (stable; on by default).

824 885

825Key886Key

826 887

827`mcp_servers.<id>.env`888`features.skill_env_var_dependency_prompt`

828 889

829Type / Values890Type / Values

830 891

831`map<string,string>`892`boolean`

832 893

833Details894Details

834 895

835Environment variables forwarded to the MCP stdio server.896Prompt for missing skill environment-variable dependencies (under development).

836 897

837Key898Key

838 899

839`mcp_servers.<id>.env_http_headers`900`features.skill_mcp_dependency_install`

840 901

841Type / Values902Type / Values

842 903

843`map<string,string>`904`boolean`

844 905

845Details906Details

846 907

847HTTP headers populated from environment variables for an MCP HTTP server.908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

848 909

849Key910Key

850 911

851`mcp_servers.<id>.env_vars`912`features.sqlite`

852 913

853Type / Values914Type / Values

854 915

855`array<string>`916`boolean`

856 917

857Details918Details

858 919

859Additional environment variables to whitelist for an MCP stdio server.920Enable SQLite-backed state persistence (stable; on by default).

860 921

861Key922Key

862 923

863`mcp_servers.<id>.http_headers`924`features.steer`

864 925

865Type / Values926Type / Values

866 927

867`map<string,string>`928`boolean`

868 929

869Details930Details

870 931

871Static HTTP headers included with each MCP HTTP request.932Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

872 933

873Key934Key

874 935

875`mcp_servers.<id>.required`936`features.undo`

876 937

877Type / Values938Type / Values

878 939

880 941

881Details942Details

882 943

883When true, fail startup/resume if this enabled MCP server cannot initialize.944Enable undo support (stable; off by default).

884 945

885Key946Key

886 947

887`mcp_servers.<id>.startup_timeout_ms`948`features.unified_exec`

888 949

889Type / Values950Type / Values

890 951

891`number`952`boolean`

892 953

893Details954Details

894 955

895Alias for `startup_timeout_sec` in milliseconds.956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

896 957

897Key958Key

898 959

899`mcp_servers.<id>.startup_timeout_sec`960`features.use_linux_sandbox_bwrap`

900 961

901Type / Values962Type / Values

902 963

903`number`964`boolean`

904 965

905Details966Details

906 967

907Override the default 10s startup timeout for an MCP server.968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

908 969

909Key970Key

910 971

911`mcp_servers.<id>.tool_timeout_sec`972`features.web_search`

912 973

913Type / Values974Type / Values

914 975

915`number`976`boolean`

916 977

917Details978Details

918 979

919Override the default 60s per-tool timeout for an MCP server.980Deprecated legacy toggle; prefer the top-level `web_search` setting.

920 981

921Key982Key

922 983

923`mcp_servers.<id>.url`984`features.web_search_cached`

924 985

925Type / Values986Type / Values

926 987

927`string`988`boolean`

928 989

929Details990Details

930 991

931Endpoint for an MCP streamable HTTP server.992Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`.

932 993

933Key994Key

934 995

935`model`996`features.web_search_request`

936 997

937Type / Values998Type / Values

938 999

939`string`1000`boolean`

940 1001

941Details1002Details

942 1003

943Model to use (e.g., `gpt-5-codex`).1004Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`.

944 1005

945Key1006Key

946 1007

947`model_auto_compact_token_limit`1008`feedback.enabled`

948 1009

949Type / Values1010Type / Values

950 1011

951`number`1012`boolean`

952 1013

953Details1014Details

954 1015

955Token threshold that triggers automatic history compaction (unset uses model defaults).1016Enable feedback submission via `/feedback` across Codex surfaces (default: true).

956 1017

957Key1018Key

958 1019

959`model_context_window`1020`file_opener`

960 1021

961Type / Values1022Type / Values

962 1023

963`number`1024`vscode | vscode-insiders | windsurf | cursor | none`

964 1025

965Details1026Details

966 1027

967Context window tokens available to the active model.1028URI scheme used to open citations from Codex output (default: `vscode`).

968 1029

969Key1030Key

970 1031

971`model_instructions_file`1032`forced_chatgpt_workspace_id`

972 1033

973Type / Values1034Type / Values

974 1035

975`string (path)`1036`string (uuid)`

976 1037

977Details1038Details

978 1039

979Replacement for built-in instructions instead of `AGENTS.md`.1040Limit ChatGPT logins to a specific workspace identifier.

980 1041

981Key1042Key

982 1043

983`model_provider`1044`forced_login_method`

984 1045

985Type / Values1046Type / Values

986 1047

987`string`1048`chatgpt | api`

988 1049

989Details1050Details

990 1051

991Provider id from `model_providers` (default: `openai`).1052Restrict Codex to a specific authentication method.

992 1053

993Key1054Key

994 1055

995`model_providers.<id>.base_url`1056`hide_agent_reasoning`

1057

1058Type / Values

1059

1060`boolean`

1061

1062Details

1063

1064Suppress reasoning events in both the TUI and `codex exec` output.

1065

1066Key

1067

1068`history.max_bytes`

1069

1070Type / Values

1071

1072`number`

1073

1074Details

1075

1076If set, caps the history file size in bytes by dropping oldest entries.

1077

1078Key

1079

1080`history.persistence`

1081

1082Type / Values

1083

1084`save-all | none`

1085

1086Details

1087

1088Control whether Codex saves session transcripts to history.jsonl.

1089

1090Key

1091

1092`instructions`

996 1093

997Type / Values1094Type / Values

998 1095

1000 1097

1001Details1098Details

1002 1099

1003API base URL for the model provider.1100Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`.

1004 1101

1005Key1102Key

1006 1103

1007`model_providers.<id>.env_http_headers`1104`log_dir`

1008 1105

1009Type / Values1106Type / Values

1010 1107

1011`map<string,string>`1108`string (path)`

1012 1109

1013Details1110Details

1014 1111

1015HTTP headers populated from environment variables when present.1112Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`.

1016 1113

1017Key1114Key

1018 1115

1019`model_providers.<id>.env_key`1116`mcp_oauth_callback_port`

1117

1118Type / Values

1119

1120`integer`

1121

1122Details

1123

1124Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.

1125

1126Key

1127

1128`mcp_oauth_callback_url`

1020 1129

1021Type / Values1130Type / Values

1022 1131

1024 1133

1025Details1134Details

1026 1135

1027Environment variable supplying the provider API key.1136Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

1028 1137

1029Key1138Key

1030 1139

1031`model_providers.<id>.env_key_instructions`1140`mcp_oauth_credentials_store`

1141

1142Type / Values

1143

1144`auto | file | keyring`

1145

1146Details

1147

1148Preferred store for MCP OAuth credentials.

1149

1150Key

1151

1152`mcp_servers.<id>.args`

1153

1154Type / Values

1155

1156`array<string>`

1157

1158Details

1159

1160Arguments passed to the MCP stdio server command.

1161

1162Key

1163

1164`mcp_servers.<id>.bearer_token_env_var`

1032 1165

1033Type / Values1166Type / Values

1034 1167

1036 1169

1037Details1170Details

1038 1171

1039Optional setup guidance for the provider API key.1172Environment variable sourcing the bearer token for an MCP HTTP server.

1040 1173

1041Key1174Key

1042 1175

1043`model_providers.<id>.experimental_bearer_token`1176`mcp_servers.<id>.command`

1044 1177

1045Type / Values1178Type / Values

1046 1179

1048 1181

1049Details1182Details

1050 1183

1051Direct bearer token for the provider (discouraged; use `env_key`).1184Launcher command for an MCP stdio server.

1052 1185

1053Key1186Key

1054 1187

1055`model_providers.<id>.http_headers`1188`mcp_servers.<id>.cwd`

1189

1190Type / Values

1191

1192`string`

1193

1194Details

1195

1196Working directory for the MCP stdio server process.

1197

1198Key

1199

1200`mcp_servers.<id>.disabled_tools`

1201

1202Type / Values

1203

1204`array<string>`

1205

1206Details

1207

1208Deny list applied after `enabled_tools` for the MCP server.

1209

1210Key

1211

1212`mcp_servers.<id>.enabled`

1213

1214Type / Values

1215

1216`boolean`

1217

1218Details

1219

1220Disable an MCP server without removing its configuration.

1221

1222Key

1223

1224`mcp_servers.<id>.enabled_tools`

1225

1226Type / Values

1227

1228`array<string>`

1229

1230Details

1231

1232Allow list of tool names exposed by the MCP server.

1233

1234Key

1235

1236`mcp_servers.<id>.env`

1056 1237

1057Type / Values1238Type / Values

1058 1239

1060 1241

1061Details1242Details

1062 1243

1063Static HTTP headers added to provider requests.1244Environment variables forwarded to the MCP stdio server.

1064 1245

1065Key1246Key

1066 1247

1067`model_providers.<id>.name`1248`mcp_servers.<id>.env_http_headers`

1068 1249

1069Type / Values1250Type / Values

1070 1251

1071`string`1252`map<string,string>`

1072 1253

1073Details1254Details

1074 1255

1075Display name for a custom model provider.1256HTTP headers populated from environment variables for an MCP HTTP server.

1076 1257

1077Key1258Key

1078 1259

1079`model_providers.<id>.query_params`1260`mcp_servers.<id>.env_vars`

1261

1262Type / Values

1263

1264`array<string>`

1265

1266Details

1267

1268Additional environment variables to whitelist for an MCP stdio server.

1269

1270Key

1271

1272`mcp_servers.<id>.http_headers`

1080 1273

1081Type / Values1274Type / Values

1082 1275

1084 1277

1085Details1278Details

1086 1279

1087Extra query parameters appended to provider requests.1280Static HTTP headers included with each MCP HTTP request.

1088 1281

1089Key1282Key

1090 1283

1091`model_providers.<id>.request_max_retries`1284`mcp_servers.<id>.oauth_resource`

1092 1285

1093Type / Values1286Type / Values

1094 1287

1095`number`1288`string`

1096 1289

1097Details1290Details

1098 1291

1099Retry count for HTTP requests to the provider (default: 4).1292Optional RFC 8707 OAuth resource parameter to include during MCP login.

1100 1293

1101Key1294Key

1102 1295

1103`model_providers.<id>.requires_openai_auth`1296`mcp_servers.<id>.required`

1104 1297

1105Type / Values1298Type / Values

1106 1299

1108 1301

1109Details1302Details

1110 1303

1111The provider uses OpenAI authentication (defaults to false).1304When true, fail startup/resume if this enabled MCP server cannot initialize.

1112 1305

1113Key1306Key

1114 1307

1115`model_providers.<id>.stream_idle_timeout_ms`1308`mcp_servers.<id>.scopes`

1309

1310Type / Values

1311

1312`array<string>`

1313

1314Details

1315

1316OAuth scopes to request when authenticating to that MCP server.

1317

1318Key

1319

1320`mcp_servers.<id>.startup_timeout_ms`

1321

1322Type / Values

1323

1324`number`

1325

1326Details

1327

1328Alias for `startup_timeout_sec` in milliseconds.

1329

1330Key

1331

1332`mcp_servers.<id>.startup_timeout_sec`

1333

1334Type / Values

1335

1336`number`

1337

1338Details

1339

1340Override the default 10s startup timeout for an MCP server.

1341

1342Key

1343

1344`mcp_servers.<id>.tool_timeout_sec`

1345

1346Type / Values

1347

1348`number`

1349

1350Details

1351

1352Override the default 60s per-tool timeout for an MCP server.

1353

1354Key

1355

1356`mcp_servers.<id>.url`

1357

1358Type / Values

1359

1360`string`

1361

1362Details

1363

1364Endpoint for an MCP streamable HTTP server.

1365

1366Key

1367

1368`model`

1369

1370Type / Values

1371

1372`string`

1373

1374Details

1375

1376Model to use (e.g., `gpt-5-codex`).

1377

1378Key

1379

1380`model_auto_compact_token_limit`

1381

1382Type / Values

1383

1384`number`

1385

1386Details

1387

1388Token threshold that triggers automatic history compaction (unset uses model defaults).

1389

1390Key

1391

1392`model_catalog_json`

1393

1394Type / Values

1395

1396`string (path)`

1397

1398Details

1399

1400Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1401

1402Key

1403

1404`model_context_window`

1405

1406Type / Values

1407

1408`number`

1409

1410Details

1411

1412Context window tokens available to the active model.

1413

1414Key

1415

1416`model_instructions_file`

1417

1418Type / Values

1419

1420`string (path)`

1421

1422Details

1423

1424Replacement for built-in instructions instead of `AGENTS.md`.

1425

1426Key

1427

1428`model_provider`

1429

1430Type / Values

1431

1432`string`

1433

1434Details

1435

1436Provider id from `model_providers` (default: `openai`).

1437

1438Key

1439

1440`model_providers.<id>.base_url`

1441

1442Type / Values

1443

1444`string`

1445

1446Details

1447

1448API base URL for the model provider.

1449

1450Key

1451

1452`model_providers.<id>.env_http_headers`

1453

1454Type / Values

1455

1456`map<string,string>`

1457

1458Details

1459

1460HTTP headers populated from environment variables when present.

1461

1462Key

1463

1464`model_providers.<id>.env_key`

1465

1466Type / Values

1467

1468`string`

1469

1470Details

1471

1472Environment variable supplying the provider API key.

1473

1474Key

1475

1476`model_providers.<id>.env_key_instructions`

1477

1478Type / Values

1479

1480`string`

1481

1482Details

1483

1484Optional setup guidance for the provider API key.

1485

1486Key

1487

1488`model_providers.<id>.experimental_bearer_token`

1489

1490Type / Values

1491

1492`string`

1493

1494Details

1495

1496Direct bearer token for the provider (discouraged; use `env_key`).

1497

1498Key

1499

1500`model_providers.<id>.http_headers`

1501

1502Type / Values

1503

1504`map<string,string>`

1505

1506Details

1507

1508Static HTTP headers added to provider requests.

1509

1510Key

1511

1512`model_providers.<id>.name`

1513

1514Type / Values

1515

1516`string`

1517

1518Details

1519

1520Display name for a custom model provider.

1521

1522Key

1523

1524`model_providers.<id>.query_params`

1525

1526Type / Values

1527

1528`map<string,string>`

1529

1530Details

1531

1532Extra query parameters appended to provider requests.

1533

1534Key

1535

1536`model_providers.<id>.request_max_retries`

1537

1538Type / Values

1539

1540`number`

1541

1542Details

1543

1544Retry count for HTTP requests to the provider (default: 4).

1545

1546Key

1547

1548`model_providers.<id>.requires_openai_auth`

1549

1550Type / Values

1551

1552`boolean`

1553

1554Details

1555

1556The provider uses OpenAI authentication (defaults to false).

1557

1558Key

1559

1560`model_providers.<id>.stream_idle_timeout_ms`

1561

1562Type / Values

1563

1564`number`

1565

1566Details

1567

1568Idle timeout for SSE streams in milliseconds (default: 300000).

1569

1570Key

1571

1572`model_providers.<id>.stream_max_retries`

1573

1574Type / Values

1575

1576`number`

1577

1578Details

1579

1580Retry count for SSE streaming interruptions (default: 5).

1581

1582Key

1583

1584`model_providers.<id>.supports_websockets`

1585

1586Type / Values

1587

1588`boolean`

1589

1590Details

1591

1592Whether that provider supports the Responses API WebSocket transport.

1593

1594Key

1595

1596`model_providers.<id>.wire_api`

1597

1598Type / Values

1599

1600`responses`

1601

1602Details

1603

1604Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1605

1606Key

1607

1608`model_reasoning_effort`

1609

1610Type / Values

1611

1612`minimal | low | medium | high | xhigh`

1613

1614Details

1615

1616Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).

1617

1618Key

1619

1620`model_reasoning_summary`

1621

1622Type / Values

1623

1624`auto | concise | detailed | none`

1625

1626Details

1627

1628Select reasoning summary detail or disable summaries entirely.

1629

1630Key

1631

1632`model_supports_reasoning_summaries`

1633

1634Type / Values

1635

1636`boolean`

1637

1638Details

1639

1640Force Codex to send or not send reasoning metadata.

1641

1642Key

1643

1644`model_verbosity`

1645

1646Type / Values

1647

1648`low | medium | high`

1649

1650Details

1651

1652Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1653

1654Key

1655

1656`notice.hide_full_access_warning`

1657

1658Type / Values

1659

1660`boolean`

1661

1662Details

1663

1664Track acknowledgement of the full access warning prompt.

1665

1666Key

1667

1668`notice.hide_gpt-5.1-codex-max_migration_prompt`

1669

1670Type / Values

1671

1672`boolean`

1673

1674Details

1675

1676Track acknowledgement of the gpt-5.1-codex-max migration prompt.

1677

1678Key

1679

1680`notice.hide_gpt5_1_migration_prompt`

1681

1682Type / Values

1683

1684`boolean`

1685

1686Details

1687

1688Track acknowledgement of the GPT-5.1 migration prompt.

1689

1690Key

1691

1692`notice.hide_rate_limit_model_nudge`

1693

1694Type / Values

1695

1696`boolean`

1697

1698Details

1699

1700Track opt-out of the rate limit model switch reminder.

1701

1702Key

1703

1704`notice.hide_world_writable_warning`

1705

1706Type / Values

1707

1708`boolean`

1709

1710Details

1711

1712Track acknowledgement of the Windows world-writable directories warning.

1713

1714Key

1715

1716`notice.model_migrations`

1717

1718Type / Values

1719

1720`map<string,string>`

1721

1722Details

1723

1724Track acknowledged model migrations as old->new mappings.

1725

1726Key

1727

1728`notify`

1729

1730Type / Values

1731

1732`array<string>`

1733

1734Details

1735

1736Command invoked for notifications; receives a JSON payload from Codex.

1737

1738Key

1739

1740`oss_provider`

1741

1742Type / Values

1743

1744`lmstudio | ollama`

1745

1746Details

1747

1748Default local provider used when running with `--oss` (defaults to prompting if unset).

1749

1750Key

1751

1752`otel.environment`

1753

1754Type / Values

1755

1756`string`

1757

1758Details

1759

1760Environment tag applied to emitted OpenTelemetry events (default: `dev`).

1761

1762Key

1763

1764`otel.exporter`

1765

1766Type / Values

1767

1768`none | otlp-http | otlp-grpc`

1769

1770Details

1771

1772Select the OpenTelemetry exporter and provide any endpoint metadata.

1773

1774Key

1775

1776`otel.exporter.<id>.endpoint`

1777

1778Type / Values

1779

1780`string`

1781

1782Details

1783

1784Exporter endpoint for OTEL logs.

1785

1786Key

1787

1788`otel.exporter.<id>.headers`

1789

1790Type / Values

1791

1792`map<string,string>`

1793

1794Details

1795

1796Static headers included with OTEL exporter requests.

1797

1798Key

1799

1800`otel.exporter.<id>.protocol`

1801

1802Type / Values

1803

1804`binary | json`

1805

1806Details

1807

1808Protocol used by the OTLP/HTTP exporter.

1809

1810Key

1811

1812`otel.exporter.<id>.tls.ca-certificate`

1813

1814Type / Values

1815

1816`string`

1817

1818Details

1819

1820CA certificate path for OTEL exporter TLS.

1821

1822Key

1823

1824`otel.exporter.<id>.tls.client-certificate`

1116 1825

1117Type / Values1826Type / Values

1118 1827

1119`number`1828`string`

1120 1829

1121Details1830Details

1122 1831

1123Idle timeout for SSE streams in milliseconds (default: 300000).1832Client certificate path for OTEL exporter TLS.

1124 1833

1125Key1834Key

1126 1835

1127`model_providers.<id>.stream_max_retries`1836`otel.exporter.<id>.tls.client-private-key`

1128 1837

1129Type / Values1838Type / Values

1130 1839

1131`number`1840`string`

1132 1841

1133Details1842Details

1134 1843

1135Retry count for SSE streaming interruptions (default: 5).1844Client private key path for OTEL exporter TLS.

1136 1845

1137Key1846Key

1138 1847

1139`model_providers.<id>.wire_api`1848`otel.log_user_prompt`

1140 1849

1141Type / Values1850Type / Values

1142 1851

1143`chat | responses`1852`boolean`

1144 1853

1145Details1854Details

1146 1855

1147Protocol used by the provider (defaults to `chat` if omitted).1856Opt in to exporting raw user prompts with OpenTelemetry logs.

1148 1857

1149Key1858Key

1150 1859

1151`model_reasoning_effort`1860`otel.metrics_exporter`

1152 1861

1153Type / Values1862Type / Values

1154 1863

1156 1865

1157Details1866Details

1158 1867

1159Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).1868Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1160 1869

1161Key1870Key

1162 1871

1163`model_reasoning_summary`1872`otel.trace_exporter`

1164 1873

1165Type / Values1874Type / Values

1166 1875

1168 1877

1169Details1878Details

1170 1879

1171Select reasoning summary detail or disable summaries entirely.1880Select the OpenTelemetry trace exporter and provide any endpoint metadata.

1172 1881

1173Key1882Key

1174 1883

1175`model_supports_reasoning_summaries`1884`otel.trace_exporter.<id>.endpoint`

1176 1885

1177Type / Values1886Type / Values

1178 1887

1179`boolean`1888`string`

1180 1889

1181Details1890Details

1182 1891

1183Force Codex to send or not send reasoning metadata.1892Trace exporter endpoint for OTEL logs.

1184 1893

1185Key1894Key

1186 1895

1187`model_verbosity`1896`otel.trace_exporter.<id>.headers`

1188 1897

1189Type / Values1898Type / Values

1190 1899

1191`low | medium | high`1900`map<string,string>`

1192 1901

1193Details1902Details

1194 1903

1195Control GPT-5 Responses API verbosity (defaults to `medium`).1904Static headers included with OTEL trace exporter requests.

1196 1905

1197Key1906Key

1198 1907

1199`notice.hide_full_access_warning`1908`otel.trace_exporter.<id>.protocol`

1200 1909

1201Type / Values1910Type / Values

1202 1911

1203`boolean`1912`binary | json`

1204 1913

1205Details1914Details

1206 1915

1207Track acknowledgement of the full access warning prompt.1916Protocol used by the OTLP/HTTP trace exporter.

1208 1917

1209Key1918Key

1210 1919

1211`notice.hide_gpt-5.1-codex-max_migration_prompt`1920`otel.trace_exporter.<id>.tls.ca-certificate`

1212 1921

1213Type / Values1922Type / Values

1214 1923

1215`boolean`1924`string`

1216 1925

1217Details1926Details

1218 1927

1219Track acknowledgement of the gpt-5.1-codex-max migration prompt.1928CA certificate path for OTEL trace exporter TLS.

1220 1929

1221Key1930Key

1222 1931

1223`notice.hide_gpt5_1_migration_prompt`1932`otel.trace_exporter.<id>.tls.client-certificate`

1224 1933

1225Type / Values1934Type / Values

1226 1935

1227`boolean`1936`string`

1228 1937

1229Details1938Details

1230 1939

1231Track acknowledgement of the GPT-5.1 migration prompt.1940Client certificate path for OTEL trace exporter TLS.

1232 1941

1233Key1942Key

1234 1943

1235`notice.hide_rate_limit_model_nudge`1944`otel.trace_exporter.<id>.tls.client-private-key`

1236 1945

1237Type / Values1946Type / Values

1238 1947

1239`boolean`1948`string`

1240 1949

1241Details1950Details

1242 1951

1243Track opt-out of the rate limit model switch reminder.1952Client private key path for OTEL trace exporter TLS.

1244 1953

1245Key1954Key

1246 1955

1247`notice.hide_world_writable_warning`1956`permissions.network.admin_url`

1248 1957

1249Type / Values1958Type / Values

1250 1959

1251`boolean`1960`string`

1252 1961

1253Details1962Details

1254 1963

1255Track acknowledgement of the Windows world-writable directories warning.1964Admin endpoint for the managed network proxy.

1256 1965

1257Key1966Key

1258 1967

1259`notice.model_migrations`1968`permissions.network.allow_local_binding`

1260 1969

1261Type / Values1970Type / Values

1262 1971

1263`map<string,string>`1972`boolean`

1264 1973

1265Details1974Details

1266 1975

1267Track acknowledged model migrations as old->new mappings.1976Permit local bind/listen operations through the managed proxy.

1268 1977

1269Key1978Key

1270 1979

1271`notify`1980`permissions.network.allow_unix_sockets`

1272 1981

1273Type / Values1982Type / Values

1274 1983

1276 1985

1277Details1986Details

1278 1987

1279Command invoked for notifications; receives a JSON payload from Codex.1988Allowlist of Unix socket paths permitted through the managed proxy.

1280 1989

1281Key1990Key

1282 1991

1283`oss_provider`1992`permissions.network.allow_upstream_proxy`

1284 1993

1285Type / Values1994Type / Values

1286 1995

1287`lmstudio | ollama`1996`boolean`

1288 1997

1289Details1998Details

1290 1999

1291Default local provider used when running with `--oss` (defaults to prompting if unset).2000Allow the managed proxy to chain to another upstream proxy.

1292 2001

1293Key2002Key

1294 2003

1295`otel.environment`2004`permissions.network.allowed_domains`

1296 2005

1297Type / Values2006Type / Values

1298 2007

1299`string`2008`array<string>`

1300 2009

1301Details2010Details

1302 2011

1303Environment tag applied to emitted OpenTelemetry events (default: `dev`).2012Allowlist of domains permitted through the managed proxy.

1304 2013

1305Key2014Key

1306 2015

1307`otel.exporter`2016`permissions.network.dangerously_allow_all_unix_sockets`

1308 2017

1309Type / Values2018Type / Values

1310 2019

1311`none | otlp-http | otlp-grpc`2020`boolean`

1312 2021

1313Details2022Details

1314 2023

1315Select the OpenTelemetry exporter and provide any endpoint metadata.2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

1316 2025

1317Key2026Key

1318 2027

1319`otel.exporter.<id>.endpoint`2028`permissions.network.dangerously_allow_non_loopback_admin`

1320 2029

1321Type / Values2030Type / Values

1322 2031

1323`string`2032`boolean`

1324 2033

1325Details2034Details

1326 2035

1327Exporter endpoint for OTEL logs.2036Permit non-loopback bind addresses for the managed proxy admin listener.

1328 2037

1329Key2038Key

1330 2039

1331`otel.exporter.<id>.headers`2040`permissions.network.dangerously_allow_non_loopback_proxy`

1332 2041

1333Type / Values2042Type / Values

1334 2043

1335`map<string,string>`2044`boolean`

1336 2045

1337Details2046Details

1338 2047

1339Static headers included with OTEL exporter requests.2048Permit non-loopback bind addresses for the managed proxy listener.

1340 2049

1341Key2050Key

1342 2051

1343`otel.exporter.<id>.protocol`2052`permissions.network.denied_domains`

1344 2053

1345Type / Values2054Type / Values

1346 2055

1347`binary | json`2056`array<string>`

1348 2057

1349Details2058Details

1350 2059

1351Protocol used by the OTLP/HTTP exporter.2060Denylist of domains blocked by the managed proxy.

1352 2061

1353Key2062Key

1354 2063

1355`otel.exporter.<id>.tls.ca-certificate`2064`permissions.network.enable_socks5`

1356 2065

1357Type / Values2066Type / Values

1358 2067

1359`string`2068`boolean`

1360 2069

1361Details2070Details

1362 2071

1363CA certificate path for OTEL exporter TLS.2072Expose a SOCKS5 listener from the managed network proxy.

1364 2073

1365Key2074Key

1366 2075

1367`otel.exporter.<id>.tls.client-certificate`2076`permissions.network.enable_socks5_udp`

1368 2077

1369Type / Values2078Type / Values

1370 2079

1371`string`2080`boolean`

1372 2081

1373Details2082Details

1374 2083

1375Client certificate path for OTEL exporter TLS.2084Allow UDP over the SOCKS5 listener when enabled.

1376 2085

1377Key2086Key

1378 2087

1379`otel.exporter.<id>.tls.client-private-key`2088`permissions.network.enabled`

1380 2089

1381Type / Values2090Type / Values

1382 2091

1383`string`2092`boolean`

1384 2093

1385Details2094Details

1386 2095

1387Client private key path for OTEL exporter TLS.2096Enable the managed network proxy configuration for subprocesses.

1388 2097

1389Key2098Key

1390 2099

1391`otel.log_user_prompt`2100`permissions.network.mode`

1392 2101

1393Type / Values2102Type / Values

1394 2103

1395`boolean`2104`limited | full`

1396 2105

1397Details2106Details

1398 2107

1399Opt in to exporting raw user prompts with OpenTelemetry logs.2108Network proxy mode used for subprocess traffic.

1400 2109

1401Key2110Key

1402 2111

1403`otel.trace_exporter`2112`permissions.network.proxy_url`

1404 2113

1405Type / Values2114Type / Values

1406 2115

1407`none | otlp-http | otlp-grpc`2116`string`

1408 2117

1409Details2118Details

1410 2119

1411Select the OpenTelemetry trace exporter and provide any endpoint metadata.2120HTTP proxy endpoint used by the managed network proxy.

1412 2121

1413Key2122Key

1414 2123

1415`otel.trace_exporter.<id>.endpoint`2124`permissions.network.socks_url`

1416 2125

1417Type / Values2126Type / Values

1418 2127

1420 2129

1421Details2130Details

1422 2131

1423Trace exporter endpoint for OTEL logs.2132SOCKS5 proxy endpoint used by the managed network proxy.

1424 2133

1425Key2134Key

1426 2135

1427`otel.trace_exporter.<id>.headers`2136`personality`

1428 2137

1429Type / Values2138Type / Values

1430 2139

1431`map<string,string>`2140`none | friendly | pragmatic`

1432 2141

1433Details2142Details

1434 2143

1435Static headers included with OTEL trace exporter requests.2144Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.

1436 2145

1437Key2146Key

1438 2147

1439`otel.trace_exporter.<id>.protocol`2148`plan_mode_reasoning_effort`

1440 2149

1441Type / Values2150Type / Values

1442 2151

1444 2153

1445Details2154Details

1446 2155

1447Protocol used by the OTLP/HTTP trace exporter.2156Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

1448 2157

1449Key2158Key

1450 2159

1451`otel.trace_exporter.<id>.tls.ca-certificate`2160`profile`

1452 2161

1453Type / Values2162Type / Values

1454 2163

1456 2165

1457Details2166Details

1458 2167

1459CA certificate path for OTEL trace exporter TLS.2168Default profile applied at startup (equivalent to `--profile`).

1460 2169

1461Key2170Key

1462 2171

1463`otel.trace_exporter.<id>.tls.client-certificate`2172`profiles.<name>.*`

1464 2173

1465Type / Values2174Type / Values

1466 2175

1467`string`2176`various`

1468 2177

1469Details2178Details

1470 2179

1471Client certificate path for OTEL trace exporter TLS.2180Profile-scoped overrides for any of the supported configuration keys.

1472 2181

1473Key2182Key

1474 2183

1475`otel.trace_exporter.<id>.tls.client-private-key`2184`profiles.<name>.analytics.enabled`

1476 2185

1477Type / Values2186Type / Values

1478 2187

1479`string`2188`boolean`

1480 2189

1481Details2190Details

1482 2191

1483Client private key path for OTEL trace exporter TLS.2192Profile-scoped analytics enablement override.

1484 2193

1485Key2194Key

1486 2195

1487`personality`2196`profiles.<name>.experimental_use_unified_exec_tool`

1488 2197

1489Type / Values2198Type / Values

1490 2199

1491`none | friendly | pragmatic`2200`boolean`

1492 2201

1493Details2202Details

1494 2203

1495Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.2204Legacy name for enabling unified exec; prefer `[features].unified_exec`.

1496 2205

1497Key2206Key

1498 2207

1499`profile`2208`profiles.<name>.model_catalog_json`

1500 2209

1501Type / Values2210Type / Values

1502 2211

1503`string`2212`string (path)`

1504 2213

1505Details2214Details

1506 2215

1507Default profile applied at startup (equivalent to `--profile`).2216Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1508 2217

1509Key2218Key

1510 2219

1511`profiles.<name>.*`2220`profiles.<name>.model_instructions_file`

1512 2221

1513Type / Values2222Type / Values

1514 2223

1515`various`2224`string (path)`

1516 2225

1517Details2226Details

1518 2227

1519Profile-scoped overrides for any of the supported configuration keys.2228Profile-scoped replacement for the built-in instruction file.

1520 2229

1521Key2230Key

1522 2231

1523`profiles.<name>.experimental_use_freeform_apply_patch`2232`profiles.<name>.oss_provider`

1524 2233

1525Type / Values2234Type / Values

1526 2235

1527`boolean`2236`lmstudio | ollama`

1528 2237

1529Details2238Details

1530 2239

1531Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2240Profile-scoped OSS provider for `--oss` sessions.

1532 2241

1533Key2242Key

1534 2243

1535`profiles.<name>.experimental_use_unified_exec_tool`2244`profiles.<name>.personality`

1536 2245

1537Type / Values2246Type / Values

1538 2247

1539`boolean`2248`none | friendly | pragmatic`

1540 2249

1541Details2250Details

1542 2251

1543Legacy name for enabling unified exec; prefer `[features].unified_exec`.2252Profile-scoped communication style override for supported models.

1544 2253

1545Key2254Key

1546 2255

1547`profiles.<name>.include_apply_patch_tool`2256`profiles.<name>.plan_mode_reasoning_effort`

1548 2257

1549Type / Values2258Type / Values

1550 2259

1552 2261

1553Details2262Details

1554 2263

1555Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2264Profile-scoped Plan-mode reasoning override.

1556 2265

1557Key2266Key

1558 2267

1559`profiles.<name>.oss_provider`2268`profiles.<name>.service_tier`

1560 2269

1561Type / Values2270Type / Values

1562 2271

1563`lmstudio | ollama`2272`flex | fast`

1564 2273

1565Details2274Details

1566 2275

1567Profile-scoped OSS provider for `--oss` sessions.2276Profile-scoped service tier preference for new turns.

1568 2277

1569Key2278Key

1570 2279

1571`profiles.<name>.personality`2280`profiles.<name>.tools_view_image`

1572 2281

1573Type / Values2282Type / Values

1574 2283

1575`none | friendly | pragmatic`2284`boolean`

1576 2285

1577Details2286Details

1578 2287

1579Profile-scoped communication style override for supported models.2288Enable or disable the `view_image` tool in that profile.

1580 2289

1581Key2290Key

1582 2291

1592 2301

1593Key2302Key

1594 2303

2304`profiles.<name>.windows.sandbox`

2305

2306Type / Values

2307

2308`unelevated | elevated`

2309

2310Details

2311

2312Profile-scoped Windows sandbox mode override.

2313

2314Key

2315

1595`project_doc_fallback_filenames`2316`project_doc_fallback_filenames`

1596 2317

1597Type / Values2318Type / Values

1712 2433

1713Key2434Key

1714 2435

2436`service_tier`

2437

2438Type / Values

2439

2440`flex | fast`

2441

2442Details

2443

2444Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.

2445

2446Key

2447

1715`shell_environment_policy.exclude`2448`shell_environment_policy.exclude`

1716 2449

1717Type / Values2450Type / Values

1832 2565

1833Key2566Key

1834 2567

2568`sqlite_home`

2569

2570Type / Values

2571

2572`string (path)`

2573

2574Details

2575

2576Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

2577

2578Key

2579

1835`suppress_unstable_features_warning`2580`suppress_unstable_features_warning`

1836 2581

1837Type / Values2582Type / Values

1856 2601

1857Key2602Key

1858 2603

2604`tools.view_image`

2605

2606Type / Values

2607

2608`boolean`

2609

2610Details

2611

2612Enable the local-image attachment tool `view_image`.

2613

2614Key

2615

1859`tools.web_search`2616`tools.web_search`

1860 2617

1861Type / Values2618Type / Values

1904 2661

1905Key2662Key

1906 2663

2664`tui.model_availability_nux.<model>`

2665

2666Type / Values

2667

2668`integer`

2669

2670Details

2671

2672Internal startup-tooltip state keyed by model slug.

2673

2674Key

2675

1907`tui.notification_method`2676`tui.notification_method`

1908 2677

1909Type / Values2678Type / Values

1952 2721

1953Key2722Key

1954 2723

2724`tui.theme`

2725

2726Type / Values

2727

2728`string`

2729

2730Details

2731

2732Syntax-highlighting theme override (kebab-case theme name).

2733

2734Key

2735

1955`web_search`2736`web_search`

1956 2737

1957Type / Values2738Type / Values

1974 2755

1975Track Windows onboarding acknowledgement (Windows only).2756Track Windows onboarding acknowledgement (Windows only).

1976 2757

2758Key

2759

2760`windows.sandbox`

2761

2762Type / Values

2763

2764`unelevated | elevated`

2765

2766Details

2767

2768Windows-only native sandbox mode when running Codex natively on Windows.

2769

1977Expand to view all2770Expand to view all

1978 2771

1979You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2772You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

1988 2781

1989## `requirements.toml`2782## `requirements.toml`

1990 2783

1991`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).2784`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

1992 2785

1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2786For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

1994requirements. See the security page for precedence details.2787requirements. See the security page for precedence details.

1995 2788

2789Use `[features]` in `requirements.toml` to pin feature flags by the same

2790canonical keys that `config.toml` uses. Omitted keys remain unconstrained.

2791

1996| Key | Type / Values | Details |2792| Key | Type / Values | Details |

1997| --- | --- | --- |2793| --- | --- | --- |

2000| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2796| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2797| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2798| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2001| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2799| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2020 2818

2021Details2819Details

2022 2820

2023Allowed values for `approval\_policy`.2821Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).

2024 2822

2025Key2823Key

2026 2824

2048 2846

2049Key2847Key

2050 2848

2849`features`

2850

2851Type / Values

2852

2853`table`

2854

2855Details

2856

2857Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

2858

2859Key

2860

2861`features.<name>`

2862

2863Type / Values

2864

2865`boolean`

2866

2867Details

2868

2869Require a specific canonical feature key to stay enabled or disabled.

2870

2871Key

2872

2051`mcp_servers`2873`mcp_servers`

2052 2874

2053Type / Values2875Type / Values

config-sample.md +187 −109

Details

1# Sample Configuration1# Sample Configuration

2 2

~~3Use this example configuration as a starting point. It includes most keys Codex reads from `config.toml`, along with defaults and short notes.~~3Use this example configuration as a starting point. It includes most keys Codex reads from `config.toml`, along with default behaviors, recommended values where helpful, and short notes.

4 4

5For explanations and guidance, see:5For explanations and guidance, see:

6 6

7- [Config basics](https://developers.openai.com/codex/config-basic)7- [Config basics](https://developers.openai.com/codex/config-basic)

8- [Advanced Config](https://developers.openai.com/codex/config-advanced)8- [Advanced Config](https://developers.openai.com/codex/config-advanced)

9- [Config Reference](https://developers.openai.com/codex/config-reference)9- [Config Reference](https://developers.openai.com/codex/config-reference)

~~10- [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals)~~10- [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals)

~~11- [Managed configuration](https://developers.openai.com/codex/security#managed-configuration)~~11- [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)

12 12

13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.13Use the snippet below as a reference. Copy only the keys and sections you need into `~/.codex/config.toml` (or into a project-scoped `.codex/config.toml`), then adjust values for your setup.

14 14

15```toml15```toml

16# Codex example configuration (config.toml)16# Codex example configuration (config.toml)

17#17#

~~18# This file lists all keys Codex reads from config.toml, their default values,~~18# This file lists the main keys Codex reads from config.toml, along with default

~~19# and concise explanations. Values here mirror the effective defaults compiled~~19# behaviors, recommended examples, and concise explanations. Adjust as needed.

~~20# into the CLI. Adjust as needed.~~

21#20#

22# Notes21# Notes

23# - Root keys must appear before tables in TOML.22# - Root keys must appear before tables in TOML.

28# Core Model Selection27# Core Model Selection

29################################################################################28################################################################################

30 29

~~31# Primary model used by Codex. Default: "gpt-5.2-codex" on all platforms.~~30# Primary model used by Codex. Recommended example for most users: "gpt-5.4".

~~32model = "gpt-5.2-codex"~~31model = "gpt-5.4"

33 32

~~34# Default communication style for supported models. Default: "friendly".~~33# Communication style for supported models. Allowed values: none | friendly | pragmatic

~~35# Allowed values: none | friendly | pragmatic~~34# personality = "pragmatic"

~~36# personality = "friendly"~~

37 35

38# Optional model override for /review. Default: unset (uses current session model).36# Optional model override for /review. Default: unset (uses current session model).

~~39# review_model = "gpt-5.2-codex"~~37# review_model = "gpt-5.4"

40 38

41# Provider id selected from [model_providers]. Default: "openai".39# Provider id selected from [model_providers]. Default: "openai".

42model_provider = "openai"40model_provider = "openai"

44# 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.

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

46 44

~~47# Optional manual model metadata. When unset, Codex auto-detects from model.~~45# Preferred service tier. `fast` is honored only when enabled in [features].

~~48# Uncomment to force values.~~46# service_tier = "flex" # fast | flex

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

~~50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults~~50# model_auto_compact_token_limit = 64000 # tokens; unset uses model defaults

~~51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex~~51# tool_output_token_limit = 12000 # tokens stored per tool output

52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override

53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

52# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"

55# sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory

53 56

54################################################################################57################################################################################

55# Reasoning & Verbosity (Responses API capable models)58# Reasoning & Verbosity (Responses API capable models)

56################################################################################59################################################################################

57 60

~~59model_reasoning_effort = "medium"~~62# model_reasoning_effort = "medium"

65# plan_mode_reasoning_effort = "high"

60 66

62# model_reasoning_summary = "auto"68# model_reasoning_summary = "auto"

63 69

~~64# Text verbosity for GPT-5 family (Responses API): low | medium | high (default: medium)~~70# Text verbosity for GPT-5 family (Responses API): low | medium | high

65# model_verbosity = "medium"71# model_verbosity = "medium"

66 72

~~67# Force enable or disable reasoning summaries for current model~~73# Force enable or disable reasoning summaries for current model.

68# model_supports_reasoning_summaries = true74# model_supports_reasoning_summaries = true

69 75

70################################################################################76################################################################################

74# Additional user instructions are injected before AGENTS.md. Default: unset.80# Additional user instructions are injected before AGENTS.md. Default: unset.

75# developer_instructions = ""81# developer_instructions = ""

76 82

~~77# (Ignored) Optional legacy base instructions override (prefer AGENTS.md). Default: unset.~~

~~78# instructions = ""~~

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

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

82 85

86# Override the default commit co-author trailer. Set to "" to disable it.

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

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

84# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"90# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

85 91

~~86# Migration note: experimental_instructions_file was renamed to model_instructions_file (deprecated).~~

88# Load the compact prompt override from a file. Default: unset.92# Load the compact prompt override from a file. Default: unset.

89# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"93# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"

90 94

~~91# Legacy name for apply_patch_freeform. Default: false~~

~~92include_apply_patch_tool = false~~

94################################################################################95################################################################################

95# Notifications96# Notifications

96################################################################################97################################################################################

97 98

98# External notifier program (argv array). When unset: disabled.99# External notifier program (argv array). When unset: disabled.

~~99# Example: notify = ["notify-send", "Codex"]~~100# notify = ["notify-send", "Codex"]

100notify = [ ]

101 101

102################################################################################102################################################################################

103# Approval & Sandbox103# Approval & Sandbox

107# - untrusted: only known-safe read-only commands auto-run; others prompt107# - untrusted: only known-safe read-only commands auto-run; others prompt

108# - on-request: model decides when to ask (default)108# - on-request: model decides when to ask (default)

109# - never: never prompt (risky)109# - never: never prompt (risky)

110# - { reject = { ... } }: auto-reject selected prompt categories

110approval_policy = "on-request"111approval_policy = "on-request"

112# Example granular auto-reject policy:

113# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

114

115# Allow login-shell semantics for shell-based tools when they request `login = true`.

116# Default: true. Set false to force non-login shells and reject explicit login-shell requests.

117allow_login_shell = true

111 118

112# Filesystem/network sandbox policy for tool calls:119# Filesystem/network sandbox policy for tool calls:

113# - read-only (default)120# - read-only (default)

122# Where to persist CLI login credentials: file (default) | keyring | auto129# Where to persist CLI login credentials: file (default) | keyring | auto

123cli_auth_credentials_store = "file"130cli_auth_credentials_store = "file"

124 131

125# Base URL for ChatGPT auth flow (not OpenAI API). Default:132# Base URL for ChatGPT auth flow (not OpenAI API).

126chatgpt_base_url = "https://chatgpt.com/backend-api/"133chatgpt_base_url = "https://chatgpt.com/backend-api/"

127 134

128# Restrict ChatGPT login to a specific workspace id. Default: unset.135# Restrict ChatGPT login to a specific workspace id. Default: unset.

129# forced_chatgpt_workspace_id = ""136# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

130 137

131# Force login mechanism when Codex would normally auto-select. Default: unset.138# Force login mechanism when Codex would normally auto-select. Default: unset.

132# Allowed values: chatgpt | api139# Allowed values: chatgpt | api

134 141

135# Preferred store for MCP OAuth credentials: auto (default) | file | keyring142# Preferred store for MCP OAuth credentials: auto (default) | file | keyring

136mcp_oauth_credentials_store = "auto"143mcp_oauth_credentials_store = "auto"

~~137~~

138# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.144# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.

139# mcp_oauth_callback_port = 4321145# mcp_oauth_callback_port = 4321

146# Optional redirect URI override for MCP OAuth login (for example, remote devbox ingress).

147# Custom callback paths are supported. `mcp_oauth_callback_port` still controls the listener port.

148# mcp_oauth_callback_url = "https://devbox.example.internal/callback"

140 149

141################################################################################150################################################################################

142# Project Documentation Controls151# Project Documentation Controls

187# If you use --yolo or another full access sandbox setting, web search defaults to live.196# If you use --yolo or another full access sandbox setting, web search defaults to live.

188web_search = "cached"197web_search = "cached"

189 198

199# Active profile name. When unset, no profile is applied.

200# profile = "default"

201

202# Suppress the warning shown when under-development feature flags are enabled.

203# suppress_unstable_features_warning = true

204

190################################################################################205################################################################################

191# Profiles (named presets)206# Agents (multi-agent roles and limits)

192################################################################################207################################################################################

193 208

194# Active profile name. When unset, no profile is applied.209[agents]

195# profile = "default"210# Maximum concurrently open agent threads. Default: 6

211# max_threads = 6

212# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

213# max_depth = 1

214# Default timeout per worker for spawn_agents_on_csv jobs. When unset, the tool defaults to 1800 seconds.

215# job_max_runtime_seconds = 1800

216

217# [agents.reviewer]

218# description = "Find correctness, security, and test risks in code."

219# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

220# nickname_candidates = ["Athena", "Ada"]

196 221

197################################################################################222################################################################################

198# Skills (per-skill overrides)223# Skills (per-skill overrides)

200 225

201# Disable or re-enable a specific skill without deleting it.226# Disable or re-enable a specific skill without deleting it.

202[[skills.config]]227[[skills.config]]

203# path = "/path/to/skill"228# path = "/path/to/skill/SKILL.md"

204# enabled = false229# enabled = false

205 230

206################################################################################

207# Experimental toggles (legacy; prefer [features])

208################################################################################

~~209~~

210experimental_use_unified_exec_tool = false

~~211~~

212# Include apply_patch via freeform editing path (affects default tool set). Default: false

213experimental_use_freeform_apply_patch = false

~~214~~

215################################################################################231################################################################################

216# Sandbox settings (tables)232# Sandbox settings (tables)

217################################################################################233################################################################################

234[shell_environment_policy]250[shell_environment_policy]

235# inherit: all (default) | core | none251# inherit: all (default) | core | none

236inherit = "all"252inherit = "all"

237# Skip default excludes for names containing KEY/SECRET/TOKEN (case-insensitive). Default: true253# Skip default excludes for names containing KEY/SECRET/TOKEN (case-insensitive). Default: false

238ignore_default_excludes = true254ignore_default_excludes = false

239# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []255# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []

240exclude = []256exclude = []

241# Explicit key/value overrides (always win). Default: {}257# Explicit key/value overrides (always win). Default: {}

245# Experimental: run via user shell profile. Default: false261# Experimental: run via user shell profile. Default: false

246experimental_use_profile = false262experimental_use_profile = false

247 263

264################################################################################

265# Managed network proxy settings

266################################################################################

267

268[permissions.network]

269# enabled = true

270# proxy_url = "http://127.0.0.1:43128"

271# admin_url = "http://127.0.0.1:43129"

272# enable_socks5 = false

273# socks_url = "http://127.0.0.1:43130"

274# enable_socks5_udp = false

275# allow_upstream_proxy = false

276# dangerously_allow_non_loopback_proxy = false

277# dangerously_allow_non_loopback_admin = false

278# dangerously_allow_all_unix_sockets = false

279# mode = "limited" # limited | full

280# allowed_domains = ["api.openai.com"]

281# denied_domains = ["example.com"]

282# allow_unix_sockets = ["/var/run/docker.sock"]

283# allow_local_binding = false

284

248################################################################################285################################################################################

249# History (table)286# History (table)

250################################################################################287################################################################################

253# save-all (default) | none290# save-all (default) | none

254persistence = "save-all"291persistence = "save-all"

255# Maximum bytes for history file; oldest entries are trimmed when exceeded. Example: 5242880292# Maximum bytes for history file; oldest entries are trimmed when exceeded. Example: 5242880

256# max_bytes = 0293# max_bytes = 5242880

257 294

258################################################################################295################################################################################

259# UI, Notifications, and Misc (tables)296# UI, Notifications, and Misc (tables)

276# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).313# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).

277# alternate_screen = "auto"314# alternate_screen = "auto"

278 315

279# Ordered list of footer status-line item IDs. Default: null (disabled).316# Ordered list of footer status-line item IDs. When unset, Codex uses:

317# ["model-with-reasoning", "context-remaining", "current-dir"].

318# Set to [] to hide the footer.

280# status_line = ["model", "context-remaining", "git-branch"]319# status_line = ["model", "context-remaining", "git-branch"]

281 320

321# Syntax-highlighting theme (kebab-case). Use /theme in the TUI to preview and save.

322# You can also add custom .tmTheme files under $CODEX_HOME/themes.

323# theme = "catppuccin-mocha"

324

325# Internal tooltip state keyed by model slug. Usually managed by Codex.

326# [tui.model_availability_nux]

327# "gpt-5.4" = 1

328

329# Enable or disable analytics for this machine. When unset, Codex uses its default behavior.

330[analytics]

331enabled = true

332

282# Control whether users can submit feedback from `/feedback`. Default: true333# Control whether users can submit feedback from `/feedback`. Default: true

283[feedback]334[feedback]

284enabled = true335enabled = true

292# "hide_gpt-5.1-codex-max_migration_prompt" = true343# "hide_gpt-5.1-codex-max_migration_prompt" = true

293# model_migrations = { "gpt-4.1" = "gpt-5.1" }344# model_migrations = { "gpt-4.1" = "gpt-5.1" }

294 345

295# Suppress the warning shown when under-development feature flags are enabled.

296# suppress_unstable_features_warning = true

~~297~~

298################################################################################346################################################################################

299# Centralized Feature Flags (preferred)347# Centralized Feature Flags (preferred)

300################################################################################348################################################################################

301 349

302[features]350[features]

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

304shell_tool = true352# shell_tool = true

305# apps = false353# apps = false

306# apps_mcp_gateway = false354# apps_mcp_gateway = false

307# Deprecated legacy toggles; prefer the top-level `web_search` setting.355# unified_exec = false

308# web_search = false356# shell_snapshot = false

309# web_search_cached = false

310# web_search_request = false

311unified_exec = false

312shell_snapshot = false

313apply_patch_freeform = false

314# search_tool = false

315# personality = true357# personality = true

316request_rule = true358# use_linux_sandbox_bwrap = false

317collaboration_modes = true359# runtime_metrics = true

318use_linux_sandbox_bwrap = false360# powershell_utf8 = true

319experimental_windows_sandbox = false361# child_agents_md = false

320elevated_windows_sandbox = false362# sqlite = true

321remote_models = false363# fast_mode = true

322runtime_metrics = false364# enable_request_compression = true

323powershell_utf8 = true365# image_generation = false

324child_agents_md = false366# skill_mcp_dependency_install = true

367# skill_env_var_dependency_prompt = false

368# default_mode_request_user_input = false

369# artifact = false

370# prevent_idle_sleep = false

371# responses_websockets = false

372# responses_websockets_v2 = false

373# image_detail_original = false

325 374

326################################################################################375################################################################################

327# Define MCP servers under this table. Leave empty to disable.376# Define MCP servers under this table. Leave empty to disable.

343# tool_timeout_sec = 60.0 # optional; default 60.0 seconds392# tool_timeout_sec = 60.0 # optional; default 60.0 seconds

344# enabled_tools = ["search", "summarize"] # optional allow-list393# enabled_tools = ["search", "summarize"] # optional allow-list

345# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)394# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)

395# scopes = ["read:docs"] # optional OAuth scopes

396# oauth_resource = "https://docs.example.com/" # optional OAuth resource

346 397

347# --- Example: Streamable HTTP transport ---398# --- Example: Streamable HTTP transport ---

348# [mcp_servers.github]399# [mcp_servers.github]

355# startup_timeout_sec = 10.0 # optional406# startup_timeout_sec = 10.0 # optional

356# tool_timeout_sec = 60.0 # optional407# tool_timeout_sec = 60.0 # optional

357# enabled_tools = ["list_issues"] # optional allow-list408# enabled_tools = ["list_issues"] # optional allow-list

409# disabled_tools = ["delete_issue"] # optional deny-list

410# scopes = ["repo"] # optional OAuth scopes

358 411

359################################################################################412################################################################################

360# Model Providers413# Model Providers

361################################################################################414################################################################################

362 415

363# Built-ins include:416# Built-ins include:

364# - openai (Responses API; requires login or OPENAI_API_KEY via auth flow)417# - openai

365# - oss (Chat Completions API; defaults to http://localhost:11434/v1)418# - ollama

419# - lmstudio

366 420

367[model_providers]421[model_providers]

368 422

370# [model_providers.openaidr]424# [model_providers.openaidr]

371# name = "OpenAI Data Residency"425# name = "OpenAI Data Residency"

372# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix426# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix

373# wire_api = "responses" # "responses" | "chat" (default varies)427# wire_api = "responses" # only supported value

374# # requires_openai_auth = true # built-in OpenAI defaults to true428# # requires_openai_auth = true # built-in OpenAI defaults to true

375# # request_max_retries = 4 # default 4; max 100429# # request_max_retries = 4 # default 4; max 100

376# # stream_max_retries = 5 # default 5; max 100430# # stream_max_retries = 5 # default 5; max 100

377# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)431# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)

432# # supports_websockets = true # optional

378# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token433# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token

379# # http_headers = { "X-Example" = "value" }434# # http_headers = { "X-Example" = "value" }

380# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }435# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }

381 436

382# --- Example: Azure (Chat/Responses depending on endpoint) ---437# --- Example: Azure/OpenAI-compatible provider ---

383# [model_providers.azure]438# [model_providers.azure]

384# name = "Azure"439# name = "Azure"

385# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"440# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"

386# wire_api = "responses" # or "chat" per endpoint441# wire_api = "responses"

387# query_params = { api-version = "2025-04-01-preview" }442# query_params = { api-version = "2025-04-01-preview" }

388# env_key = "AZURE_OPENAI_API_KEY"443# env_key = "AZURE_OPENAI_API_KEY"

389# # env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"444# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

445# # supports_websockets = false

390 446

391# --- Example: Local OSS (e.g., Ollama-compatible) ---447# --- Example: Local OSS (e.g., Ollama-compatible) ---

392# [model_providers.ollama]448# [model_providers.ollama]

393# name = "Ollama"449# name = "Ollama"

394# base_url = "http://localhost:11434/v1"450# base_url = "http://localhost:11434/v1"

395# wire_api = "chat"451# wire_api = "responses"

452

453################################################################################

454# Apps / Connectors

455################################################################################

456

457# Optional per-app controls.

458[apps]

459# [_default] applies to all apps unless overridden per app.

460# [apps._default]

461# enabled = true

462# destructive_enabled = true

463# open_world_enabled = true

464#

465# [apps.google_drive]

466# enabled = false

467# destructive_enabled = false # block destructive-hint tools for this app

468# default_tools_enabled = true

469# default_tools_approval_mode = "prompt" # auto | prompt | approve

470#

471# [apps.google_drive.tools."files/delete"]

472# enabled = false

473# approval_mode = "approve"

396 474

397################################################################################475################################################################################

398# Profiles (named presets)476# Profiles (named presets)

401[profiles]479[profiles]

402 480

403# [profiles.default]481# [profiles.default]

404# model = "gpt-5.2-codex"482# model = "gpt-5.4"

405# model_provider = "openai"483# model_provider = "openai"

406# approval_policy = "on-request"484# approval_policy = "on-request"

407# sandbox_mode = "read-only"485# sandbox_mode = "read-only"

486# service_tier = "flex"

408# oss_provider = "ollama"487# oss_provider = "ollama"

409# model_reasoning_effort = "medium"488# model_reasoning_effort = "medium"

489# plan_mode_reasoning_effort = "high"

410# model_reasoning_summary = "auto"490# model_reasoning_summary = "auto"

411# model_verbosity = "medium"491# model_verbosity = "medium"

412# personality = "friendly" # or "pragmatic" or "none"492# personality = "pragmatic" # or "friendly" or "none"

413# chatgpt_base_url = "https://chatgpt.com/backend-api/"493# chatgpt_base_url = "https://chatgpt.com/backend-api/"

494# model_catalog_json = "./models.json"

495# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

414# experimental_compact_prompt_file = "./compact_prompt.txt"496# experimental_compact_prompt_file = "./compact_prompt.txt"

415# include_apply_patch_tool = false497# tools_view_image = true

416# experimental_use_unified_exec_tool = false

417# experimental_use_freeform_apply_patch = false

418# tools.web_search = false # deprecated legacy alias; prefer top-level `web_search`

419# features = { unified_exec = false }498# features = { unified_exec = false }

420 499

421################################################################################

422# Apps / Connectors

423################################################################################

~~424~~

425# Optional per-app controls.

426[apps]

427# [apps.google_drive]

428# enabled = false

429# disabled_reason = "user" # or "unknown"

~~430~~

431################################################################################500################################################################################

432# Projects (trust levels)501# Projects (trust levels)

433################################################################################502################################################################################

434 503

435# Mark specific worktrees as trusted or untrusted.

436[projects]504[projects]

505# Mark specific worktrees as trusted or untrusted.

437# [projects."/absolute/path/to/project"]506# [projects."/absolute/path/to/project"]

438# trust_level = "trusted" # or "untrusted"507# trust_level = "trusted" # or "untrusted"

439 508

509################################################################################

510# Tools

511################################################################################

512

513[tools]

514# view_image = true

515

440################################################################################516################################################################################

441# OpenTelemetry (OTEL) - disabled by default517# OpenTelemetry (OTEL) - disabled by default

442################################################################################518################################################################################

450exporter = "none"526exporter = "none"

451# Trace exporter: none (default) | otlp-http | otlp-grpc527# Trace exporter: none (default) | otlp-http | otlp-grpc

452trace_exporter = "none"528trace_exporter = "none"

529# Metrics exporter: none | statsig | otlp-http | otlp-grpc

530metrics_exporter = "statsig"

453 531

454# Example OTLP/HTTP exporter configuration532# Example OTLP/HTTP exporter configuration

455# [otel.exporter."otlp-http"]533# [otel.exporter."otlp-http"]

459# [otel.exporter."otlp-http".headers]537# [otel.exporter."otlp-http".headers]

460# "x-otlp-api-key" = "${OTLP_TOKEN}"538# "x-otlp-api-key" = "${OTLP_TOKEN}"

461 539

462# Example OTLP/gRPC exporter configuration

463# [otel.exporter."otlp-grpc"]

464# endpoint = "https://otel.example.com:4317",

465# headers = { "x-otlp-meta" = "abc123" }

~~466~~

467# Example OTLP exporter with mutual TLS

468# [otel.exporter."otlp-http"]

469# endpoint = "https://otel.example.com/v1/logs"

470# protocol = "binary"

~~471~~

472# [otel.exporter."otlp-http".headers]

473# "x-otlp-api-key" = "${OTLP_TOKEN}"

~~474~~

475# [otel.exporter."otlp-http".tls]540# [otel.exporter."otlp-http".tls]

476# ca-certificate = "certs/otel-ca.pem"541# ca-certificate = "certs/otel-ca.pem"

477# client-certificate = "/etc/codex/certs/client.pem"542# client-certificate = "/etc/codex/certs/client.pem"

478# client-private-key = "/etc/codex/certs/client-key.pem"543# client-private-key = "/etc/codex/certs/client-key.pem"

544

545# Example OTLP/gRPC trace exporter configuration

546# [otel.trace_exporter."otlp-grpc"]

547# endpoint = "https://otel.example.com:4317"

548# headers = { "x-otlp-meta" = "abc123" }

549

550################################################################################

551# Windows

552################################################################################

553

554[windows]

555# Native Windows sandbox mode (Windows only): unelevated | elevated

556sandbox = "unelevated"

479```557```

enterprise/admin-setup.md +299 −86

Details

1# Admin Setup1# Admin Setup

2 2

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

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

4 6

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

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

6 10

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

8 12

9- No training on enterprise data13- No training on enterprise data

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

~~11- Residency and retention follow ChatGPT Enterprise policies~~15- Residency and retention that follow ChatGPT Enterprise policies

12- Granular user access controls16- Granular user access controls

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

18- Audit logging via the ChatGPT Compliance API

14 19

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

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

16 22

~~17## Local vs. cloud setup~~23## Pre-requisites: Determine owners and rollout strategy

18 24

~~19Codex operates in two environments: local and cloud.~~25During your rollout, team members may support different aspects of integrating Codex into your organization. Ensure you have the following owners:

20 26

~~211. Local use includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.~~27- **ChatGPT Enterprise workspace owner:** required to configure Codex settings in your workspace.

222. Use in the cloud includes Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack). The agent runs remotely in a hosted container with your codebase.28- **Security owner:** determines agent permissions settings for Codex.

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

23 30

~~24Use separate permissions and role-based access control (RBAC) to control access to local and cloud features. You can enable local, cloud, or both for all users or for specific groups.~~31Decide which Codex surfaces you will use:

25 32

~~26## Codex local setup~~33- **Codex local:** includes the Codex app, CLI, and IDE extension. The agent runs on the developer's computer in a sandbox.

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

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

27 36

~~28### Enable Codex app, CLI, and IDE extension in workspace settings~~37You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

29 38

30To enable Codex locally for workspace members, go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings). Turn on **Allow members to use Codex Local**. This setting doesn’t require the GitHub connector.39## Step 1: Enable Codex in your workspace

31 40

32After you turn this on, users can sign in to use the Codex app, CLI, and IDE extension with their ChatGPT account. If you turn off this setting, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”41You configure access to Codex in ChatGPT Enterprise workspace settings.

33 42

~~34## Team Config~~43Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

35 44

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

37 46

~~38| Type | Path | Use it to |~~47Codex local is enabled by default for new ChatGPT Enterprise workspaces. If

~~39| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |~~48 you are not a ChatGPT workspace owner, you can test whether you have access by

~~40| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |~~49 [installing Codex](https://developers.openai.com/codex/quickstart) and logging in with your work email.

~~41| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |~~

~~42| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |~~

43 50

~~44For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).~~51Turn on **Allow members to use Codex Local**.

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

55If 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.”

57#### Enable device code authentication for Codex CLI

45 58

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

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

63### Codex cloud

47 64

48### Prerequisites65### Prerequisites

49 66

57 74

58Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).75Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

59 76

~~60To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**.~~77To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**. Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.

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

81#### Enable Codex Slack app to post answers on task completion

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

85To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).

87#### Enable Codex agent to access the internet

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

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

61 92

~~62Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.~~93For security implications of internet access and runtime controls, see [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

63 94

64![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)95![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)

65 96

~~66After you turn on Codex in your Enterprise workspace settings, it may take up~~97## Step 2: Set up custom roles (RBAC)

~~67to 10 minutes for Codex to appear in ChatGPT.~~

68 98

~~69### Configure the GitHub Connector IP allow list~~99Use RBAC to control granular permissions for access Codex local and Codex cloud.

70 100

~~71To control which IP addresses can connect to your ChatGPT GitHub connector, configure these IP ranges:~~101![Codex cloud toggle](/images/codex/enterprise/rbac_custom_roles.png)

72 102

~~73- [ChatGPT egress IP ranges](https://openai.com/chatgpt-actions.json)~~103### What RBAC lets you do

~~74- [Codex container egress IP ranges](https://openai.com/chatgpt-agents.json)~~

75 104

~~76These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.~~105Workspace Owners can use RBAC in ChatGPT admin settings to:

77 106

~~78### Allow members to administer Codex~~107- Set a default role for users who aren't assigned any custom role

108- Create custom roles with granular permissions

109- Assign one or more custom roles to Groups

110- Automatically sync users into Groups via SCIM

111- Manage roles centrally from the Custom Roles tab

79 112

~~80This toggle allows users to view Codex workspace analytics and manage environments (edit and delete).~~113Users can inherit more than one role, and permissions resolve to the most permissive (least restrictive) access across those roles.

81 114

~~82Codex supports role-based access (see [Role-based access (RBAC)](#role-based-access-rbac)), so you can turn on this toggle for a specific subset of users.~~115### Create a Codex Admin group

83 116

~~84### Enable Codex Slack app to post answers on task completion~~117Set up a dedicated "Codex Admin" group rather than granting Codex administration to a broad audience.

85 118

~~86Codex integrates with Slack. When a user mentions `@Codex` in Slack, Codex starts a cloud task, gets context from the Slack thread, and responds with a link to a PR to review in the thread.~~119The **Allow members to administer Codex** toggle grants the Codex Admin role. Codex Admins can:

87 120

88To allow the Slack app to post answers on task completion, turn on **Allow Codex Slack app to post answers on task completion**. When enabled, Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.121- View Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics)

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

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

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

89 125

~~90To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).~~126Use this role for the small set of admins who own Codex rollout, policy management, and governance. It's not required for general Codex users. You don't need Codex cloud to enable this toggle.

91 127

~~92### Enable Codex agent to access the internet~~128Recommended rollout pattern:

93 129

~~94By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.~~130- Create a "Codex Users" group for people who should use Codex

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

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

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

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

135

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

137

138## Step 3: Configure Codex local requirements

139

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

141

142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.

143

144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

145

146Recommended setup:

147

1481. Create a baseline policy for most users, then create stricter or more permissive variants only where needed.

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

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

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

152

153These cloud-managed policies apply across Codex local surfaces when users sign in with ChatGPT, including the Codex app, CLI, and IDE extension.

154

155### Example requirements.toml policies

156

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

95 158

~~96As an admin, you can allow users to enable agent internet access in their environments. To enable it, turn on **Allow Codex agent to access the internet**.~~159![Example managed requirements policy](/images/codex/enterprise/example_policy.png)

160

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

162

163```toml

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

165allowed_sandbox_modes = ["workspace-write"]

166allowed_approval_policies = ["on-request"]

167```

168

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

170

171```toml

172[rules]

173prefix_rules = [

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

175]

176```

177

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

179

180### Checking user policies

181

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

183

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

185

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

187

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

189

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

97 191

~~98When this setting is on, users can use an allow list for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.~~192You can check Team Config settings into the repository under the `.codex` directory. Codex automatically picks up Team Config settings when a user opens that repository.

193

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

195

196| Type | Path | Use it to |

197| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

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

199| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |

200| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |

201

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

203

204## Step 5: Configure Codex cloud usage (if enabled)

205

206This step covers repository and environment setup after you enable the Codex cloud workspace toggle.

207

208### Connect Codex cloud to repositories

209

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

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

2123. Install or connect the ChatGPT GitHub Connector

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

2145. Allow the repositories you want to connect to Codex

215

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

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

218 repositories in Codex cloud.

219

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

221

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

223

224### Configure IP addresses

225

226If your GitHub organization controls the IP addresses that apps use to connect, make sure to include these [egress IP ranges](https://openai.com/chatgpt-agents.json).

227

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

99 229

100### Enable code review with Codex cloud230### Enable code review with Codex cloud

101 231

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

233

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

235

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

237

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

239

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

241 requests automatically for connected repositories.

242

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

244

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

246 Codex review.

247

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

249

250### Configure Codex security

251

252Codex Security helps engineering and security teams find, confirm, and remediate likely vulnerabilities in connected GitHub repositories.

253

254At a high level, Codex Security:

255

256- scans connected repositories commit by commit

257- ranks likely findings and confirms them when possible

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

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

260

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

262

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

264

265## Step 6: Set up governance and observability

266

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

268

269### Codex governance typically uses

270

271- Analytics Dashboard for quick, self-serve visibility

272- Analytics API for programmatic reporting and business intelligence integration

273- Compliance API for audit and investigation workflows

274

275### Recommended baseline setup

276

277- Assign an owner for adoption reporting

278- Assign an owner for audit and compliance review

279- Define a review cadence

280- Decide what success looks like

281

282### Analytics API setup steps

283

284To set up the Analytics API key:

285

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

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

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

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

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

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

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

293

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

295

296To use the Analytics API key:

297

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

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

3003. Choose the endpoint you want to query:

301

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

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

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

305

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

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

103 308

104Users can specify whether they want Codex to review their pull requests. Users can also configure whether code review runs for all contributors to a repository.309Example curl command to retrieve workspace usage:

105 310

106Codex supports two types of code reviews:311```bash

312curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \

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

314```

107 315

1081. Automatically triggered code reviews when a user opens a PR for review.316For more details on the Analytics API, see [Analytics API](https://developers.openai.com/codex/enterprise/governance#analytics-api).

1092. Reactive code reviews when a user mentions @Codex to look at issues. For example, “@Codex fix this CI error” or “@Codex address that feedback.”

110 317

111## Role-based access (RBAC)318### Compliance API setup steps

112 319

113Codex supports role-based access. RBAC is a security and permissions model used to control access to systems or resources based on a user’s role assignments.320To set up the Compliance API key:

114 321

115To enable RBAC for Codex, navigate to Settings & Permissions → Custom Roles in [ChatGPT’s admin page](https://chatgpt.com/admin/settings) and assign roles to groups created in the Groups tab.3221. Sign in to the [OpenAI API Platform Portal](https://platform.openai.com) as an owner or admin, and select the correct organization.

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

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

3254. Choose All permissions.

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

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

116 328

117This simplifies permission management for Codex and improves security in your ChatGPT workspace. To learn more, see the [Help Center article](https://help.openai.com/en/articles/11750701-rbac).329- the last 4 digits of the API key

330- the key name

331- the created-by name

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

118 333

119## Set up your first Codex cloud environment3347. Wait for OpenAI to confirm your API key has Compliance API access.

120 335

1211. Go to Codex cloud and select **Get started**.336To use the Compliance API key:

1222. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven’t already connected GitHub to ChatGPT.

123 - Allow the ChatGPT Connector for your account.

124 - Choose an installation target for the ChatGPT Connector (typically your main organization).

125 - Allow the repositories you want to connect to Codex (a GitHub admin may need to approve this).

1263. Create your first environment by selecting the repository most relevant to your developers, then select **Create environment**.

127 - Add the email addresses of any environment collaborators to give them edit access.

1284. Start a few starter tasks (for example, writing tests, fixing bugs, or exploring code).

129 337

130You have now created your first environment. Users who connect to GitHub can create tasks using this environment. Users who have access to the repository can also push pull requests generated from their tasks.3381. Find your `workspace_id` in the [ChatGPT Admin console](https://chatgpt.com/admin) under Workspace details.

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

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

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

131 342

132### Environment management343- /compliance/workspaces/`{workspace_id}`/logs

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

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

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

133 347

134As a ChatGPT workspace administrator, you can edit and delete Codex environments in your workspace.3485. For most Codex compliance integrations, start with the logs endpoint and request Codex event types such as CODEX_LOG or CODEX_SECURITY_LOG.

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

135 350

136### Connect more GitHub repositories with Codex cloud351Example curl command to list compliance log files:

137 352

1381. Select **Environments**, or open the environment selector and select **Manage Environments**.353```bash

1392. Select **Create Environment**.354curl -L -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

1403. Select the repository you want to connect.355 "https://api.chatgpt.com/v1/compliance/workspaces/WORKSPACE_ID/logs?event_type=CODEX_LOG&after=2026-03-01T00:00:00Z"

1414. Enter a name and description.356```

1425. Select the environment visibility.

1436. Select **Create Environment**.

144 357

145Codex automatically optimizes your environment setup by reviewing your codebase. Avoid advanced environment configuration until you observe specific performance issues. For more, see [Codex cloud](https://developers.openai.com/codex/cloud).358Example curl command to list Codex tasks:

146 359

147### Share setup instructions with users360```bash

361curl -H "Authorization: Bearer YOUR_COMPLIANCE_API_KEY" \

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

363```

148 364

149You can share these steps with end users:365For more details on the Compliance API, see [Compliance API](https://developers.openai.com/codex/enterprise/governance#compliance-api).

150 366

1511. Go to [Codex](https://chatgpt.com/codex) in the left-hand panel of ChatGPT.367## Step 7: Confirm and verify setup

1522. Select **Connect to GitHub** in the prompt composer if you’re not already connected.

153 - Sign in to GitHub.

1543. You can now use shared environments with your workspace or create your own environment.

1554. Try a task in both Ask and Code mode. For example:

156 - Ask: Find bugs in this codebase.

157 - Write code: Improve test coverage following the existing test patterns.

158 368

159## Track Codex usage369### What to verify

160 370

161- For workspaces with rate limits, use [Settings → Usage](https://chatgpt.com/codex/settings/usage) to view workspace metrics for Codex.371- Users can sign in to Codex local (ChatGPT or API key)

162- For more detail on enterprise governance, refer to the [Governance](https://developers.openai.com/codex/enterprise/governance) page.372- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)

163- For enterprise workspaces with flexible pricing, you can see credit usage in the ChatGPT workspace billing console.373- MFA and SSO requirements match your enterprise security policy

374- RBAC and workspace toggles produce the expected access behavior

375- Managed configuration applies for users

376- Governance data is visible for admins

164 377

165## Zero data retention (ZDR)378For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).

166 379

167Codex supports OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled.380Once your team is confident with setup, you can roll Codex out to more teams and organizations.

enterprise/governance.md +2 −0

Details

88 88

89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.

90 90

91For Codex usage authenticated through ChatGPT, Compliance API exports provide audit records for Codex activity and can be used in investigations and compliance workflows. These audit logs are retained for up to 30 days. API-key-authenticated Codex usage follows your API organization settings and is not included in Compliance API exports.

91### What you can export93### What you can export

92 94

93#### Activity logs95#### Activity logs

enterprise/managed-configuration.md +192 −0 added

Details

1# Managed configuration

3Enterprise admins can control local Codex behavior in two ways:

5- **Requirements**: admin-enforced constraints that users can't override.

6- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

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

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

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

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

16### Locations and precedence

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

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

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

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

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

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

28### Cloud-managed requirements

30When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also fetch admin-enforced requirements from the Codex service. This is another source of `requirements.toml`-compatible requirements. This applies across Codex surfaces, including the CLI, App, and IDE Extension.

32#### Configure cloud-managed requirements

34Go to the [Codex managed-config page](https://chatgpt.com/codex/settings/managed-configs).

36Create a new managed requirements file using the same format and keys as `requirements.toml`.

38```toml

39enforce_residency = "us"

40allowed_approval_policies = ["on-request"]

41allowed_sandbox_modes = ["read-only", "workspace-write"]

43[rules]

44prefix_rules = [

45 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entrypoints" },

46]

47```

49Save the configuration. Once saved, the updated managed requirements apply immediately for matching users.

50For more examples, see [Example requirements.toml](#example-requirementstoml).

52#### Assign requirements to groups

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

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

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

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

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

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

66### Example requirements.toml

68This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

70```toml

71allowed_approval_policies = ["untrusted", "on-request"]

72allowed_sandbox_modes = ["read-only", "workspace-write"]

73```

75You can also constrain web search mode:

77```toml

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

79```

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

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

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

86```

87[features]

88personality = true

89unified_exec = false

90```

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

94### Enforce command rules from requirements

96Admins can also enforce restrictive command rules from `requirements.toml`

97using a `[rules]` table. These rules merge with regular `.rules` files, and the

98most restrictive decision still wins.

100Unlike `.rules`, requirements rules must specify `decision`, and that decision

101must be `"prompt"` or `"forbidden"` (not `"allow"`).

102

103```toml

104[rules]

105prefix_rules = [

106 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

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

108]

109```

110

111To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

112

113```toml

114[mcp_servers.docs]

115identity = { command = "codex-mcp" }

116

117[mcp_servers.remote]

118identity = { url = "https://example.com/mcp" }

119```

120

121If `mcp_servers` is present but empty, Codex disables all MCP servers.

122

123## Managed defaults (`managed_config.toml`)

124

125Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

126

127Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

128

129### Precedence and layering

130

131Codex assembles the effective configuration in this order (top overrides bottom):

132

133- Managed preferences (macOS MDM; highest precedence)

134- `managed_config.toml` (system/managed file)

135- `config.toml` (user's base configuration)

136

137CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

138

139Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.

140

141### Locations

142

143- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

144- Windows/non-Unix: `~/.codex/managed_config.toml`

145

146If the file is missing, Codex skips the managed layer.

147

148### macOS managed preferences (MDM)

149

150On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

151

152- Preference domain: `com.openai.codex`

153- Keys:

154 - `config_toml_base64` (managed defaults)

155 - `requirements_toml_base64` (requirements)

156

157Codex parses these "managed preferences" payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above. The same requirements-side `[features]` table works in `requirements_toml_base64`; use canonical feature keys there as well.

158

159### MDM setup workflow

160

161Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

162

1631. Build the managed payload TOML and encode it with `base64` (no wrapping).

1642. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

1653. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

1664. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

167

168Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

169

170### Example managed_config.toml

171

172```toml

173# Set conservative defaults

174approval_policy = "on-request"

175sandbox_mode = "workspace-write"

176

177[sandbox_workspace_write]

178network_access = false # keep network disabled unless explicitly allowed

179

180[otel]

181environment = "prod"

182exporter = "otlp-http" # point at your collector

183log_user_prompt = false # keep prompts redacted

184# exporter details live under exporter tables; see Monitoring and telemetry above

185```

186

187### Recommended guardrails

188

189- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

190- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

191- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

192- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

ide.md +1 −0

Details

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

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

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

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

67 68

68---69---

69 70

ide/features.md +1 −1

Details

57 57

58## Web search58## Web search

59 59

60Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex enables web search by default and serves results from a web search cache. 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 configure your sandbox for [full access](https://developers.openai.com/codex/security), web search defaults to live results. See [Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the most recent data.60Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex enables web search by default and serves results from a web search cache. 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 configure your sandbox for [full access](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. See [Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the most recent data.

61 61

62You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.62You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.

63 63

integrations/linear.md +1 −1

Details

62 62

63When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a task.63When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a task.

64Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).64Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

~~65For more on security, see the [Codex security documentation](https://developers.openai.com/codex/security).~~65For more on security, see the [Codex security documentation](https://developers.openai.com/codex/agent-approvals-security).

66 66

67Codex uses large language models that can make mistakes. Always review answers and diffs.67Codex uses large language models that can make mistakes. Always review answers and diffs.

68 68

integrations/slack.md +1 −1

Details

31 31

32When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a task.32When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a task.

33Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).33Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

~~34For more on security, see the Codex [security documentation](https://developers.openai.com/codex/security).~~34For more on security, see the Codex [security documentation](https://developers.openai.com/codex/agent-approvals-security).

35 35

36Codex uses large language models that can make mistakes. Always review answers and diffs.36Codex uses large language models that can make mistakes. Always review answers and diffs.

37 37

learn/best-practices.md +223 −0 added

Details

1# Best practices

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

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

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

9## Strong first use: Context and prompts

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

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

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

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

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

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

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

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

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

26- Low for faster, well-scoped tasks

27- Medium or High for more complex changes or debugging

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

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

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

33## Plan first for difficult tasks

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

37A few approaches work well:

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

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

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

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

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

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

51A good `AGENTS.md` covers:

53- repo layout and important directories

54- How to run the project

55- Build, test, and lint commands

56- Engineering conventions and PR expectations

57- Constraints and do-not rules

58- What done means and how to verify work

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

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

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

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

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

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

71## Configure Codex for consistency

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

75A good starting pattern is:

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

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

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

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

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

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

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

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

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

91 wrong model defaults, or missing tools and connectors.

93## Improve reliability with testing and review

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

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

99That can include:

100

101- Writing or updating tests for the change

102- Running the right test suites

103- Checking lint, formatting, or type checks

104- Confirming the final behavior matches the request

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

106

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

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

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

110

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

112

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

114- Review uncommitted changes

115- Review a commit

116- Use custom review instructions

117

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

119

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

121

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

123

124## Use MCPs for external context

125

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

127

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

129

130Use MCP when:

131

132- The needed context lives outside the repo

133- The data changes frequently

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

135- You need a repeatable integration across users or projects

136

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

138

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

140

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

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

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

144

145## Turn repeatable work into skills

146

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

148

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

150

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

152

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

154

155Skills are especially useful for recurring jobs like:

156

157- Log triage

158- Release note drafting

159- PR review against a checklist

160- Migration planning

161- Telemetry or incident summaries

162- Standard debugging flows

163

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

165

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

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

168 helpful for onboarding new teammates.

169

170## Use automations for repeated work

171

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

173

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

175

176Good candidates include:

177

178- Summarizing recent commits

179- Scanning for likely bugs

180- Drafting release notes

181- Checking CI failures

182- Producing standup summaries

183- Running repeatable analysis workflows on a schedule

184

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

186

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

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

189 instructions, or workflow setup over time.

190

191## Organize long-running work with session controls

192

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

194

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

196

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

198- `/resume` to resume a saved conversation

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

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

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

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

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

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

205

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

207

208Use Codex’s [subagent](https://developers.openai.com/codex/concepts/subagents) workflows to offload bounded

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

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

211

212## Common mistakes

213

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

215

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

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

218- Skipping planning on multi-step and complex tasks

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

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

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

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

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

mcp.md +9 −1

Details

75- `enabled_tools` (optional): Tool allow list.75- `enabled_tools` (optional): Tool allow list.

76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).

77 77

~~78If your OAuth provider requires a static callback URI, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.~~78If 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.

80If your MCP OAuth flow must use a specific callback URL (for example, a remote devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on loopback; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

79 81

80#### config.toml examples82#### config.toml examples

81 83

88MY_ENV_VAR = "MY_ENV_VALUE"90MY_ENV_VAR = "MY_ENV_VALUE"

89```91```

90 92

93```toml

94# Optional MCP OAuth callback overrides (used by `codex mcp login`)

95mcp_oauth_callback_port = 5555

96mcp_oauth_callback_url = "https://devbox.example.internal/callback"

97```

91```toml99```toml

92[mcp_servers.figma]100[mcp_servers.figma]

93url = "https://mcp.figma.com/mcp"101url = "https://mcp.figma.com/mcp"

models.md +32 −20

Details

2 2

3## Recommended models3## Recommended models

4 4

~~5![gpt-5.3-codex](/images/codex/codex-wallpaper-1.webp)~~5![gpt-5.4](/images/api/models/gpt-5.4.jpg)

6 6

~~7gpt-5.3-codex~~7gpt-5.4

8 8

~~9Most capable agentic coding model to date, combining frontier coding performance with stronger reasoning and professional knowledge capabilities.~~9Flagship frontier model for professional work that brings the industry-leading coding capabilities of GPT-5.3-Codex together with stronger reasoning, tool use, and agentic workflows.

10 10

~~11codex -m gpt-5.3-codex~~11codex -m gpt-5.4

12 12

13Copy command13Copy command

14 14

26 26

27API Access27API Access

28 28

~~29![gpt-5.3-codex-spark](/images/codex/codex-wallpaper-2.webp)~~29![gpt-5.3-codex](/images/codex/codex-wallpaper-1.webp)

30 30

~~31gpt-5.3-codex-spark~~31gpt-5.3-codex

32 32

~~33Text-only research preview model optimized for near-instant, real-time coding iteration. Available to ChatGPT Pro users.~~33Industry-leading coding model for complex software engineering. Its coding capabilities now also power GPT-5.4.

34 34

~~35codex -m gpt-5.3-codex-spark~~35codex -m gpt-5.3-codex

36 36

37Copy command37Copy command

38 38

50 50

51API Access51API Access

52 52

~~53![gpt-5.2-codex](/images/codex/gpt-5.2-codex.png)~~53![gpt-5.3-codex-spark](/images/codex/codex-wallpaper-2.webp)

54 54

~~55gpt-5.2-codex~~55gpt-5.3-codex-spark

56 56

~~57Advanced coding model for real-world engineering. Succeeded by GPT-5.3-Codex.~~57Text-only research preview model optimized for near-instant, real-time coding iteration. Available to ChatGPT Pro users.

58 58

~~59codex -m gpt-5.2-codex~~59codex -m gpt-5.3-codex-spark

60 60

61Copy command61Copy command

62 62

74 74

75API Access75API Access

76 76

~~77For most coding tasks in Codex, start with gpt-5.3-codex. It is available for~~77For most tasks in Codex, start with `gpt-5.4`. It combines strong coding,

~~78ChatGPT-authenticated Codex sessions in the Codex app, CLI, IDE extension, and~~78reasoning, native computer use, and broader professional workflows in one

~~79Codex Cloud. API access for GPT-5.3-Codex will come soon. The~~79model. The `gpt-5.3-codex-spark` model is available in research preview for

~~80gpt-5.3-codex-spark model is available in research preview for ChatGPT Pro~~80ChatGPT Pro subscribers and is optimized for near-instant, real-time coding

~~81subscribers.~~81iteration.

82 82

83## Alternative models83## Alternative models

84 84

85![gpt-5.2-codex](/images/codex/gpt-5.2-codex.png)

87gpt-5.2-codex

89Advanced coding model for real-world engineering. Succeeded by GPT-5.3-Codex.

91codex -m gpt-5.2-codex

93Copy command

95Show details

85![gpt-5.2](/images/api/models/gpt-5.2.jpg)97![gpt-5.2](/images/api/models/gpt-5.2.jpg)

86 98

87gpt-5.299gpt-5.2

88 100

~~89Our best general agentic model for tasks across industries and domains.~~101Previous general-purpose model for coding and agentic tasks across industries and domains. Succeeded by GPT-5.4.

90 102

91codex -m gpt-5.2103codex -m gpt-5.2

92 104

182The Codex CLI and IDE extension use the same `config.toml` [configuration file](https://developers.openai.com/codex/config-basic). To specify a model, add a `model` entry to your configuration file. If you don't specify a model, the Codex app, CLI, or IDE Extension defaults to a recommended model.194The Codex CLI and IDE extension use the same `config.toml` [configuration file](https://developers.openai.com/codex/config-basic). To specify a model, add a `model` entry to your configuration file. If you don't specify a model, the Codex app, CLI, or IDE Extension defaults to a recommended model.

183 195

184```196```

185model = "gpt-5.2"197model = "gpt-5.4"

186```198```

187 199

188### Choosing a different local model temporarily200### Choosing a different local model temporarily

192To start a new Codex CLI thread with a specific model or to specify the model for `codex exec` you can use the `--model`/`-m` flag:204To start a new Codex CLI thread with a specific model or to specify the model for `codex exec` you can use the `--model`/`-m` flag:

193 205

194```bash206```bash

195codex -m gpt-5.3-codex207codex -m gpt-5.4

196```208```

197 209

198### Choosing your model for cloud tasks210### Choosing your model for cloud tasks

multi-agent.md +0 −131 deleted

File DeletedView Diff

~~1# Multi-agents~~

3Codex can run multi-agent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.

~~5With multi-agent workflows you can also define your own set of agents with different model configurations and instructions depending on the agent.~~

7For the concepts and tradeoffs behind multi-agent workflows (including context pollution/context rot and model-selection guidance), see [Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents).

~~9## Enable multi-agent~~

~~11Multi-agent workflows are currently experimental and need to be explicitly enabled.~~

~~13You can enable this feature from the CLI with `/experimental`. Enable~~

~~14**Multi-agents**, then restart Codex.~~

~~16Multi-agent activity is currently surfaced in the CLI. Visibility in other~~

~~17surfaces (the Codex app and IDE Extension) is coming soon.~~

~~19You can also add the [`multi_agent` feature flag](https://developers.openai.com/codex/config-basic#feature-flags) directly to your configuration file (`~/.codex/config.toml`):~~

~~21```~~

~~22[features]~~

~~23multi_agent = true~~

~~24```~~

~~26## Typical workflow~~

~~28Codex handles orchestration across agents, including spawning new sub-agents, routing follow-up instructions, waiting for results, and closing agent threads.~~

~~30When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.~~

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

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

~~36```~~

~~37I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.~~

~~381. Security issue~~

~~392. Code quality~~

~~403. Bugs~~

~~414. Race~~

~~425. Test flakiness~~

~~436. Maintainability of the code~~

~~44```~~

~~46## Managing sub-agents~~

~~48- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.~~

~~49- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.~~

~~51## Approvals and sandbox controls~~

~~53Sub-agents inherit your current sandbox policy, but they run with~~

~~54non-interactive approvals. If a sub-agent attempts an action that would require~~

~~55a new approval, that action fails and the error is surfaced in the parent~~

~~56workflow.~~

~~58You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.~~

~~60## Agent roles~~

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

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

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

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

~~69Codex ships with built-in roles:~~

~~71- `default`~~

~~72- `worker`~~

~~73- `explorer`~~

~~75Each agent role can override your default configuration. Common settings to override for an agent role are:~~

~~77- `model` and `model_reasoning_effort` to select a specific model for your agent role~~

~~78- `sandbox_mode` to mark an agent as `read-only`~~

~~79- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them~~

~~81### Schema~~

~~84| --- | --- | --- | --- |~~

~~85| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |~~

~~86| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |~~

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

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

~~90**Notes:**~~

~~92- Unknown fields in `[agents.<name>]` are rejected.~~

~~93- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.~~

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

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

~~96- Any configuration not set by the agent role will be inherited from the parent session.~~

~~98### Example agent roles~~

100Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.

~~101~~

102Example `~/.codex/config.toml`:

~~103~~

104```

105[agents.default]

106description = "General-purpose helper."

~~107~~

108[agents.reviewer]

109description = "Find security, correctness, and test risks in code."

110config_file = "agents/reviewer.toml"

~~111~~

112[agents.explorer]

113description = "Fast codebase explorer for read-heavy tasks."

114config_file = "agents/custom-explorer.toml"

115```

~~116~~

117Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):

~~118~~

119```

120model = "gpt-5.3-codex"

121model_reasoning_effort = "high"

122developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."

123```

~~124~~

125Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):

~~126~~

127```

128model = "gpt-5.3-codex-spark"

129model_reasoning_effort = "medium"

130sandbox_mode = "read-only"

131```

noninteractive.md +22 −0

Details

111 111

112`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:112`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:

113 113

114### Use API key auth (recommended)

115

114- Set `CODEX_API_KEY` as a secret environment variable for the job.116- Set `CODEX_API_KEY` as a secret environment variable for the job.

115- Keep prompts and tool output in mind: they can include sensitive code or data.117- Keep prompts and tool output in mind: they can include sensitive code or data.

116 118

122 124

123`CODEX_API_KEY` is only supported in `codex exec`.125`CODEX_API_KEY` is only supported in `codex exec`.

124 126

127Use ChatGPT-managed auth in CI/CD (advanced)

128

129Read this if you need to run CI/CD jobs with a Codex user account instead of an

130API key, such as enterprise teams using ChatGPT-managed Codex access on trusted

131runners or users who need ChatGPT/Codex rate limits instead of API key usage.

132

133API keys are the right default for automation because they are simpler to

134provision and rotate. Use this path only if you specifically need to run as

135your Codex account.

136

137Treat `~/.codex/auth.json` like a password: it contains access tokens. Don't

138commit it, paste it into tickets, or share it in chat.

139

140Do not use this workflow for public or open-source repositories. If `codex login`

141is not an option on the runner, seed `auth.json` through secure storage, run

142Codex on the runner so Codex refreshes it in place, and persist the updated file

143between runs.

144

145See [Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).

146

125## Resume a non-interactive session147## Resume a non-interactive session

126 148

127If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:149If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:

open-source.md +2 −0

Details

2 2

3OpenAI develops key parts of Codex in the open. That work lives on GitHub so you can follow progress, report issues, and contribute improvements.3OpenAI develops key parts of Codex in the open. That work lives on GitHub so you can follow progress, report issues, and contribute improvements.

4 4

5If you maintain a widely used open-source project or want to nominate maintainers stewarding important projects, you can also [apply to the Codex open source program](https://developers.openai.com/codex/community/codex-for-oss) for API credits, ChatGPT Pro with Codex, and selective access to Codex Security.

5## Open-source components7## Open-source components

6 8

overview.md +5 −1

Details

24 24

25Explore Codex Ambassadors and upcoming community meetups by location.25Explore Codex Ambassadors and upcoming community meetups by location.

26 26

~~27 See community](https://developers.openai.com/codex/community/meetups)~~27 See community](https://developers.openai.com/codex/community/meetups) [### Codex for OSS

29Apply or nominate maintainers for API credits, ChatGPT Pro with Codex, and selective Codex Security access.

31 Learn more](https://developers.openai.com/codex/community/codex-for-oss)

prompting.md +1 −1

Details

31 31

32Threads can run either locally or in the cloud:32Threads can run either locally or in the cloud:

33 33

34- **Local threads** run on your machine. Codex can read and edit your files and run commands, so you can see what changes and use your existing tools. To reduce the risk of unwanted changes outside your workspace, local threads run in a [sandbox](https://developers.openai.com/codex/security).34- **Local threads** run on your machine. Codex can read and edit your files and run commands, so you can see what changes and use your existing tools. To reduce the risk of unwanted changes outside your workspace, local threads run in a [sandbox](https://developers.openai.com/codex/agent-approvals-security).

35- **Cloud threads** run in an isolated [environment](https://developers.openai.com/codex/cloud/environments). Codex clones your repository and checks out the branch it's working on. Cloud threads are useful when you want to run work in parallel or delegate tasks from another device. To use cloud threads with your repo, push your code to GitHub first. You can also [delegate tasks from your local machine](https://developers.openai.com/codex/ide/cloud-tasks), which includes your current working state.35- **Cloud threads** run in an isolated [environment](https://developers.openai.com/codex/cloud/environments). Codex clones your repository and checks out the branch it's working on. Cloud threads are useful when you want to run work in parallel or delegate tasks from another device. To use cloud threads with your repo, push your code to GitHub first. You can also [delegate tasks from your local machine](https://developers.openai.com/codex/ide/cloud-tasks), which includes your current working state.

36 36

37## Context37## Context

quickstart.md +5 −2

Details

14 14

151. Download and install the Codex app151. Download and install the Codex app

16 16

~~17 The Codex app is currently only available for macOS.~~17 Download the Codex app for Windows or macOS.

18 18

19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

20 20

~~21 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)~~21 [Get notified for Linux](https://openai.com/form/codex-app/)

222. Open Codex and sign in222. Open Codex and sign in

23 23

24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

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

42 41

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

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

44 44

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

46 46

694. Use Git checkpoints694. Use Git checkpoints

70 70

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

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

72 73

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

74 75

1004. Use Git checkpoints1014. Use Git checkpoints

101 102

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

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

103 105

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

105 107

rules.md +1 −1

Details

43carefully before accepting it.43carefully before accepting it.

44 44

45Admins can also enforce restrictive `prefix_rule` entries from45Admins can also enforce restrictive `prefix_rule` entries from

~~46[`requirements.toml`](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~46[`requirements.toml`](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

47 47

48## Understand rule fields48## Understand rule fields

49 49

security.md +22 −372

Details

1# Codex Security1# Codex Security

2 2

~~3Codex helps protect your code and data and reduces the risk of misuse.~~3Codex Security helps engineering and security teams find, validate, and remediate likely vulnerabilities in connected GitHub repositories.

4 4

5By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.5This page covers Codex Security, the product that scans connected GitHub

6 repositories for likely security issues. For Codex sandboxing, approvals,

7 network controls, and admin settings, see [Agent approvals &

8 security](https://developers.openai.com/codex/agent-approvals-security).

6 9

~~7## Sandbox and approvals~~10It helps teams:

8 11

~~9Codex security controls come from two layers that work together:~~121. **Find likely vulnerabilities** by using a repo-specific threat model and real code context.

132. **Reduce noise** by validating findings before you review them.

143. **Move findings toward fixes** with ranked results, evidence, and suggested patch options.

10 15

~~11- **Sandbox mode**: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.~~16## How it works

~~12- **Approval policy**: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).~~

13 17

~~14Codex uses different sandbox modes depending on where you run it:~~18Codex Security scans connected repositories commit by commit.

19It builds scan context from your repo, checks likely vulnerabilities against that context, and validates high-signal issues in an isolated environment before surfacing them.

15 20

16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. You can expand access intentionally (for example, to install dependencies or allow specific domains) when needed. Network access is always enabled during the setup phase, which runs before the agent has access to your code.21You get a workflow focused on:

17- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

18 22

~~19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.~~23- repo-specific context instead of generic signatures

24- validation evidence that helps reduce false positives

25- suggested fixes you can review in GitHub

20 26

21Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.27## Access and prerequisites

22 28

~~23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change.~~29Codex Security works with connected GitHub repositories through Codex Web. OpenAI manages access. If you need access or a repository isn't visible, contact your OpenAI account team and confirm the repository is available through your Codex Web workspace.

24 30

~~25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)~~31## Related docs

26 32

~~27For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.~~33- [Codex Security setup](https://developers.openai.com/codex/security/setup) covers setup, scanning, and findings review.

28 34- [FAQ](https://developers.openai.com/codex/security/faq) covers common product questions.

~~29For the Codex app, CLI, or IDE Extension, the default `workspace-write` sandbox mode keeps network access turned off unless you enable it in your configuration:~~35- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.

~~31```~~

~~32[sandbox_workspace_write]~~

~~33network_access = true~~

~~34```~~

36You 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:

~~38```~~

~~39web_search = "cached" # default~~

~~40# web_search = "disabled"~~

~~41# web_search = "live" # same as --search~~

~~42```~~

~~44Use caution when enabling network access or web search in Codex. Prompt injection can cause the agent to fetch and follow untrusted instructions.~~

~~46## Defaults and recommendations~~

~~48- On launch, Codex detects whether the folder is version-controlled and recommends:~~

~~49 - Version-controlled folders: `Auto` (workspace write + on-request approvals)~~

~~50 - Non-version-controlled folders: `read-only`~~

~~51- Depending on your setup, Codex may also start in `read-only` until you explicitly trust the working directory (for example, via an onboarding prompt or `/permissions`).~~

~~52- The workspace includes the current directory and temporary directories like `/tmp`. Use the `/status` command to see which directories are in the workspace.~~

~~53- To accept the defaults, run `codex`.~~

~~54- You can set these explicitly:~~

~~55 - `codex --sandbox workspace-write --ask-for-approval on-request`~~

~~56 - `codex --sandbox read-only --ask-for-approval on-request`~~

~~58### Protected paths in writable roots~~

~~60In the default `workspace-write` sandbox policy, writable roots still include protected paths:~~

~~62- `<writable_root>/.git` is protected as read-only whether it appears as a directory or file.~~

~~63- If `<writable_root>/.git` is a pointer file (`gitdir: ...`), the resolved Git directory path is also protected as read-only.~~

~~64- `<writable_root>/.agents` is protected as read-only when it exists as a directory.~~

~~65- `<writable_root>/.codex` is protected as read-only when it exists as a directory.~~

~~66- Protection is recursive, so everything under those paths is read-only.~~

~~68### Run without approval prompts~~

~~70You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).~~

~~72This option works with all `--sandbox` modes, so you still control Codex’s level of autonomy. Codex makes a best effort within the constraints you set.~~

74If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

~~76### Common sandbox and approval combinations~~

~~78| Intent | Flags | Effect |~~

~~79| --- | --- | --- |~~

80| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

~~81| 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. |~~

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

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

~~84| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |~~

~~86`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.~~

88With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

~~90#### Configuration in `config.toml`~~

92For the broader configuration workflow, see [Config basics](https://developers.openai.com/codex/config-basic), [Advanced Config](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://developers.openai.com/codex/config-reference).

~~94```~~

~~95# Always ask for approval mode~~

~~96approval_policy = "untrusted"~~

~~97sandbox_mode = "read-only"~~

~~99# Optional: Allow network in workspace-write mode~~

100[sandbox_workspace_write]

101network_access = true

102```

~~103~~

104You can also save presets as profiles, then select them with `codex --profile <name>`:

~~105~~

106```

107[profiles.full_auto]

108approval_policy = "on-request"

109sandbox_mode = "workspace-write"

~~110~~

111[profiles.readonly_quiet]

112approval_policy = "never"

113sandbox_mode = "read-only"

114```

~~115~~

116### Test the sandbox locally

~~117~~

118To see what happens when a command runs under the Codex sandbox, use these Codex CLI commands:

~~119~~

120```

121# macOS

122codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

123# Linux

124codex sandbox linux [--full-auto] [COMMAND]...

125```

~~126~~

127The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

~~128~~

129## OS-level sandbox

~~130~~

131Codex enforces the sandbox differently depending on your OS:

~~132~~

133- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected.

134- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`).

135- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.

~~136~~

137If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:

~~138~~

139```

140{

141 "chatgpt.runCodexInWindowsSubsystemForLinux": true

142}

143```

~~144~~

145This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).

~~146~~

147The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.

~~148~~

149When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.

~~150~~

151In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

~~152~~

153## Version control

~~154~~

155Codex works best with a version control workflow:

~~156~~

157- Work on a feature branch and keep `git status` clean before delegating. This keeps Codex patches easier to isolate and revert.

158- Prefer patch-based workflows (for example, `git diff`/`git apply`) over editing tracked files directly. Commit frequently so you can roll back in small increments.

159- Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

~~160~~

161## Monitoring and telemetry

~~162~~

163Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

~~164~~

165### Overview

~~166~~

167- Codex turns off OTel export by default to keep local runs self-contained.

168- When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.

169- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

~~170~~

171### Enable OTel (opt-in)

~~172~~

173Add an `[otel]` block to your Codex configuration (typically `~/.codex/config.toml`), choosing an exporter and whether to log prompt text.

~~174~~

175```

176[otel]

177environment = "staging" # dev | staging | prod

178exporter = "none" # none | otlp-http | otlp-grpc

179log_user_prompt = false # redact prompt text unless policy allows

180```

~~181~~

182- `exporter = "none"` leaves instrumentation active but doesn’t send data anywhere.

183- To send events to your own collector, pick one of:

~~184~~

185```

186[otel]

187exporter = { otlp-http = {

188 endpoint = "https://otel.example.com/v1/logs",

189 protocol = "binary",

190 headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }

191}}

192```

~~193~~

194```

195[otel]

196exporter = { otlp-grpc = {

197 endpoint = "https://otel.example.com:4317",

198 headers = { "x-otlp-meta" = "abc123" }

199}}

200```

~~201~~

202Codex batches events and flushes them on shutdown. Codex exports only telemetry produced by its OTel module.

~~203~~

204### Event categories

~~205~~

206Representative event types include:

~~207~~

208- `codex.conversation_starts` (model, reasoning settings, sandbox/approval policy)

209- `codex.api_request` (attempt, status/success, duration, and error details)

210- `codex.sse_event` (stream event kind, success/failure, duration, plus token counts on `response.completed`)

211- `codex.websocket_request` and `codex.websocket_event` (request duration plus per-message kind/success/error)

212- `codex.user_prompt` (length; content redacted unless explicitly enabled)

213- `codex.tool_decision` (approved/denied, source: configuration vs. user)

214- `codex.tool_result` (duration, success, output snippet)

~~215~~

216Associated OTel metrics (counter plus duration histogram pairs) include `codex.api_request`, `codex.sse_event`, `codex.websocket.request`, `codex.websocket.event`, and `codex.tool.call` (with corresponding `.duration_ms` instruments).

~~217~~

218For the full event catalog and configuration reference, see the [Codex configuration documentation on GitHub](https://github.com/openai/codex/blob/main/docs/config.md#otel).

~~219~~

220### Security and privacy guidance

~~221~~

222- Keep `log_user_prompt = false` unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.

223- Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.

224- Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.

225- Review local data retention settings (for example, `history.persistence` / `history.max_bytes`) if you don’t want Codex to save session transcripts under `CODEX_HOME`. See [Advanced Config](https://developers.openai.com/codex/config-advanced#history-persistence) and [Configuration Reference](https://developers.openai.com/codex/config-reference).

226- If you run the CLI with network access turned off, OTel export can’t reach your collector. To export, allow network access in `workspace-write` mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.

227- Review events periodically for approval/sandbox changes and unexpected tool executions.

~~228~~

229OTel is optional and designed to complement, not replace, the sandbox and approval protections described above.

~~230~~

231## Managed configuration

~~232~~

233Enterprise admins can control local Codex behavior in two ways. For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml):

~~234~~

235- **Requirements**: admin-enforced constraints that users can’t override.

236- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

~~237~~

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

~~239~~

240Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers you can enable). If a user explicitly selects a disallowed value (via `config.toml`, CLI flags, profiles, or in-session UI), Codex rejects the change. If a value isn’t explicitly set and the default conflicts with requirements, Codex falls back to a requirements-compliant default. If you configure an `mcp_servers` approved list, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex turns it off.

~~241~~

242#### Locations

~~243~~

244- Linux/macOS (Unix): `/etc/codex/requirements.toml`

245- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`

~~246~~

247#### Cloud requirements (Business and Enterprise)

~~248~~

249When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also

250fetch admin-enforced requirements from the Codex service. This applies across

251Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.

~~252~~

253Cloud requirements are currently best-effort. If the fetch fails or times out,

254Codex continues without the cloud layer.

~~255~~

256Requirements layer in this order (higher wins):

~~257~~

258- macOS managed preferences (MDM; highest precedence)

259- Cloud requirements (ChatGPT Business or Enterprise)

260- `/etc/codex/requirements.toml`

~~261~~

262Cloud requirements only fill unset requirement fields, so higher-precedence

263managed layers still win when both specify the same constraint.

~~264~~

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

~~266~~

267#### Example requirements.toml

~~268~~

269This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

~~270~~

271```

272allowed_approval_policies = ["untrusted", "on-request"]

273allowed_sandbox_modes = ["read-only", "workspace-write"]

274```

~~275~~

276You can also constrain web search mode:

~~277~~

278```

279allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

280```

~~281~~

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

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

~~284~~

285#### Enforce command rules from requirements

~~286~~

287Admins can also enforce restrictive command rules from `requirements.toml`

288using a `[rules]` table. These rules merge with regular `.rules` files, and the

289most restrictive decision still wins.

~~290~~

291Unlike `.rules`, requirements rules must specify `decision`, and that decision

292must be `"prompt"` or `"forbidden"` (not `"allow"`).

~~293~~

294```

295[rules]

296prefix_rules = [

297 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

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

299]

300```

~~301~~

302To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

~~303~~

304```

305[mcp_servers.docs]

306identity = { command = "codex-mcp" }

~~307~~

308[mcp_servers.remote]

309identity = { url = "https://example.com/mcp" }

310```

~~311~~

312If `mcp_servers` is present but empty, Codex disables all MCP servers.

~~313~~

314### Managed defaults (managed\_config.toml)

~~315~~

316Managed defaults merge on top of a user’s local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

~~317~~

318Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

~~319~~

320#### Precedence and layering

~~321~~

322Codex assembles the effective configuration in this order (top overrides bottom):

~~323~~

324- Managed preferences (macOS MDM; highest precedence)

325- `managed_config.toml` (system/managed file)

326- `config.toml` (user’s base configuration)

~~327~~

328CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

~~329~~

330Cloud requirements affect the requirements layer (not managed defaults). See

331[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)

332for their precedence.

~~333~~

334#### Locations

~~335~~

336- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

337- Windows/non-Unix: `~/.codex/managed_config.toml`

~~338~~

339If the file is missing, Codex skips the managed layer.

~~340~~

341#### macOS managed preferences (MDM)

~~342~~

343On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

~~344~~

345- Preference domain: `com.openai.codex`

346- Keys:

347 - `config_toml_base64` (managed defaults)

348 - `requirements_toml_base64` (requirements)

~~349~~

350Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.

~~351~~

352### MDM setup workflow

~~353~~

354Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

~~355~~

3561. Build the managed payload TOML and encode it with `base64` (no wrapping).

3572. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

3583. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

3594. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

~~360~~

361Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

~~362~~

363### Example managed\_config.toml

~~364~~

365```

366# Set conservative defaults

367approval_policy = "on-request"

368sandbox_mode = "workspace-write"

~~369~~

370[sandbox_workspace_write]

371network_access = false # keep network disabled unless explicitly allowed

~~372~~

373[otel]

374environment = "prod"

375exporter = "otlp-http" # point at your collector

376log_user_prompt = false # keep prompts redacted

377# exporter details live under exporter tables; see Monitoring and telemetry above

378```

~~379~~

380### Recommended guardrails

~~381~~

382- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

383- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

384- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

385- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

security/faq.md +104 −0 added

Details

1# FAQ

3## Getting started

5### What is Codex Security?

7Software security remains one of the hardest and most important problems in engineering. Codex Security is an LLM-driven security analysis toolkit that inspects source code and returns structured, ranked vulnerability findings with proposed patches. It helps developers and security teams discover and fix security issues at scale.

9### Why does it matter?

11Software is foundational to modern industry and society, and vulnerabilities create systemic risk. Codex Security supports a defender-first workflow by continuously identifying likely issues, validating them when possible, and proposing fixes. That helps teams improve security without slowing development.

13### What business problem does Codex Security solve?

15Codex Security shortens the path from a suspected issue to a confirmed, reproducible finding with evidence and a proposed patch. That reduces triage load and cuts false positives compared with traditional scanners alone.

17### How does Codex Security work?

19Codex Security runs analysis in an ephemeral, isolated container and temporarily clones the target repository. It performs code-level analysis and returns structured findings with a description, file and location, criticality, root cause, and a suggested remediation.

21For findings that include verification steps, the system executes proposed commands or tests in the same sandbox, records success or failure, exit codes, stdout, stderr, test results, and any generated diffs or artifacts, and attaches that output as evidence for review.

23### Does it replace SAST?

25No. Codex Security complements SAST. It adds semantic, LLM-based reasoning and automated validation, while existing SAST tools still provide broad deterministic coverage.

27## Features

29### What is the analysis pipeline?

31Codex Security follows a staged pipeline:

331. **Analysis** builds a threat model for the repository.

342. **Commit scanning** reviews merged commits and repository history for likely issues.

353. **Validation** tries to reproduce likely vulnerabilities in a sandbox to reduce false positives.

364. **Patching** integrates with Codex to propose patches that reviewers can inspect before opening a PR.

38It works alongside engineers in GitHub, Codex, and standard review workflows.

40### What languages are supported?

42Codex Security is language-agnostic. In practice, performance depends on the model's reasoning ability for the language and framework used by the repository.

44### What outputs do I get after the scan completes?

46You get ranked findings with criticality, validation status, and a proposed patch when one is available. Findings can also include crash output, reproduction evidence, call-path context, and related annotations.

48### How is customer code isolated?

50Each analysis and validation job runs in an ephemeral Codex container with session-scoped tools. Artifacts are extracted for review, and the container is torn down after the job completes.

52### Does Codex Security auto-apply patches?

54No. The proposed patch is a recommended remediation. Users can review it and push it as a PR to GitHub from the findings UI, but Codex Security does not auto-apply changes to the repository.

56### Does the project need to be built for scanning?

58No. Codex Security can produce findings from repository and commit context without a compile step. During auto-validation, it may try to build the project inside the container if that helps reproduce the issue. For environment setup details, see [Codex cloud environments](https://developers.openai.com/codex/cloud/environments).

60### How does Codex Security reduce false positives and avoid broken patches?

62Codex Security uses two stages. First, the model ranks likely issues. Then auto-validation tries to reproduce each issue in a clean container. Findings that successfully reproduce are marked as validated, which helps reduce false positives before human review.

64### How long do initial scans take, and what happens after that?

66Initial scan time depends on repository size, build time, and how many findings proceed to validation. For some repositories, scans can take several hours. For larger repositories, they can take multiple days. Later scans are usually faster because they focus on new commits and incremental changes.

68### What is a threat model?

70A threat model is the scan-time security context for a repository. It combines a concise project overview with attack-surface details such as entry points, trust boundaries, auth assumptions, and risky components. For more detail, see [Improving the threat model](https://developers.openai.com/codex/security/threat-model).

72### How is a threat model generated?

74Codex Security prompts the model to summarize the repository architecture and security entry points, classify the repository type, run specialized extractors, and merge the results into a project overview or threat model artifact used throughout the scan.

76### Does it replace manual security review?

78No. Codex Security accelerates review and helps rank findings, but it does not replace code-level validation, exploitability checks, or human threat assessment.

80### Can I edit the threat model?

82Yes. Codex Security creates the initial threat model, and you can update it as the architecture, risks, and business context change. For the editing workflow, see [Improving the threat model](https://developers.openai.com/codex/security/threat-model).

84### Do I need to configure a scan before using threat modeling?

86Yes. Threat-model guidance is tied to how and what you scan, so you need to configure the repository first. See [Codex Security setup](https://developers.openai.com/codex/security/setup).

88### What does the proposed patch contain?

90The proposed patch contains a minimal actionable diff with filename and line context when a remediation can be generated for the finding.

92### Does the patch directly modify my PR branch?

94No. The workflow generates a diff, patch file, or suggested change for maintainers and reviewers to inspect before applying.

96## Validation

98### What is auto-validation?

100Auto-validation is the phase that tries to reproduce a suspected issue in an isolated container. It records whether reproduction succeeded or failed and captures logs, commands, and related artifacts as evidence.

101

102### What happens if validation fails?

103

104The finding remains unvalidated. Logs and reports still capture what was attempted so engineers can retry, investigate further, or adjust the reproduction steps.

security/setup.md +97 −0 added

Details

1# Codex Security setup

3This page walks you from initial access to reviewed findings and remediation pull requests in Codex Security.

5Confirm you've set up Codex Cloud first. If not, see [Codex

6 Cloud](https://developers.openai.com/codex/cloud) to get started.

8## 1. Access and environment

10Codex Security scans GitHub repositories connected through [Codex Cloud](https://developers.openai.com/codex/cloud).

12- Confirm your workspace has access to Codex Security.

13- Confirm the repository you want to scan is available in Codex Cloud.

15Go to [Codex environments](https://chatgpt.com/codex/settings/environments) and check whether the repository already has an environment. If it doesn't, create one there before continuing.

17[Open environments](https://chatgpt.com/codex/settings/environments)

19![Codex environments](/_astro/create_environment.M-EPszPH.png)

21## 2. New security scan

23After the environment exists, go to [Create a security scan](https://chatgpt.com/codex/security/scans/new) and choose the repository you just connected.

25[Create a security scan](https://chatgpt.com/codex/security/scans/new)

27Codex Security scans repositories from newest commits backward first. It uses this to build and refresh scan context as new commits come in.

29To configure a repository:

311. Select the GitHub organization.

322. Select the repository.

333. Select the branch you want to scan.

344. Select the environment.

355. Choose a **history window**. Longer windows provide more context, but backfill takes longer.

366. Click **Create**.

38![Create a security scan](/_astro/create_scan.mEjmf4U_.png)

40## 3. Initial scans can take a while

42When you create the scan, Codex Security first runs a commit-level security pass across the selected history window.

43The initial backfill can take a few hours, especially for larger repositories or longer windows.

44If findings aren't visible right away, this is expected. Wait for the initial scan to finish before opening a ticket or troubleshooting.

46Initial scan setup is automatic and thorough. This can take a few hours. Don’t

47 be alarmed if the first set of findings is delayed.

49## 4. Review scans and improve the threat model

51[Review scans](https://chatgpt.com/codex/security/scans)

53![Threat model editor in Codex Security](/_astro/review_threat_model.JTLMQEmx.png)

55When the initial scan finishes, open the scan and review the threat model that was generated.

56After initial findings appear, update the threat model so it matches your architecture, trust boundaries, and business context.

57This helps Codex Security rank issues for your team.

59If you want scan results to change, you can edit the threat model with your

60 updated scope, priorities, and assumptions.

62After initial findings appear, revisit the model so scan guidance stays aligned with current priorities.

63Keeping it current helps Codex Security produce better suggestions.

65For a deeper explanation of threat models and how they affect criticality and triage, see [Improving the threat model](https://developers.openai.com/codex/security/threat-model).

67## 5. Review findings and patch

69After the initial backfill completes, review findings from the **Findings** view.

71[Open findings](https://chatgpt.com/codex/security/findings)

73You can use two views:

75- **Recommended Findings**: an evolving top 10 list of the most critical issues in the repo

76- **All Findings**: a sortable, filterable table of findings across the repository

78![Recommended findings view](https://developers.openai.com/codex/security/images/aardvark_recommended_findings.png)

80Click a finding to open its detail page, which includes:

82- a concise description of the issue

83- key metadata such as commit details and file paths

84- contextual reasoning about impact

85- relevant code excerpts

86- call-path or data-flow context when available

87- validation steps and validation output

89You can review each finding and create a PR directly from the finding detail page.

91[Review findings and create a PR](https://chatgpt.com/codex/security/findings)

93## Related docs

95- [Codex Security](https://developers.openai.com/codex/security) gives the product overview.

96- [FAQ](https://developers.openai.com/codex/security/faq) covers common questions.

97- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to improve scan context and finding prioritization.

security/threat-model.md +40 −0 added

Details

1# Improving the threat model

3Learn what a threat model is and how editing it improves Codex Security's suggestions.

5## What a threat model is

7A threat model is a short security summary of how your repository works. In Codex Security, you edit it as a `project overview`, and the system uses it as scan context for future scans, prioritization, and review.

9Codex Security creates the first draft from the code. If the findings feel off, this is the first thing to edit.

11A useful threat model calls out:

13- entry points and untrusted inputs

14- trust boundaries and auth assumptions

15- sensitive data paths or privileged actions

16- the areas your team wants reviewed first

18For example:

20> Public API for account changes. Accepts JSON requests and file uploads. Uses an internal auth service for identity checks and writes billing changes through an internal service. Focus review on auth checks, upload parsing, and service-to-service trust boundaries.

22That gives Codex Security a better starting point for future scans and finding prioritization.

24## Improving and revisiting the threat model

26If you want to improve the results, edit the threat model first. Use it when findings are missing the areas you care about or showing up in places you don't expect. The threat model changes future scan context.

28Some users copy the current threat model into Codex, have a conversation to

29 improve it based on the areas they want reviewed more closely, and then paste

30 the updated version back into the web UI.

32### Where to edit

34To review or update the threat model, go to [Codex Security scans](https://chatgpt.com/codex/security/scans), open the repository, and click **Edit**.

36## Related docs

38- [Codex Security setup](https://developers.openai.com/codex/security/setup) covers repository setup and findings review.

39- [Codex Security](https://developers.openai.com/codex/security) gives the product overview.

40- [FAQ](https://developers.openai.com/codex/security/faq) covers common questions.

skills.md +2 −2

Details

67 67

68## Install skills68## Install skills

69 69

~~70To install skills beyond the built-ins, use `$skill-installer`:~~70To install skills beyond the built-ins, use `$skill-installer`. For example, to install the `$linear` skill:

71 71

72```bash72```bash

~~73$skill-installer install the linear skill from the .experimental folder~~73$skill-installer linear

74```74```

75 75

76You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.76You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.

speed.md +24 −0 added

Details

1# Speed

3## Fast mode

5Codex offers the ability to increase the speed of the model for increased

6credit consumption.

8Fast mode is currently supported on GPT-5.4. When enabled, speed is increased

9by 1.5x and credits are consumed at a 2x rate.

11Enable it by typing `/fast`. It’s available in Codex IDE Extensions, Codex

12CLI, and the Codex app when you sign in with ChatGPT. With an API key, Codex

13uses standard API pricing instead and you can’t use `/fast`.

15[

16Your browser does not support the video tag.

17](/videos/codex/fast-mode-demo.mp4)

19## Codex-Spark

21GPT-5.3-Codex-Spark is a separate fast, less-capable Codex model optimized for near-instant, real-time coding iteration. Unlike fast mode, which speeds up GPT-5.4 at a higher credit rate,

22Codex-Spark is its own model choice and has its own usage limits.

24During research preview Codex-Spark is only available for ChatGPT Pro subscribers.

subagents.md +340 −0 added

Details

1# Subagents

3Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.

5With subagent workflows, you can also define your own custom agents with different model configurations and instructions depending on the task.

7For the concepts and tradeoffs behind subagent workflows, including context pollution, context rot, and model-selection guidance, see [Subagent concepts](https://developers.openai.com/codex/concepts/subagents).

9## Availability

11Current Codex releases enable subagent workflows by default.

13Subagent activity is currently surfaced in the Codex app and CLI. Visibility

14 in the IDE Extension is coming soon.

16Codex only spawns subagents when you explicitly ask it to. Because each

17subagent does its own model and tool work, subagent workflows consume more

18tokens than comparable single-agent runs.

20## Typical workflow

22Codex handles orchestration across agents, including spawning new subagents,

23routing follow-up instructions, waiting for results, and closing agent

24threads.

26When many agents are running, Codex waits until all requested results are

27available, then returns a consolidated response.

29Codex only spawns a new agent when you explicitly ask it to do so.

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

33```text

34I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.

351. Security issue

362. Code quality

373. Bugs

384. Race

395. Test flakiness

406. Maintainability of the code

41```

43## Managing subagents

45- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.

46- Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.

48## Approvals and sandbox controls

50Subagents inherit your current sandbox policy.

52In interactive CLI sessions, approval requests can surface from inactive agent

53threads even while you are looking at the main thread. The approval overlay

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

55you approve, reject, or answer the request.

57In non-interactive flows, or whenever a run can't surface a fresh approval, an

58action that needs new approval fails and Codex surfaces the error back to the

59parent workflow.

61Codex also reapplies the parent turn's live runtime overrides when it spawns a

62child. That includes sandbox and approval choices you set interactively during

63the session, such as `/approvals` changes or `--yolo`, even if the selected

64custom agent file sets different defaults.

66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.

68## Custom agents

70Codex ships with built-in agents:

72- `default`: general-purpose fallback agent.

73- `worker`: execution-focused agent for implementation and fixes.

74- `explorer`: read-heavy codebase exploration agent.

76To define your own custom agents, add standalone TOML files under

77`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped

78agents.

80Each file defines one custom agent. Codex loads these files as configuration

81layers for spawned sessions, so custom agents can override the same settings as

82a normal Codex session config. That can feel heavier than a dedicated agent

83manifest, and the format may evolve as authoring and sharing mature.

85Every standalone custom agent file must define:

87- `name`

88- `description`

89- `developer_instructions`

91Optional fields such as `nickname_candidates`, `model`,

92`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`

93inherit from the parent session when you omit them.

95### Global settings

97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

100| --- | --- | --- | --- |

104

105**Notes:**

106

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

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

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

110- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

111

112### Custom agent file schema

113

115| --- | --- | --- | --- |

120

121You can also include other supported `config.toml` keys in a custom agent file, such as `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.

122

123Codex identifies the custom agent by its `name` field. Matching the filename to

124the agent name is the simplest convention, but the `name` field is the source

125of truth.

126

127### Display nicknames

128

129Use `nickname_candidates` when you want Codex to assign more readable display

130names to spawned agents. This is especially helpful when you run many

131instances of the same custom agent and want the UI to show distinct labels

132instead of repeating the same agent name.

133

134Nicknames are presentation-only. Codex still identifies and spawns the agent by

135its `name`.

136

137Nickname candidates must be a non-empty list of unique names. Each nickname can

138use ASCII letters, digits, spaces, hyphens, and underscores.

139

140Example:

141

142```toml

143name = "reviewer"

144description = "PR reviewer focused on correctness, security, and missing tests."

145developer_instructions = """

146Review code like an owner.

147Prioritize correctness, security, behavior regressions, and missing test coverage.

148"""

149nickname_candidates = ["Atlas", "Delta", "Echo"]

150```

151

152In practice, the Codex app and CLI can show the nicknames where agent activity

153appears, while the underlying agent type stays

154`reviewer`.

155

156### Example custom agents

157

158The best custom agents are narrow and opinionated. Give each one clear job, a

159tool surface that matches that job, and instructions that keep it from

160drifting into adjacent work.

161

162#### Example 1: PR review

163

164This pattern splits review across three focused custom agents:

165

166- `pr_explorer` maps the codebase and gathers evidence.

167- `reviewer` looks for correctness, security, and test risks.

168- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

169

170Project config (`.codex/config.toml`):

171

172```toml

173[agents]

174max_threads = 6

175max_depth = 1

176```

177

178`.codex/agents/pr-explorer.toml`:

179

180```toml

181name = "pr_explorer"

182description = "Read-only codebase explorer for gathering evidence before changes are proposed."

183model = "gpt-5.3-codex-spark"

184model_reasoning_effort = "medium"

185sandbox_mode = "read-only"

186developer_instructions = """

187Stay in exploration mode.

188Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

189Prefer fast search and targeted file reads over broad scans.

190"""

191```

192

193`.codex/agents/reviewer.toml`:

194

195```toml

196name = "reviewer"

197description = "PR reviewer focused on correctness, security, and missing tests."

198model = "gpt-5.4"

199model_reasoning_effort = "high"

200sandbox_mode = "read-only"

201developer_instructions = """

202Review code like an owner.

203Prioritize correctness, security, behavior regressions, and missing test coverage.

204Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

205"""

206```

207

208`.codex/agents/docs-researcher.toml`:

209

210```toml

211name = "docs_researcher"

212description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

213model = "gpt-5.3-codex-spark"

214model_reasoning_effort = "medium"

215sandbox_mode = "read-only"

216developer_instructions = """

217Use the docs MCP server to confirm APIs, options, and version-specific behavior.

218Return concise answers with links or exact references when available.

219Do not make code changes.

220"""

221

222[mcp_servers.openaiDeveloperDocs]

223url = "https://developers.openai.com/mcp"

224```

225

226This setup works well for prompts like:

227

228```text

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

230```

231

232## Process CSV batches with subagents (experimental)

233

234This workflow is experimental and may change as subagent support evolves.

235Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker subagent per row, waits for the full batch to finish, and exports the combined results to CSV.

236

237This works well for repeated audits such as:

238

239- reviewing one file, package, or service per row

240- checking a list of incidents, PRs, or migration targets

241- generating structured summaries for many similar inputs

242

243The tool accepts:

244

245- `csv_path` for the source CSV

246- `instruction` for the worker prompt template, using `{column_name}` placeholders

247- `id_column` when you want stable item ids from a specific column

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

249- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

250

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

252

253Example prompt:

254

255```text

256Create /tmp/components.csv with columns path,owner and one row per frontend component.

257

258Then call spawn_agents_on_csv with:

259- csv_path: /tmp/components.csv

260- id_column: path

261- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."

262- output_csv_path: /tmp/components-review.csv

263- output_schema: an object with required string fields path, risk, summary, and follow_up

264```

265

266When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.

267

268Related runtime settings:

269

270- `agents.max_threads` caps how many agent threads can stay open concurrently.

271- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.

272- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.

273

274#### Example 2: Frontend integration debugging

275

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

277

278Project config (`.codex/config.toml`):

279

280```toml

281[agents]

282max_threads = 6

283max_depth = 1

284```

285

286`.codex/agents/code-mapper.toml`:

287

288```toml

289name = "code_mapper"

290description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

291model = "gpt-5.3-codex-spark"

292model_reasoning_effort = "medium"

293sandbox_mode = "read-only"

294developer_instructions = """

295Map the code that owns the failing UI flow.

296Identify entry points, state transitions, and likely files before the worker starts editing.

297"""

298```

299

300`.codex/agents/browser-debugger.toml`:

301

302```toml

303name = "browser_debugger"

304description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

305model = "gpt-5.4"

306model_reasoning_effort = "high"

307sandbox_mode = "workspace-write"

308developer_instructions = """

309Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

310Use browser tooling for screenshots, console output, and network evidence.

311Do not edit application code.

312"""

313

314[mcp_servers.chrome_devtools]

315url = "http://localhost:3000/mcp"

316startup_timeout_sec = 20

317```

318

319`.codex/agents/ui-fixer.toml`:

320

321```toml

322name = "ui_fixer"

323description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

324model = "gpt-5.3-codex-spark"

325model_reasoning_effort = "medium"

326developer_instructions = """

327Own the fix once the issue is reproduced.

328Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

329"""

330

331[[skills.config]]

332path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

333enabled = false

334```

335

336This setup works well for prompts like:

337

338```text

339Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.

340```

windows.md +45 −24

Details

1# Windows1# Windows

2 2

3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.3The easiest way to use Codex on Windows is to use the [Codex app](https://developers.openai.com/codex/app/windows). You can also [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 4

5When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).5[![](/images/codex/codex-banner-icon.webp)

6 6

7Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.7Use the Codex app on Windows

9Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)

11When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).

13If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.

15## Windows sandbox

17Native Windows sandbox support includes two modes that you can configure in `config.toml`:

19```

20[windows]

21sandbox = "unelevated" # or "elevated"

22```

24How `elevated` mode works:

26- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

27- Runs commands as a dedicated Windows Sandbox User.

28- Limits network access by installing Windows Firewall rules.

30### Sandbox permissions

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

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

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

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

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

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

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

40### Grant sandbox read access

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

44```text

45/sandbox-add-read-dir C:\absolute\directory\path

46```

48The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

8 49

9## Windows Subsystem for Linux50## Windows Subsystem for Linux

10 51

81 ```122 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.123- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 124

~~84## Windows experimental sandbox~~125## Troubleshooting and FAQ

~~86The Windows sandbox support is experimental. How it works:~~

~~88- Launches commands inside a restricted token derived from an AppContainer profile.~~

~~89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.~~

~~90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.~~

92Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.

~~94### Grant sandbox read access~~

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

~~98```text~~

~~99/sandbox-add-read-dir C:\absolute\directory\path~~

100```

~~101~~

102The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

~~103~~

104### Troubleshooting and FAQ

105 126

106#### Installed extension, but it’s unresponsive127#### Installed extension, but it’s unresponsive

107 128

OpenAI - Codex Docs Changes 2026-02-23 18:27 UTC → 2026-03-17 00:33 UTC