config.toml, Precedence & Profiles

Most tools have a config file. Codex has a stack of them, and the single most useful idea in this lesson is to stop thinking "where is the config file?" and start thinking "which layers apply, and in what order do they win?"

Codex resolves every setting by layering several config.toml files on top of each other, then letting anything you typed on the command line override the result. Picture a stack of transparency sheets: a system-wide default at the bottom, your personal defaults above it, an optional per-project file above that, an optional named profile overlay, and your live CLI flags on the very top. To read any setting, you look down through the stack and take the first sheet that defines it.

This is the same idea you already met with AGENTS.md — global guidance layered with project overrides — but applied to machine behavior (which model, when to ask permission, what the sandbox allows) rather than prose instructions. The two systems are complementary: AGENTS.md tells Codex how to work on this project; config.toml tells Codex how to run.

Everything Codex needs lives under one home directory — ~/.codex/ by default — holding config.toml, your credentials (auth.json), profiles, sessions, and history. Relocate the whole thing by setting the CODEX_HOME environment variable, which is exactly how you keep work and personal setups separate or pin a clean config in CI.

There are three places a config.toml can live, each scoped differently. Learn the scope, not just the path — the scope is what determines the precedence later.

The user file is your home base: set your preferred model, default approval posture, and MCP servers here once and every project inherits them. The project file lets a repo ship its own settings — say, a tighter sandbox or a repo-specific MCP server — so contributors get consistent behavior without each configuring it by hand. The system file is where an admin pins machine-wide policy.

A config.toml is plain TOML: top-level key = value pairs and [table] sections. You don't need to create every file — Codex falls back to built-in defaults for anything no layer defines, so a brand-new install with no config.toml at all still runs.

When two layers set the same key, Codex needs a tiebreaker. That tiebreaker is a fixed precedence chain. From highest priority (wins) to lowest (loses):

1. CLI flags & -c/--config overrides — what you typed this run
2. Project config — .codex/config.toml, closest directory wins
3. Profile file — the --profile overlay (covered in §7)
4. User config — ~/.codex/config.toml
5. System config — /etc/codex/config.toml
6. Built-in defaults — Codex's baked-in fallbacks

Read it top-down: Codex takes the value from the highest layer that defines the key, and lower layers fill in only the keys nobody above them set. So your user config sets model = "gpt-5.5", a project pins sandbox_mode = "read-only", and a single -m gpt-5.4 on the command line beats both for the model — while the project's sandbox setting still stands because nothing higher overrode it.

The ordering is deliberately intuitive: the more specific and immediate the source, the more authority it has. A flag you typed for one run beats a file you wrote once; a per-repo file beats your global default; your global default beats the admin baseline. This is exactly why you can keep sane defaults in your user config and still steer any individual run without editing files.

  CLI flags / -c overrides        (highest — this run only)
        ▼
  project .codex/config.toml      (closest dir wins)
        ▼
  --profile overlay file
        ▼
  user ~/.codex/config.toml
        ▼
  /etc/codex/config.toml
        ▼
  built-in defaults               (lowest — fallback)

Most settings have a dedicated flag — -m/--model, -s/--sandbox, -a/--ask-for-approval. But for the long tail of keys that don't have a shortcut, there's a universal escape hatch: -c key=value (long form --config key=value), repeatable, which sets any config key for that single invocation without touching a file.

# Send this run's logs to a project-local dir, just this once
codex -c log_dir=./.codex-log

# Stack several one-off overrides
codex -c model_reasoning_effort=high -c sandbox_mode=read-only

# Works with the headless runner too
codex exec -c model=gpt-5.4 "summarize the failing tests"

Because -c sits at the top of the precedence chain, it overrides every file layer. It's the right tool when you want to try a setting before committing it to a file, or run one task under a different posture without disturbing your durable config.

