# How to Specify and Use Different Codex Models (e.g., gpt-5.4-mini, spark) with the Plugin

> Learn how to specify and use different Codex models like gpt-5.4-mini and spark with the openai codex-plugin-cc. Control model selection via CLI or code for seamless integration.

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

---

**The openai/codex-plugin-cc repository supports model selection via the `--model` CLI flag or `model` option in code, with automatic alias resolution for shortcuts like `spark`.**

The openai/codex-plugin-cc plugin provides flexible model selection, allowing you to specify any Codex model identifier or use convenient aliases when running tasks. Whether you need the lightweight `gpt-5.4-mini` for quick iterations or want to leverage the `spark` variant for specialized workloads, the plugin handles model normalization and propagation automatically.

## How Model Selection Works in the Codex Plugin

The plugin implements a three-stage pipeline for model specification that ensures your requested model reaches the Codex service correctly.

### CLI Argument Parsing in codex-companion.mjs

The entry point `plugins/codex/scripts/codex-companion.mjs` captures the `--model` argument through `parseCommandInput`. This raw value undergoes normalization before being passed to the execution layer.

### Model Name Normalization

The `normalizeRequestedModel` function handles all model string processing. Located in `codex-companion.mjs`, this function:

- Trims whitespace from the input
- Checks against the `MODEL_ALIASES` map for shorthand expansions
- Returns unmapped strings unchanged for direct model identifiers

```javascript
function normalizeRequestedModel(model) {
  if (model == null) return null;
  const normalized = String(model).trim();
  if (!normalized) return null;
  return MODEL_ALIASES.get(normalized.toLowerCase()) ?? normalized;
}

```

The alias map includes `"spark" → "gpt-5.3-codex-spark"`, enabling you to use the shorter form in commands.

### Request Propagation to Codex Service

After normalization, the model string attaches to `options.model` and forwards through `plugins/codex/scripts/lib/codex.mjs` to the underlying Codex client. This ensures the specified model parameter reaches the service API without modification.

## Supported Model Specification Methods

You can specify models in three ways when using the Codex plugin:

- **Direct model identifier** — Pass full names like `gpt-5.4-mini` or `gpt-5.4-large` for explicit control
- **Alias shorthand** — Use `spark` to automatically expand to `gpt-5.3-codex-spark`
- **Default behavior** — Omit `--model` entirely to let Codex apply its internal heuristics

## CLI Examples for Model Selection

Use the `--model` flag with the `task` command to select your preferred Codex model:

```bash

# Specify the full model name directly

node plugins/codex/scripts/codex-companion.mjs task \
     --model gpt-5.4-mini --effort medium "Refactor the login flow"

# Use the spark alias for the gpt-5.3-codex-spark variant

node plugins/codex/scripts/codex-companion.mjs task \
     --model spark --effort low "Diagnose the failing test"

```

## Programmatic Model Configuration

When importing the library directly, pass the `model` option to `runTask`:

```javascript
import { runTask } from "./plugins/codex/scripts/lib/codex.mjs";

// Explicit full model name
await runTask({
  cwd: process.cwd(),
  model: "gpt-5.4-mini",
  effort: "medium",
  prompt: "Generate a summary of the changelog."
});

// Alias resolution happens automatically
await runTask({
  cwd: process.cwd(),
  model: "spark",
  effort: "low",
  prompt: "Diagnose the failing test."
});

```

The library handles alias expansion internally, so both approaches produce identical behavior to the CLI.

## Test Verification of Alias Resolution

The mapping functionality is verified in `tests/runtime.test.mjs`. The test suite invokes the CLI with `--model spark` and asserts that the internal state records the expanded identifier:

```javascript
// Test invocation from runtime.test.mjs line 776
run("node", [SCRIPT, "task", "--model", "spark", /* ... */])

// Assertion from runtime.test.mjs line 783
assert.equal(fakeState.lastTurnStart.model, "gpt-5.3-codex-spark")

```

This confirms that alias resolution occurs before model values reach the Codex service.

## Key Source Files

| File | Purpose |
|------|---------|
| `plugins/codex/scripts/codex-companion.mjs` | Contains `normalizeRequestedModel` and CLI parsing logic |
| `plugins/codex/scripts/lib/codex.mjs` | Forwards normalized `model` option to Codex service |
| `tests/runtime.test.mjs` | Validates `spark` alias expansion to `gpt-5.3-codex-spark` |

## Summary

- The `--model` CLI flag and `model` option enable runtime model selection in openai/codex-plugin-cc
- **Direct identifiers** like `gpt-5.4-mini` pass through unchanged
- **Alias `spark`** automatically expands to `gpt-5.3-codex-spark` via `MODEL_ALIASES`
- The `normalizeRequestedModel` function in `codex-companion.mjs` handles all string processing
- Omitting `--model` delegates selection to Codex default heuristics

## Frequently Asked Questions

### What happens if I specify an invalid model name?

The plugin passes unmapped strings directly to the Codex service without validation. The service returns an error if the identifier is unrecognized. Always verify model availability against current Codex documentation.

### Can I add custom model aliases?

The `MODEL_ALIASES` map is defined internally in `codex-companion.mjs`. To add custom aliases, you would need to modify the source code and rebuild the plugin. There is no runtime configuration for alias extensions.

### Does model selection affect pricing or token limits?

Different Codex models have varying capabilities, context windows, and pricing structures. The plugin itself does not enforce limits—it merely forwards your selection. Consult OpenAI's Codex documentation for model-specific constraints and costs.

### Is gpt-5.4-mini the same as the spark model?

No. `gpt-5.4-mini` is a distinct model identifier passed directly, while `spark` is an alias that resolves to `gpt-5.3-codex-spark`. These represent different model variants with separate characteristics.