SU8 Codes
< Back to blog
Official article 12 min read

Codex config.toml Reference

A field-by-field guide to Codex's config.toml: where user and project files live, which layer wins, and the accepted values and minimal examples for model, provider, reasoning effort, approvals, sandboxing, profiles, MCP servers, notify, and history. Checked against OpenAI's documentation and the openai/codex repository on November 15, 2026.

#codex#config.toml#tutorial
Codex config.toml Reference

~/.codex/config.toml is the user-level configuration file for the Codex CLI; the IDE extension shares the same configuration layers. It uses TOML: one key = value per line, with tables in square brackets such as [history]. Model selection, approvals, sandboxing, external tools, notifications, and local history all live here.

The official configuration reference is long, and you do not need most of it. This Codex config.toml reference walks through the keys people actually change, with the accepted values, when to use each one, and a minimal example. The full key list is linked at the end. Details are checked against OpenAI's documentation and the official openai/codex repository (commit ee344ca) as of November 15, 2026.

Where the file lives and which layer wins

Codex reads configuration from more than one place. Personal defaults go in ~/.codex/config.toml. Project overrides go in .codex/config.toml inside a repository. The Codex home directory defaults to ~/.codex; set CODEX_HOME to move it.

When the same key appears in several layers, the higher layer wins. The documented order, highest priority first:

  1. CLI flags and --config overrides.
  2. Project config files: .codex/config.toml, from the project root down to the current directory, with the closest file winning.
  3. Profile files selected with --profile <name> (~/.codex/<name>.config.toml).
  4. User config: ~/.codex/config.toml.
  5. Cloud-managed defaults delivered for the signed-in workspace.
  6. System config: /etc/codex/config.toml on Unix, if present.
  7. Built-in defaults.

Project config has a security gate: Codex loads project-scoped .codex/ layers only when you trust the project. If the project is marked untrusted, the entire project layer is skipped, including project config, hooks, and rules. User and system config still load.

A related restriction catches people off guard: project config cannot set machine-local provider, auth, notification, profile-selection, or telemetry keys. Codex ignores openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel in a project-local .codex/config.toml, and prints a startup warning when it sees them. Put those in the user-level file. Relative paths inside a project config resolve against the .codex/ directory that contains it.

A minimal project-level file:

# <repo>/.codex/config.toml
model_reasoning_effort = "high"
project_doc_max_bytes = 65536

model, model_provider, and model_reasoning_effort

These three keys answer: which model, through which provider, and how much reasoning.

model is the model name, as a string. The official examples use gpt-6.1-sol, with a note that the model requires access on your signed-in account or workspace. If you do not have access, substitute a model you can use. The documentation does not name a fixed default model, so check availability before copying the example.

model = "gpt-6.1-sol"

model_provider selects a provider from model_providers; the default is openai. Change it when you need a different provider; a custom gateway or proxy is the common case. A custom provider usually sets a name and base_url; point env_key at an environment variable instead of hard-coding the API key. The only supported wire_api value is responses, and it is the default when omitted.

model = "gpt-6.1-sol"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Built-in provider IDs cannot be overridden; the documentation names openai, ollama, and lmstudio among them. If all you want is a different base URL for the built-in OpenAI provider, use openai_base_url instead of defining a new provider:

openai_base_url = "https://us.api.openai.com/v1"

model_reasoning_effort controls how much reasoning the model applies before answering. It takes a string. The available levels depend on the model and client; the documentation lists low, medium, high, xhigh, max, and ultra as examples. Not every model accepts every level, so check the model's supported settings first. For everyday coding, medium is a reasonable starting point; raise it for harder problems.

model_reasoning_effort = "medium"

Three related keys sit in the same area:

  • model_reasoning_summary: detail level for reasoning summaries — auto, concise, detailed, or none.
  • model_verbosity: response length — low, medium, or high. It applies only to providers using the Responses API; Chat Completions providers ignore it.
  • model_context_window: context window size in tokens. You usually do not need it when the model or provider already reports a window; set it to override or cap the value.

approval_policy: when Codex must ask

Codex has two control layers. The sandbox decides what Codex can technically do; the approval policy decides when it must ask you first. approval_policy controls the second layer.

