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

> Learn to configure OpenAI Codex models and reasoning effort using runtime selection, command-line flags, or config files. Optimize your plugin performance today.

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

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) files at the user (`~/.codex/config.toml`) or project level ([`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) – overrides the user file for that specific repository (only loaded when the project is trusted)

Example configuration from the README:

```toml
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:

```bash
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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at your project root:

```bash
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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md) support explicit flag overrides that bypass configuration files:

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

```

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

```bash
/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:

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

```

## Summary

- Configure Codex models and reasoning effort through [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) in two locations: first at `~/.codex/config.toml` for user-level defaults, then at [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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.