Codex config.toml: location, precedence, profiles and key options

Codex reads its settings from ~/.codex/config.toml, a TOML file in your home folder, and optionally from .codex/config.toml files inside a trusted project. Command line flags override both, and since Codex 0.134.0 profiles live in their own files named ~/.codex/<name>.config.toml.

This guide covers where the file lives, which layer wins, how profiles work now, and the options most people set. Everything here comes from OpenAI's Config basics and Advanced config pages, read on 24 October 2026. If you are new to Codex, start with the Codex CLI guide.

Where is the Codex config.toml file?

There are three places you will touch:

The ~/.codex folder is the default value of CODEX_HOME. OpenAI's environment variables page describes it this way: "Sets the root for Codex state, including config, auth, logs, sessions, skills, and standalone package metadata." If you point CODEX_HOME somewhere else, that folder must already exist, and Codex reads config.toml from there.

The CLI and the Codex IDE extension share the same configuration layers. In the extension, select the gear icon, then Codex Settings > Open config.toml. On Unix systems an administrator can also place defaults in /etc/codex/config.toml.

Which Codex config layer wins?

Codex merges several layers. From highest priority to lowest, the config basics page lists:

1. CLI flags and --config overrides
2. Project config files, from the project root down to the current directory (closest wins, trusted projects only)
3. Profile files selected with --profile
4. User config, ~/.codex/config.toml
5. Cloud-managed config.toml defaults, when your signed-in workspace delivers them
6. System config, /etc/codex/config.toml on Unix
7. Built-in defaults

Organizations can also enforce limits with requirements.toml. The docs draw a clear line: requirements constrain behavior, while configuration values only provide defaults. So if a setting will not stick, an admin requirement may be blocking it.

When you are not sure which file a value came from, run /debug-config in the Codex terminal UI. The command reference says it prints "config layer and requirements diagnostics." /status shows the active model, approval policy and writable roots for the current session.

How does project config work?

Codex walks from the project root to your working directory and loads every .codex/config.toml it finds. When two files set the same key, the one closest to your working directory wins. By default the project root is the nearest folder containing .git, and you can change that:

# ~/.codex/config.toml
project_root_markers = [".git", ".hg", ".sl"]

Two rules matter for teams:

• Trust. Codex loads project .codex/ layers only when you trust the project. For an untrusted project it skips project config, hooks and rules, while user and system config still load.
• Ignored keys. Some keys are ignored in project files, and Codex prints a startup warning if it sees them: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url and otel. Put those in ~/.codex/config.toml instead.

Relative paths in a project file, such as model_instructions_file, resolve relative to the .codex/ folder that holds that file.

How do Codex profiles work?

A profile is a small TOML file with only the values that differ from your base config. Name it ~/.codex/<name>.config.toml, using letters, numbers, hyphens and underscores, and write top-level keys, not a [profiles.<name>] table.

# ~/.codex/deep-review.config.toml
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile deep-review
codex exec --profile deep-review "review this change"

--profile (short form -p) loads ~/.codex/config.toml first, then layers the profile file on top. Project config and CLI flags still beat it.

If you followed older tutorials, note the change. The advanced config page says that in Codex 0.134.0 and later, --profile no longer reads [profiles.<name>] from config.toml, and the top-level profile = "<name>" selector is no longer supported. To migrate, move each table's settings into its own <name>.config.toml file and delete the old table and selector. A project .codex/config.toml cannot select a profile.

What are the key config.toml options?

These are the settings most people change first. Allowed values come from the configuration reference.

A starting file using settings shown in the docs:

# ~/.codex/config.toml
model = "gpt-6.1-sol"            # replace with a model you have access to
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false           # set true to let commands use the network

[shell_environment_policy]
ignore_default_excludes = false  # strip variables with KEY, SECRET or TOKEN in the name

[history]
persistence = "none"             # do not save transcripts to history.jsonl

A few details from the reference worth knowing:

• approval_policy = "untrusted" is unsupported and on-failure is deprecated. Use on-request for interactive work and never for non-interactive runs.
• With --yolo or another full-access sandbox, the default for web_search becomes live.
• [features] toggles capabilities by name, such as hooks, memories or multi_agent. Leave keys out to keep defaults.
• log_dir changes where logs go. Setting it also turns on the plaintext codex-tui.log.
• notify runs a program of your choice after each finished agent turn; it belongs in your user config, since project files ignore it.

Model Context Protocol servers also live in this file under [mcp_servers.<name>]. The Codex MCP guide covers those tables in detail.

How do you override config for one run?

Use a dedicated flag when one exists: --model, --sandbox, --ask-for-approval or --search. For anything else, pass -c (or --config) with a dotted key:

codex --config model='"gpt-6.1-sol"'
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'
codex -c mcp_servers.context7.enabled=false

The value after = is parsed as TOML, not JSON. If it does not parse as TOML, Codex treats it as a plain string. Quote the whole argument so your shell does not split it. --enable <feature> and --disable <feature> are short forms for -c features.<name>=true and false.

If you share a config across machines with different Codex versions, --strict-config makes Codex stop with an error when config.toml contains fields that version does not recognize, instead of skipping them quietly.

Tips for a config that stays manageable

• Keep the base file small. Put shared defaults in config.toml and only the differences in profile files, as the docs suggest.
• Commit project config, not secrets. A .codex/config.toml in the repo is a good place for team defaults. Keep tokens in environment variables and refer to them by name.
• Check before you debug. /debug-config and /status answer "which value is active" faster than reading files.
• Use the sample. OpenAI publishes a full sample config with every key commented.

Settings only shape how Codex behaves. The instructions you give it belong in AGENTS.md (see the AGENTS.md guide) and in skills (see Codex skills).

Where should your Codex skills live?

config.toml is per machine, but your skills and prompts are worth keeping in one place you control. Kipt stores prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Codex or Claude Code with one command: npx skills add https://github.com/<you>/<repo>.git --all -g. If you have a prompt you keep retyping, the free SKILL.md generator turns it into a skill in your browser.