OpenAI - Codex Docs Changes

agent-approvals-security.md +253 −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).

14## Sandbox and approvals

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

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

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

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

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

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

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

28Codex 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.

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

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

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

36For 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:

38```toml

39[sandbox_workspace_write]

40network_access = true

41```

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

45```toml

46web_search = "cached" # default

47# web_search = "disabled"

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

49```

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

53## Defaults and recommendations

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

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

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

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

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

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

61- You can set these explicitly:

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

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

65### Protected paths in writable roots

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

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

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

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

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

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

75### Run without approval prompts

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

79This 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.

81If 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.

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

85### Common sandbox and approval combinations

87| Intent | Flags | Effect |

88| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

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

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

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

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

97With `--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.

99#### Configuration in `config.toml`

100

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

102

103```toml

104# Always ask for approval mode

105approval_policy = "untrusted"

106sandbox_mode = "read-only"

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

108

109# Optional: Allow network in workspace-write mode

110[sandbox_workspace_write]

111network_access = true

112

113# Optional: granular approval prompt auto-rejection

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

115```

116

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

118

119```toml

120[profiles.full_auto]

121approval_policy = "on-request"

122sandbox_mode = "workspace-write"

123

124[profiles.readonly_quiet]

125approval_policy = "never"

126sandbox_mode = "read-only"

127```

128

129### Test the sandbox locally

130

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

132

133```bash

134# macOS

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

136# Linux

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

138```

139

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

141

142## OS-level sandbox

143

144Codex enforces the sandbox differently depending on your OS:

145

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

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

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

149

150If 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:

151

152```json

153{

154 "chatgpt.runCodexInWindowsSubsystemForLinux": true

155}

156```

157

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

159

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

161

162```toml

163[windows]

164sandbox = "unelevated" # or "elevated"

165```

166

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

168

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

170

171In 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.

172

173## Version control

174

175Codex works best with a version control workflow:

176

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

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

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

180

181## Monitoring and telemetry

182

183Codex 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.

184

185### Overview

186

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

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

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

190

191### Enable OTel (opt-in)

192

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

194

195```toml

196[otel]

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

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

199log_user_prompt = false # redact prompt text unless policy allows

200```

201

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

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

204

205```toml

206[otel]

207exporter = { otlp-http = {

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

209 protocol = "binary",

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

211}}

212```

213

214```toml

215[otel]

216exporter = { otlp-grpc = {

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

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

219}}

220```

221

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

223

224### Event categories

225

226Representative event types include:

227

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

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

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

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

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

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

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

235

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

237

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

239

240### Security and privacy guidance

241

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

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

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

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

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

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

248

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

250

251## Managed configuration

252

253Enterprise 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 +4 −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.

app-server.md +14 −10

Details

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

233- `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.

234- `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.

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

236 236

237## Models237## Models

238 238

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

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

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

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

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

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

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

251 "hidden": false,250 "hidden": false,

252 "defaultReasoningEffort": "medium",251 "defaultReasoningEffort": "medium",

253 "reasoningEffort": [{252 "supportedReasoningEfforts": [{

254 "effort": "low",253 "reasoningEffort": "low",

255 "description": "Lower latency"254 "description": "Lower latency"

256 }],255 }],

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

264 263

265Each model entry can include:264Each model entry can include:

266 265

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

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

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

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

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

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

724 "requirements": {724 "requirements": {

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

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

727 "featureRequirements": {

728 "personality": true,

729 "unified_exec": false

730 },

727 "network": {731 "network": {

728 "enabled": true,732 "enabled": true,

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

734} }738} }

735```739```

736 740

737`result.requirements` is `null` when no requirements are configured. When present, the optional `network` object carries managed proxy constraints (domain rules, proxy settings, and unix-socket policy).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.

738 742

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

740 744

868 872

869When `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.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.

870 874

871Codex deduplicates 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.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.

872 876

873### File change approvals877### File change approvals

874 878

app/features.md +15 −3

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)

101 101

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

103 103

104## Native Windows sandbox

105

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

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

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

109

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

111

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

113

104## Voice dictation114## Voice dictation

105 115

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.116Use 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 roam162opening separate projects or using worktrees rather than asking Codex to roam

153outside the project root.163outside the project root.

154 164

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

166configuration details, see the

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

156 168

157## MCP support169## MCP support

158 170

165 177

166Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex178Codex 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 your179enables 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. See180sandbox 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 the181[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the

170most recent data.182most recent data.

171 183

app/settings.md +1 −1

Details

24 24

25Codex agents in the app inherit the same configuration as the IDE and CLI extension.25Codex 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 advanced26Use the in-app controls for common settings, or edit `config.toml` for advanced

~~27options. See [Codex security](https://developers.openai.com/codex/security) and~~27options. 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.28[config basics](https://developers.openai.com/codex/config-basic) for more detail.

29 29

30## Git30## Git

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 +170 −35

Details

~~1# Codex app~~1# Windows

2 2

~~3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.~~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).

4 8

~~5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).~~9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

6 10

~~7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)~~11## Download and update the Codex app

8 12

~~9## Getting started~~13Download the Codex app from the

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

10 15

~~11The Codex app is available on macOS (Apple Silicon).~~16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

12 17

~~131. Download and install the Codex app~~18To update the app, open the Microsoft Store, go to **Downloads**, and click

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

14 20

~~15 The Codex app is currently only available for macOS.~~21For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.

16 23

~~17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)~~24If you prefer a command-line install path, or need an alternative to opening

25the Microsoft Store UI, run:

18 26

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

~~202. Open Codex and sign in~~28winget install Codex -s msstore

29```

21 30

~~22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.~~31## Customize for your dev setup

23 32

~~24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.~~33### Preferred editor

~~253. Select a project~~

26 34

~~27 Choose a project folder that you want Codex to work in.~~35Choose a default app for **Open**, such as Visual Studio, VS Code, or another

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

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

38choice takes precedence.

28 39

~~29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.~~40![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)

30 41

~~314. Send your first message~~42### Integrated terminal

32 43

~~33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.~~44You can also choose the default integrated terminal. Depending on what you have

45installed, options include:

34 46

~~35 You can ask Codex anything about the project or your computer in general. Here are some examples:~~47- PowerShell

48- Command Prompt

49- Git Bash

50- WSL

36 51

~~37- Tell me about this project~~52This change applies only to new terminal sessions. If you already have an

~~38- Build a classic Snake game in this repo.~~53integrated terminal open, restart the app or start a new thread before

~~39- Find and fix bugs in my codebase with minimal, high-confidence changes.~~54expecting the new default terminal to appear.

40 55

~~41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).~~56![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)

42 57

58## Windows Subsystem for Linux (WSL)

43 59

~~44## Work with the Codex app~~60By default, the Codex app uses the Windows-native agent. That means the agent

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

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

45 63

~~46[### Multitask across projects~~64If you want to add a project from the WSL filesystem, click **Add new project**

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

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

67want to open.

47 68

~~48Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools~~69If you plan to keep using the Windows-native agent, prefer storing projects on

70your Windows filesystem and accessing them from WSL through

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

72directly from the WSL filesystem.

49 73

~~50Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks~~74If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,

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

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

77place after restart.

51 78

~~52Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support~~79![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

53 80

~~54Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations~~81You configure the integrated terminal independently from the agent. See

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

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

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

55 85

56Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal86## Useful developer tools

57 87

~~58Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments~~88Codex works best when a few common developer tools are already installed:

59 89

~~60Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension~~90- **Git**: Powers the review panel in the Codex app and lets you inspect or

91 revert changes.

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

93 efficiently.

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

95 efficiently.

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

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

61 98

~~62Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support~~99Install them with the default Windows package manager `winget` by pasting this

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

101asking Codex to install them:

63 102

~~64Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)~~103```powershell

104winget install --id Git.Git

105winget install --id OpenJS.NodeJS.LTS

106winget install --id Python.Python.3.14

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

108winget install --id GitHub.cli

109```

65 110

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

112the app.

66 113

~~67Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).~~114If you need a different Python or .NET version, change the package IDs to the

115version you want.

116

117## Troubleshooting and FAQ

118

119### Run commands with elevated permissions

120

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

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

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

124permission level.

125

126### PowerShell execution policy blocks commands

127

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

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

130

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

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

133them.

134

135An error may look something like this:

136

137```text

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

139```

140

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

142

143```powershell

144Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

145```

146

147For details and other options, check Microsoft's

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

149before changing the policy.

150

151### Local environment scripts on Windows

152

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

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

155set of actions for every platform.

156

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

158Windows-specific actions.

159

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

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

162

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

164and PowerShell otherwise.

165

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

167

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

169`%USERPROFILE%\.codex`.

170

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

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

173auth, or session history with the Windows app.

174

175To share them, use one of these approaches:

176

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

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

179

180```bash

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

182```

183

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

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

186

187### Git features are unavailable

188

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

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

191

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

193

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

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

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

197

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

199

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

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

202Codex or reboot.

auth.md +12 −2

Details

26 26

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

28 28

~~29Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Do not expose Codex execution in untrusted or publicly triggerable environments.~~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.

30 34

31## Secure your Codex cloud account35## Secure your Codex cloud account

32 36

85 89

86If 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.

87 91

~~88These 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).

89 93

90## Login on headless devices94## Login on headless devices

91 95

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

142```146```

143 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

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

145 155

146If 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 +1 −1

Details

55 55

56Run `codex` to start an interactive terminal UI (TUI) session.](https://developers.openai.com/codex/cli/features#running-in-interactive-mode)[### Control model and reasoning56Run `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 57

~~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~~58Use `/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 59

60Attach screenshots or design specs so Codex reads them alongside your prompt.](https://developers.openai.com/codex/cli/features#image-inputs)[### Run local code review60Attach 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 61

cli/features.md +4 −4

Details

46 46

47## Models and reasoning47## Models and reasoning

48 48

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

50 50

~~51Switch 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.

52 52

53```bash53```bash

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

55```55```

56 56

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

105 105

106## Web search106## Web search

107 107

108Codex 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.108Codex 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.

109 109

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

111 111

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

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

config-advanced.md +6 −6

Details

45 45

46```shell46```shell

47# Dedicated flag47# Dedicated flag

~~48codex --model gpt-5.2~~48codex --model gpt-5.4

49 49

50# Generic key/value override (value is TOML, not JSON)50# Generic key/value override (value is TOML, not JSON)

~~51codex --config model='"gpt-5.2"'~~51codex --config model='"gpt-5.4"'

52codex --config sandbox_workspace_write.network_access=true52codex --config sandbox_workspace_write.network_access=true

53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

54```54```

190 190

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

192 192

193For 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 that are easy to miss 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 194

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories (sandbox approvals, execpolicy rule prompts, or MCP elicitations) while keeping other prompts interactive.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.

196 196

197```197```

198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }

206network_access = false # Opt in to outbound network206network_access = false # Opt in to outbound network

207```207```

208 208

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

210 210

211In workspace-write mode, some environments keep `.git/` and `.codex/`211In workspace-write mode, some environments keep `.git/` and `.codex/`

212 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

304 304

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

306 306

307### Metrics307### Metrics

308 308

config-basic.md +7 −8

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

38 requirements](https://developers.openai.com/codex/enterprise/managed-configuration#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

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

71 71

72#### Windows sandbox mode72#### Windows sandbox mode

73 73

74When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you do not have administrator permissions or if elevated setup fails.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.

75 75

76```toml76```toml

77[windows]77[windows]

81 81

82#### Web search mode82#### Web search mode

83 83

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/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`:

85 85

86- `"cached"` (default) serves results from the web search cache.86- `"cached"` (default) serves results from the web search cache.

87- `"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`).

147 147

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

config-reference.md +658 −57

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

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

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

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

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

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

~~41| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |~~

~~43| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |~~

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

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

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

48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

62| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

63| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

64| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

70| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

72| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

73| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

74| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

~~69| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |~~

102| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

104| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

128| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

158| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

160| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

166| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

171| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

143| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

