Where is the Codex config file? (config.toml location and layers)

What you see

You were told to “edit your config” but cannot find the file. You may not know it lives in a dot-directory, that a project can override it, or whether the app and the CLI read the same file.

What it usually means

The user-level config file is in a dot-directory off your home folder. On macOS and Linux it is ~/.codex/config.toml; on Windows it is %USERPROFILE%\.codex\config.toml. A project can add its own .codex/config.toml to scope settings to that repo, and CODEX_HOME can move the whole directory. The CLI and the IDE extension share the same configuration layers.

Quick checks

1. Open the user-level path for your OS (see above).
2. Check the project directory for a .codex/config.toml that overrides the user-level file.
3. Check whether CODEX_HOME is set — if it is, the config lives under that directory instead of ~/.codex.
4. Confirm the CLI and the IDE read the same file — the documentation states the CLI and the IDE extension share configuration layers.

Fixes, by branch

If you cannot find the user-level file

Open ~/.codex/config.toml (macOS/Linux) or %USERPROFILE%\.codex\config.toml (Windows) in a plain-text editor. These paths are stated by the official help centre, read directly this session.

If a project file should override

Add or edit .codex/config.toml in the repo root. The documentation states project config is loaded only when the project is trusted, and that the closest file to your working directory wins.

If you use CODEX_HOME

CODEX_HOME moves the whole local state directory (config.toml, auth.json, history.jsonl, logs and caches). This is documented on the advanced config page, read via a mirror.

If you need to know which layer wins

The documented precedence order, highest first: CLI flags and --config overrides; project config files (closest wins, trusted projects only); profile files selected with --profile; user config (~/.codex/config.toml); system config (/etc/codex/config.toml on Unix); built-in defaults. An org layer can also enforce constraints via requirements.toml. These details are from the config-basic reference page, read via a mirror.

If a key you set is ignored in a project file

The documentation lists keys a project-local config.toml cannot override and that it prints a startup warning for: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel. (Read via a mirror.)

What not to do

• Do not delete the whole ~/.codex directory to “find” or reset your config. That removes history, auth and caches as well as the file you wanted.
• Do not assume the app and the CLI read different files — the documentation states they share layers. A difference is more likely a project file or a profile.
• Do not run an undocumented --config example that depends on JSON-vs-TOML parsing; two official pages disagree on the format, so a quoted string is the only safe form.

How to tell it worked

You opened config.toml at the expected path and confirmed it is the file your client loads (editing it and restarting changes behaviour).

If it is still failing

If the file exists but the client errors on it, the problem is a parse or load error, not location — see the codex-invalid-config-toml guide. If codex doctor is available in your client, the help centre documents it as a diagnostics tool covering startup, connectivity and performance.

Known limits of this guidance

• Evidence level: documentary for the core location claim, which comes from the official help centre opened directly this session (the per-OS path and codex doctor). The precedence, CODEX_HOME, CLI/IDE-sharing and override-list details are from the developers.openai.com config pages read via a mirror, because the canonical host returned Forbidden; they were not confirmed on the canonical host and should be re-checked there.
• The help centre does not mention MCP servers or the config file format beyond one key, so this page does not cover parse errors.
• No Windows system-level config path is documented; only /etc/codex/config.toml on Unix is named.
• codex doctor’s output format is unknown from the pages opened; the help centre documents that it exists and what it covers.