config-basic.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-02 00:48 UTC

1# Config basics1# Config basics

2 2 

3Learn the basics of configuring your local Codex client3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project `.codex/` layers only when you trust the project.

4 

5Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project config files only when you trust the project.

6 4 

7## Codex configuration file5## Codex configuration file

8 6 

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

14 12 

15- Set the default model and provider.13- Set the default model and provider.

16- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/security).14- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals).

17- Configure [MCP servers](https://developers.openai.com/codex/mcp).15- Configure [MCP servers](https://developers.openai.com/codex/mcp).

18 16 

19## Configuration precedence17## Configuration precedence

29 27 

30Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.

31 29 

32If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers (including `.codex/config.toml`) and falls back to user, system, and built-in defaults.30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

33 31 

34For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).

35 33 

36On managed machines, your organization may also enforce constraints via34On managed machines, your organization may also enforce constraints via

37 `requirements.toml` (for example, disallowing `approval_policy = "never"` or35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or

38`sandbox_mode = "danger-full-access"`). See [Security](https://developers.openai.com/codex/security).36 `sandbox_mode = "danger-full-access"`). See [Managed

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

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.5"

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

60#### Sandbox level62#### Sandbox level

61 63 

62Adjust how much filesystem and network access Codex has while executing commands.64Adjust how much filesystem and network access Codex has while executing commands.

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

66```68```

67 69 

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#### Permission profiles

73 

74Use a named permission profile when you want one reusable filesystem or network policy across sessions:

75 

76```toml

77default_permissions = ":workspace"

78```

79 

80Built-in profiles include `:read-only`, `:workspace`, and `:danger-no-sandbox`. For custom filesystem or network rules, define `[permissions.<name>]` tables and set `default_permissions` to that name.

81 

82#### Windows sandbox mode

83 

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

85 

86```toml

87[windows]

88sandbox = "elevated" # Recommended

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

90```

91 

68#### Web search mode92#### Web search mode

69 93 

70Codex 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), web search defaults to live results. Choose a mode with `web_search`:94Codex 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`:

71 95 

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

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

97 121 

98You can override this later in an active session with `/personality` or per thread/turn when using the app-server APIs.122You can override this later in an active session with `/personality` or per thread/turn when using the app-server APIs.

99 123 

124#### TUI keymap

125 

126Customize terminal shortcuts under `tui.keymap`. Context-specific bindings override `tui.keymap.global`, and an empty list unbinds the action.

127 

128```toml

129[tui.keymap.global]

130open_transcript = "ctrl-t"

131 

132[tui.keymap.composer]

133submit = ["enter", "ctrl-m"]

134```

135 

100#### Command environment136#### Command environment

101 137 

102Control which environment variables Codex forwards to spawned commands.138Control which environment variables Codex forwards to spawned commands.

133 169 

134| Key | Default | Maturity | Description |170| Key | Default | Maturity | Description |

135| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

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

137| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |172| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

138| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |173| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

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

140| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |175| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

141| `experimental_windows_sandbox` | false | Experimental | Use the Windows restricted-token sandbox |176| `multi_agent` | true | Stable | Enable subagent collaboration tools |

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

143| `personality` | true | Stable | Enable personality selection controls |177| `personality` | true | Stable | Enable personality selection controls |

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

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

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

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

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

149| `shell_tool` | true | Stable | Enable the default `shell` tool |179| `shell_tool` | true | Stable | Enable the default `shell` tool |

150| `use_linux_sandbox_bwrap` | false | Experimental | Use the bubblewrap-based Linux sandbox pipeline |180| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

151| `unified_exec` | false | Beta | Use the unified PTY-backed exec tool |181| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

152| `undo` | true | Stable | Enable undo via per-turn git ghost snapshots |

153| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |182| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

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

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

156 185 

157The Maturity column uses feature maturity labels such as Experimental, Beta,186The Maturity column uses feature maturity labels such as Experimental, Beta,

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

160 189 

161Omit feature keys to keep their defaults.190Omit feature keys to keep their defaults.

162 191 

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

193 

163### Enabling features194### Enabling features

164 195 

165- In `config.toml`, add `feature_name = true` under `[features]`.196- In `config.toml`, add `feature_name = true` under `[features]`.