You set a model in ~/.codex/config.toml, and Codex uses another one. You turn web search off, and in one repository it is still on. Almost always another layer is winning. This lesson shows the order and the four ways to use it on purpose.
Read the order
Open Config Studio for Codex, stay on config.toml: model and defaults, and open Where it lives under the description. It lists every place this surface is read from, highest precedence first:
| Order | Where | What it is |
|---|---|---|
| 1 | /etc/codex/requirements.toml | An administrator's limits |
| 2 | codex -c key=value | A flag or override, for one run |
| 3 | ./.codex/config.toml | The repository's, in a trusted project |
| 4 | ~/.codex/<name>.config.toml | A profile, when you run --profile <name> |
| 5 | ~/.codex/config.toml | Yours, in every project |
The first layer that sets a key decides it. Your own file is the lowest, so a project or a flag beats it. Requirements are different: they do not set a value, they allow some and refuse the rest, and a refused value falls back to an allowed one whoever set it.
Every config.toml surface (sandbox, MCP servers, the status line and the rest) follows the same order.
Trust the project
A repository's .codex/config.toml is read only when you trust the project, and so are its rules, hooks and agents. Press Trusted projects, type the repository's path in Folder, and pick a Trust level. The file gets a [projects."<path>"] table with its trust_level.
Trust a repository you know. Its config then beats yours inside it, which is what a team wants and what a stranger's repository should not get by default.
Make a profile
A profile is a set of values you switch on for some runs: a careful review, a fast draft, a CI job. Press Profiles, type a Profile name such as deep-review, and set only what differs from your config, for example Reasoning effort high.
The right column shows its own file, ~/.codex/deep-review.config.toml, and the command that uses it: codex --profile deep-review. A profile sits above your config.toml and below the project, so a trusted repository still has the last word on its own settings. A [profiles.<name>] table inside config.toml is no longer read.
Override one run
Flags for one run builds a command instead of a file: When it stops to ask, Where commands may write, Model, Profile, Also writable and Config overrides. Pick what you need and copy the codex command from the right column. Nothing on disk changes, and the flags beat every file for that run.
When a setting is ignored
Work down the list:
- Is it set on the command line, or in a profile you chose? Those beat your file.
- Is there a
.codex/config.tomlin the repository, or in a folder above where you are? In a trusted project it wins. - Does
requirements.tomlrefuse the value? Then no layer can set it. - Is the key in the right table? A key after a
[table]header belongs to that table. Config Studio for Codex writes every top-level key before the first table, so its files never have this problem.
Next: rules, hooks and AGENTS.md, the files that decide what Codex may run and what it is told.