# How to Configure Model Reasoning Effort (low/medium/high) in `.codex/config.toml`

> Control Codex model reasoning effort low medium or high by editing your .codex/config.toml file Set the default effort for all model requests easily

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-08-04

---

**Add `model_reasoning_effort = "high"` (or `"low"`, `"medium"`, etc.) to your [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file to set the default reasoning effort for all Codex model requests.**

The OpenAI Codex plugin supports persistent configuration of reasoning effort through a TOML configuration file. This setting controls how much computational depth the model applies to each turn, with valid options ranging from `none` to `xhigh`. The configuration is read at startup and validated before every model call.

## Where to Place the Configuration File

The plugin searches for [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in two locations:

- **Project-level**: At the root of the directory where you started the Codex session
- **User-level**: In your home directory (`~/.codex/config.toml`)

Project-level settings override user-level settings when both exist.

## Valid Values for `model_reasoning_effort`

The `codex-companion.mjs` script enforces a strict set of allowed values. According to the source at `plugins/codex/scripts/codex-companion.mjs` (line 124), the valid options are:

| Value | Description |
|-------|-------------|
| `none` | No additional reasoning |
| `minimal` | Minimal reasoning overhead |
| `low` | Reduced reasoning for faster responses |
| `medium` | Balanced reasoning (default when omitted) |
| `high` | Deeper reasoning for complex tasks |
| `xhigh` | Maximum reasoning depth |

An invalid value triggers this error:

```text
Unsupported reasoning effort "...". Use one of: none, minimal, low, medium, high, xhigh.

```

## Configuration Examples

### Basic High-Effort Setup

Create [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at your project root:

```toml

# .codex/config.toml

model_reasoning_effort = "high"

```

### Combining with Model Selection

Specify both the model and reasoning effort:

```toml

# .codex/config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

```

With this configuration, every turn uses `gpt-5.4-mini` with **high** reasoning effort unless explicitly overridden.

### Command-Line Override

Use the `--effort` flag to temporarily bypass the config file:

```bash
codex review --effort low

```

This single invocation uses `low` effort regardless of the [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) setting.

## How the Configuration Flow Works

The architectural implementation in `openai/codex-plugin-cc` follows this sequence:

1. **Load** [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) via the Codex core configuration loader
2. **Extract** `model_reasoning_effort` if the key exists
3. **Pass** the value to the turn-initialization logic in `codex-companion.mjs`
4. **Validate** against the allowed enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`)
5. **Apply** the validated effort to all subsequent model calls

The `plugins/codex/scripts/lib/codex.mjs` module manages turn state, including the reasoning-effort metadata that flows into each request. If `model_reasoning_effort` is absent from config, the plugin falls back to `"medium"` as the built-in default.

## Key Source Files

Understanding these files helps with debugging configuration issues:

- **`plugins/codex/scripts/codex-companion.mjs`** — Validates and applies `model_reasoning_effort`; contains the error message for invalid values
- **`plugins/codex/scripts/lib/codex.mjs`** — Handles turn state and reasoning-effort metadata propagation
- **[`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md)** (lines 273-277) — Documents the user-level configuration format with examples
- **`plugins/codex/commands/*.md`** — CLI documentation showing optional `--effort` flag usage

## Summary

- **Set** `model_reasoning_effort` in [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) for persistent default behavior
- **Choose** from six validated levels: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
- **Override** per-command with `--effort` flag
- **Locate** config at project root ([`./.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/./.codex/config.toml)) or user home (`~/.codex/config.toml`)
- **Expect** `"medium"` fallback when the key is omitted

## Frequently Asked Questions

### What happens if I specify an invalid reasoning effort value?

The `codex-companion.mjs` validator throws an error immediately on startup or turn initialization, listing all six supported values. The session will not proceed until you correct the configuration file.

### Can I set different reasoning efforts for different models?

Not directly in the config file. The `model_reasoning_effort` key applies globally to all model calls. To vary effort by model, use command-line `--effort` flags or script multiple Codex sessions with separate config directories.

### Does the command-line `--effort` flag always override the config file?

Yes. According to the CLI implementation documented in `plugins/codex/commands/*.md`, explicit `--effort` values take precedence over [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) settings for that single invocation only.

### Where does the plugin look for config.toml first—project or user level?

The plugin checks the project-level [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) first (relative to the working directory where Codex was started), then falls back to `~/.codex/config.toml` if not found. Project settings override user settings when both exist.