Configuring Codex with config.toml

Who this is for and what you will be able to do

This guide is for people who already have the Codex CLI or the IDE extension installed and want to change its default behavior. After reading it you should know where the configuration file lives, how the configuration layers combine, how to write a few common keys such as the model, approval policy, sandbox and web search, and how to turn feature flags on and off.^[1]

Where the configuration file lives

User-level configuration is stored in ~/.codex/config.toml.^[1] To scope settings to one project or subfolder, add a .codex/config.toml file to the repository.^[1] Codex loads project .codex/ layers only when you trust the project.^[1]

In the IDE extension, select the gear icon in the top-right corner, then choose Codex Settings and Open config.toml.^[1] The CLI and the IDE extension share the same configuration layers, so a change applies to both.^[1]

How values are resolved

Codex resolves each value from the following sources, highest precedence first:^[1]

1. CLI flags and --config overrides.
2. Project config files named .codex/config.toml. Codex reads them from the project root down toward the current directory, the closest one wins, and only trusted projects are used.
3. A profile file selected with --profile, at ~/.codex/profile-name.config.toml.
4. The user config at ~/.codex/config.toml.
5. Cloud-managed defaults for the signed-in workspace, when they are delivered.
6. The system config, which on Unix is /etc/codex/config.toml.
7. Built-in defaults.

If you mark a project as untrusted, Codex skips its project-scoped .codex/ layers, including project-local config, hooks, and rules. The user and system config still load.^[1]

For a one-off override, use -c or --config, for example codex -c log_dir=./.codex-log.^[1]

Common settings

Model, approvals and sandbox

The model key sets the default model. The config can also set the default provider.^[1]

approval_policy controls when Codex pauses to ask before it runs commands it has generated. The docs use on-request as the example value.^[1]

sandbox_mode sets how much filesystem and network access Codex has while it executes commands. The docs use workspace-write as the example value.^[1]

Permissions can also be packaged as named profiles. The built-in ones are :read-only, :workspace and :danger-full-access. Custom profiles are written in [permissions.<name>] tables and selected with default_permissions.^[1]

The untrusted value of approval_policy has been retired. If a configuration still uses it, follow the official migration steps.^[1]

Web search

The web_search key accepts four values:^[1]

• cached, the default, serves results from the web search cache.
• indexed allows external web access only when the search index gates the request.
• live fetches the most recent data from the web and is the same as the --search flag.
• disabled turns off the web search tool.

The cache is an index of web results maintained by OpenAI. Cached mode returns pre-indexed results instead of fetching live pages, which reduces exposure to prompt injection from live content. Web results should still be treated as untrusted.^[1] With --yolo or another full-access sandbox setting, web search defaults to live results.^[1]

Reasoning effort and personality

model_reasoning_effort tunes how much reasoning effort the model applies, where that is supported. The docs use medium as the example.^[1]

Setting personality to none removes the Personality section from the model's built-in instructions. It does not change custom base instructions you set explicitly.^[1] The older friendly and pragmatic values no longer select a style, and the /personality command is no longer provided.^[1]

Environment variables for commands

[shell_environment_policy] controls which environment variables Codex passes to the commands it starts. ignore_default_excludes defaults to true, which skips automatic filtering of variable names that contain KEY, SECRET or TOKEN. Set it to false to turn that filtering on.^[1]

Log directory

log_dir sets where Codex writes its local logs. Setting it explicitly also enables an opt-in plaintext TUI log, codex-tui.log, in the same directory.^[1]

Feature flags

The [features] table turns optional and experimental capabilities on or off. Writing feature_name = true in the config enables a feature, and codex --enable feature_name does the same from the command line. To disable a feature, set its key to false.^[1]

In the docs' table of common flags, hooks and multi_agent default to on, memories defaults to off, and all three are labeled Stable.^[1] The maturity labels are Experimental, Beta and Stable. The table lists only common user-facing flags.^[1]

Windows needs a different setup. The docs suggest preferring MXC when the device and policy support it, and keeping a legacy implementation as the fallback:^[1]

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Use unelevated only when elevated setup is unavailable and the organization's policy allows it.^[1]

Common problems

If a change does not take effect, check whether a higher-precedence command-line flag or project config overrides it, and whether the current project is trusted.^[1]

Limits

On managed machines, an organization can enforce constraints with requirements.toml, for example by disallowing approval_policy = "never". Requirements limit what the configuration can do, while configuration values only provide defaults.^[1]

Next steps

This guide covers the basics. The configuration reference and the advanced configuration page have the full list of keys.^[1]