There are three forms:

  • "on-request": commands allowed by the sandbox run without approval. Codex asks when it needs to leave the sandbox, use the network, or touch files outside the workspace. Use this for interactive work.
  • "never": no approval prompts at all. It works with every sandbox_mode, so the sandbox boundary still applies; Codex just stops asking. Use it for CI or non-interactive runs.
  • { granular = { ... } }: per-category control over which prompts surface and which are auto-rejected. The categories are sandbox_approval, rules, mcp_elicitations, request_permissions, and skill_approval.

Two values need attention. "untrusted" is unsupported and can prevent the client from starting. "on-failure" is deprecated; use on-request for interactive runs and never for non-interactive ones. The documentation does not give a fixed default value for approval_policy. Its startup guidance recommends the Auto preset (workspace-write plus on-request) for version-controlled folders, and an untrusted folder may start in read-only. If you want predictable behavior, set the key explicitly.

approval_policy = "on-request"

Approval requests go to you by default. To route eligible requests through the reviewer agent first, set approvals_reviewer:

approval_policy = "on-request"
approvals_reviewer = "auto_review"  # default is "user"

Auto-review uses extra model calls, so it can add to usage. It only reviews actions that already require approval; it does not change the sandbox boundary.

sandbox_mode: what Codex can do

sandbox_mode sets the filesystem and network access available while Codex runs commands. It has three values:

  • "read-only": read access, no writes.
  • "workspace-write": the workspace is writable, the rest of the filesystem is read-only. The documentation describes the CLI/IDE default as write access limited to the active workspace with no network access; this is the matching mode.
  • "danger-full-access": no sandbox. The documentation says to use it only when your environment already isolates processes. It is not a convenience switch.
sandbox_mode = "workspace-write"

Workspace mode has its own table:

[sandbox_workspace_write]
network_access = false          # off by default; set true to allow outbound network
writable_roots = ["/Users/YOU/.pyenv/shims"]  # extra writable roots
exclude_tmpdir_env_var = false  # false allows $TMPDIR
exclude_slash_tmp = false       # false allows /tmp

Two details matter:

  1. A writable workspace is not entirely writable. Under workspace-write, the official docs keep .git, .agents, .codex, and .aws read-only, recursively. That is why commands such as git commit may still need to run outside the sandbox and request approval.
  2. Network access is off by default. Commands inside the workspace reach the network only after you set network_access = true.

Codex also has beta permission profiles: built-ins :read-only, :workspace, and :danger-full-access, plus custom profiles under [permissions.<name>] selected with default_permissions. This is a separate model from sandbox_mode; the reference says not to combine them. The Permissions page covers the details.

profiles: save a configuration per task

Profiles solve the "different settings for different tasks" problem: medium reasoning for everyday coding, high for review, and so on.

There is an important version change. Starting in Codex 0.134.0, --profile no longer reads [profiles.<name>] tables from config.toml, and the top-level profile = "<name>" selector is no longer supported. Each profile is a separate file at ~/.codex/<name>.config.toml (or under $CODEX_HOME when set). Use top-level keys in that file; do not nest them.

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"

Select it with --profile:

codex --profile deep-review
codex exec --profile deep-review "review this change"

The profile file sits above the base user config and below project and CLI config, so it only needs the values that differ. Profile names can contain letters, numbers, hyphens, and underscores.

To migrate an old profile, move the keys from [profiles.deep-review] into ~/.codex/deep-review.config.toml as top-level keys, then remove the [profiles.deep-review] table and the profile = "deep-review" line from config.toml.

mcp_servers: add external tools

MCP stands for Model Context Protocol, a common interface that lets a model call external tools and data sources. The mcp_servers table tells Codex which MCP servers exist, how to launch them, and how to connect.

A common setup is a stdio server: Codex launches a local process and talks to it over standard input and output.

[mcp_servers.local_tools]
command = "/usr/local/bin/my-mcp-server"
args = ["--stdio"]
env = { LOG_LEVEL = "info" }
cwd = "/Users/YOU/projects"

For a server exposed as a streamable HTTP endpoint, use url instead of command:

