config-basic.md Codex Docs, 2026-02-19 20:37 UTC → 2026-02-23 18:27 UTC

1# Config basics1# Config basics

2 2 

3Learn the basics of configuring your local Codex client

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

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

39 39 

40## Common configuration options40## Common configuration options

41 41 

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

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

71 

68#### Web search mode72#### Web search mode

69 73 

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

71 75 

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

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