The Codex Config File Reference, Explained

The config file is where a decision you'd otherwise repeat on every single invocation — which model to default to, which sandbox posture to start in — becomes a persistent setting instead, and understanding its structure is what lets you stop retyping the same flags every session.

Why a config file exists alongside command-line flags

Flags are for a specific invocation's specific needs; a config file is for what you want true by default, every time, without restating it. The two aren't competing mechanisms — a config default sets your starting point, and a flag on any given invocation overrides that default for just that one run, without changing the persistent setting for every future session. Understanding this relationship is what lets you set a sensible default once and still deviate from it deliberately whenever a specific task calls for something different.

What actually belongs in a persistent default versus a per-invocation flag

A model preference you want most sessions to use, a default sandbox posture matching how you generally work, an approval mode reflecting your usual comfort level — these are reasonable config defaults, since restating them every single session is pure friction for a preference that rarely changes. A one-off deviation for a specific task — a stricter sandbox for reviewing something unfamiliar, a different model for a specific job — belongs as a flag on that one invocation, not a change to the persistent default that would then apply to every unrelated session afterward too.

Finding the config reference for your actual installed version

The authoritative source for exact key names and their accepted values is the CLI's own current config-file reference documentation — worth checking directly rather than relying on a static guide's memory of what the keys were called at some earlier point, since this is exactly the layer of the CLI most likely to gain new options or rename existing ones across releases.

A reasonable set of defaults to actually configure

For most regular users, it's worth deliberately setting a default model (rather than leaving the CLI's own shipped default unexamined), a default sandbox mode matching your typical comfort level for the kind of work you usually do, and a default approval mode consistent with whether you're usually present and available to answer prompts. None of these need to be exotic choices — the value is in choosing them deliberately once, rather than inheriting whatever the CLI ships with by default without ever having decided it was actually the right fit for how you work.

Per-project versus global configuration

Beyond a single global default, many workflows benefit from per-project configuration that overrides the global default for a specific repository — a project with different sandbox needs than your general default, for instance. This site covers per-project defaults in more depth separately; the key point for understanding the config file's overall structure is that it's not necessarily a single flat file with no notion of scope, and checking whether your version supports project-level overrides is worth doing before assuming every setting has to be global.

Validating a config change before trusting it broadly

After editing the config file, running a quick session and checking /status to confirm the settings actually took effect the way you intended is worth doing immediately, rather than assuming a config edit worked correctly and only discovering a typo or a misunderstood key days later when a session behaves unexpectedly. A config file with a silently ignored or misspelled key is a particularly quiet kind of bug, since the CLI may simply fall back to its own default without necessarily erroring loudly.

Keeping a config file under version control for a team

For a team wanting consistent defaults across everyone's setup — the same default sandbox posture, the same model preference — checking a shared config file into the project repository itself, if the CLI's structure supports project-level configuration this way, is worth considering over relying on every team member independently configuring their own global settings identically by convention. A shared, version-controlled config file is self-documenting and stays consistent in a way that "everyone remembers to set this the same way" reliably isn't.

What to do when the config file and a flag seem to disagree

If a session's actual behavior doesn't match what you expect from your config file, checking /status to see what's actually active, then checking whether a flag on that specific invocation might be overriding the config default, is the right debugging order — flags win over config defaults by design, and an override you forgot you'd set (in a wrapper script, an alias, a habit) is a more common explanation for unexpected behavior than the config file itself being wrong.

Keeping a personal record of why each setting was chosen

For anyone whose config file grows to include several deliberate, non-default choices, a brief comment next to each one explaining why it was set that way — not what it does, which the reference documentation already covers, but why you specifically chose it — pays off months later when you're deciding whether a setting still reflects a decision you'd still make today, or whether it was a one-time fix for a problem that no longer applies.

Revisiting your config periodically rather than setting it once

A config file, like any other configuration, tends to accumulate settings that made sense at the time and are simply never revisited. Treating it as worth a periodic review — does this default still reflect how I actually work now, not how I worked when I first set it up — is a small habit that keeps the file genuinely useful rather than a growing record of decisions nobody remembers the reasoning behind.