Orange cover with a tilted white tile showing an isometric office with plants, title OpenCode models: change and set a default, an OpenCode tag and vibeide.dev
All articles

OpenCode models: change and set a default model (v1, v2)

Change the model in OpenCode with /models or --model, set a default in opencode.json, pick variants, and see what changed for models in OpenCode 2.

OpenCode does not ship with one model. It talks to dozens of providers through the Models.dev catalog and provider integrations, and it can run local models too. That flexibility is the main reason people pick it, but it also means you answer three questions yourself: which providers are connected, which model is the default, and which model each agent uses.

Every terminal in one Grid.Six agents typing at once, no tab juggling. VibeiDE Grid view.See the Grid

As of November 2026 there are also two release lines. OpenCode 1 (the 1.x CLI most package managers still install) and OpenCode 2 (an explicit upgrade) select models the same way, but they differ on variants, config keys and what OpenCode falls back to. This guide covers both, with the commands from the official OpenCode models docs, checked on 7 November 2026, and the OpenCode 1.18 CLI help. If OpenCode is not installed yet, start with how to install OpenCode, which explains how to pick OpenCode 1 or 2, or with OpenCode on Windows.

How do I change the model in OpenCode?

Type /models in the OpenCode TUI and pick a model from the list. To make a model the default, set "model": "provider/model" in opencode.json, and to use a model for one scripted run, pass --model (or -m in OpenCode 1) to opencode run. If the model you want is missing, connect its provider with /connect first.

GoalCommand or setting
Switch model in the current session/models
Set a default for every session"model" in ~/.config/opencode/opencode.json
Set a default for one project"model" in the project's opencode.json
Use a model for one runopencode run --model provider/model "..."
Pick a reasoning variant for one runOpenCode 1: --variant high; OpenCode 2: provider/model#high
Add a model from a new provider/connect, then /models

OpenCode 1 vs OpenCode 2: what changed for models?

Most of the model workflow is identical. The differences that trip people up after an upgrade, as of November 2026:

TopicOpenCode 1 (1.x CLI)OpenCode 2 (current docs)
Pick a model/models, -m or --model/models, --model
Pick a variant--variant high on opencode runAppend #variant to the selector, for example openai/gpt-6.1-sol#high
Provider config keyproviderproviders
Per-model tuningoptionssettings, plus headers and body
Custom variantsvariants object on a modelvariants array of { "id", "settings" } entries
Configured model unavailableFalls back to the last used model, then an internal priorityFalls back to the newest available supported model
Local modelsConfigure Ollama or LM Studio as a providerDiscovered automatically from Ollama, LM Studio and vLLM at their default addresses

In both lines, switching a session's model does not rewrite your config file, and the configured model only keeps a provider and model, not a variant. In OpenCode 2 the docs say so directly: "the root model currently retains only the default provider and model, not a variant."

How OpenCode names models

Every model has a two-part ID: provider/model. The provider ends at the first slash, and the model part can contain more slashes. Provider and model IDs are case-sensitive.

The ID anthropic/claude-sonnet-4-5 split into provider_id and model_id, above three steps: /connect to add credentials, /models to pick in the TUI, and the model key in opencode.json as the default.
Every OpenCode model is addressed as provider_id/model_id. Connect a provider, pick a model with /models, then save it as the default in opencode.json.

Examples of the format, taken from the OpenCode docs as of November 2026:

IDProvider partModel part
anthropic/claude-sonnet-5-5anthropicclaude-sonnet-5-5
openai/gpt-6.1-sol#highopenaigpt-6.1-sol, variant high (OpenCode 2)
openrouter/anthropic/claude-sonnet-5.5openrouteranthropic/claude-sonnet-5.5
ollama/gemma3:4bollamagemma3:4b

You rarely need to guess an ID. Pick it from /models, or in OpenCode 1 let the CLI print the exact strings:

opencode models              # every model from configured providers
opencode models anthropic    # only one provider
opencode models --refresh    # refresh the cached list from models.dev
opencode models --verbose    # include metadata such as costs

Use --refresh when a provider has just released a model and it does not show up yet.

How do I add models to OpenCode?

A model only appears once its provider is available in the current project. In the TUI, run /connect, search for the provider and follow the prompts. In OpenCode 1, opencode auth login does the same from the shell, and opencode auth list shows what is connected. The OpenCode 2 docs add that availability is project-specific: credentials and configuration from another project do not carry over automatically.

As of November 2026, the providers page highlights a few options:

  • The OpenCode provider (opencode): models served by the OpenCode team through an OpenCode Console account. It also includes models with no input price; see OpenCode free models, OpenRouter free models and free AI coding models. Signed out, the opencode provider is absent until you connect a Console account or set OPENCODE_API_KEY, and OPENCODE_DISABLE_FREE_MODELS=1 hides the free ones.
  • OpenAI: sign in with ChatGPT in the browser, or enter an API key.
  • GitHub Copilot: connect through GitHub's device code flow and use the models your Copilot plan includes.
  • Anthropic: use an Anthropic API key. As of October 2026 the providers page warned that plugins using Claude Pro or Max subscriptions inside OpenCode are prohibited by Anthropic.

Other supported providers include Azure OpenAI, Google Vertex AI, Groq, DeepSeek and Together AI, plus anything OpenAI-compatible. Our OpenCode vs Claude Code comparison covers what changes with each subscription.

How do I set the default model in OpenCode?

Set model in your config. The global file is ~/.config/opencode/opencode.json, and an opencode.json (or opencode.jsonc) in the project root overrides it for that project:

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

A model you pick with /models applies to that session and takes precedence over the configured default, but it never rewrites the file. That is the usual answer to "why does OpenCode keep opening with a different model": check the project opencode.json first, then whether a script or alias passes --model.

