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

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.

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:

// 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:

// 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.

Validating Reasoning Effort Parameters

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

// 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:

// 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
2. Forwards the model and effort parameters to the LLM endpoint
3. Applies the default model when model is null

Practical Command Examples

# 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	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 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 (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.

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