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

You can configure Codex models and reasoning effort through three methods: default runtime selection, command-line overrides with --model and --effort flags, or persistent config.toml files at the user (~/.codex/config.toml) or project level (.codex/config.toml).

The openai/codex-plugin-cc repository provides multiple mechanisms to control which Codex model executes your tasks and how much reasoning effort it applies. Whether you need to set permanent defaults for all projects or override settings for a single rescue operation, understanding these configuration options ensures optimal performance and cost management.

Understanding the Configuration Hierarchy

The plugin determines which model and reasoning effort to use through a cascading priority system.

Default Runtime Behavior

When you don't specify a model or effort flag, the plugin allows Codex to select its own defaults. As documented in the README.md, this "default-reasoning-effort" behavior handles routine tasks without requiring explicit configuration, letting the system optimize for the specific task type.

Command-Line Overrides

Rescue-related commands such as /codex:rescue and /codex:transfer accept --model and --effort flags that take precedence over defaults. According to plugins/codex/skills/codex-cli-runtime/SKILL.md, the codex-cli-runtime skill normalizes these flags and forwards them to the underlying codex task call while stripping them from the natural-language prompt text.

The --model flag accepts either specific model names or the special value spark, which maps to gpt-5.3-codex-spark. Any other model name (e.g., gpt-5.4-mini) passes through unchanged.

The --effort flag accepts these values: none, minimal, low, medium, high, or xhigh.

Persistent Configuration Files

For permanent settings, create a config.toml file. The plugin checks two locations, with the project-level file taking precedence over the user-level file:

• User-level: ~/.codex/config.toml – applies to every project you run Claude Code in
• Project-level: .codex/config.toml – overrides the user file for that specific repository (only loaded when the project is trusted)

Example configuration from the README:

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

When this file exists, the plugin automatically supplies --model gpt-5.4-mini and --effort high to all rescue-type commands unless you explicitly override them on the command line.

Setting Up Configuration Files

User-Level Defaults

Create a file at ~/.codex/config.toml to apply settings across every Claude Code project:

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
EOF

Project-Level Overrides

For repository-specific settings, create .codex/config.toml at your project root:

cat > .codex/config.toml <<'EOF'
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
EOF

This overrides the user-level configuration for that specific repository only.

Using Command-Line Flags

Rescue Commands and Flag Syntax

Rescue commands documented in plugins/codex/commands/rescue.md support explicit flag overrides that bypass configuration files:

/codex:rescue --model spark --effort medium investigate the flaky test

When you run a rescue command without flags, the plugin respects your configuration files:

/codex:rescue investigate why the build is failing

# The plugin internally invokes:

#   codex task --model gpt-5.4-mini --effort high "investigate why the build is failing"

Model Mapping and Special Values

When you specify spark as the model, the codex-cli-runtime skill maps it to gpt-5.3-codex-spark before executing the task. All other model identifiers pass through verbatim to the underlying Codex API.

Example overriding config for a single command:

/codex:rescue --model gpt-5.4-mini --effort low fix the failing test

Summary

• Configure Codex models and reasoning effort through config.toml files, command-line flags, or default runtime selection.
• User-level configuration lives at ~/.codex/config.toml while project-level settings reside in .codex/config.toml.
• Command-line flags --model and --effort override file-based configuration for rescue commands like /codex:rescue.
• The special spark model value maps to gpt-5.3-codex-spark while other model names pass through unchanged.
• Effort levels range from none to xhigh and control the reasoning depth applied to tasks.

Frequently Asked Questions

Where does the openai/codex-plugin-cc look for configuration files?

The plugin searches for config.toml in two locations: first at ~/.codex/config.toml for user-level defaults, then at .codex/config.toml for project-specific settings. Project-level configuration takes precedence but only loads when the project is trusted, providing a secure way to tailor settings per repository.

What is the difference between the spark model and other model names?

When you specify --model spark, the codex-cli-runtime skill automatically maps this value to gpt-5.3-codex-spark according to the skill implementation. Any other model name you provide (such as gpt-5.4-mini) passes through to the underlying codex task command without modification, allowing you to specify exact model versions.

Can I override configuration file settings for a single command?

Yes. Command-line flags always take precedence over config.toml settings. For example, if your project config specifies high effort but you need low effort for a specific task, use /codex:rescue --effort low <task description> to override the configuration for that invocation only. This flexibility allows you to maintain sensible defaults while adapting to specific task requirements.

What are the valid reasoning effort levels?

The --effort flag accepts six values: none, minimal, low, medium, high, and xhigh. These values are passed verbatim to the underlying codex task command as implemented in the codex-cli-runtime skill, controlling the depth of reasoning the model applies to your request.

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