Codex config.toml: location, keys and examples

Where the Codex CLI config.toml lives

Per the basic config page, user-level configuration is stored at ~/.codex/config.toml. To scope settings to a project or subfolder, add a .codex/config.toml file in the repository. The CLI and the IDE extension share the same configuration layers, and the extension can open the file from the gear icon via Codex Settings > Open config.toml.

CODEX_HOME sets the root for Codex state — config, auth, logs, sessions, skills and standalone package metadata — and defaults to ~/.codex; if you set it, the directory must already exist (environment variables). Files commonly found there include config.toml, auth.json and history.jsonl (advanced config).

On Windows, OpenAI’s Help Center (Using Codex with your ChatGPT plan) says to open ~/.codex/config.toml on macOS or Linux, or %USERPROFILE%\.codex\config.toml on Windows.

Codex configuration layers and precedence

The basic config page lists the order Codex resolves a value in, highest precedence first:

1. CLI flags and --config overrides
2. Project .codex/config.toml (trusted projects only; the closest one wins)
3. The profile file selected with --profile
4. User ~/.codex/config.toml
5. Cloud-managed defaults
6. System /etc/codex/config.toml
7. Built-in defaults

For security, Codex loads project .codex/ layers only when you trust the project. Even then, the advanced config page says Codex ignores some keys in a project-local file and prints a startup warning: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url and otel. On managed machines an organization may also enforce constraints through requirements.toml. Inside the CLI, /debug-config prints the config layers and policy sources (command reference).

Codex config keys documented in the reference

A selection, one line each, paraphrased from the descriptions in the Configuration Reference (which documents many more). Re-read the reference before relying on any key not listed here.

Profiles

Profiles are separate files. When you pass --profile profile-name, Codex loads ~/.codex/config.toml and then overlays ~/.codex/profile-name.config.toml; the profile file uses top-level keys, not a table. Try it with codex --profile deep-review. The advanced config page also says that in current releases the older [profiles.profile-name] table in config.toml and the top-level profile = "profile-name" selector no longer work.

One-off overrides with -c / --config

Prefer a dedicated flag when one exists; use -c / --config to override an arbitrary key. Values are parsed as TOML, dot notation sets nested keys, and the docs advise quoting the value so your shell does not split it on spaces. Lines copied from the “One-off overrides from the CLI” section of the advanced config page:

# Generic key/value override (value is TOML, not JSON)
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Feature flags have their own switch: codex --enable feature_name from the CLI, and codex features enable|disable persists flags into $CODEX_HOME/config.toml.

Codex config toml example snippets

Copied line for line from the official pages. Lines that name a specific model were left out on purpose, because model names change.

A profile file

From the “Profiles” section of the advanced config page:

# ~/.codex/deep-review.config.toml
model_reasoning_effort = "medium"
approval_policy = "on-request"

Turning off history, and a notify command

From the “History persistence” and “Notifications” sections of the same page:

[history]
persistence = "none"

notify = ["python3", "/path/to/notify.py"]

A custom model provider

From the “Custom model providers” section of the same page:

model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

Is there a usage-limit or reset setting in config.toml?

No rate-limit, usage or reset key appears in the Configuration Reference, and none of the pages checked links config.toml to usage limits. The closest thing is display only: tui.status_line (set interactively by /statusline) can show rate limits in the CLI footer. Likewise, this guide found no command that resets the config file to defaults, and nothing suggests that clearing or editing local configuration refreshes a usage window. Limits are tracked by your account, and OpenAI Support does not reset usage limits; see how to check Codex usage, how the windows work, and the three kinds of reset OpenAI describes.