Configuration lives in ~/.codex/config.toml, or $CODEX_HOME/config.toml if you set it. The settings that matter are model, model_reasoning_effort, sandbox_mode, and approval_policy. Profiles are now separate files: codex -p build layers $CODEX_HOME/build.config.toml on top of the base config, and the old [profiles.name] tables stopped working in Codex 0.134.0. MCP servers are declared in the same file.
- One file:
~/.codex/config.toml. Point$CODEX_HOMEelsewhere to isolate an account. model_reasoning_effortis the biggest single lever on both cost and quality.- Profiles are separate files now:
-p buildloads$CODEX_HOME/build.config.toml. [profiles.name]tables no longer work with--profile, and having both is a hard error.- MCP servers live in the same file under
[mcp_servers.name], with per-tool approval. -c key=valueoverrides anything for one run. The value is parsed as TOML.--strict-configerrors on keys this version does not recognise. Run it after any upgrade.
Where configuration lives
| Path | Holds |
|---|---|
~/.codex/config.toml | The base configuration |
~/.codex/<name>.config.toml | One named profile, loaded with -p <name> |
~/.codex/auth.json | Credentials, written by codex login |
~/.codex/sessions/ | JSONL transcripts of every run |
AGENTS.md in the repo | Project instructions, which are content rather than configuration |
CODEX_HOME=~/.codex-work codex login
CODEX_HOME=~/.codex-work codexA full configuration
# ── model ──────────────────────────────────────────────
model = "gpt-5.6-sol" # sol | terra | luna | 5.5 | 5.4
model_reasoning_effort = "low" # sol ships at low and is strong there
# service_tier = "priority" # Fast mode. Faster, burns credits quicker.
# ── permissions ────────────────────────────────────────
sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access
approval_policy = "on-request" # untrusted | on-request | never
# Network is OFF in workspace-write unless you say otherwise.
[sandbox_workspace_write]
network_access = false
writable_roots = []
# ── context ────────────────────────────────────────────
model_auto_compact_token_limit = 200000 # compact before the window fills
# ── MCP servers ────────────────────────────────────────
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgres://localhost/dev" }
enabled = trueThe settings that matter
| Setting | Values | Effect |
|---|---|---|
model | A model id | Which model runs. Biggest cost lever after effort. |
model_reasoning_effort | minimal to ultra | How much it thinks before acting |
sandbox_mode | Three modes | Hard capability boundary, enforced by the OS |
approval_policy | untrusted, on-request, never | When it stops to ask you |
approvals_reviewer | user, auto_review | Who reviews approval requests |
service_tier | priority for Fast mode | Faster responses, and it burns credits quicker |
network_access | bool | Off by default in workspace-write |
model_auto_compact_token_limit | Token count | When the session summarises itself |
review_model | A model id | Model used by /review and codex review |
web_search | bool | Enables the native search tool, same as --search |
Reasoning effort is the one to tune
Effort controls how much the model deliberates before it acts, and it moves cost, latency, and quality together. The available levels differ by model.
Supported reasoning efforts per model, from the CLI model catalogue, August 2026.
| Model | Default | Supports |
|---|---|---|
gpt-5.6-sol | low | low, medium, high, xhigh, max, ultra |
gpt-5.6-terra | medium | low, medium, high, xhigh, max, ultra |
gpt-5.6-luna | medium | low, medium, high, xhigh, max |
gpt-5.5, gpt-5.4 | medium | low, medium, high, xhigh |
gpt-5.3-codex-spark | high | low, medium, high, xhigh |
What to reach for.
| Effort | Use for |
|---|---|
low | Routine changes in familiar code. Sol ships here and is strong here. |
medium | Ordinary feature work |
high | Architecture, stubborn bugs, unfamiliar systems |
xhigh / max | A task that has already resisted a high-effort attempt |
ultra | Maximum reasoning with automatic task delegation |
Profiles: what changed, and how to migrate
Profiles are the feature worth using, because sandbox and approval settings work as a pair and naming the pair removes the mistake. The mechanism changed in Codex 0.134.0, and old configs now fail loudly rather than silently.
| Before 0.134.0 | Now | |
|---|---|---|
| Where a profile lives | [profiles.build] in config.toml | $CODEX_HOME/build.config.toml |
| Selecting one | --profile build or profile = "build" | -p build / --profile build |
| Having both | Fine | Hard error |
Error loading config.toml: --profile `explore` cannot be used while
~/.codex/config.toml contains legacy `profile = "explore"` or
`[profiles.explore]` config; move those settings into
~/.codex/explore.config.toml and remove the legacy profile
selector/table.# each profile becomes its own file next to config.toml
$EDITOR ~/.codex/explore.config.toml
$EDITOR ~/.codex/build.config.toml
$EDITOR ~/.codex/deep.config.toml
# then remove every [profiles.*] table and any top-level profile = "..."
$EDITOR ~/.codex/config.tomlmodel = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
approval_policy = "never"codex -p explore # read-only, cheap model, no prompts
codex -p build # the normal working setup
codex -p deep # high effort for something hardMCP servers
Model Context Protocol servers are declared in the same file, so a tool the agent can call is configuration rather than a plugin install.
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
enabled = true
# per-tool approval, so the dangerous ones still ask
[mcp_servers.playwright.tools.browser_navigate]
approval_mode = "approve"codex mcp list
codex mcp add ...
codex mcp get <name>
codex mcp remove <name>
codex mcp login <name> # for servers behind OAuthOverriding for one run
| Flag | Does |
|---|---|
-c key=value | Override any config key. Dotted paths reach nested tables. |
-p <name> | Layer a named profile file |
-m, -s, -a | Model, sandbox, approvals |
--enable / --disable | A feature flag, same as -c features.<name>=true |
--strict-config | Error on unrecognised keys instead of ignoring them |
--ignore-user-config | Skip config.toml entirely. Auth still resolves from CODEX_HOME. |
# any key, for one run. The value is parsed as TOML.
codex -c model_reasoning_effort="high"
codex -c 'sandbox_workspace_write.network_access=true'
# a reproducible run for CI: no user config, no session files
codex exec --ignore-user-config --ephemeral -s read-only -a never "review the diff"Questions people ask
~/.codex/config.toml, or $CODEX_HOME/config.toml if you set that variable. Credentials sit beside it in auth.json and transcripts in sessions/.
Each profile is its own file: codex -p build loads $CODEX_HOME/build.config.toml and layers it over the base config. Since Codex 0.134.0 the --profile flag no longer reads [profiles.name] tables from config.toml.
Because config.toml still contains a [profiles.name] table or a top-level profile = "name" selector. Move those settings into a file named after the profile, such as build.config.toml, beside config.toml, then delete the legacy table.
How much the model deliberates before acting. Levels run minimal, low, medium, high, xhigh, max, ultra, and which are available depends on the model. gpt-5.6-sol defaults to low and supports everything up to ultra.
Add an [mcp_servers.name] block with command, args, and any env it needs, or use codex mcp add. Set approval_mode on individual tools so the ones that act on the world still ask.
Project instructions go in AGENTS.md at the repository root. For runtime settings, define a profile and commit a small wrapper script so everyone on the team runs the same configuration.
codex -c key="value". Any key from config.toml works and dotted paths reach nested tables, so -c sandbox_workspace_write.network_access=true is valid. Flags take precedence over the file.
Give each one its own CODEX_HOME. Separate config, separate auth.json, separate session history, and no chance of the wrong subscription being billed.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.