Valid Model Aliases and Reasoning Effort Options in the OpenAI Codex Plugin

The Codex plugin accepts one model alias (spark) and six reasoning effort levels (none, minimal, low, medium, high, xhigh), validated in codex-companion.mjs.

When running the OpenAI Codex plugin, you can override the default language model and its reasoning intensity using runtime flags. This article maps exactly which values are recognized by the source code and how the validation logic works.

Model Aliases in Codex

The Codex plugin supports a compact set of model aliases that translate short names into full model identifiers. According to the source in plugins/codex/scripts/codex-companion.mjs, the MODEL_ALIASES map contains exactly one entry:

Alias	Resolves To
spark	gpt-5.3-codex-spark

If you pass an unrecognized alias, the plugin treats it as an invalid model name and will error out rather than attempt resolution.

Reasoning Effort Options

The reasoning effort parameter controls how much computational depth the model applies to a task. The normalizeReasoningEffort function in codex-companion.mjs enforces a strict allowlist of six values:

• none — No additional reasoning
• minimal — Bare minimum cognitive overhead
• low — Light reasoning
• medium — Standard reasoning depth
• high — Extensive analysis
• xhigh — Maximum reasoning intensity

Supplying any value outside this set triggers an explicit "Unsupported reasoning effort" error. The validation logic is located around line 124 of plugins/codex/scripts/codex-companion.mjs.

Using Model Aliases and Reasoning Effort Flags

Both options are passed via the codex:rescue command-line interface. When omitted, Codex falls back to its internal defaults, which can be overridden globally through a user- or project-level config.toml.

# Use the spark alias with low reasoning effort

codex:rescue --model spark --effort low "Fix the flaky test"

# Specify a concrete model identifier with high reasoning effort

codex:rescue --model gpt-5.4-mini --effort high "Investigate performance regression"

# Rely on defaults for both model and effort

codex:rescue "Refactor the data-processing module"

Where These Options Are Defined

File Path	Purpose
plugins/codex/scripts/codex-companion.mjs	Defines MODEL_ALIASES and normalizeReasoningEffort validator
README.md	Documents runtime flags and default-selection behavior
tests/commands.test.mjs	Validates CLI documentation reflects --model <model|spark> and --effort <none|minimal|low|medium|high|xhigh>
tests/runtime.test.mjs	Confirms model and effort selections forward correctly to the app-server

Summary

• Only spark is a valid model alias, mapping to gpt-5.3-codex-spark
• Reasoning effort must be one of: none, minimal, low, medium, high, or xhigh
• Validation occurs in normalizeReasoningEffort inside plugins/codex/scripts/codex-companion.mjs
• Test coverage in tests/commands.test.mjs and tests/runtime.test.mjs ensures CLI contracts are maintained

Frequently Asked Questions

How do I check if my model alias is valid?

Pass it to codex:rescue --model. If the alias isn't spark, Codex will reject it as an invalid model name. The source code in codex-companion.mjs performs a direct lookup against MODEL_ALIASES with no fallback behavior.

What happens if I specify an unsupported reasoning effort?

The normalizeReasoningEffort function throws an "Unsupported reasoning effort" error and exits. The validation is strict—partial matches or case variations are not accepted.

Can I set defaults instead of using flags every time?

Yes. Codex reads from a config.toml file at the user or project level to establish default model and effort values. The runtime flags override these defaults when present.

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