GuidesRunning & maintaining

Codex config.toml: where it lives, precedence and key settings

Where Codex CLI's config.toml lives, how project files, profiles and -c overrides stack, the keys people set most, and how to check what's in effect.

November 21, 2026The Everpod team
The short answer

Codex CLI reads its settings from ~/.codex/config.toml, or $CODEX_HOME/config.toml if you set CODEX_HOME. A repository can add its own .codex/config.toml, which Codex loads only once you trust the project. The order, highest first: command-line flags and -c key=value, the project files, a profile file chosen with --profile, your user file, then the system file /etc/codex/config.toml and the built-in defaults. Inside a session, /status shows the model and permissions in effect and /debug-config lists the layers they came from. This page describes Codex CLI 0.171.0, as of November 2026.

# ~/.codex/config.toml
model = "gpt-6.2-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
Copied

Where the file lives

If it is not there yet, create it; without it Codex runs on its built-in defaults. OpenAI’s advanced config page says Codex “stores its local state under CODEX_HOME (defaults to ~/.codex)”, so the same folder holds your history and logs as well. Setting CODEX_HOME to another folder gives you a separate Codex with its own config, which is useful on a shared server or for keeping a second account apart. On a Linux server the file belongs to the user Codex runs as: a config written as root is not the one your own account reads.

mkdir -p ~/.codex
nano ~/.codex/config.toml
Copied

The other places Codex looks are a project’s .codex/config.toml and, on Linux and other Unix systems, the machine-wide /etc/codex/config.toml. The same file is read by the interactive codex and by codex exec; setting Codex up on a server from scratch is in installing Codex CLI on a Linux server.

What wins when several set the same key

The config basics page gives the order, highest precedence first:

1. Command-line flags and -c / --config overrides
2. Project .codex/config.toml files (trusted projects only;
   the one closest to your working directory wins)
3. A profile file chosen with --profile
4. Your user file, ~/.codex/config.toml
5. Cloud-managed defaults, where your workspace delivers them
6. The system file, /etc/codex/config.toml
7. Built-in defaults
Copied

Separately, an administrator’s requirements.toml can constrain what any of these is allowed to set; a config file only sets defaults within those limits.

Project config and trust

Codex walks from the project root (by default, the folder holding .git) down to your working directory and loads every .codex/config.toml on the way, the closest winning. Relative paths in one resolve against the .codex/ folder that holds it. None of this happens until the project is trusted: in OpenAI’s words, “Codex loads project .codex/ layers only when you trust the project.” The interactive CLI asks the first time you open a folder (inside a Git repository, trust applies to the repository root) and records your answer in your user file:

[projects."/home/me/projects/app"]
trust_level = "trusted"
Copied

The value is "trusted" or "untrusted". A non-interactive codex exec cannot ask, so it skips an untrusted project’s config unless you pass --trust; that warning is covered in the untrusted project configuration guide.

Some keys are never taken from a project file, even a trusted one, so a cloned repository cannot point Codex at another provider or set a notification command. Codex ignores these in .codex/config.toml and prints a warning at startup: model_provider, model_providers, notify, profile, profiles, openai_base_url, chatgpt_base_url, apps_mcp_product_sku, experimental_realtime_ws_base_url and otel. They belong in your user file.

One-off overrides with -c

Any key can be set for one run with -c (or --config), using dots for nested tables. The value is parsed as TOML, and “if the value can’t be parsed as TOML, Codex treats it as a string”, so quote anything with spaces or brackets:

codex -c model_reasoning_effort=high
codex --config model='"gpt-6.1-sol"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
Copied

The common settings also have their own flags: -m for the model, -s for the sandbox, -a for the approval policy, -p for a profile and -C for the working directory.

Profiles are separate files now

Most tutorials show [profiles.name] tables inside config.toml and a top-level profile = "name". That stopped working: “In Codex 0.134.0 and later, --profile no longer reads [profiles.profile-name] from config.toml, and the top-level profile = "profile-name" selector is no longer supported.” A profile is now its own file beside the main one, ~/.codex/<name>.config.toml, with plain top-level keys, layered over your user file when you pass --profile <name>. It only needs the values that differ:

# ~/.codex/deep-review.config.toml
model = "gpt-6.2-astra"
model_reasoning_effort = "high"
Copied
codex --profile deep-review
codex exec --profile deep-review "review this change"
Copied

To migrate, move each old table’s keys into its own file and delete the table and the profile = line.

The keys people set most

MCP servers and other providers

Each MCP server is a table under mcp_servers: a local one is a command with args and an optional env table, a remote one a url. /mcp in a session lists the tools Codex sees.

[mcp_servers.local-tool]
command = "/path/to/server"
args = ["--stdio"]

[mcp_servers.remote-tool]
url = "https://example.com/mcp"
Copied

A provider other than OpenAI is a [model_providers.<id>] table with a base_url and the name of the environment variable that holds its key in env_key, selected with model_provider. Only wire_api = "responses" is supported, so a tutorial with "chat" is out of date. The full block for OpenRouter, and what changes when you leave your ChatGPT sign-in, is in using OpenRouter with Codex, OpenCode and Claude Code.

Checking what is in effect

If an edit seems to have no effect, the usual causes are a key in a project file Codex ignores, a project that is not trusted, a flag or -c on the command line that outranks the file, or a different CODEX_HOME in the environment Codex was started from.

Run Codex on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.