There is, however, a hard boundary the override system enforces. A project config (and therefore a repo you cloned) cannot override machine-local keys: provider/auth configuration, notification settings, profile selection, and telemetry routing all stay under your control. This is a security boundary, not an oversight — without it, cloning a hostile repo could silently repoint your model provider at an attacker's endpoint or exfiltrate via a notification hook. Those keys can only come from your user or system config, or your own CLI flags.

There's a subtle risk in the precedence chain: a project's .codex/config.toml ranks above your user config. If Codex blindly honored every repo's config, cloning a sketchy project could change your agent's behavior the moment you opened it. Project trust is the gate that prevents this.

Project-scoped .codex/ layers load only for trusted projects. You mark trust explicitly in your user config:

[projects."/Users/you/work/payments-api"]
trust_level = "trusted"     # "trusted" | "untrusted"

The key is the absolute path to the repo. When a project is untrusted, Codex skips its project-scoped .codex/ config layer entirely — your user and system config still load, but the repo's own settings are ignored. So an untrusted repo runs with your defaults, never settings it shipped.

The practical workflow: trust your own repos and your team's known projects so their .codex/config.toml and project AGENTS.md take effect; leave anything you just cloned from the internet untrusted until you've actually read what its .codex/ folder contains. Combined with the machine-local key boundary from §5, trust gives you two layers of defense — even a trusted project still can't touch your auth or provider keys.

The config reference is long, but in practice you reach for a small set. Here are the keys worth memorizing — the same ones you've been setting with flags in earlier lessons, now made durable. Model names, the default model, and per-model defaults are volatile — confirm the current values on the live models page rather than trusting any hard-coded value below.

# ── Model & reasoning ──
model = "gpt-5.5"                  # leave UNSET on ChatGPT auth to track the recommended default
model_reasoning_effort = "medium" # minimal | low | medium | high | xhigh (Responses-API models only)
model_reasoning_summary = "auto"  # auto | concise | detailed | none

# ── Approvals & sandbox (the two independent controls) ──
approval_policy = "on-request"    # untrusted | on-request | never   (WHEN Codex asks)
sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access   (WHERE it can act)

[sandbox_workspace_write]
network_access = false            # network is OFF by default in workspace-write — opt in here
writable_roots = ["/extra/path"]  # grant extra writable dirs

# ── MCP servers (one table per server) ──
[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/repo"]

A few things to internalize:

• approval_policy and sandbox_mode are independent. Approvals decide when Codex stops to ask you; the sandbox decides where Codex is allowed to act. You set them separately — a repo can be read-only but never ask, or workspace-write but ask on-request.
• On ChatGPT-account auth, leaving model unset is the recommendation — Codex then tracks the current recommended default instead of pinning you to a name that may get retired.
• model_reasoning_effort applies only to Responses-API models, and its per-model default varies — so omit it unless you specifically want to dial reasoning up or down.
• [mcp_servers.<id>] registers a tool server; the <id> is your label. You'll usually add these with codex mcp add (covered in the MCP lesson), which writes this same table for you.

Editing config.toml every time you switch between careful review and fast autonomous work gets old fast. Profiles solve this: a profile is a named overlay of config that you activate with a single flag.

As of Codex 0.134.0+, a profile is a standalone file: ~/.codex/<name>.config.toml. Codex loads your base ~/.codex/config.toml first, then overlays the profile file on top — so a profile only needs to specify the keys it changes.

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

Select it with --profile (short -p), in both interactive and headless modes:

codex --profile deep-review
codex -p deep-review
codex exec --profile deep-review "review the auth refactor for security regressions"

In the precedence chain (§3), the profile sits above your user config but below the project config and CLI flags — so a project .codex/config.toml or a one-off -c can still override what a profile sets. Profile names may use letters, numbers, hyphens, and underscores.

One deprecation to know: the older inline [profiles.NAME] table inside config.toml is deprecated as of 0.134.0+. If you have profiles defined as [profiles.deep-review] sections in your config.toml, migrate each to its own standalone ~/.codex/deep-review.config.toml file. This is exactly the kind of version-gated detail that rots — confirm the current syntax in the config-advanced docs and the changelog before relying on either form.