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.
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 = trueCopiedWhere 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.tomlCopiedThe 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 defaultsCopiedSeparately, 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"CopiedThe 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"]'CopiedThe 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"Copiedcodex --profile deep-review
codex exec --profile deep-review "review this change"CopiedTo migrate, move each old table’s keys into its own file and delete the table and the profile = line.
The keys people set most
model. The model id, such as"gpt-6.2-sol", which OpenAI’s models page recommends for everyday work (gpt-6.2-astrafor demanding work). Left unset, Codex uses its recommended model. A model your ChatGPT plan does not include fails at the first message; that is the model-not-supported error.model_reasoning_effort. Whatever the selected model advertises, such aslow,medium,highorxhigh; the reference also listsmaxandultrafor models that offer them./modelin a session shows the choices for yours.approval_policy."on-request"lets the model decide when to ask you;"never"never asks, and failures go straight back to the model. The reference marksuntrustedas unsupported andon-failureas deprecated, so older configs with either need changing. There is also agranularform for per-flow control.sandbox_mode."read-only","workspace-write"(write inside the project) or"danger-full-access"(no sandbox). Running Codex without prompts on a machine of its own is in running Claude Code and Codex without permission prompts.[sandbox_workspace_write].network_access = truelets commands in theworkspace-writesandbox reach the network; it defaults tofalse, so with the default a command such asnpm installhas no network inside that sandbox.writable_rootsadds folders outside the project that Codex may write to.web_search."cached"(the default),"indexed","live"or"disabled".[history]. Codex keeps its history in~/.codex/history.jsonl.persistence = "none"turns that off (the default is"save-all"), andmax_bytescaps the file by dropping the oldest entries.notify. A command Codex runs when a turn finishes (the only event today isagent-turn-complete), given one JSON argument with fields such ascwdandlast-assistant-message. On a server, that is a way to send yourself a message when a long task is done:notify = ["python3", "/home/me/notify.py"].
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"CopiedA 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
/statusshows the model (with its reasoning effort), the directory, the permissions (sandbox and approval together), the provider when it is not the default, and your account./debug-configshows “config layers and requirement sources”: which files were loaded, which is how you find out that a project file was skipped or a key came from/etc/codex.
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.