Models

opencode uses a flexible model configuration system that lets you specify primary models, lightweight fallbacks, provider-specific model options, and model variants.

Setting the Model

The primary LLM is set via the model key in opencode.json. Models use the provider_id/model_id format.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

Small Model for Lightweight Tasks

The small_model key specifies a cheaper or faster model for lightweight operations such as file summarization, quick edits, and classification tasks.

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

When small_model is not set, opencode attempts to auto-select a cheaper model from the same provider. If no suitable fallback is found, the primary model is used for all tasks.

CLI Flag Override

Models can be overridden at runtime via the --model CLI flag:

opencode --model openai/gpt-5.2

This overrides both the config file and the last-used model for the current session only.

Model Selection Commands

TUI Model Picker

Open the model picker in the terminal UI with:

/models

This lists all available models from configured providers. Models are grouped by provider with usage metadata shown alongside each entry.

CLI Model Listing

List available models from all configured providers:

opencode models

List models from a specific provider:

opencode models anthropic

Refreshing the Model Cache

Model lists are cached locally. To force a refresh:

opencode models --refresh

This is useful after adding a new provider or when a provider adds new models.

Global Model Options

Options that apply to all models can be configured at the provider level:

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

Option Reference

Option	Type	Default	Description
timeout	number	600000	Maximum time in ms to wait for a complete response
chunkTimeout	number	30000	Maximum time in ms between streaming chunks
setCacheKey	boolean	false	Enable prompt caching (Anthropic)
reasoningEffort	string	provider default	Reasoning token budget (none, low, medium, high)
thinking	object	null	Configuration for extended thinking (Anthropic)
textVerbosity	string	"normal"	Controls response detail level

Reasoning Effort

Controls how much computation the model spends on reasoning before responding:

{
  "provider": {
    "openai": {
      "options": {
        "reasoningEffort": "high"
      }
    }
  }
}

Supported values: none, minimal, low, medium, high, xhigh. Not all providers support every level.

Extended Thinking

For Anthropic models, extended thinking can be configured to dedicate a thinking budget:

{
  "provider": {
    "anthropic": {
      "options": {
        "thinking": {
          "budgetTokens": 16000
        }
      }
    }
  }
}

This enables Claude to produce longer chains of internal reasoning before generating a response, useful for complex problem-solving.

The Variants System

Variants allow you to run the same model with different configurations (e.g., different reasoning effort, temperature, or thinking budget) and switch between them at runtime.

Built-in Variants

Some providers ship with predefined variant sets.

Anthropic:

Variant Key	Description
high	High reasoning effort
max	Maximum reasoning with thinking

{
  "provider": {
    "anthropic": {
      "variants": {
        "high": {
          "reasoningEffort": "high"
        },
        "max": {
          "reasoningEffort": "high",
          "thinking": { "budgetTokens": 32000 }
        }
      }
    }
  }
}

OpenAI:

Variant Key	Description
none	No reasoning effort
minimal	Minimal reasoning
low	Low reasoning effort
medium	Medium reasoning effort
high	High reasoning effort
xhigh	Maximum reasoning effort

Google:

Variant Key	Description
low	Low reasoning effort
high	High reasoning effort

Custom Variants

Define your own variants in the config:

{
  "provider": {
    "anthropic": {
      "variants": {
        "fast": {
          "reasoningEffort": "none"
        },
        "balanced": {
          "reasoningEffort": "medium"
        },
        "deep": {
          "reasoningEffort": "high",
          "thinking": { "budgetTokens": 32000 }
        }
      }
    }
  }
}

Cycling Variants

When one or more variants are defined, you can cycle through them at runtime. Set a keybinding in tui.json:

{
  "keybinds": {
    "variant_cycle": "ctrl+t"
  }
}

Each press of Ctrl+T advances to the next variant in the cycle. The active variant is shown in the TUI status bar.

Model Loading Priority

When determining which model to use, opencode checks in this order:

1. --model CLI flag (highest priority)
2. model key in the active config file
3. Last-used model from the session (persisted per-project)
4. Internal priority list of recommended models

This means if you have a config with "model": "openai/gpt-5.2" but last session you switched to anthropic/claude-sonnet-4-5, the last-used model takes priority over the config — unless the --model flag is provided.

Model ID Format

Model IDs follow the format provider_id/model_name:

anthropic/claude-sonnet-4-5
openai/gpt-5.2
google/gemini-3-pro
openrouter/mistralai/mixtral-8x22b-instruct

The provider ID must match the key used in the provider config section. The model name must match what the provider API expects.

To see exact model IDs available from a provider:

opencode models anthropic --refresh

Recommended Models

Model	Provider ID	Notes
GPT 5.2	openai	Best general-purpose model
GPT 5.1 Codex	openai	Optimized for code generation
Claude Opus 4.5	anthropic	Best for complex reasoning
Claude Sonnet 4.5	anthropic	Best balance of speed and quality
Minimax M2.1	minimax	Strong alternative for code tasks
Gemini 3 Pro	google	Excellent for multimodal tasks
Claude Haiku 4.5	anthropic	Fast and cheap for lightweight tasks
GPT 5.1 Mini	openai	Low-cost option for simple tasks
DeepSeek-R1	deepseek	Strong open-weight reasoning model
Mistral Large	mistral	Good multilingual support

Agent-Level Model Override

Each agent can specify its own model, overriding the global model setting:

{
  "agent": {
    "build": {
      "model": "openai/gpt-5.1-codex",
      "small_model": "openai/gpt-5.1-mini"
    },
    "debug": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

This allows different agents to use models optimized for their specific tasks without changing the global configuration.

Agent Model Inheritance

If an agent does not specify a model, it inherits from the global config. If the agent specifies only model, the global small_model is used as fallback.

Model Configuration in Custom Commands

Commands can also specify model overrides:

{
  "command": {
    "refactor": {
      "template": "Refactor the code in $ARGUMENTS to improve readability and performance.",
      "description": "Refactor code",
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

Per-Model Provider Options

Override provider options for specific models:

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 300000
      }
    }
  }
}

All models from that provider inherit these options, pushing provider-level granularity to the model level.

Disabling a Model

To prevent a model from being used, set it at the provider level:

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5.2": { "enabled": false }
      }
    }
  }
}

This hides the model from the model picker and prevents it from being used in any session.