144| `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_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). |

180| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

185| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

212| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

172| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

217| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

175| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |218| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

222| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

179| `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. |223| `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. |

206 250

207Key251Key

208 252

253`agents.<name>.nickname_candidates`

254

255Type / Values

256

257`array<string>`

258

259Details

260

261Optional pool of display nicknames for spawned agents in that role.

262

263Key

264

209`agents.job_max_runtime_seconds`265`agents.job_max_runtime_seconds`

210 266

211Type / Values267Type / Values

254 310

255Key311Key

256 312

313`analytics.enabled`

314

315Type / Values

316

317`boolean`

318

319Details

320

321Enable or disable analytics for this machine/profile. When unset, the client default applies.

322

323Key

324

257`approval_policy`325`approval_policy`

258 326

259Type / Values327Type / Values

470 538

471Key539Key

472 540

541`commit_attribution`

542

543Type / Values

544

545`string`

546

547Details

548

549Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

550

551Key

552

473`compact_prompt`553`compact_prompt`

474 554

475Type / Values555Type / Values

518 598

519Key599Key

520 600

521`experimental_use_freeform_apply_patch`601`experimental_use_unified_exec_tool`

522 602

523Type / Values603Type / Values

524 604

526 606

527Details607Details

528 608

529Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.609Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

530 610

531Key611Key

532 612

533`experimental_use_unified_exec_tool`613`features.apps`

534 614

535Type / Values615Type / Values

536 616

538 618

539Details619Details

540 620

541Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.621Enable ChatGPT Apps/connectors support (experimental).

542 622

543Key623Key

544 624

545`features.apply_patch_freeform`625`features.apps_mcp_gateway`

546 626

547Type / Values627Type / Values

548 628

550 630

551Details631Details

552 632

553Expose the freeform `apply_patch` tool (experimental).633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

554 634

555Key635Key

556 636

557`features.apps`637`features.artifact`

558 638

559Type / Values639Type / Values

560 640

562 642

563Details643Details

564 644

565Enable ChatGPT Apps/connectors support (experimental).645Enable native artifact tools such as slides and spreadsheets (under development).

566 646

567Key647Key

568 648

569`features.apps_mcp_gateway`649`features.child_agents_md`

570 650

571Type / Values651Type / Values

572 652

574 654

575Details655Details

576 656

577Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).657Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

578 658

579Key659Key

580 660

581`features.child_agents_md`661`features.collaboration_modes`

582 662

583Type / Values663Type / Values

584 664

586 666

587Details667Details

588 668

589Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).669Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

590 670

591Key671Key

592 672

593`features.collaboration_modes`673`features.default_mode_request_user_input`

594 674

595Type / Values675Type / Values

596 676

598 678

599Details679Details

600 680

601Enable collaboration modes such as plan mode (stable; on by default).681Allow `request_user_input` in default collaboration mode (under development; off by default).

682

683Key

684

685`features.elevated_windows_sandbox`

686

687Type / Values

688

689`boolean`

690

691Details

692

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

694

695Key

696

697`features.enable_request_compression`

698

699Type / Values

700

701`boolean`

702

703Details

704

705Compress streaming request bodies with zstd when supported (stable; on by default).

706

707Key

708

709`features.experimental_windows_sandbox`

710

711Type / Values

712

713`boolean`

714

715Details

716

717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

718

719Key

720

721`features.fast_mode`

722

723Type / Values

724

725`boolean`

726

727Details

728

729Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

730

731Key

732

733`features.image_detail_original`

734

735Type / Values

736

737`boolean`

738

739Details

740

741Allow image outputs with `detail = "original"` on supported models (under development).

742

743Key

744

745`features.image_generation`

746

747Type / Values

748

749`boolean`

750

751Details

752

753Enable the built-in image generation tool (under development).

602 754

603Key755Key

604 756

634 786

635Details787Details

636 788

637Force PowerShell UTF-8 output (defaults to true).789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

790

791Key

792

793`features.prevent_idle_sleep`

794

795Type / Values

796

797`boolean`

798

799Details

800

801Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

638 802

639Key803Key

640 804

646 810

647Details811Details

648 812

649Refresh remote model list before showing readiness (experimental).813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

650 814

651Key815Key

652 816

658 822

659Details823Details

660 824

661Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

826

827Key

828

829`features.responses_websockets`

830

831Type / Values

832

833`boolean`

834

835Details

836

837Prefer the Responses API WebSocket transport for supported providers (under development).

838

839Key

840

841`features.responses_websockets_v2`

842

843Type / Values

844

845`boolean`

846

847Details

848

849Enable Responses API WebSocket v2 mode (under development).

662 850

663Key851Key

664 852

682 870

683Details871Details

684 872

685Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).873Legacy toggle for an older Apps discovery flow. Current builds do not use it.

686 874

687Key875Key

688 876

694 882

695Details883Details

696 884

697Snapshot shell environment to speed up repeated commands (beta).885Snapshot shell environment to speed up repeated commands (stable; on by default).

698 886

699Key887Key

700 888

710 898

711Key899Key

712 900

901`features.skill_env_var_dependency_prompt`

902

903Type / Values

904

905`boolean`

906

907Details

908

909Prompt for missing skill environment-variable dependencies (under development).

910

911Key

912

913`features.skill_mcp_dependency_install`

914

915Type / Values

916

917`boolean`

918

919Details

920

921Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

922

923Key

924

925`features.sqlite`

926

927Type / Values

928

929`boolean`

930

931Details

932

933Enable SQLite-backed state persistence (stable; on by default).

934

935Key

936

937`features.steer`

938

939Type / Values

940

941`boolean`

942

943Details

944

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

946

947Key

948

949`features.undo`

950

951Type / Values

952

953`boolean`

954

955Details

956

957Enable undo support (stable; off by default).

958

959Key

960

713`features.unified_exec`961`features.unified_exec`

714 962

715Type / Values963Type / Values

718 966

719Details967Details

720 968

721Use the unified PTY-backed exec tool (beta).969Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

722 970

723Key971Key

724 972

854 1102

855Key1103Key

856 1104

857`include_apply_patch_tool`

~~858~~

859Type / Values

~~860~~

861`boolean`

~~862~~

863Details

~~864~~

865Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.

~~866~~

867Key

~~868~~

869`instructions`1105`instructions`

870 1106

871Type / Values1107Type / Values

1058 1294

1059Key1295Key

1060 1296

1297`mcp_servers.<id>.oauth_resource`

1298

1299Type / Values

1300

1301`string`

1302

1303Details

1304

1305Optional RFC 8707 OAuth resource parameter to include during MCP login.

1306

1307Key

1308

1061`mcp_servers.<id>.required`1309`mcp_servers.<id>.required`

1062 1310

1063Type / Values1311Type / Values

1070 1318

1071Key1319Key

1072 1320

1321`mcp_servers.<id>.scopes`

1322

1323Type / Values

1324

1325`array<string>`

1326

1327Details

1328

1329OAuth scopes to request when authenticating to that MCP server.

1330

1331Key

1332

1073`mcp_servers.<id>.startup_timeout_ms`1333`mcp_servers.<id>.startup_timeout_ms`

1074 1334

1075Type / Values1335Type / Values

1334 1594

1335Key1595Key

1336 1596

1597`model_providers.<id>.supports_websockets`

1598

1599Type / Values

1600

1601`boolean`

1602

1603Details

1604

1605Whether that provider supports the Responses API WebSocket transport.

1606

1607Key

1608

1337`model_providers.<id>.wire_api`1609`model_providers.<id>.wire_api`

1338 1610

1339Type / Values1611Type / Values

1340 1612

1341`chat | responses`1613`responses`

1342 1614

1343Details1615Details

1344 1616

1345Protocol used by the provider (defaults to `chat` if omitted).1617Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1346 1618

1347Key1619Key

1348 1620

1390 1662

1391Details1663Details

1392 1664

1393Control GPT-5 Responses API verbosity (defaults to `medium`).1665Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1394 1666

1395Key1667Key

1396 1668

1598 1870

1599Key1871Key

1600 1872

1873`otel.metrics_exporter`

1874

1875Type / Values

1876

1877`none | statsig | otlp-http | otlp-grpc`

1878

1879Details

1880

1881Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1882

1883Key

1884

1601`otel.trace_exporter`1885`otel.trace_exporter`

1602 1886

1603Type / Values1887Type / Values

1682 1966

1683Key1967Key

1684 1968

1969`permissions.network.admin_url`

1970

1971Type / Values

1972

1973`string`

1974

1975Details

1976

1977Admin endpoint for the managed network proxy.

1978

1979Key

1980

1981`permissions.network.allow_local_binding`

1982

1983Type / Values

1984

1985`boolean`

1986

1987Details

1988

1989Permit local bind/listen operations through the managed proxy.

1990

1991Key

1992

1993`permissions.network.allow_unix_sockets`

1994

1995Type / Values

1996

1997`array<string>`

1998

1999Details

2000

2001Allowlist of Unix socket paths permitted through the managed proxy.

2002

2003Key

2004

2005`permissions.network.allow_upstream_proxy`

2006

2007Type / Values

2008

2009`boolean`

2010

2011Details

2012

2013Allow the managed proxy to chain to another upstream proxy.

2014

2015Key

2016

2017`permissions.network.allowed_domains`

2018

2019Type / Values

2020

2021`array<string>`

2022

2023Details

2024

2025Allowlist of domains permitted through the managed proxy.

2026

2027Key

2028

2029`permissions.network.dangerously_allow_all_unix_sockets`

2030

2031Type / Values

2032

2033`boolean`

2034

2035Details

2036

2037Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2038

2039Key

2040

2041`permissions.network.dangerously_allow_non_loopback_admin`

2042

2043Type / Values

2044

2045`boolean`

2046

2047Details

2048

2049Permit non-loopback bind addresses for the managed proxy admin listener.

2050

2051Key

2052

2053`permissions.network.dangerously_allow_non_loopback_proxy`

2054

2055Type / Values

2056

2057`boolean`

2058

2059Details

2060

2061Permit non-loopback bind addresses for the managed proxy listener.

2062

2063Key

2064

2065`permissions.network.denied_domains`

2066

2067Type / Values

2068

2069`array<string>`

2070

2071Details

2072

2073Denylist of domains blocked by the managed proxy.

2074

2075Key

2076

2077`permissions.network.enable_socks5`

2078

2079Type / Values

2080

2081`boolean`

2082

2083Details

2084

2085Expose a SOCKS5 listener from the managed network proxy.

2086

2087Key

2088

2089`permissions.network.enable_socks5_udp`

2090

2091Type / Values

2092

2093`boolean`

2094

2095Details

2096

2097Allow UDP over the SOCKS5 listener when enabled.

2098

2099Key

2100

2101`permissions.network.enabled`

2102

2103Type / Values

2104

2105`boolean`

2106

2107Details

2108

2109Enable the managed network proxy configuration for subprocesses.

2110

2111Key

2112

2113`permissions.network.mode`

2114

2115Type / Values

2116

2117`limited | full`

2118

2119Details

2120

2121Network proxy mode used for subprocess traffic.

2122

2123Key

2124

2125`permissions.network.proxy_url`

2126

2127Type / Values

2128

2129`string`

2130

2131Details

2132

2133HTTP proxy endpoint used by the managed network proxy.

2134

2135Key

2136

2137`permissions.network.socks_url`

2138

2139Type / Values

2140

2141`string`

2142

2143Details

2144

2145SOCKS5 proxy endpoint used by the managed network proxy.

2146

2147Key

2148

1685`personality`2149`personality`

1686 2150

1687Type / Values2151Type / Values

1694 2158

1695Key2159Key

1696 2160

2161`plan_mode_reasoning_effort`

2162

2163Type / Values

2164

2166

2167Details

2168

2169Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default.

2170

2171Key

2172

1697`profile`2173`profile`

1698 2174

1699Type / Values2175Type / Values

1718 2194

1719Key2195Key

1720 2196

1721`profiles.<name>.experimental_use_freeform_apply_patch`2197`profiles.<name>.analytics.enabled`

1722 2198

1723Type / Values2199Type / Values

1724 2200

1726 2202

1727Details2203Details

1728 2204

1729Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2205Profile-scoped analytics enablement override.

1730 2206

1731Key2207Key

1732 2208

1742 2218

1743Key2219Key

1744 2220

1745`profiles.<name>.include_apply_patch_tool`2221`profiles.<name>.model_catalog_json`

1746 2222

1747Type / Values2223Type / Values

1748 2224

1749`boolean`2225`string (path)`

1750 2226

1751Details2227Details

1752 2228

1753Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.2229Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1754 2230

1755Key2231Key

1756 2232

1757`profiles.<name>.model_catalog_json`2233`profiles.<name>.model_instructions_file`

1758 2234

1759Type / Values2235Type / Values

1760 2236

1762 2238

1763Details2239Details

1764 2240

1765Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).2241Profile-scoped replacement for the built-in instruction file.

1766 2242

1767Key2243Key

1768 2244

1790 2266

1791Key2267Key

1792 2268

2269`profiles.<name>.plan_mode_reasoning_effort`

2270

2271Type / Values

2272

2274

2275Details

2276

2277Profile-scoped Plan-mode reasoning override.

2278

2279Key

2280

2281`profiles.<name>.service_tier`

2282

2283Type / Values

2284

2285`flex | fast`

2286

2287Details

2288

2289Profile-scoped service tier preference for new turns.

2290

2291Key

2292

2293`profiles.<name>.tools_view_image`

2294

2295Type / Values

2296

2297`boolean`

2298

2299Details

2300

2301Enable or disable the `view_image` tool in that profile.

2302

2303Key

2304

1793`profiles.<name>.web_search`2305`profiles.<name>.web_search`

1794 2306

1795Type / Values2307Type / Values

1802 2314

1803Key2315Key

1804 2316

2317`profiles.<name>.windows.sandbox`

2318

2319Type / Values

2320

2321`unelevated | elevated`

2322

2323Details

2324

2325Profile-scoped Windows sandbox mode override.

2326

2327Key

2328

1805`project_doc_fallback_filenames`2329`project_doc_fallback_filenames`

1806 2330

1807Type / Values2331Type / Values

1922 2446

1923Key2447Key

1924 2448

2449`service_tier`

2450

2451Type / Values

2452

2453`flex | fast`

2454

2455Details

2456

2457Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.

2458

2459Key

2460

1925`shell_environment_policy.exclude`2461`shell_environment_policy.exclude`

1926 2462

1927Type / Values2463Type / Values

2078 2614

2079Key2615Key

2080 2616

2617`tools.view_image`

2618

2619Type / Values

2620

2621`boolean`

2622

2623Details

2624

2625Enable the local-image attachment tool `view_image`.

2626

2627Key

2628

2081`tools.web_search`2629`tools.web_search`

2082 2630

2083Type / Values2631Type / Values

2126 2674

2127Key2675Key

2128 2676

2677`tui.model_availability_nux.<model>`

2678

2679Type / Values

2680

2681`integer`

2682

2683Details

2684

2685Internal startup-tooltip state keyed by model slug.

2686

2687Key

2688

2129`tui.notification_method`2689`tui.notification_method`

2130 2690

2131Type / Values2691Type / Values

2174 2734

2175Key2735Key

2176 2736

2737`tui.theme`

2738

2739Type / Values

2740

2741`string`

2742

2743Details

2744

2745Syntax-highlighting theme override (kebab-case theme name).

2746

2747Key

2748

2177`web_search`2749`web_search`

2178 2750

2179Type / Values2751Type / Values

2227For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2799For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

2228requirements. See the security page for precedence details.2800requirements. See the security page for precedence details.

2229 2801

2802Use `[features]` in `requirements.toml` to pin feature flags by the same

2803canonical keys that `config.toml` uses. Omitted keys remain unconstrained.

2804

2230| Key | Type / Values | Details |2805| Key | Type / Values | Details |

2231| --- | --- | --- |2806| --- | --- | --- |

2234| `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`. |2809| `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`. |

2810| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2811| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2235| `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. |2812| `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. |

2282 2859

2283Key2860Key

2284 2861

2862`features`

2863

2864Type / Values

2865

2866`table`

2867

2868Details

2869

2870Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table.

2871

2872Key

2873

2874`features.<name>`

2875

2876Type / Values

2877

2878`boolean`

2879

2880Details

2881

2882Require a specific canonical feature key to stay enabled or disabled.

2883

2884Key

2885

2285`mcp_servers`2886`mcp_servers`

2286 2887

2287Type / Values2888Type / Values

config-sample.md +136 −113

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 override52# 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)53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

54# 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"

58# Reasoning & Verbosity (Responses API capable models)58# Reasoning & Verbosity (Responses API capable models)

59################################################################################59################################################################################

60 60

~~62model_reasoning_effort = "medium"~~62# model_reasoning_effort = "medium"

65# plan_mode_reasoning_effort = "high"

63 66

65# model_reasoning_summary = "auto"68# model_reasoning_summary = "auto"

66 69

~~67# 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

68# model_verbosity = "medium"71# model_verbosity = "medium"

69 72

~~70# Force enable or disable reasoning summaries for current model~~73# Force enable or disable reasoning summaries for current model.

71# model_supports_reasoning_summaries = true74# model_supports_reasoning_summaries = true

72 75

73################################################################################76################################################################################

77# Additional user instructions are injected before AGENTS.md. Default: unset.80# Additional user instructions are injected before AGENTS.md. Default: unset.

78# developer_instructions = ""81# developer_instructions = ""

79 82

~~80# (Ignored) Optional legacy base instructions override (prefer AGENTS.md). Default: unset.~~

~~81# instructions = ""~~

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

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

85 85

86# Override the default commit co-author trailer. Set to "" to disable it.

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

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

87# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"90# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

88 91

~~89# Migration note: experimental_instructions_file was renamed to model_instructions_file (deprecated).~~

91# Load the compact prompt override from a file. Default: unset.92# Load the compact prompt override from a file. Default: unset.

92# 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"

93 94

~~94# Legacy name for apply_patch_freeform. Default: false~~

~~95include_apply_patch_tool = false~~

97################################################################################95################################################################################

98# Notifications96# Notifications

99################################################################################97################################################################################

100 98

101# External notifier program (argv array). When unset: disabled.99# External notifier program (argv array). When unset: disabled.

102# Example: notify = ["notify-send", "Codex"]100# notify = ["notify-send", "Codex"]

103notify = [ ]

104 101

105################################################################################102################################################################################

106# Approval & Sandbox103# Approval & Sandbox

132# Where to persist CLI login credentials: file (default) | keyring | auto129# Where to persist CLI login credentials: file (default) | keyring | auto

133cli_auth_credentials_store = "file"130cli_auth_credentials_store = "file"

134 131

135# Base URL for ChatGPT auth flow (not OpenAI API). Default:132# Base URL for ChatGPT auth flow (not OpenAI API).

136chatgpt_base_url = "https://chatgpt.com/backend-api/"133chatgpt_base_url = "https://chatgpt.com/backend-api/"

137 134

138# Restrict ChatGPT login to a specific workspace id. Default: unset.135# Restrict ChatGPT login to a specific workspace id. Default: unset.

139# forced_chatgpt_workspace_id = ""136# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

140 137

141# Force login mechanism when Codex would normally auto-select. Default: unset.138# Force login mechanism when Codex would normally auto-select. Default: unset.

142# Allowed values: chatgpt | api139# Allowed values: chatgpt | api

201# 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.

202web_search = "cached"197web_search = "cached"

203 198

204################################################################################

205# Profiles (named presets)

206################################################################################

~~207~~

208# Active profile name. When unset, no profile is applied.199# Active profile name. When unset, no profile is applied.

209# profile = "default"200# profile = "default"

210 201

202# Suppress the warning shown when under-development feature flags are enabled.

203# suppress_unstable_features_warning = true

204

211################################################################################205################################################################################

212# Agents (multi-agent roles and limits)206# Agents (multi-agent roles and limits)

213################################################################################207################################################################################

214 208

215# [agents]209[agents]

216# Maximum concurrently open agent threads. Default: 6210# Maximum concurrently open agent threads. Default: 6

217# max_threads = 6211# max_threads = 6

218# Maximum nested spawn depth. Root session starts at depth 0. Default: 1212# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

221# job_max_runtime_seconds = 1800215# job_max_runtime_seconds = 1800

222 216

223# [agents.reviewer]217# [agents.reviewer]

224# description = "Find security, correctness, and test risks in code."218# description = "Find correctness, security, and test risks in code."

225# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it219# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

220# nickname_candidates = ["Athena", "Ada"]

226 221

227################################################################################222################################################################################

228# Skills (per-skill overrides)223# Skills (per-skill overrides)

233# path = "/path/to/skill/SKILL.md"228# path = "/path/to/skill/SKILL.md"

234# enabled = false229# enabled = false

235 230

236################################################################################

237# Experimental toggles (legacy; prefer [features])

238################################################################################

~~239~~

240experimental_use_unified_exec_tool = false

~~241~~

242# Include apply_patch via freeform editing path (affects default tool set). Default: false

243experimental_use_freeform_apply_patch = false

~~244~~

245################################################################################231################################################################################

246# Sandbox settings (tables)232# Sandbox settings (tables)

247################################################################################233################################################################################

264[shell_environment_policy]250[shell_environment_policy]

265# inherit: all (default) | core | none251# inherit: all (default) | core | none

266inherit = "all"252inherit = "all"

267# 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

268ignore_default_excludes = true254ignore_default_excludes = false

269# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []255# Case-insensitive glob patterns to remove (e.g., "AWS_*", "AZURE_*"). Default: []

270exclude = []256exclude = []

271# Explicit key/value overrides (always win). Default: {}257# Explicit key/value overrides (always win). Default: {}

275# Experimental: run via user shell profile. Default: false261# Experimental: run via user shell profile. Default: false

276experimental_use_profile = false262experimental_use_profile = false

277 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

278################################################################################285################################################################################

279# History (table)286# History (table)

280################################################################################287################################################################################

283# save-all (default) | none290# save-all (default) | none

284persistence = "save-all"291persistence = "save-all"

285# 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

286# max_bytes = 0293# max_bytes = 5242880

287 294

288################################################################################295################################################################################

289# UI, Notifications, and Misc (tables)296# UI, Notifications, and Misc (tables)

315# You can also add custom .tmTheme files under $CODEX_HOME/themes.322# You can also add custom .tmTheme files under $CODEX_HOME/themes.

316# theme = "catppuccin-mocha"323# theme = "catppuccin-mocha"

317 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

318# Control whether users can submit feedback from `/feedback`. Default: true333# Control whether users can submit feedback from `/feedback`. Default: true

319[feedback]334[feedback]

320enabled = true335enabled = true

328# "hide_gpt-5.1-codex-max_migration_prompt" = true343# "hide_gpt-5.1-codex-max_migration_prompt" = true

329# model_migrations = { "gpt-4.1" = "gpt-5.1" }344# model_migrations = { "gpt-4.1" = "gpt-5.1" }

330 345

331# Suppress the warning shown when under-development feature flags are enabled.

332# suppress_unstable_features_warning = true

~~333~~

334################################################################################346################################################################################

335# Centralized Feature Flags (preferred)347# Centralized Feature Flags (preferred)

336################################################################################348################################################################################

340# shell_tool = true352# shell_tool = true

341# apps = false353# apps = false

342# apps_mcp_gateway = false354# apps_mcp_gateway = false

343# web_search_cached = false

344# web_search_request = false

345# unified_exec = false355# unified_exec = false

346# shell_snapshot = false356# shell_snapshot = false

347# apply_patch_freeform = false

348# multi_agent = false357# multi_agent = false

349# search_tool = false

350# personality = true358# personality = true

351# request_rule = true

352# collaboration_modes = true

353# use_linux_sandbox_bwrap = false359# use_linux_sandbox_bwrap = false

354# remote_models = false360# runtime_metrics = true

355# runtime_metrics = false

356# powershell_utf8 = true361# powershell_utf8 = true

357# child_agents_md = false362# child_agents_md = false

363# sqlite = true

364# fast_mode = true

365# enable_request_compression = true

366# image_generation = false

367# skill_mcp_dependency_install = true

368# skill_env_var_dependency_prompt = false

369# default_mode_request_user_input = false

370# artifact = false

371# prevent_idle_sleep = false

372# responses_websockets = false

373# responses_websockets_v2 = false

374# image_detail_original = false

358 375

359################################################################################376################################################################################

360# Define MCP servers under this table. Leave empty to disable.377# Define MCP servers under this table. Leave empty to disable.

376# tool_timeout_sec = 60.0 # optional; default 60.0 seconds393# tool_timeout_sec = 60.0 # optional; default 60.0 seconds

377# enabled_tools = ["search", "summarize"] # optional allow-list394# enabled_tools = ["search", "summarize"] # optional allow-list

378# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)395# disabled_tools = ["slow-tool"] # optional deny-list (applied after allow-list)

396# scopes = ["read:docs"] # optional OAuth scopes

397# oauth_resource = "https://docs.example.com/" # optional OAuth resource

379 398

380# --- Example: Streamable HTTP transport ---399# --- Example: Streamable HTTP transport ---

381# [mcp_servers.github]400# [mcp_servers.github]

388# startup_timeout_sec = 10.0 # optional407# startup_timeout_sec = 10.0 # optional

389# tool_timeout_sec = 60.0 # optional408# tool_timeout_sec = 60.0 # optional

390# enabled_tools = ["list_issues"] # optional allow-list409# enabled_tools = ["list_issues"] # optional allow-list

410# disabled_tools = ["delete_issue"] # optional deny-list

411# scopes = ["repo"] # optional OAuth scopes

391 412

392################################################################################413################################################################################

393# Model Providers414# Model Providers

394################################################################################415################################################################################

395 416

396# Built-ins include:417# Built-ins include:

397# - openai (Responses API; requires login or OPENAI_API_KEY via auth flow)418# - openai

398# - oss (Chat Completions API; defaults to http://localhost:11434/v1)419# - ollama

420# - lmstudio

399 421

400[model_providers]422[model_providers]

401 423

403# [model_providers.openaidr]425# [model_providers.openaidr]

404# name = "OpenAI Data Residency"426# name = "OpenAI Data Residency"

405# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix427# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix

406# wire_api = "responses" # "responses" | "chat" (default varies)428# wire_api = "responses" # only supported value

407# # requires_openai_auth = true # built-in OpenAI defaults to true429# # requires_openai_auth = true # built-in OpenAI defaults to true

408# # request_max_retries = 4 # default 4; max 100430# # request_max_retries = 4 # default 4; max 100

409# # stream_max_retries = 5 # default 5; max 100431# # stream_max_retries = 5 # default 5; max 100

410# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)432# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)

433# # supports_websockets = true # optional

411# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token434# # experimental_bearer_token = "sk-example" # optional dev-only direct bearer token

412# # http_headers = { "X-Example" = "value" }435# # http_headers = { "X-Example" = "value" }

413# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }436# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }

414 437

415# --- Example: Azure (Chat/Responses depending on endpoint) ---438# --- Example: Azure/OpenAI-compatible provider ---

416# [model_providers.azure]439# [model_providers.azure]

417# name = "Azure"440# name = "Azure"

418# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"441# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"

419# wire_api = "responses" # or "chat" per endpoint442# wire_api = "responses"

420# query_params = { api-version = "2025-04-01-preview" }443# query_params = { api-version = "2025-04-01-preview" }

421# env_key = "AZURE_OPENAI_API_KEY"444# env_key = "AZURE_OPENAI_API_KEY"

422# # env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"445# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

446# # supports_websockets = false

423 447

424# --- Example: Local OSS (e.g., Ollama-compatible) ---448# --- Example: Local OSS (e.g., Ollama-compatible) ---

425# [model_providers.ollama]449# [model_providers.ollama]

426# name = "Ollama"450# name = "Ollama"

427# base_url = "http://localhost:11434/v1"451# base_url = "http://localhost:11434/v1"

428# wire_api = "chat"452# wire_api = "responses"

~~429~~

430################################################################################

431# Profiles (named presets)

432################################################################################

~~433~~

434[profiles]

~~435~~

436# [profiles.default]

437# model = "gpt-5.2-codex"

438# model_provider = "openai"

439# approval_policy = "on-request"

440# sandbox_mode = "read-only"

441# oss_provider = "ollama"

442# model_reasoning_effort = "medium"

443# model_reasoning_summary = "auto"

444# model_verbosity = "medium"

445# personality = "friendly" # or "pragmatic" or "none"

446# chatgpt_base_url = "https://chatgpt.com/backend-api/"

447# model_catalog_json = "./models.json"

448# experimental_compact_prompt_file = "./compact_prompt.txt"

449# include_apply_patch_tool = false

450# experimental_use_unified_exec_tool = false

451# experimental_use_freeform_apply_patch = false

452# tools.web_search = false # deprecated legacy alias; prefer top-level `web_search`

453# features = { unified_exec = false }

454 453

455################################################################################454################################################################################

456# Apps / Connectors455# Apps / Connectors

474# enabled = false473# enabled = false

475# approval_mode = "approve"474# approval_mode = "approve"

476 475

476################################################################################

477# Profiles (named presets)

478################################################################################

479

480[profiles]

481

482# [profiles.default]

483# model = "gpt-5.4"

484# model_provider = "openai"

485# approval_policy = "on-request"

486# sandbox_mode = "read-only"

487# service_tier = "flex"

488# oss_provider = "ollama"

489# model_reasoning_effort = "medium"

490# plan_mode_reasoning_effort = "high"

491# model_reasoning_summary = "auto"

492# model_verbosity = "medium"

493# personality = "pragmatic" # or "friendly" or "none"

494# chatgpt_base_url = "https://chatgpt.com/backend-api/"

495# model_catalog_json = "./models.json"

496# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

497# experimental_compact_prompt_file = "./compact_prompt.txt"

498# tools_view_image = true

499# features = { unified_exec = false }

500

477################################################################################501################################################################################

478# Projects (trust levels)502# Projects (trust levels)

479################################################################################503################################################################################

480 504

481# Mark specific worktrees as trusted or untrusted.

482[projects]505[projects]

506# Mark specific worktrees as trusted or untrusted.

483# [projects."/absolute/path/to/project"]507# [projects."/absolute/path/to/project"]

484# trust_level = "trusted" # or "untrusted"508# trust_level = "trusted" # or "untrusted"

485 509

510################################################################################

511# Tools

512################################################################################

513

514[tools]

515# view_image = true

516

486################################################################################517################################################################################

487# OpenTelemetry (OTEL) - disabled by default518# OpenTelemetry (OTEL) - disabled by default

488################################################################################519################################################################################

496exporter = "none"527exporter = "none"

497# Trace exporter: none (default) | otlp-http | otlp-grpc528# Trace exporter: none (default) | otlp-http | otlp-grpc

498trace_exporter = "none"529trace_exporter = "none"

530# Metrics exporter: none | statsig | otlp-http | otlp-grpc

531metrics_exporter = "statsig"

499 532

500# Example OTLP/HTTP exporter configuration533# Example OTLP/HTTP exporter configuration

501# [otel.exporter."otlp-http"]534# [otel.exporter."otlp-http"]

505# [otel.exporter."otlp-http".headers]538# [otel.exporter."otlp-http".headers]

506# "x-otlp-api-key" = "${OTLP_TOKEN}"539# "x-otlp-api-key" = "${OTLP_TOKEN}"

507 540

508# Example OTLP/gRPC exporter configuration

509# [otel.exporter."otlp-grpc"]

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

511# headers = { "x-otlp-meta" = "abc123" }

~~512~~

513# Example OTLP exporter with mutual TLS

514# [otel.exporter."otlp-http"]

515# endpoint = "https://otel.example.com/v1/logs"

516# protocol = "binary"

~~517~~

518# [otel.exporter."otlp-http".headers]

519# "x-otlp-api-key" = "${OTLP_TOKEN}"

~~520~~

521# [otel.exporter."otlp-http".tls]541# [otel.exporter."otlp-http".tls]

522# ca-certificate = "certs/otel-ca.pem"542# ca-certificate = "certs/otel-ca.pem"

523# client-certificate = "/etc/codex/certs/client.pem"543# client-certificate = "/etc/codex/certs/client.pem"

524# client-private-key = "/etc/codex/certs/client-key.pem"544# client-private-key = "/etc/codex/certs/client-key.pem"

525```

