Codex Plugin CC Configuration Options for Model Selection and Reasoning Effort

Configure which LLM the Codex Plugin CC uses and control how much "reasoning effort" it applies via opencode.json defaults and --model / --effort CLI flags.

The Codex Plugin CC from OpenAI provides granular control over model selection and reasoning intensity through a combination of static configuration and runtime overrides. This guide examines the specific configuration options available in opencode.json and codex-companion.mjs, demonstrating how to tailor both settings for your workflows.

Model Selection Configuration

Default and Fallback Models

The plugin defines two primary model tiers in opencode.json:

• model — The primary LLM used when no --model flag is supplied
• small_model — A cheaper alternative for lightweight workloads or when the primary model is unavailable

These defaults are read at startup and can be overridden per-invocation.

Provider Configuration and Fallback Chains

For each model, opencode.json specifies an ordered list of backend providers under provider.openrouter.models. Each entry declares whether fallbacks are permitted if the primary provider fails.

Concrete examples from the configuration:

• openai/gpt-oss-120b — Attempts fireworks first, then falls back to cerebras
• qwen/qwen3-32b — Attempts sambanova first, then falls back to groq

The runtime in codex-companion.mjs reads this ordering when constructing request payloads to the app-server.

Runtime Model Override

Override any default at runtime with the --model flag. Valid arguments include:

• A specific model identifier (e.g., openrouter/openai/gpt-oss-120b)
• spark — An alias that resolves to the configured small_model

This behavior is documented in the help text within codex-companion.mjs at line 82.

Reasoning Effort Configuration

Effort Levels and Validation

Reasoning effort controls how much time the model spends on internal "thinking" steps before generating output. Configure it via the --effort flag with these accepted values:

Value	Description
none	No reasoning steps
minimal	Token-minimal thinking
low	Reduced thinking depth
medium	Balanced reasoning (explicit selection)
high	Extended analysis
xhigh	Maximum reasoning depth

The validation and normalization logic resides in codex-companion.mjs (lines 114–124). The function enforces the allowed set strictly—supplying an unknown value triggers an error listing valid options.

Default Behavior

When --effort is omitted, the value defaults to null. In this case, the plugin does not specify effort in the request payload, letting the backend select an appropriate default based on model capabilities and context. This logic appears in the request builder at lines 604–608 of codex-companion.mjs.

Practical Usage Examples

Run the default model with automatic effort selection:

node plugins/codex/scripts/codex-companion.mjs task "Explain the PR diff"

Explicitly use the small "spark" model with medium reasoning:

node plugins/codex/scripts/codex-companion.mjs task \
  --model spark \
  --effort medium \
  "Write a test that covers edge-case X"

Select a specific provider-backed model and disable reasoning entirely:

node plugins/codex/scripts/codex-companion.mjs task \
  --model openrouter/openai/gpt-oss-120b \
  --effort none \
  "Generate a one-line summary of the repo"

Key Configuration Files

File	Purpose
opencode.json	Stores global defaults for model, small_model, and provider ordering with fallback rules
plugins/codex/scripts/codex-companion.mjs	CLI entry point that parses --model and --effort, validates effort values, and builds request payloads
README.md	Documents runtime flags and their defaults
tests/commands.test.mjs	Contains unit tests asserting help text accuracy and effort flag validation behavior

Summary

• Model selection is configured in opencode.json via model and small_model fields, with provider chains defining fallback behavior
• --model overrides defaults at runtime, accepting specific identifiers or the spark alias
• Reasoning effort accepts six levels from none to xhigh, defaulting to null (backend-decided) when unspecified
• Validation logic in codex-companion.mjs rejects invalid effort values with a descriptive error
• Both settings are attached to the outgoing request payload and interpreted by the backend app-server

Frequently Asked Questions

What happens if I omit both --model and --effort flags?

The plugin uses the model value from opencode.json and sets effort to null, allowing the backend to apply its own defaults based on the selected model and request context.

Can I use a model not listed in opencode.json?

Yes. The --model flag accepts any valid model identifier. However, models not configured in provider.openrouter.models will not have provider fallback chains defined, which may affect reliability if your primary provider is unavailable.

Why does --effort reject values like lowest or maximum?

The normalization function in codex-companion.mjs enforces a strict whitelist of six specific strings. This explicit validation prevents ambiguous or model-specific effort descriptors from being passed to backends that may interpret them inconsistently.

How do I verify my configuration is being applied correctly?

Run with --help to confirm flag recognition, or inspect the generated request payload by adding debug logging to codex-companion.mjs near lines 604–608 where the effort property is attached.

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