Codex config.toml location and overrides

Find the active Codex home first, then check project and profile overrides before editing config.toml.

Start here

Check CODEX_HOME in the affected environment before opening the default user configuration.

Find the configuration for the environment you use

The default user configuration is ~/.codex/config.toml on macOS/Linux and %USERPROFILE%\.codex\config.toml on Windows. If CODEX_HOME is set, use config.toml inside that directory instead.

Windows, WSL and a remote SSH host may have different home directories and environment variables. Check the environment where the affected Codex client runs; changing a Windows file does not establish that a WSL client has read it.

Read-only checks

In PowerShell, show the configured home and default candidate:

$env:CODEX_HOME
Join-Path $env:USERPROFILE '.codex\config.toml'

In a macOS/Linux/WSL shell:

printf '%s\n' "$CODEX_HOME"
printf '%s\n' "$HOME/.codex/config.toml"

An empty CODEX_HOME means the default home is the candidate. These checks do not prove which overrides a running app inherited. A terminal opened after changing an environment variable can differ from an app that was already running.

Check overrides before editing

The official configuration guide documents multiple layers. Command-line overrides take priority, followed by trusted project configuration, selected profiles and user settings. Managed workspace defaults, system settings and built-in defaults may also apply. Organization requirements can constrain permitted values.

A trusted project can contain .codex/config.toml; nested project files closer to the working directory take precedence. An untrusted project does not load those project layers. A key appearing in different valid layers is an override, not automatically a duplicate-key syntax error.

The CLI and IDE extension share configuration layers when they use the same environment. In the IDE, the documented route is the gear icon, Codex Settings, then Open config.toml. Different homes, selected profiles or project directories can still produce different effective settings.

Edit only the file you intend to change

  1. Identify the active home and project directory.
  2. Make a private backup of the existing file before editing.
  3. Check whether the setting belongs at user or project scope in the current reference. Some keys cannot be overridden by a project.
  4. Change one setting, save, then restart the affected client when required.
  5. Verify the intended behavior in that client and project.

If the default file does not exist, do not search for credentials or delete the state directory. Use the client’s documented configuration entry point, or create a minimal file at the verified user-level path when you actually need an override. Not every setting needs a custom value.

If a setting seems ignored

Check the selected profile, launch flags and trusted project files before editing the same value again. On a managed machine, ask the administrator whether a policy constrains it. Do not try to bypass policy by copying configuration into another home.

If startup reports a parsing error, follow config.toml syntax troubleshooting. A valid path and valid TOML do not guarantee every key is recognized by your installed version.

How to tell it worked

The affected client starts, reads the intended setting and behaves as expected in the original project. Keep the backup until that check succeeds. Never publish your entire configuration: it may include private endpoints, commands or credentials.

This guide is part of our Codex installation troubleshooting.

Compare another message in the Codex error guide library. First check whether this is a Codex service-side problem → View live Codex status.

Useful Codex tools

Sources

Each source lists what it is used to support. Sources are re-read on the review schedule, not continuously.

How this page is checked
Evidence level
Documentary - supported by official documentation
Last reviewed
2026-09-22
Content updated
2026-10-03
Full version scope
Current official configuration references reviewed on 2026-09-22. Key availability can differ by installed client version and organization policy.
Symptoms indexed
  • You were told to edit config.toml but cannot find the file
  • You are unsure whether the CLI and the app read the same config
  • A project-level setting seems ignored or overridden

Reviewer note

Source and editorial review on 2026-09-22. Official commands and documented behavior were checked against primary sources; public issue reports remain conditional evidence, not locally reproduced fixes.

Last updated: