Based on OpenAI’s official docs, checked October 29, 2026

Codex config.toml: location, precedence and the settings to change

Codex CLI and the Codex IDE extension read their settings from TOML files called config.toml. Your personal defaults live in ~/.codex/config.toml, a repo can add its own .codex/config.toml, and a single run can override any key from the command line. This guide shows where each file lives, the order Codex applies them in, and working examples for the options OpenAI says people change most: default model, approval prompts, sandbox level, web search, reasoning effort, profiles and feature flags. Everything here comes from OpenAI’s Codex config docs, checked October 29, 2026.

1. 1. Open your user config

   Codex stores user-level configuration at ~/.codex/config.toml. In the Codex IDE extension, select the gear icon in the top-right corner, then Codex Settings > Open config.toml. The CLI and IDE extension share the same configuration layers.

   mkdir -p ~/.codex
   ${EDITOR:-nano} ~/.codex/config.toml

2. 2. Set your everyday defaults

   These top-level keys set the default model, when Codex pauses for approval, how much the sandbox allows and how much reasoning the model uses.

   model = "gpt-6.1-sol"
   approval_policy = "on-request"
   sandbox_mode = "workspace-write"
   model_reasoning_effort = "medium"

3. 3. Add project overrides

   Put a .codex/config.toml in your repo to scope settings to that project. Codex walks from the project root to your current directory and loads each one it finds, closest wins. It loads project layers only for projects you trust.

   mkdir -p .codex
   printf 'model_reasoning_effort = "high"\n' > .codex/config.toml

4. 4. Override one run from the CLI

   Prefer a dedicated flag such as --model when there is one. For any other key use -c or --config; the value is TOML, not JSON, so strings need their own quotes.

   codex --model gpt-6.1-sol
   codex --config model='"gpt-6.1-sol"'
   codex -c log_dir=./.codex-log

Which setting wins

OpenAI’s docs list the order from highest to lowest: CLI flags and --config overrides; project .codex/config.toml files (closest to your working directory wins, trusted projects only); a profile file selected with --profile; your user ~/.codex/config.toml; cloud-managed defaults for a signed-in workspace; system config such as /etc/codex/config.toml on Unix; then built-in defaults.

If you mark a project as untrusted, Codex skips its .codex/ layers, including project config, hooks and rules. On managed machines a requirements.toml file can also forbid values, for example approval_policy = "never" or sandbox_mode = "danger-full-access", whatever your config.toml says.

Profiles: switch whole setups at once

Running codex --profile profile-name loads ~/.codex/config.toml and then overlays ~/.codex/profile-name.config.toml. Create a separate TOML file for each profile and use top-level keys in it; don’t nest them under [profiles.profile-name]. Profile names can use letters, numbers, hyphens and underscores.

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

# run it
codex --profile deep-review

Web search

Codex enables web search by default for local chats and serves results from an OpenAI-maintained cache, which OpenAI says reduces exposure to prompt injection from live pages. Choose cached (the default), indexed, live (the same as --search) or disabled. With --yolo or another full-access setting, web search defaults to live results.

web_search = "cached"
# web_search = "live"
# web_search = "disabled"

Feature flags

Optional capabilities sit under [features]. OpenAI’s table lists hooks, multi_agent, apps, goals and fast_mode as stable and on by default, and memories as experimental and off by default. You can also turn one on for a session with codex --enable feature_name. Omit a key to keep its default.

[features]
memories = true
hooks = true

Environment passed to commands

shell_environment_policy controls which environment variables reach the commands Codex runs. ignore_default_excludes defaults to true, which skips automatic filtering of names containing KEY, SECRET or TOKEN; set it to false to filter them out.

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

Where MCP servers and Windows settings go

MCP servers are configured in the same file under [mcp_servers.<name>]; our Codex MCP guide covers that table. On Windows, the [windows] table and features.prefer_mxc choose the sandbox implementation.

Tips

• Keep secrets out of config.toml; pass them through environment variables instead.
• Commit a project .codex/config.toml for team defaults, and keep personal choices like model in your user file.
• Use /status and /debug-config in the CLI to see which configuration is active.
• personality = "none" removes the built-in personality instructions; Codex no longer has a /personality command.

Next steps

Sources

• https://developers.openai.com/codex/config-basic · checked 2026-10-29
• https://developers.openai.com/codex/config-advanced · checked 2026-10-29