Config basics

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

Codex configuration file

Codex stores user-level configuration at ~/.codex/config.toml. To scope settings to a specific project or subfolder, add a .codex/config.toml file in your repo.

To open the configuration file from the Codex IDE extension, select the gear icon in the top-right corner, then select Codex Settings > Open config.toml.

The CLI and IDE extension share the same configuration layers. You can use them to:

• Set the default model and provider.
• Configure approval policies and sandbox settings.
• Configure MCP servers.

Configuration precedence

Codex resolves values in this order (highest precedence first):

1. CLI flags and --config overrides
2. Profile values (from --profile <name>)
3. Project config files: .codex/config.toml, ordered from the project root down to your current working directory (closest wins; trusted projects only)
4. User config: ~/.codex/config.toml
5. System config (if present): /etc/codex/config.toml on Unix
6. Built-in defaults

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

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

For one-off overrides via -c/--config (including TOML quoting rules), see Advanced Config.

Common configuration options

Here are a few options people change most often:

Default model

Choose the model Codex uses by default in the CLI and IDE.

model = "gpt-5.2"

Approval prompts

Control when Codex pauses to ask before running generated commands.

approval_policy = "on-request"

Sandbox level

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

sandbox_mode = "workspace-write"

Web search mode

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

• "cached" (default) serves results from the web search cache.
• "live" fetches the most recent data from the web (same as --search).
• "disabled" turns off the web search tool.

web_search = "cached"  # default; serves results from the web search cache
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Reasoning effort

Tune how much reasoning effort the model applies when supported.

model_reasoning_effort = "high"

Command environment

Control which environment variables Codex forwards to spawned commands.

[shell_environment_policy]
include_only = ["PATH", "HOME"]

Feature flags

Use the [features] table in config.toml to toggle optional and experimental capabilities.

[features]
shell_snapshot = true           # Speed up repeated commands

Supported features

Enabling features

• In config.toml, add feature_name = true under [features].
• From the CLI, run codex --enable feature_name.
• To enable more than one feature, run codex --enable feature_a --enable feature_b.
• To disable a feature, set the key to false in config.toml.