For a single run, pass the model on the command line. This is the form to use in scripts:

opencode run --model anthropic/claude-sonnet-5-5 "Summarize the failing tests"

Which model wins at startup

In OpenCode 1, OpenCode checks these sources in order and uses the first one that has a model:

Four rows checked top to bottom when OpenCode starts: the --model or -m flag, the model key in opencode.json, the last used model, then the first model by internal priority.
OpenCode picks its starting model from the first source that has one: the command-line flag, your config, the model you used last, then an internal priority list.
  1. The --model or -m flag
  2. The model key in your OpenCode config
  3. The last model you used
  4. The first model by an internal priority

In OpenCode 2, a model already selected for the session wins, then the configured model if it is enabled and its provider is available, and otherwise the newest available supported model. If an OpenCode 2 project suddenly opens with a newer model than you set, the configured one is usually disabled or its provider is not connected in that project.

Tune a model with variants

Variants are named settings for one model, most often reasoning effort or token budgets. Variant names come from the model's catalog metadata, so low, high and max are not available for every model, and an unknown name fails with a model-resolution error.

In OpenCode 1, pick a variant for a scripted run with --variant:

opencode run -m openai/gpt-6.1-sol --variant high "Review this migration plan"

In OpenCode 2, append it to the selector instead, and define your own variants in the model's variants array:

opencode run --model openai/gpt-6.1-sol#high "Review this migration plan"
{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "models": {
        "gpt-6.1-sol": {
          "settings": { "reasoningEffort": "medium" },
          "variants": [
            { "id": "fast", "settings": { "reasoningEffort": "low" } },
            { "id": "deep", "settings": { "reasoningEffort": "high", "reasoningSummary": "auto" } }
          ]
        }
      }
    }
  }
}

OpenCode 2 applies provider values first, then model values, then the selected variant. Nested objects merge; later scalars and arrays replace earlier ones. If you copy an OpenCode 1 config with provider and options, rename them to providers and settings after upgrading.

Give each agent its own model

Agents and commands can override the model, which is where the provider flexibility pays off. A planning agent can run on a faster, cheaper model while the build agent uses your strongest one. According to the agents docs, an agent without a model uses the configured default, and a subagent without one uses the model of the agent that invoked it.

Plan agent set to a faster model, build agent on the main model, small_model for titles and light tasks, and a subagent without its own model inheriting the model of the agent that called it.
Each OpenCode agent can set its own model. small_model handles lightweight jobs such as titles, and a subagent without a model uses the model of the primary agent that invoked it.

In opencode.json:

{
  "agent": {
    "plan": { "model": "openrouter/anthropic/claude-sonnet-5.5" }
  }
}

Or in a Markdown agent file, in the frontmatter:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-5-5
---

In OpenCode 2, agent and command model fields accept the same string, including #variant, so a review agent can run the same model at a higher reasoning effort.

Local models with Ollama, LM Studio or vLLM

OpenCode 2 discovers local models automatically from Ollama (http://127.0.0.1:11434), LM Studio (http://127.0.0.1:1234) and vLLM at their default addresses, so a pulled Ollama model shows up as, for example, ollama/gemma3:4b. In OpenCode 1, add the server as an OpenAI-compatible provider with its base URL and the models you pulled, then address it the same way.

Test a local model on a real task before you make it the default: few local models are good at both writing code and calling tools.

Common questions

How do I change the model in OpenCode? Run /models in the TUI and pick one. Set model in opencode.json to make it the default, or pass --model provider/model to opencode run for one run.

How do I set the default model in OpenCode? Add "model": "provider/model" to ~/.config/opencode/opencode.json for every project, or to the project's own opencode.json for one project. Picking a model with /models does not change that file.

Why does a model I just connected not show up? Check that its provider is connected in this project (/connect, or opencode auth list in OpenCode 1), then refresh the catalog with opencode models --refresh in OpenCode 1. In OpenCode 2, also check that the model is not disabled in config.

How do I pick a reasoning level? Use a variant: --variant high in OpenCode 1, or provider/model#high in OpenCode 2. Only the variant names the model's catalog lists will work.

Is my OpenCode 1 config valid in OpenCode 2? The model key carries over. Per-model tuning moved from provider and options to providers and settings, and custom variants became an array, so review those blocks after upgrading.

Where VibeiDE fits

VibeiDE is a desktop app that coordinates the Codex, Claude Code and OpenCode CLIs you already installed. OpenCode runs headless with recorded activity, and each user signs in to their own provider accounts, so provider subscriptions, usage and costs stay separate from the VibeiDE license. Each project has its own task queue and its own parallel limit per provider, which helps when OpenCode, Codex and Claude Code tasks share one repository. See VibeiDE for OpenCode, or compare it with other options in the best tools to run several coding agents in parallel.

Takeaways

  • Change the model with /models; set model in opencode.json for a default; use opencode run --model provider/model for one run.
  • A session's model choice never rewrites your config.
  • Variants: --variant high in OpenCode 1, provider/model#high in OpenCode 2.
  • OpenCode 2 renames provider and options to providers and settings, and falls back to the newest available model when the configured one is unavailable.
  • Subagents inherit the caller's model unless you set one.

Comparing tools rather than models? Read OpenCode vs Codex or, on the Codex side, how to change the model in Codex.

Share this article

Post on XShare on LinkedIn

Related articles

Necessary cookies support sign-in, security, your language and this choice. Optional categories stay off until accepted.

First-party page views and acquisition measurement, plus Google Analytics 4 (Google Ireland, data may reach the US). Advertising personalization stays off.

With Analytics enabled, retain Google, Microsoft and Reddit ad click identifiers and share download, signup, activation and purchase conversions with the relevant ad provider. No personalized advertising.

Privacy · Cookie inventory