Find the file that actually applies
A desktop client, a terminal, and a remote host can use different configuration directories. Saving a file does not prove that the running session loaded it. Record the client version, CLI version, working directory, and original error before changing settings.
codex --version
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"Without CODEX_HOME, user settings normally live in ~/.codex/config.toml. In PowerShell, check $env:CODEX_HOME, then the .codex directory under $HOME if it is empty. Open the desktop client’s active configuration through its settings and compare the actual paths.
Choose the right layer
| Location | Use | Constraint |
|---|---|---|
| ~/.codex/config.toml | Personal defaults and provider routing | Keep a backup; keep credentials out of Git |
| <project>/.codex/config.toml | Project-specific model or execution defaults | Trusted projects only; provider routing cannot be overridden here |
| ~/.codex/<name>.config.toml | Differences selected with --profile | Separate profile files apply to Codex 0.134.0 and later |
Start with a minimal change
Keep your working authentication and model selection. Add these settings at the top level, merging with any existing values rather than duplicating keys. Appending them after a TOML table header can put them in the wrong table.
approval_policy = "on-request"
sandbox_mode = "workspace-write"If you set model = "YOUR_MODEL_ID", replace the placeholder with a model your account or provider actually exposes. Add reasoning settings only after checking that model’s supported values.
Trace overrides before editing again
- Inspect startup flags such as --model, --profile, and -c.
- Check trusted project layers from the repository root to the working directory; the closer layer wins for overlapping keys.
- Then inspect the selected profile, user configuration, and managed defaults.
- Administrative requirements constrain permitted values; they are not merely another preference you can override.
Verify and roll back
Start a fresh CLI session or fully restart the desktop client. Use /status for the active session and /debug-config for configuration-layer diagnostics when supported by your installed version. Begin with a read-only request to summarize the README and confirm the expected model and execution permissions.
If parsing fails, undo only your change or restore the backup. Do not delete your entire Codex home. Continue with custom providers, profiles, or MCP after the baseline works.
Sources and version notes
Based on the official documentation below. Replace example URLs, models, and paths for your environment. Older versions and managed environments may differ.
Sources checked：