526 545

527################################################################################546# Example OTLP/gRPC trace exporter configuration

547# [otel.trace_exporter."otlp-grpc"]

548# endpoint = "https://otel.example.com:4317"

549# headers = { "x-otlp-meta" = "abc123" }

528 550

551################################################################################

529# Windows552# Windows

~~530~~

531################################################################################553################################################################################

532 554

533[windows]555[windows]

~~534~~

535# Native Windows sandbox mode (Windows only): unelevated | elevated556# Native Windows sandbox mode (Windows only): unelevated | elevated

~~536~~

537sandbox = "unelevated"557sandbox = "unelevated"

558```

enterprise/admin-setup.md +4 −4

Details

2 2

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

4 4

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

6 6

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

8 8

14- Granular user access controls14- Granular user access controls

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

16 16

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

18 18

19## Local vs. cloud setup19## Local vs. cloud setup

20 20

100 100

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

102 102

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

104 104

105![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)105![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)

106 106

158- MCP / connectors policy158- MCP / connectors policy

159- Local logging and telemetry posture159- Local logging and telemetry posture

160 160

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

162 162

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

164 164

enterprise/managed-configuration.md +13 −1

Details

9 9

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

11 11

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

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

13 15

14### Locations and precedence16### Locations and precedence

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

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

81 83

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 effective feature set to satisfy these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

82### Enforce command rules from requirements94### Enforce command rules from requirements

83 95

84Admins can also enforce restrictive command rules from `requirements.toml`96Admins can also enforce restrictive command rules from `requirements.toml`

142 - `config_toml_base64` (managed defaults)154 - `config_toml_base64` (managed defaults)

143 - `requirements_toml_base64` (requirements)155 - `requirements_toml_base64` (requirements)

144 156

145Codex 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.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.

146 158

147### MDM setup workflow159### MDM setup workflow

148 160

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

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

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 +2 −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.

security.md +22 −233

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. 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.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. 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).29Codex Security works with connected GitHub repositories through Codex cloud. OpenAI manages access. If you need access or a repository isn’t visible, contact your OpenAI account team and confirm the repository is available through your Codex cloud workspace.

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.

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

~~78### Common sandbox and approval combinations~~

~~80| Intent | Flags | Effect |~~

~~81| --- | --- | --- |~~

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

~~83| 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. |~~

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

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

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

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

90With `--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.

~~92#### Configuration in `config.toml`~~

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

~~96```~~

~~97# Always ask for approval mode~~

~~98approval_policy = "untrusted"~~

~~99sandbox_mode = "read-only"~~

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

~~101~~

102# Optional: Allow network in workspace-write mode

103[sandbox_workspace_write]

104network_access = true

~~105~~

106# Optional: granular approval prompt auto-rejection

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

108```

~~109~~

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

~~111~~

112```

113[profiles.full_auto]

114approval_policy = "on-request"

115sandbox_mode = "workspace-write"

~~116~~

117[profiles.readonly_quiet]

118approval_policy = "never"

119sandbox_mode = "read-only"

120```

~~121~~

122### Test the sandbox locally

~~123~~

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

~~125~~

126```

127# macOS

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

129# Linux

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

131```

~~132~~

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

~~134~~

135## OS-level sandbox

~~136~~

137Codex enforces the sandbox differently depending on your OS:

~~138~~

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

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

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

~~142~~

143If 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:

~~144~~

145```

146{

147 "chatgpt.runCodexInWindowsSubsystemForLinux": true

148}

149```

~~150~~

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

~~152~~

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

~~154~~

155```

156[windows]

157sandbox = "unelevated" # or "elevated"

158```

~~159~~

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

~~161~~

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

