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

> Learn how the OpenAI Codex plugin manages model selection and reasoning effort via a three-stage pipeline including CLI parsing, normalization, and execution. Understand the configuration options.

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

---

**The OpenAI Codex plugin handles model selection and reasoning effort through a three-stage pipeline: CLI parsing in `codex-companion.mjs`, normalization via `normalizeRequestedModel` and `normalizeReasoningEffort`, and execution through `executeTaskRun` with fallback to defaults defined in [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json).**

The `codex-plugin-cc` repository provides a flexible interface for controlling which LLM powers your coding tasks and how much computational depth it applies. Understanding this parameter flow helps you optimize for speed, cost, or reasoning quality depending on your use case.

## Command-Line Interface for Model and Effort Selection

All Codex task commands accept `--model` (or `-m`) and `--effort` flags. These are registered in the argument parser within `codex-companion.mjs`:

```javascript
// plugins/codex/scripts/codex-companion.mjs
const { options } = parseCommandInput(argv, {
  valueOptions: ["model", "effort", "cwd", "prompt-file"],
  aliasMap: { m: "model" }
});

```

The `valueOptions` array declares which flags accept string values, while `aliasMap` enables the shorthand `-m` syntax.

## Normalizing Model Selection

The `normalizeRequestedModel` function processes raw user input into a canonical model identifier:

```javascript
// plugins/codex/scripts/codex-companion.mjs
function normalizeRequestedModel(model) {
  if (model == null) return null;
  const normalized = String(model).trim();
  if (!normalized) return null;
  return MODEL_ALIASES.get(normalized.toLowerCase()) ?? normalized;
}

```

This function:

- Returns `null` for empty or missing input, triggering fallback behavior
- Trims whitespace to handle sloppy CLI input
- Resolves aliases through the `MODEL_ALIASES` Map before falling back to the raw string
- Performs case-insensitive matching for user convenience

When `normalizeRequestedModel` returns `null`, the plugin defaults to `openrouter/openai/gpt-oss-120b` as specified in [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json).

## Validating Reasoning Effort Parameters

Reasoning effort controls how much computation the model expends on a task. The `normalizeReasoningEffort` function enforces strict validation:

```javascript
// plugins/codex/scripts/codex-companion.mjs
function normalizeReasoningEffort(effort) {
  if (effort == null) return null;
  const normalized = String(effort).trim().toLowerCase();
  if (!normalized) return null;
  if (!VALID_REASONING_EFFORTS.has(normalized)) {
    throw new Error(
      `Unsupported reasoning effort "${effort}". Use one of: none, minimal, low, medium, high, xhigh.`
    );
  }
  return normalized;
}

```

The `VALID_REASONING_EFFORTS` set accepts six discrete levels:

- **none** – Fastest response, minimal computation
- **minimal** – Slight reasoning overhead
- **low** – Reduced depth for straightforward tasks
- **medium** – Default balancing point (used when effort is unspecified)
- **high** – Extended analysis for complex problems
- **xhigh** – Maximum reasoning depth

Invalid values trigger immediate errors with explicit guidance, preventing silent failures.

## Building and Executing the Task Request

After normalization, parameters flow into `buildTaskRequest` and `executeTaskRun`:

```javascript
// plugins/codex/scripts/codex-companion.mjs (excerpt)
const model = normalizeRequestedModel(options.model);
const effort = normalizeReasoningEffort(options.effort);
…
const request = buildTaskRequest({ cwd, model, effort, prompt, … });

```

The `executeTaskRun` function in `lib/process.mjs` receives this request object and:

1. Selects the appropriate provider configuration from [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json)
2. Forwards the `model` and `effort` parameters to the LLM endpoint
3. Applies the default model when `model` is `null`

## Practical Command Examples

```bash

# Default model with default effort (medium)

codex task "Write a function that sums an array"

# Explicit model alias with high reasoning

codex task -m gpt-4 --effort high "Explain how binary search works"

# Maximum speed with no reasoning overhead

codex task -m claude-2 --effort none "Generate a JSON schema for a user profile"

```

## Key Configuration Files and Functions

| Component | Location | Purpose |
|-----------|----------|---------|
| Default model definition | [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json) | Declares `openrouter/openai/gpt-oss-120b` as fallback |
| CLI parsing and normalization | `plugins/codex/scripts/codex-companion.mjs` | Implements `normalizeRequestedModel` and `normalizeReasoningEffort` |
| Request dispatch | `plugins/codex/scripts/lib/process.mjs` | `executeTaskRun` routes parameters to providers |

## Summary

- **Model selection** supports aliases through `MODEL_ALIASES` with graceful fallback to [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json) defaults
- **Reasoning effort** enforces six strict levels from `none` to `xhigh` via `VALID_REASONING_EFFORTS`
- **Normalization** happens in dedicated functions that trim, validate, and canonicalize user input
- **Execution** passes clean parameters to the provider layer with full default handling

## Frequently Asked Questions

### What happens if I don't specify a model?

The `normalizeRequestedModel` function returns `null`, and `executeTaskRun` substitutes the default defined in [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/opencode.json) (`openrouter/openai/gpt-oss-120b`).

### What is the default reasoning effort?

Medium. When `--effort` is omitted, `normalizeReasoningEffort` returns `null`, and the runtime applies its internal default of `medium` unless overridden by provider configuration.

### Why does invalid effort throw an error instead of defaulting?

Strict validation prevents silent degradation of task quality. The error message explicitly lists all six valid options so users can correct immediately rather than discovering unexpected behavior later.

### Can I use custom model names not in the alias map?

Yes. The `?? normalized` fallback in `normalizeRequestedModel` passes through any unrecognized string directly, enabling provider-specific identifiers that haven't been aliased yet.