Codex config.toml: set the model, model_reasoning_effort (low to ultra) and per-task profiles

Almost everything about how Codex CLI behaves is decided in ~/.codex/config.toml: model, reasoning effort, approval policy, sandbox, MCP servers. This article focuses on the settings you will actually touch day to day.

Location and structure

# ~/.codex/config.toml

model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

The file is TOML: top-level keys are defaults; tables such as [profiles.name] and [mcp_servers.name] hold specific settings.

Model and reasoning effort

Key	Example	Meaning
model	"gpt-5-codex" etc.	The model to use. Check available names with /model
model_reasoning_effort	"low" / "medium" / "high" / "xhigh" / "max" / "ultra"	How much reasoning to spend. Higher is more careful but slower and costlier. The reference notes that the available levels depend on the model and client

Model names change with each release. If the one in your config.toml stops working, run /model and update it.

Rules of thumb for effort:

• low: routine edits, comments, small refactors
• medium: everyday development
• high: design decisions, hard bugs, large changes

/model changes both temporarily inside a session; config.toml sets the default for the next start.

How to change effort in Codex CLI

There are three places to change reasoning effort, depending on how long you want the change to last:

You want to	Do this
Change it permanently	Set model_reasoning_effort in ~/.codex/config.toml
Change it for one run	codex -c model_reasoning_effort='"high"' "<your prompt>"
Change it mid-session	Run /model

The configuration reference describes the value as the "reasoning effort advertised by the selected model, such as low, medium, high, xhigh, max, or ultra", and adds that the available levels depend on the model and client. (minimal, listed in earlier versions of the reference, is no longer there.) Separate keys exist for plan mode (plan_mode_reasoning_effort) and spawned agents (agents.default_subagent_reasoning_effort). All of this is covered in detail in How to change reasoning effort in Codex CLI.

Profiles for different tasks

Instead of repeating options, define profiles:

model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.quick]
model_reasoning_effort = "low"
approval_policy = "on-failure"

[profiles.deep]
model_reasoning_effort = "high"
approval_policy = "on-request"

[profiles.readonly]
sandbox_mode = "read-only"
approval_policy = "on-request"

codex --profile quick "Fix the typos"
codex --profile deep "Review the authentication design"
codex --profile readonly "List every caller of this function"

Keys missing from a profile fall back to the top-level values. Choosing approval and sandbox settings is covered in Codex CLI approval modes versus sandbox modes.

Setting a default profile

profile = "quick"

makes quick the profile used when --profile is not given.

Precedence

When the same setting appears in several places:

1. Command-line options (--model, --sandbox, ...)
2. The profile selected with --profile
3. Top-level values in config.toml
4. Codex's built-in defaults

Remember "option > profile > top level > default" and unexpected values become easy to trace.

Other useful keys

# Maximum total size of AGENTS.md files loaded at start (bytes)
project_doc_max_bytes = 32768

# Notification command on supported systems
notify = ["notify-send", "Codex"]

# History persistence
[history]
persistence = "save-all"

Key names change between versions; if a setting has no effect, check the current configuration reference.

yolo mode (--yolo) does not belong in config.toml

codex --yolo is documented as an alias of --dangerously-bypass-approvals-and-sandbox. It runs commands with no approval prompts and no sandbox. The docs say to "use caution before doing so", and note that with --yolo or another full access sandbox setting, web search defaults to live results.

It is a per-invocation flag, not something to make permanent in config.toml. To approach it through settings, set approval_policy and sandbox_mode explicitly, and keep that to disposable containers or CI runners. The combinations are covered in Codex approval modes and sandbox.

MCP servers

MCP servers are also configured in config.toml under [mcp_servers.name] with command, args and env.

Checking what is active

/status shows the current model, reasoning effort, approval policy, sandbox and the AGENTS.md files that were loaded. Check it after editing config.toml.

Summary

• Settings live in ~/.codex/config.toml: defaults at the top level, task-specific ones in [profiles.name]
• Use names from /model for model, and pick model_reasoning_effort per task
• Switch with codex --profile name, or set profile = "name" as default
• Precedence: command-line option > profile > top level > default

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Production config files cannot be modified"
  }
}