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

You can configure custom models and reasoning effort in the Codex plugin by setting defaults in a .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 file at the root of your repository to establish default settings for all plugin commands in that project.

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) – 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.

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:

# 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:

# Maps to gpt-5.3-codex-spark

/codex:review --model spark --background

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

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

Combine both flags for maximum control over complex architectural decisions:

/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 (line 45), which explicitly lists these flags for the rescue command.

Summary

• Configure custom models and reasoning effort in .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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}