config-basic diff

config-basic.md +27 −5

Details

1# Config basics1# Config basics

2 2

3Codex 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.3Codex 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 4

5## Codex configuration file5## Codex configuration file

6 6

27 27

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

29 29

~~30If 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.

31 31

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

33 33

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.4"~~49model = "gpt-5.5"

50```50```

51 51

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

69 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).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#### Permission profiles

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

76```toml

77default_permissions = ":workspace"

78```

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.

72#### Windows sandbox mode82#### Windows sandbox mode

73 83

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

111 121

112You 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.

113 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

114#### Command environment136#### Command environment

115 137

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

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

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

config-basic.md Codex Docs, 2026-04-13 18:37 UTC → 2026-04-30 18:36 UTC