Which config.toml is Codex actually reading?

config.toml is Codex's settings file: the model, approval policy, sandbox, MCP servers, hooks, profiles, and a long list of smaller switches. The sandbox is the operating-system boundary around commands; MCP is the Model Context Protocol, the way Codex connects to external tool servers; a hook is a command that runs at a fixed lifecycle point. There is more than one config.toml. Codex merges settings from a stack of files, then applies command-line overrides on top.

That merge order is documented. What is less obvious is that a project's .codex/config.toml is ignored until the project is trusted, that CODEX_HOME moves the user layer, and that the desktop app and the CLI do not always read the same things even when they read the same file.

Checked against Codex's documentation on 26 October 2026.

Status, 26 October 2026: precedence is documented; the surface differences are not. Open reports cover the desktop app ignoring a project-scoped MCP server (#13025, open, updated 18 August 2026), developer_instructions not reaching app-initiated threads (#11004, open, updated 31 August 2026), and a Windows desktop in WSL mode using the Windows Codex home (#13762, open, updated 19 September 2026). The checks below tell you which layer your session actually used.

The layers, in order#

A layer is one file or source that can set keys. Codex reads them from lowest priority to highest, so a later layer wins when two set the same key. The documented order, highest precedence first:

The project layer is itself a chain. Codex walks from the project root to your working directory and loads every .codex/config.toml it finds. If two set the same key, the one closest to where you are wins. This is a different chain from AGENTS.md, even though both start at the same root: one sets configuration, the other adds instructions to the prompt.

A one-off override is the fastest way to test a value without editing a file:

codex -c model_reasoning_effort="high"

--config values are parsed as TOML. Quote anything with spaces. If a value cannot be parsed, Codex treats it as a string, which is convenient until a typo becomes a silent setting.

The trust gate#

Codex loads project-scoped config only when the project is trusted. If it is not, the whole .codex/ layer is skipped: project config, project hooks, and project rules. Your user config and the system config still load.

Trust is recorded in the user config under the project path:

[projects."/Users/you/src/app"]
trust_level = "trusted"

The reference also accepts "untrusted". Marking a repository untrusted is a useful way to keep a cloned sample's .codex/config.toml out of your session without deleting it.

This gate explains the most common "my project config does nothing" case. The file is valid, the key is right, and the project was never trusted, so Codex never opened it. Check the trust state before you edit the file again.

Which home, and which file#

The user layer is $CODEX_HOME/config.toml, and CODEX_HOME defaults to ~/.codex. Change the variable and you move the user config, the session store, the memories, and the writer locks together. Two Codex launches with different homes are two different installations as far as settings are concerned.

Run this in the same shell that launches Codex:

echo $CODEX_HOME

An empty result means ~/.codex.

On a Windows machine, WSL (Windows Subsystem for Linux) adds a second trap. A desktop app configured to use WSL can inherit the Windows CODEX_HOME instead of a home inside the Linux distribution. The reported result is that the app reads the Windows config.toml, creates Git worktrees (extra checkouts of the same repository) under /mnt/c, and leaves the WSL-side file untouched (#13762); a related report describes the app continuing to reference the Windows-hosted config (#13549, open, updated 16 June 2026). If a setting works in one WSL shell and not the other, compare echo $CODEX_HOME on both sides before editing anything.

Profiles moved into their own files#

A profile is a named layer you select at launch, useful for a review configuration or a different model and reasoning effort. It is not a section inside config.toml any more.

# ~/.codex/deep-review.config.toml
model_reasoning_effort = "high"

codex --profile deep-review

In Codex 0.134.0 and later, --profile no longer reads a [profiles.<name>] table from config.toml, and the top-level profile = "<name>" selector is gone. Move the keys into ~/.codex/<name>.config.toml and remove the old table. A profile file sits above the user config and below project config and the command line, so it can override your defaults without becoming the new default.

What a project config cannot set#

Project config is convenient and deliberately limited. Codex ignores keys that would redirect credentials, change provider authentication, alter host-owned app metadata, select a profile, or run machine-local notification and telemetry commands.

The documented list is openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel. Codex prints a startup warning when it sees one in a project file. Put provider, notification, and telemetry keys in ~/.codex/config.toml.

There is also a discovery key worth knowing if instructions are not loading: project_root_markers decides which filenames mark the project root. If your repository has no Git directory and no marker Codex recognises, project discovery starts at the current directory instead of walking up. That produces the same symptom as a skipped file.

The desktop app is not the CLI#

The CLI and the IDE extension share the same configuration layers. The desktop app also reads your user layer and discovers project files from a project's primary folder, but its project handling differs in practice, as the reports below show.

First, a desktop project has a primary folder. Codex uses that folder for automatic discovery of AGENTS.md, skills, and config.toml. Other attached folders are readable and editable, but Codex does not scan them for project files. If you attached a repository as a secondary folder, its project config will not apply.

Second, the app adds its own instruction and MCP handling. An open report says developer_instructions from config.toml is not attached to threads started in the app (#11004); another says an MCP server defined only in a project .codex/config.toml does not appear in desktop threads while the user-level server does (#13025). Both are open. Until they are fixed, keep settings the app depends on in the user layer, and restart the app after changing them.

The IDE extension is the simplest case: it shares the CLI's layers. Its settings menu has Codex Settings > Open config.toml, which opens the user file. That is a shortcut to the same ~/.codex/config.toml, not a separate store.

See what actually won#

/debug-config is the documented view. In a terminal session it prints the config layer order from lowest precedence first, whether each layer is on, and policy sources such as allowed approval policies, sandbox modes, MCP servers, rules, and any experimental network constraints. Use it to confirm that the file you edited is in the stack, and that the value you expected appears at the right level.

codex doctor produces a local diagnostic report covering installation, configuration, authentication, runtime, Git, terminal, background app-server health (the local helper that runs chats), and saved-chat inventory. It is a health report, not a replacement for /debug-config.

For a setting that still seems not to apply, work down this list:

1. Confirm the shell's CODEX_HOME and the file's existence.
2. Run /debug-config and check that the layer is present and enabled.
3. Check the project's trust state in the user config.
4. Check whether a profile is selected with --profile; a profile can override the user layer.
5. Check for a -c override in the command that launched Codex, including a wrapper or alias.
6. Restart the surface. Configuration is read at launch.

The order matters because each step rules out a different layer. Editing the project file again will not help if the project is untrusted, and raising a value in the user file will not help if a profile sets it back.

Where to go next#

• Why Codex ignores part of your AGENTS.md — the instruction file that sits alongside these settings.
• Resume a Codex session — if the config is right but the chat is missing.
• Codex guides — the rest of the set.