# Codex Plugin CC Configuration Options for Model Selection and Reasoning Effort

> Explore Codex Plugin CC configuration options for model selection and reasoning effort. Control LLM usage and effort via opencode.json and CLI flags.

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

---

**Configure which LLM the Codex Plugin CC uses and control how much "reasoning effort" it applies via [`opencode.json`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

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

```

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

```bash
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:

```bash
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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.