config-basic.md Codex Docs, 2026-02-23 18:27 UTC → 2026-03-28 06:26 UTC

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-enforced37 configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Admin-enforced

38requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).38 requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

39 39 

40## Common configuration options40## Common configuration options

41 41 

46Choose the model Codex uses by default in the CLI and IDE.46Choose the model Codex uses by default in the CLI and IDE.

47 47 

48```toml48```toml

49model = "gpt-5.2"49model = "gpt-5.4"

50```50```

51 51 

52#### Approval prompts52#### Approval prompts

57approval_policy = "on-request"57approval_policy = "on-request"

58```58```

59 59 

60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations).60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations).

61 61 

62#### Sandbox level62#### Sandbox level

63 63 

67sandbox_mode = "workspace-write"67sandbox_mode = "workspace-write"

68```68```

69 69 

70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

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 don't 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```

71 81 

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

73 83 

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

75 85 

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

77- `"live"` fetches the most recent data from the web (same as `--search`).87- `"live"` fetches the most recent data from the web (same as `--search`).

137 147 

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

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

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

141| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `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 |151| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |

143| `elevated_windows_sandbox` | false | Experimental | Use the elevated Windows sandbox pipeline |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

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

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

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

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

148| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |155| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |

149| `runtime_metrics` | false | Experimental | Show runtime metrics summaries in TUI turn separators |

150| `request_rule` | true | Stable | Enable Smart approvals (`prefix_rule` suggestions) |

151| `search_tool` | false | Experimental | Enable `search_tool_bm25` so Codex discovers Apps MCP tools via search before tool calls |

152| `shell_snapshot` | false | Beta | Snapshot your shell environment to speed up repeated commands |

153| `shell_tool` | true | Stable | Enable the default `shell` tool |156| `shell_tool` | true | Stable | Enable the default `shell` tool |

154| `use_linux_sandbox_bwrap` | false | Experimental | Use the bubblewrap-based Linux sandbox pipeline |157| `smart_approvals` | false | Experimental | Route eligible approval requests through the guardian reviewer subagent |

155| `unified_exec` | false | Beta | Use the unified PTY-backed exec tool |158| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

156| `undo` | true | Stable | Enable undo via per-turn git ghost snapshots |159| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

157| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |160| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

158| `web_search_cached` | true | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |161| `web_search_cached` | false | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |

159| `web_search_request` | true | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |162| `web_search_request` | false | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |

160 163 

161The Maturity column uses feature maturity labels such as Experimental, Beta,164The Maturity column uses feature maturity labels such as Experimental, Beta,

162 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to165 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to

164 167 

165Omit feature keys to keep their defaults.168Omit feature keys to keep their defaults.

166 169 

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

171 

167### Enabling features172### Enabling features

168 173 

169- In `config.toml`, add `feature_name = true` under `[features]`.174- In `config.toml`, add `feature_name = true` under `[features]`.