config-basic.md Codex Docs, 2026-03-05 06:22 UTC → 2026-04-23 12:28 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

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

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

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

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

153| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

154| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |

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

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

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

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

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

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

161| `shell_tool` | true | Stable | Enable the default `shell` tool |157| `shell_tool` | true | Stable | Enable the default `shell` tool |

162| `use_linux_sandbox_bwrap` | false | Experimental | Use the bubblewrap-based Linux sandbox pipeline |158| `guardian_approval` | false | Experimental | Route eligible approval requests through the guardian reviewer subagent (set `approvals_reviewer = "guardian_subagent"`). |

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

164| `undo` | true | Stable | Enable undo via per-turn git ghost snapshots |160| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

165| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |161| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

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

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

168 164 

169The Maturity column uses feature maturity labels such as Experimental, Beta,165The Maturity column uses feature maturity labels such as Experimental, Beta,

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

172 168 

173Omit feature keys to keep their defaults.169Omit feature keys to keep their defaults.

174 170 

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

172 

175### Enabling features173### Enabling features

176 174 

177- In `config.toml`, add `feature_name = true` under `[features]`.175- In `config.toml`, add `feature_name = true` under `[features]`.