DownloadCodex Unofficial guide
English

Configure Codex with config.toml

Codex reads personal settings from ~/.codex/config.toml and project overrides from .codex/config.toml in trusted repositories. CLI flags win over project files, which win over profiles, which win over your user file. The options people change most are model, approval_policy, sandbox_mode, web_search, and model_reasoning_effort.

Where the file lives

  • User config: ~/.codex/config.toml. On Windows with the desktop app, the Codex home is %USERPROFILE%\.codex.
  • Project config: .codex/config.toml inside a repository, loaded only if you trust the project.
  • In the IDE extension: gear icon, then Codex Settings, then Open config.toml.

The CLI and IDE extension share the same configuration layers.

Which setting wins

Highest precedence first:

  1. CLI flags and --config / -c overrides
  2. Project .codex/config.toml files, closest folder wins (trusted projects only)
  3. A profile chosen with --profile name (~/.codex/name.config.toml)
  4. Your user ~/.codex/config.toml
  5. Cloud-managed defaults for your workspace, if any
  6. System config, /etc/codex/config.toml on Unix
  7. Built-in defaults

On managed machines, your organization can also enforce limits with requirements.toml that you can’t override.

A starter file

# ~/.codex/config.toml
model = "gpt-6.1-sol"              # the example OpenAI's docs used on 2026-10-16
approval_policy = "on-request"     # ask before going beyond the sandbox
sandbox_mode = "workspace-write"   # edit inside the project, not elsewhere
web_search = "cached"              # default; "live" fetches fresh pages
model_reasoning_effort = "medium"

Model names change often. If a model is rejected, check OpenAI’s current config docs or remove the model line to use the default.

Options worth knowing

KeyValuesNotes
approval_policy"on-request", "never"untrusted is retired. See OpenAI’s migration note.
sandbox_mode"read-only", "workspace-write", "danger-full-access"Full access removes the project boundary.
web_search"cached", "indexed", "live", "disabled"Treat web results as untrusted.
personality"none"Removes the built-in personality instructions
log_dira pathAlso turns on the plaintext codex-tui.log
project_doc_max_bytesnumberAGENTS.md size cap, 32 KiB by default
[features]flagsFor example memories = true, which is experimental

Windows sandbox

[windows]
sandbox = "elevated"   # legacy fallback

[features]
prefer_mxc = true

OpenAI suggests preferring MXC where your device and policy support it. Use unelevated only if elevated setup isn’t available and your organization allows it.

Want this done for you? Use the config generator.

Questions people ask

My project's .codex/config.toml is ignored. Why?

Codex loads project .codex/ layers only for trusted projects. If you marked the project as untrusted, project config, hooks, and rules are skipped.

Can I override a setting for one run?

Yes. Use -c or --config on the command line, for example codex -c log_dir=./.codex-log. CLI flags have the highest precedence.

Sources

We link to the official source for every instruction on this page. If anything here disagrees with them, trust the official source and tell us.

Read next