Field guide / 16 min
Configure Codex by scope, not by accident
Understand precedence before mixing user defaults, project policy, profiles, and one-off overrides.
Codex resolves configuration from command-line overrides, trusted project layers, a selected profile, user config, system config, then built-in defaults. Profiles are separate files, and current model availability should be inspected live rather than frozen into evergreen advice.
Verified terminal sequence
- $
codex --profile deep-review - $
codex -c 'model_reasoning_effort="high"' - ›
/model - ›
/fast - ›
/status
Working principles
Smallest durable scope
Personal defaults belong in user config; shared repository behavior belongs in project config; a one-time experiment belongs on the command line.
Trust gates project config
Untrusted repositories cannot activate project-local config, hooks, or rules.
Catalogs move
Use /model and /status to inspect current choices. Date model-specific examples rather than presenting them as permanent.
Field procedure
- 01
Inspect active layers
Use /status and config diagnostics before editing a file you assume is authoritative.
- 02
Set a restrained user default
Choose only durable defaults such as approval policy or sandbox mode.
- 03
Add trusted project settings
Keep project settings under .codex/config.toml and avoid provider or credential redirection keys that project config cannot control.
- 04
Create a profile file
Save specialized review behavior in ~/.codex/deep-review.config.toml and select it with --profile.
- 05
Test one-off changes
Use a dedicated flag or TOML-parsed -c override, then verify the effective setting.
PASS / FAIL
Acceptance checklist
- Effective precedence is understood.
- Project config contains no ignored provider keys.
- Profiles use separate profile-name.config.toml files.
- Model guidance points readers to the live catalog.
WATCH / REJECT
Failure patterns
- Using the removed legacy profiles table.
- Copying every sample config key.
- Publishing a volatile model as the timeless default.