# How to Configure Custom Models and Reasoning Effort in the Codex Plugin

> Master the Codex plugin by configuring custom models and reasoning effort. Learn to set defaults in config file or use command flags for fine-tuned control. Boost your coding workflow.

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

---

**You can configure custom models and reasoning effort in the Codex plugin by setting defaults in a [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file or by passing `--model` and `--effort` flags to override settings per-command.**

The **openai/codex-plugin-cc** repository provides a flexible configuration system that lets you control which Codex model executes your tasks and how much computational reasoning effort to allocate. Whether you need lightweight quick suggestions or deep analytical code reviews, you can configure custom models and reasoning effort at both the project level and runtime.

## Project-Level Configuration via config.toml

Create a **[`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml)** file at the root of your repository to establish default settings for all plugin commands in that project.

```toml
model = "gpt-5.4-mini"          # the default model for all plugin commands

model_reasoning_effort = "high" # default reasoning effort (none, minimal, low, medium, high, xhigh)

```

The plugin reads these values and passes them to the Codex app-server during the `turn/start` API call.

### Configuration Precedence

The plugin resolves configuration in the following order:

1. **User-level config** (`~/.codex/config.toml`) 
2. **Project-level config** ([`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml)) – loaded only when the project is **trusted**

If you omit settings in the project-level file, the plugin falls back to user-level defaults, then to Codex's internal defaults.

## Command-Line Overrides

All task-type commands—including `/codex:review`, `/codex:rescue`, `/codex:rescue`, and `/codex:task`—accept runtime flags that override configuration file settings for a single invocation.

### Runtime Flags

| Flag | Values | Description |
|------|--------|-------------|
| `--model` | Model ID or `spark` | Selects a specific Codex model. The special value `spark` maps to `gpt-5.3-codex-spark`. |
| `--effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | Controls how much "thinking time" Codex spends on the task. |

If you omit these flags, the plugin leaves the fields unset in the API request, allowing Codex to use its own defaults or the values from your [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml).

### Validation and Implementation Details

According to the source code in **openai/codex-plugin-cc**, flag validation occurs in **`plugins/codex/scripts/codex-companion.mjs`** within the `normalizeReasoningEffort` function (line 114), which ensures only valid effort levels are accepted.

When executing a command, the plugin forwards your selections to the Codex backend via **`plugins/codex/scripts/lib/codex.mjs`**:
- **Model propagation** occurs at line 66: `model: options.model ?? null`
- **Reasoning effort propagation** occurs at line 1140: `effort: options.effort ?? null`

These values are transmitted to the Codex app-server as part of the `turn/start` API payload.

## Practical Examples

Use the project-level defaults to run a standard code review:

```bash

# Uses model=gpt-5.4-mini and effort=high from .codex/config.toml

/codex:review --background

```

Override the model for a quick syntax check using the lightweight `spark` model:

```bash

# Maps to gpt-5.3-codex-spark

/codex:review --model spark --background

```

Reduce reasoning effort for a simple task to save tokens and latency:

```bash
/codex:task "Refactor this utility function" --effort low

```

Combine both flags for maximum control over complex architectural decisions:

```bash
/codex:rescue --model gpt-5.4-mini --effort xhigh

```

The same pattern applies across all task commands, as documented in **[`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md)** (line 45), which explicitly lists these flags for the rescue command.

## Summary

- **Configure custom models and reasoning effort** in [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) using the `model` and `model_reasoning_effort` keys.
- **Override per-command** with `--model` (accepts specific model IDs or the `spark` alias) and `--effort` (accepts six levels from `none` to `xhigh`).
- **Trust matters**: Project-level configs only load when the repository is marked as trusted.
- **Source locations**: Validation happens in `codex-companion.mjs` (line 114), while API transmission occurs in `codex.mjs` (lines 66 and 1140).

## Frequently Asked Questions

### What models can I specify with the `--model` flag?

You can specify any valid Codex model identifier, such as `gpt-5.4-mini`, or use the special alias `spark` which the plugin automatically maps to `gpt-5.3-codex-spark`. The Codex plugin validates the model string before transmitting it to the app-server via the `turn/start` API call.

### What is the difference between reasoning effort levels?

The reasoning effort parameter controls how much computational "thinking time" Codex allocates to a task. Options range from `none` (instant responses) through `minimal`, `low`, `medium`, and `high`, up to `xhigh` (maximum depth). Higher effort levels typically produce more thorough analysis but consume more tokens and increase latency.

### Why are my config.toml settings not applying?

The plugin only loads [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) when the project is **trusted**. Additionally, command-line flags (`--model`, `--effort`) always take precedence over file-based configuration. Check that you have not inadvertently overridden your settings at runtime, and verify the file is located at the repository root.

### Can I set different defaults for different types of tasks?

Currently, the [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) applies globally to all plugin commands within that repository. To use different settings for specific task types, use the `--model` and `--effort` command-line flags when invoking `/codex:review`, `/codex:rescue`, or `/codex:task` to override the defaults for that specific invocation.