AI Coding Guide

Switching models, reasoning effort and profiles in Codex CLI's config.toml

Codex Published:

The settings you actually touch in ~/.codex/config.toml: model and reasoning effort, task-specific profiles with --profile, and how options, profiles and defaults take precedence.

Verified on Sep 7, 2026 These tools change quickly. Please also check the latest official documentation.
#Codex#Codex CLI#config.toml#configuration#profiles
Contents
  1. Location and structure
  2. Model and reasoning effort
  3. Profiles for different tasks
  4. Setting a default profile
  5. Precedence
  6. Other useful keys
  7. MCP servers
  8. Checking what is active
  9. Summary

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.

KEY POINT

What you will learn

  • Setting model and model_reasoning_effort, and how to choose
  • Defining profiles for different tasks and switching with --profile
  • How options, profiles and top-level values take precedence

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.

用語解説

TOML: A config format of key = value lines. Strings are double-quoted, booleans are true / false, and sections are written as [name].

Model and reasoning effort

KeyExampleMeaning
model"gpt-5-codex" etc.The model to use. Check available names with /model
model_reasoning_effort"low" / "medium" / "high"How much reasoning to spend. Higher is more careful but slower and costlier

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.

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.

Keep the API key out of config.toml

Provide OPENAI_API_KEY through the environment or codex login --api-key. A key written into config.toml leaks easily when the file is shared or backed up.

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

FAQ

Where is config.toml?
At ~/.codex/config.toml in your home directory. Create it if it does not exist.
Can I have different settings per project?
Define profiles and switch with --profile. Some versions also read project-level configuration under .codex/; check the official docs for your version.
Where do I find valid model names?
The /model command during a session lists the models you can select; use those names in config.toml.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles