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

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 (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 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 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.

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

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

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 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 → 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 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 references alternative routing paths, the configuration system documented in 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 settings for that specific execution while maintaining defaults for subsequent runs.

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