Codex config.toml: Which Setting Wins?

Find the Codex config file that controls a setting, check profile and project precedence, and catch ignored keys with a reproducible CLI check.

Last updated: 2026-09-25

By Stometa · Verification sources and dates are cited in the article.

On September 25, 2026, Codex CLI 0.156.1 gave three different outcomes for configuration edits: a CLI override took effect, a project-local provider key was ignored with a warning, and an old profile selector stopped the run before a session started. If a config.toml edit appears ineffective, the error class tells you which layer to fix. Valid TOML syntax alone does not show whether a key took effect.

The cost of a per-project setting is another layer to inspect. Start with one user default; add a project override only when collaborators need the same behavior. Keep credentials and provider routing in user configuration.

Which config.toml does Codex read?

The official config basics gives this precedence order, highest first. A lower layer supplies a value only when the layers above it do not.

Layer	Location or selector	What our September 25 check establishes
CLI	A flag or `-c key=value` on one invocation	`-c 'model_reasoning_effort="low"'` appeared as `reasoning effort: low` in a read-only run's header.
Project	`.codex/config.toml` from trusted project root toward the working directory	Official documentation says the closest file wins. We did not test nested project files.
Profile	`$CODEX_HOME/<name>.config.toml`, selected with `--profile <name>`	Official documentation defines this layer. We did not select a profile in the check.
User	`~/.codex/config.toml` by default	Shared default for the CLI and IDE extension.
Cloud, system, built-in	Cloud-managed defaults, `/etc/codex/config.toml` on Unix, then defaults	These are lower-precedence defaults when present; we did not test them.

Do not use a project file to redirect provider authentication. The official advanced config guide says Codex ignores project-local model_provider, model_providers, openai_base_url, notify, profile selection and telemetry keys. Put machine-specific settings in your user file. A trusted project is also required before its .codex/ config layer loads.

For persistent choices about reasoning effort, keep one setting in the user file:

model_reasoning_effort = "medium"

For a bounded exception, pass -c on that invocation. The CLI parses the value as TOML; the quotes around "low" are inside the shell argument:

codex exec --ephemeral --sandbox read-only \
  -c 'model_reasoning_effort="low"' \
  'Reply CONFIG_TEST_OK only. Do not use tools.'

Our exact September 25 shell command is above. Its run header included reasoning effort: low; the final text was CONFIG_TEST_OK and the exit code was 0. It used the operator's existing configured provider and global instructions, so this confirms that the invocation accepted the override. It does not establish backend model identity, answer quality or clean-install behavior. Read-only and ephemeral limit this example's intended work; review your own sandbox and approval settings before running a real task.

How do I catch an ignored or stale key?

Codex CLI 0.156.1 exposes --strict-config in codex exec --help. A generic unknown-key failure is already described by other configuration guides. We tested two more consequential cases in temporary files:

In a trusted worktree, a temporary .codex/config.toml contained only model_provider = "example-ignored". An ephemeral, read-only Codex run printed Ignored unsupported project-local config keys ...: model_provider, retained its existing provider, returned PROJECT_CONFIG_TEST_OK and exited 0. We removed the temporary file after the run. The warning explains why changing that project key did nothing; a zero exit code would have hidden it.
In a disposable $CODEX_HOME/config.toml, we put profile = "demo" above a [profiles.demo] table and ran codex exec --strict-config --ephemeral --sandbox read-only. It exited 1 before starting a session: legacy profile = "demo" config is no longer supported; use --profile demo with demo.config.toml instead. The official advanced guide dates that format change to CLI 0.134.0.

Check	Observed result on September 25	What to inspect next
One-run `-c` override	Exit 0; header `reasoning effort: low`; final `CONFIG_TEST_OK`	Confirm the effective value in the run header.
Project-local `model_provider`	Exit 0, but explicit ignored-key warning; existing provider remained active	Move provider routing to user configuration.
Legacy `profile = "demo"`	Exit 1 before the session; migration message named `--profile demo` and `demo.config.toml`	Replace the old selector and table with a separate profile file.

These are three checks on one CLI version, not a matrix of every setting. The project-key test inherited the operator's existing user configuration; the profile-selector test used a disposable home and required no authentication because it failed during configuration loading. The CLI reference and installed codex exec --help can differ from old tutorials, so check the flag available on your client before changing a file.

What remains unverified?

We did not compare two nested project files or test profile precedence locally. The table's ordering for those layers comes from OpenAI's September 25 documentation, not this single run. A future reproduction should use disposable files and record the effective value without including credentials. For the rest of a first-run workflow, see the Codex CLI guide; for standing repository instructions, use the AGENTS.md guide.