How to change reasoning effort in Codex CLI: model_reasoning_effort values and one-off overrides

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 reference names low, medium, high, xhigh, max and ultra.

The values you can set

The configuration reference describes model_reasoning_effort as a string: the "reasoning effort advertised by the selected model, such as low, medium, high, xhigh, max, or ultra". It adds that available levels depend on the model and client, so not every model offers all six. The reference states no default, so none is given here.

Value	Suited to
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
max	when you want more deliberation still, on models that offer it
ultra	the deepest level the reference names

Higher effort means slower responses and more tokens. Keeping everyday work around medium and raising it only for hard tasks is the easiest routine.

minimal, which earlier versions of the reference listed, does not appear in the September 2026 configuration reference. If you find minimal in an old config file or article, use low instead.

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-review

Keep 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.

Depth is not the same thing as display. If what you want is to show Codex's reasoning rather than change how hard it thinks, that is model_reasoning_summary (auto / concise / detailed / none) and show_raw_agent_reasoning, covered in hide_agent_reasoning and showing reasoning.

Summary

• Reasoning depth is model_reasoning_effort; the reference names low, medium, high, xhigh, max, ultra, and availability depends on the model and client
• Permanent: ~/.codex/config.toml; one run: -c model_reasoning_effort='"high"'; mid-session: /model
• For fixed use cases, create a <name>.config.toml profile and select it with --profile
• Plan mode has plan_mode_reasoning_effort; subagents have agents.default_subagent_reasoning_effort
• Higher effort is slower and costlier; keep everyday work moderate
• To show reasoning rather than deepen it, use model_reasoning_summary and show_raw_agent_reasoning