OpenAI - Codex Docs Changes 2026-02-24 00:33 UTC → 2026-02-24 06:27 UTC

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

71 71 

72#### Windows sandbox mode

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.

75 

76```toml

77[windows]

78sandbox = "elevated" # Recommended

79# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

80```

81 

72#### Web search mode82#### Web search mode

73 83 

74Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:84Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

140| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |150| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |

141| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |151| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

142| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |152| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |

143| `elevated_windows_sandbox` | false | Experimental | Use the elevated Windows sandbox pipeline |

144| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |153| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |

145| `experimental_windows_sandbox` | false | Experimental | Use the Windows restricted-token sandbox |

146| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |154| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |

147| `personality` | true | Stable | Enable personality selection controls |155| `personality` | true | Stable | Enable personality selection controls |

148| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |156| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |

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

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

49| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |47| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

50| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |48| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |49| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |

178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |176| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

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

180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |178| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

179| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

181 180 

182Key181Key

183 182 

589 588 

590Key589Key

591 590 

592`features.elevated_windows_sandbox`

593 

594Type / Values

595 

596`boolean`

597 

598Details

599 

600Enable the elevated Windows sandbox pipeline (experimental).

601 

602Key

603 

604`features.experimental_windows_sandbox`

605 

606Type / Values

607 

608`boolean`

609 

610Details

611 

612Run the Windows restricted-token sandbox (experimental).

613 

614Key

615 

616`features.multi_agent`591`features.multi_agent`

617 592 

618Type / Values593Type / Values

2195 2170 

2196Track Windows onboarding acknowledgement (Windows only).2171Track Windows onboarding acknowledgement (Windows only).

2197 2172 

2173Key

2174 

2175`windows.sandbox`

2176 

2177Type / Values

2178 

2179`unelevated | elevated`

2180 

2181Details

2182 

2183Windows-only native sandbox mode when running Codex natively on Windows.

2184 

2198Expand to view all2185Expand to view all

2199 2186 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2187You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

348# request_rule = true348# request_rule = true

349# collaboration_modes = true349# collaboration_modes = true

350# use_linux_sandbox_bwrap = false350# use_linux_sandbox_bwrap = false

351# experimental_windows_sandbox = false

352# elevated_windows_sandbox = false

353# remote_models = false351# remote_models = false

354# runtime_metrics = false352# runtime_metrics = false

355# powershell_utf8 = true353# powershell_utf8 = true

522# client-certificate = "/etc/codex/certs/client.pem"520# client-certificate = "/etc/codex/certs/client.pem"

523# client-private-key = "/etc/codex/certs/client-key.pem"521# client-private-key = "/etc/codex/certs/client-key.pem"

524```522```

523 

524################################################################################

525 

526# Windows

527 

528################################################################################

529 

530[windows]

531 

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

533 

534sandbox = "unelevated"

138 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.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.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, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.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 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: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 144 

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

153The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.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.

154 161 

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

156 163 

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 [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 4 

5When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).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).

6 6 

7Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.7If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.

8 

9## Windows sandbox

10 

11Native Windows sandbox support includes two modes that you can configure in `config.toml`:

12 

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

17 

18How `elevated` mode works:

19 

20- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

21- Runs commands as a dedicated Windows Sandbox User.

22- Limits network access by installing Windows Firewall rules.

23 

24### Grant sandbox read access

25 

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

27 

28```text

29/sandbox-add-read-dir C:\absolute\directory\path

30```

31 

32The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

8 33 

9## Windows Subsystem for Linux34## Windows Subsystem for Linux

10 35 

81 ```106 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.107- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 108 

84## Windows experimental sandbox109## Troubleshooting and FAQ

85 

86The Windows sandbox support is experimental. How it works:

87 

88- Launches commands inside a restricted token derived from an AppContainer profile.

89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.

90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.

91 

92Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.

93 

94### Grant sandbox read access

95 

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

97 

98```text

99/sandbox-add-read-dir C:\absolute\directory\path

100```

101 

102The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

103 

104### Troubleshooting and FAQ

105 110 

106#### Installed extension, but it’s unresponsive111#### Installed extension, but it’s unresponsive

107 112