~~163~~

164In 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.

~~165~~

166## Version control

~~167~~

168Codex works best with a version control workflow:

~~169~~

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

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

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

~~173~~

174## Monitoring and telemetry

~~175~~

176Codex 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.

~~177~~

178### Overview

~~179~~

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

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

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

~~183~~

184### Enable OTel (opt-in)

~~185~~

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

~~187~~

188```

189[otel]

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

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

192log_user_prompt = false # redact prompt text unless policy allows

193```

~~194~~

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

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

~~197~~

198```

199[otel]

200exporter = { otlp-http = {

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

202 protocol = "binary",

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

204}}

205```

~~206~~

207```

208[otel]

209exporter = { otlp-grpc = {

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

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

212}}

213```

~~214~~

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

~~216~~

217### Event categories

~~218~~

219Representative event types include:

~~220~~

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

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

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

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

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

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

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

~~228~~

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

~~230~~

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

~~232~~

233### Security and privacy guidance

~~234~~

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

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

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

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

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

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

~~241~~

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

~~243~~

244## Managed configuration

~~245~~

246Enterprise 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.

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.

windows.md +7 −1

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.

5[![](/images/codex/codex-banner-icon.webp)

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)

4 10

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

6 12

OpenAI - Codex Docs Changes 2026-03-04 06:20 UTC → 2026-03-08 00:35 UTC