How to Configure the Codex Model and Reasoning Effort for the Codex Plugin

You can configure the Codex model and reasoning effort for the openai/codex-plugin-cc either via project-level .codex/config.toml files or by passing --model and --effort flags to individual commands.

The Codex plugin for VS Code allows precise control over which underlying model processes your requests and how much computational reasoning is applied to each task. According to the openai/codex-plugin-cc source code, these settings can be defined as defaults for an entire repository or overridden per invocation using runtime flags.

Project-Level Configuration via .codex/config.toml

The plugin supports hierarchical configuration through TOML files, allowing you to set default values that apply to every command run within a project.

Create or edit a .codex/config.toml file at the root of your repository:

model = "gpt-5.4-mini"          # Default model for all plugin commands

model_reasoning_effort = "high" # Default reasoning effort level

Valid values for model_reasoning_effort include: none, minimal, low, medium, high, and xhigh.

Configuration Precedence

The plugin loads settings in the following order, with later sources overriding earlier ones:

1. User-level config: ~/.codex/config.toml (applies globally to all projects)
2. Project-level config: .codex/config.toml (applies only when the project is marked as trusted)

If a project is not trusted, the project-level configuration is ignored and the plugin falls back to user-level defaults or built-in values.

Command-Line Overrides

For one-off changes, all task-type commands—including /codex:review, /codex:rescue, and /codex:task—accept two runtime flags that override any configuration file settings:

• --model <model|spark>: Selects a specific Codex model. The special value spark is automatically mapped to gpt-5.3-codex-spark.
• --effort <level>: Controls reasoning intensity using the same scale as the config file (none through xhigh).

These flags are parsed and validated in codex-companion.mjs within the normalizeReasoningEffort function, which ensures only allowed values are passed to the underlying API.

How Settings Propagate to the Codex API

When you execute a command, the plugin forwards your selected model and effort level to the Codex app-server via the turn/start API call. The implementation in plugins/codex/scripts/lib/codex.mjs explicitly handles this propagation:

• Model handling (line 66): model: options.model ?? null
• Reasoning effort handling (line 1140): effort: options.effort ?? null

If you omit these flags and do not set them in your configuration files, the plugin leaves these fields as null, allowing the Codex server to apply its own defaults.

Practical Usage Examples

The following examples demonstrate how to combine configuration files with command-line overrides:

# Use project defaults (model=gpt-5.4-mini, effort=high)

/codex:review --background

# Override the model for a single review

/codex:review --model spark --background

# Adjust reasoning effort without changing the model

/codex:review --effort low --background

# Override both model and effort simultaneously

/codex:task --model gpt-5.4-mini --effort medium "Refactor authentication logic"

The --model and --effort flags work identically across all task commands, as documented in plugins/codex/commands/rescue.md, which lists these options for the rescue workflow.

Summary

• Set defaults in .codex/config.toml using the model and model_reasoning_effort keys for consistent behavior across a project.
• Override per command with --model (accepts model names or the spark alias) and --effort (accepts none through xhigh).
• Validation occurs in codex-companion.mjs, while API transmission happens in codex.mjs at lines 66 and 1140 via the turn/start endpoint.
• Configuration precedence follows: user config → project config (if trusted) → command-line flags.

Frequently Asked Questions

What happens if I specify an invalid reasoning effort level?

The plugin validates effort levels in normalizeReasoningEffort within codex-companion.mjs. If you provide an invalid value, the command will fail with a validation error before any API call is made, preventing silent failures.

Can I use different models for different commands in the same project?

Yes. While the .codex/config.toml sets defaults, you can override the model for any individual command using the --model flag. This allows you to use lighter models for quick reviews and more powerful models for complex refactoring tasks without changing your configuration file.

What is the spark alias and how does it work?

The spark value is a convenience alias mapped to gpt-5.3-codex-spark. When you pass --model spark, the plugin expands this to the full model identifier before sending it to the Codex app-server via the turn/start API call.

Do I need to restart VS Code after editing .codex/config.toml?

No. The plugin reads the configuration file at the start of each command execution, so changes take effect immediately on the next run. However, ensure your project is marked as trusted, otherwise the plugin will ignore the project-level configuration and fall back to user-level defaults.

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