[mcp_servers.remote_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "MCP_TOKEN"

Useful subkeys:

  • enabled = false: turn a server off without deleting its configuration.
  • startup_timeout_sec: startup timeout, 10 seconds by default.
  • tool_timeout_sec: per-tool timeout, 60 seconds by default.
  • enabled_tools / disabled_tools: allow list and deny list; the deny list applies after the allow list.
  • auth: authentication fallback for HTTP servers — oauth (default) or chatgpt.

notify: run a command when a turn finishes

notify runs an external program when Codex emits an event. It fits desktop notifications, chat webhooks, and CI updates. The documentation says the only supported event today is agent-turn-complete, emitted when a turn finishes.

notify = ["python3", "/Users/YOU/.codex/notify.py"]

The program receives a single JSON argument. Common fields are type, thread-id, turn-id, cwd, input-messages, and last-assistant-message. A minimal script that prints the result:

#!/usr/bin/env python3
import json, sys

event = json.loads(sys.argv[1])
if event.get("type") == "agent-turn-complete":
    print("Codex turn complete in", event.get("cwd"))

Do not confuse notify with tui.notifications. notify runs an external program; tui.notifications is the TUI's built-in terminal notification and can filter by event type, such as agent-turn-complete and approval-requested. Also note that notify is ignored in project-level config; set it in the user-level file.

history: whether to save transcripts and how much

By default, Codex saves local session transcripts under CODEX_HOME, for example ~/.codex/history.jsonl. The repository's defaults.toml sets history.persistence = "save-all", and the documentation says Codex saves transcripts by default.

To turn local persistence off:

[history]
persistence = "none"

To keep history but cap it, set max_bytes. When the file exceeds the cap, Codex drops the oldest entries, compacts the file, and keeps the newest records:

[history]
max_bytes = 104857600  # 100 MiB

Transcripts can contain source paths and command output. If your team has data-handling rules, decide whether to keep them and for how long before changing these keys.

Other keys worth knowing

KeyValues / defaultWhen to use it
web_searchcached (default), indexed, live, disabledControl how web search works; with --yolo or another full-access sandbox setting, the default becomes live
project_root_markersDefault [".git"]Change how the project root is found; [] treats the current directory as the root
project_doc_max_bytesDefault 32768 (32 KiB)Size budget for project instruction files such as AGENTS.md
shell_environment_policy.inheritall, core, noneBaseline environment inherited by spawned commands
shell_environment_policy.ignore_default_excludesDefault trueSkip automatic filtering of names containing KEY, SECRET, or TOKEN; set false to enable it
log_dirAbsolute pathChange the log directory; setting it explicitly also enables codex-tui.log there
file_openerDefault vscode; also cursor, windsurf, vscode-insiders, noneMake file citations clickable

A complete minimal config

Here is a user-level config that combines the keys above. The keys and structure come from official examples or the official reference; the MCP command and args are placeholders, so substitute your own server command. The notify line is commented out until you have a script path.

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_provider = "openai"
model_reasoning_effort = "medium"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

[history]
persistence = "save-all"
max_bytes = 104857600

[mcp_servers.local_tools]
command = "/usr/local/bin/my-mcp-server"
args = ["--stdio"]

# notify = ["python3", "/Users/YOU/.codex/notify.py"]

Common mistakes

The config is not taking effect. Check the layer first. A project's .codex/config.toml loads only when you trust the project; otherwise the whole project layer is skipped and you are seeing the user-level values.

A key is in the wrong file. model_provider, model_providers, notify, profiles, and openai_base_url cannot be overridden in project config. Codex ignores them and prints a warning. Move them to the user-level file.

Profiles use the old syntax. Since 0.134.0, [profiles.x] and the top-level profile key no longer work. Look for both in config.toml and move the settings into a separate profile file.

An old approval_policy = "untrusted" is still present. The value is unsupported and can prevent the client from starting. Remove it and use on-request for interactive work.

A -c override is missing quotes. --config values are parsed as TOML; strings need quotes, and nested quoting depends on your shell. Official examples:

codex --config model='"gpt-6.1-sol"'
codex --config sandbox_workspace_write.network_access=true

sandbox_mode and default_permissions are both set. These are two different permission models. The reference says not to combine them; pick one.

Commands cannot reach the network in the workspace. workspace-write has no network by default. Set network_access = true explicitly.

After changing the config, type /status in a session to see the active model, approval policy, writable roots, and remaining context. The official description is "Display session configuration and token usage." To try a value once without editing the file, use a -c override.

Sources