How to change reasoning effort in Codex CLI: model_reasoning_effort values and one-off overrides
The five values of model_reasoning_effort in Codex CLI (minimal to xhigh), and how to change effort in config.toml, with the -c flag, with /model, or per profile, plus plan mode.
Contents
Codex feels slow, or it overthinks a trivial fix. The knob for that is reasoning effort, the Codex counterpart of extended thinking in Claude Code, controlled by the model_reasoning_effort key.
In short: set model_reasoning_effort = "high" (or another value) in ~/.codex/config.toml to change it permanently, use the -c flag for a single run, or /model during a session. The five levels are minimal, low, medium, high, and xhigh.
KEY POINT
What you will learn
- The five values and when each fits
- Four ways to change effort: permanently, for one run, mid-session, and per profile
- The keys that change effort only for plan mode or subagents
The five values
The configuration reference defines model_reasoning_effort as a string with the values minimal | low | medium | high | xhigh. The reference does not state a default, and it may depend on the model, so none is given here.
| Value | Suited to |
|---|---|
minimal | one-line questions, formatting fixes, anything with little to reason about |
low | small bug fixes, simple refactors |
medium | everyday feature work and investigation |
high | multi-file design changes, bugs with no obvious cause |
xhigh | hard algorithms, reviews of large changes where mistakes are costly |
Higher effort means slower responses and more tokens. Keeping everyday work around medium and raising it only for hard tasks is the easiest routine.
用語解説
Reasoning effort: how much the model reasons internally before answering. It is separate from how much of the reasoning summary is displayed; hiding the display is covered in Hiding reasoning in Codex output.
Permanently: config.toml
One line in ~/.codex/config.toml:
model = "gpt-5.5"
model_reasoning_effort = "high"In a trusted project you can put it in the repository's .codex/config.toml to affect only that project; project settings outrank user settings.
For one run: the -c flag
To change effort for a single invocation without touching the file, use -c (--config). Values are parsed as TOML, so wrap the string in double quotes and wrap the whole thing in single quotes to keep the shell from eating them.
codex -c model_reasoning_effort='"high"' "Find out why this test fails and fix it"The same form works with codex exec from scripts. According to the docs, a value that cannot be parsed as TOML is treated as a string, so a missing pair of quotes often still works, but quoting makes the intent explicit.
Mid-session: /model
Run /model in a session to switch. The official command list describes it as choosing the active model "and reasoning effort, when available". Raise it before a hard investigation and drop it afterwards.
Per use case: profiles
Rather than typing the override every time you review code, bundle the settings in a profile. Profiles live in $CODEX_HOME (default ~/.codex) as <name>.config.toml and are selected with --profile <name>.
# ~/.codex/deep-review.config.toml
model_reasoning_effort = "xhigh"
approval_policy = "on-request"codex --profile deep-reviewKeep only the differences in the profile and shared settings in the base config.toml. Profiles as a whole are covered in the hub article Configuring Codex with config.toml.
Situation-specific keys
The configuration reference also lists keys that apply only in specific situations.
| Key | Applies to |
|---|---|
plan_mode_reasoning_effort | overrides effort in plan mode only |
agents.default_subagent_reasoning_effort | default effort for spawned subagents |
If you want deep planning but ordinary implementation, add plan_mode_reasoning_effort = "high" and leave model_reasoning_effort alone.
If nothing changes, check the model
A value outside what the model supports may not take effect. If /model shows no reasoning effort choices for the current model, that model does not expose effort. When speed and quality do not change after editing the setting, confirm the model first.
Summary
- Reasoning depth is
model_reasoning_effort, with valuesminimal,low,medium,high,xhigh - Permanent:
~/.codex/config.toml; one run:-c model_reasoning_effort='"high"'; mid-session:/model - For fixed use cases, create a
<name>.config.tomlprofile and select it with--profile - Plan mode has
plan_mode_reasoning_effort; subagents haveagents.default_subagent_reasoning_effort - Higher effort is slower and costlier; keep everyday work moderate
FAQ
- How do I change effort in Codex?
- Permanently, set model_reasoning_effort in ~/.codex/config.toml. For one run, pass codex -c model_reasoning_effort='"high"'. During a session, use the /model command.
- What values does model_reasoning_effort accept?
- minimal, low, medium, high, and xhigh.
- Can I change effort only for plan mode or subagents?
- Yes. There are separate keys: plan_mode_reasoning_effort and agents.default_subagent_reasoning_effort.
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.