# OpenAI Codex Plugin Model Aliases and Reasoning Effort Levels: Complete Configuration Guide

> Explore OpenAI Codex plugin model aliases and reasoning effort levels. Configure gpt-5.4, gpt-5.4-mini, and effort levels using project files, CLI flags, or API calls.

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

---

**The OpenAI Codex plugin supports two model aliases (`gpt-5.4` and `gpt-5.4-mini`) and six reasoning effort levels (`none`, `minimal`, `low`, `medium`, `high`, and `xhigh`), configurable via project files, CLI flags, or programmatic API calls.**

The `openai/codex-plugin-cc` repository provides a flexible interface for controlling LLM behavior through specific model aliases and reasoning intensity settings. Understanding the supported **OpenAI Codex plugin model aliases and reasoning effort levels** enables developers to balance computational cost against solution quality for automated coding tasks.

## Supported Model Aliases

The plugin recognizes two primary model aliases that map to underlying LLM capabilities. According to the configuration documentation in [`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) (lines 273-277), these aliases are referenced in project-level configuration files.

- **`gpt-5.4`** – The default model providing full reasoning capabilities
- **`gpt-5.4-mini`** – A lighter-weight variant optimized for faster responses and lower token usage

The plugin declaration in [`plugins/codex/.claude-plugin/plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/.claude-plugin/plugin.json) references additional underlying models (such as `openrouter/openai/gpt-oss-120b`), but the end-user facing aliases remain limited to `gpt-5.4` and `gpt-5.4-mini` as documented in the configuration examples.

## Reasoning Effort Levels

The plugin implements six distinct reasoning effort levels that control computational depth and chain-of-thought processing. As implemented in `plugins/codex/scripts/codex-companion.mjs` (lines 124-126), the validation logic strictly enforces these six tokens:

- **`none`** – No explicit reasoning effort applied
- **`minimal`** – Minimal computational overhead
- **`low`** – Reduced reasoning depth
- **`medium`** – Balanced reasoning (typical default when unspecified)
- **`high`** – Enhanced reasoning with deeper analysis
- **`xhigh`** – Maximum reasoning effort for complex problems

When you omit the effort parameter, the plugin leaves the value unset and defers to the underlying model's default behavior rather than injecting a specific level.

## Configuration Methods

### Project-Level Configuration via config.toml

Create a [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file in your project root to establish default settings for all plugin operations. The plugin reads this file at startup and applies the specified model and effort to subsequent LLM calls.

```toml

# .codex/config.toml – project-level configuration

model = "gpt-5.4-mini"          # model alias

model_reasoning_effort = "high" # reasoning effort level

```

### Command-Line Overrides

Override configuration file settings using CLI arguments parsed by `plugins/codex/scripts/lib/args.mjs`. The `--model` and `--effort` flags allow per-command customization that bypasses project defaults.

```bash

# Run a Codex command with explicit model and effort

codex review --model gpt-5.4-mini --effort medium

```

### Programmatic API Usage

When using the JavaScript API, pass configuration objects directly to the `runTask` function. The plugin injects these parameters into the request payload forwarded to the LLM.

```javascript
import { runTask } from '@openai/codex-plugin';

// Execute a task with specific model and effort
await runTask({
  command: 'review',
  params: {
    model: 'gpt-5.4-mini',
    effort: 'low',
  },
});

```

## Validation and Error Handling

The companion script at `plugins/codex/scripts/codex-companion.mjs` contains strict validation logic for reasoning effort inputs. If you provide an unrecognized effort token, the script throws an error listing the six allowed values (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) and terminates the request before reaching the LLM.

Model alias validation occurs during configuration parsing, ensuring that only supported aliases (`gpt-5.4` and `gpt-5.4-mini`) reach the request forwarding layer, though the underlying [`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json) architecture supports fallback to alternative model routing when necessary.

## Summary

- **Model aliases**: `gpt-5.4` (default) and `gpt-5.4-mini` provide full and lightweight inference options
- **Reasoning effort levels**: Six strictly validated options ranging from `none` to `xhigh`
- **Configuration hierarchy**: Project [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) → CLI flags → programmatic parameters
- **Validation location**: `plugins/codex/scripts/codex-companion.mjs` enforces effort level constraints
- **Default behavior**: Omitting effort leaves the parameter unset; omitting model defaults to `gpt-5.4`

## Frequently Asked Questions

### What are the default model and reasoning effort settings?

By default, the plugin uses the `gpt-5.4` model alias and leaves reasoning effort unset, allowing the underlying LLM to apply its internal defaults. You can override these via [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) or command-line flags at any time.

### Can I use model aliases not listed in the official documentation?

The plugin specifically validates against `gpt-5.4` and `gpt-5.4-mini` as the supported end-user aliases. While the underlying [`plugins/codex/.claude-plugin/plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/.claude-plugin/plugin.json) references alternative routing paths, the configuration system documented in [`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) (lines 273-277) only supports the two documented aliases for reliable operation.

### What happens if I provide an invalid reasoning effort level?

The validation logic in `plugins/codex/scripts/codex-companion.mjs` will throw an error and terminate the request, displaying the six allowed tokens (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) as valid options. The request will not reach the LLM until you provide a recognized value.

### How do I set different effort levels for different commands?

Since the plugin reads configuration at startup, you should specify effort levels per command using the `--effort` CLI flag parsed by `plugins/codex/scripts/lib/args.mjs`. Each invocation can specify a different level, overriding the project-level [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) settings for that specific execution while maintaining defaults for subsequent runs.