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

Codex config.toml cover

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:

  1. CLI flags and --config overrides
  2. Project .codex/config.toml files, from the project root down to your current folder
  3. A profile file selected with --profile profile-name
  4. User config, ~/.codex/config.toml
  5. Cloud-managed defaults for your signed-in workspace, if any
  6. System config, /etc/codex/config.toml on Unix
  7. 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):

Terminal
codex -c log_dir=./.codex-log

Model 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.
TOML
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.

TOML
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.
TOML
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.toml

Put only the values that differ from your main config in it:

TOML
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

Then select it:

Terminal
codex --profile review

The 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:

TOML
[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:

TOML
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false

Feature 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:

TOML
[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:

TOML
# ~/.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.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides