Codex config.toml: Location, Keys and a Starter File
Codex config.toml explained: where the file lives, the keys for model, approval policy and sandbox mode, profile files, MCP servers and a starter file to use.
Josh Pocock6 min read
AI Coding
Codex config.toml
Stride AI Academy
Codex config.toml is the settings file for OpenAI's Codex, and it lives at ~/.codex/config.toml for your user, with optional .codex/config.toml files inside trusted projects. It sets the model, reasoning effort, approval policy, sandbox mode, MCP servers and dozens of smaller options. The Codex docs say the CLI, IDE extension and ChatGPT desktop app share its MCP setup, and command-line flags override it for one run.
This guide covers where the file lives, which layer wins when settings clash, the keys worth changing, profile files, MCP blocks and a starter file. Everything here was checked against OpenAI's Codex config basics, the Codex config reference and the Codex MCP docs on November 22, 2026. OpenAI's old developers.openai.com/codex links now redirect there. Only keys documented on that date are included.
Where the Codex config file lives
| Layer | Path |
|---|---|
| User | ~/.codex/config.toml |
| Project | .codex/config.toml in your repo |
| Profile | ~/.codex/profile-name.config.toml |
| System (Unix) | /etc/codex/config.toml |
Project files only load when you trust the project. If a project isn't trusted, Codex skips its .codex/ layers, including project config, hooks and rules, and still loads your user and system config.
Which settings win
From the config basics page, highest priority first:
- CLI flags and
--configoverrides - Project
.codex/config.tomlfiles, from the project root down to your current folder - A profile file selected with
--profile profile-name - User config,
~/.codex/config.toml - Cloud-managed defaults for your signed-in workspace, if any
- System config,
/etc/codex/config.tomlon Unix - Built-in defaults
So a value in your repo's .codex/config.toml beats your user file, and a flag beats both. Workspace admins can also set managed restrictions that local config can't relax.
One-off overrides with -c
To change a setting for a single run, pass -c (or --config):
codex -c log_dir=./.codex-logModel settings
| Key | Values | Notes |
|---|---|---|
model |
A model name, such as "gpt-6.1-sol" |
The model Codex uses. |
model_provider |
A provider ID | Default openai. Points at an entry in model_providers. |
model_reasoning_effort |
low, medium, high, xhigh, max, ultra |
Which levels work depends on the model and client. |
plan_mode_reasoning_effort |
A level the model supports | Separate effort for plan mode. |
model_verbosity |
low, medium, high |
When unset, the model's default is used. |
model = "gpt-6.1-sol"
model_reasoning_effort = "high"Approval policy
approval_policy sets when Codex stops to ask you before acting.
| Value | What it means |
|---|---|
"on-request" |
Codex asks when it needs approval. |
"never" |
Codex never asks. |
| Granular table | Separate booleans for sandbox_approval, rules, mcp_elicitations, request_permissions and skill_approval. |
The reference marks untrusted as unsupported and on-failure as deprecated, so if you copied an older config with either value, change it.
approval_policy = "on-request"Sandbox mode
sandbox_mode sets what Codex can touch when it runs commands.
| Value | What it allows |
|---|---|
"read-only" |
Reading files only. |
"workspace-write" |
Writing inside your workspace. |
"danger-full-access" |
No sandbox limits. |
In workspace-write mode, a [sandbox_workspace_write] table adds detail:
| Key | What it does |
|---|---|
writable_roots |
Extra folders Codex can write to. |
network_access |
Allows outbound network access inside the sandbox. |
exclude_slash_tmp |
Removes /tmp from the writable folders. |
exclude_tmpdir_env_var |
Removes $TMPDIR from the writable folders. |
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true
writable_roots = ["/home/you/shared-assets"]Use danger-full-access only in a throwaway container or VM. Our Codex CLI tutorial covers how approval and sandbox settings play out in a session.
Profiles
Profiles let you keep a different set of settings for different jobs. In the current docs, each profile is its own file next to your user config:
~/.codex/review.config.tomlPut only the values that differ from your main config in it:
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"Then select it:
codex --profile reviewThe profile layer sits above your user config and below project config, so a trusted project's .codex/config.toml still wins.
MCP servers
Each MCP server is an [mcp_servers.<name>] table. A local server uses command and args. A remote one uses url:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"Other per-server keys include enabled, required, enabled_tools, disabled_tools, startup_timeout_sec (default 10) and tool_timeout_sec (default 60). You can also add servers with codex mcp add instead of editing the file. The full walkthrough, with token and OAuth examples, is in Codex MCP setup.
Other settings worth knowing
| Key | Values | What it does |
|---|---|---|
web_search |
disabled, cached, indexed, live |
Web search mode. Default cached. |
file_opener |
vscode, vscode-insiders, windsurf, cursor, none |
Which editor opens file links. Default vscode. |
notify |
Array of strings | A command Codex runs for notifications, with a JSON payload. |
project_doc_max_bytes |
Number | Maximum bytes read from AGENTS.md. |
history.persistence |
save-all, none |
Whether session history is saved. |
history.max_bytes |
Number | Caps the history file size. |
log_dir |
Path | Where logs go. Default $CODEX_HOME/log. |
Shell environment
[shell_environment_policy] controls which environment variables commands see. inherit takes all, core or none, set adds explicit values, and filters includes or excludes variables. The reference says ignore_default_excludes keeps variables whose names contain KEY, SECRET or TOKEN, and lists its default as true. The config basics page shows setting it to false, which drops them so commands can't read your secrets:
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = falseFeature flags and the terminal UI
The [features] table turns features on or off, such as features.hooks for lifecycle hooks or features.memories, which is off by default. The [tui] table holds terminal UI options like tui.theme, tui.status_line, tui.notifications and keybindings:
[tui.keymap.global]
open_transcript = "ctrl-t"A starter config.toml
This starter uses only keys from the reference, with values that keep Codex asking before risky steps:
# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
file_opener = "vscode"
[sandbox_workspace_write]
network_access = false
[history]
persistence = "save-all"
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"Change file_opener to cursor if you use Cursor, and set network_access = true if your builds need to download packages inside the sandbox. Check that your model supports the effort level you pick.
Codex config.toml vs Claude Code settings.json
If you also use Claude Code, the jobs are the same but the files differ. Codex uses TOML in ~/.codex/config.toml and .codex/config.toml. Claude Code uses JSON settings.json files, covered in our Claude Code settings.json guide. Codex's project instructions live in AGENTS.md, and Claude Code's in CLAUDE.md. See AGENTS.md vs CLAUDE.md for sharing rules between them.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code and Codex setups, and the Claude Code community is where members compare theirs.
FAQ
Where is the Codex config.toml file?
Your user config is at ~/.codex/config.toml. You can add .codex/config.toml in a project, which loads only if you trust that project. On Unix, a system file at /etc/codex/config.toml is read too, at lower priority.
How do I set the default model in Codex?
Add model = "model-name" at the top of ~/.codex/config.toml, for example model = "gpt-6.1-sol". Set model_reasoning_effort on the next line to pick the effort level the model supports.
What are the approval_policy values in Codex?
The reference lists on-request and never, plus a granular table form. untrusted is unsupported and on-failure is deprecated on November 22, 2026.
How do Codex profiles work?
Each profile is a file named profile-name.config.toml in ~/.codex, holding only the settings that differ. Run codex --profile profile-name to use it. Project config still overrides a profile.
Does the Codex IDE extension use config.toml?
Yes. The Codex MCP docs say the desktop app, CLI and IDE extension share MCP configuration, which lives in config.toml. Settings you add there apply across them.