config-basic diff

config-basic.md +20 −8

Details

1# Config basics1# Config basics

2 2

~~3Learn the basics of configuring your local Codex client~~

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

6 4

7## Codex configuration file5## Codex configuration file

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

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

37configuration](https://developers.openai.com/codex/security#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.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).

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

72#### Windows sandbox mode

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.

76```toml

77[windows]

78sandbox = "elevated" # Recommended

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

80```

68#### Web search mode82#### Web search mode

69 83

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

71 85

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

73- `"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`).

config-basic.md Codex Docs, 2026-02-19 20:37 UTC → 2026-03-05 18:41 UTC