Models

Choose a model for the current session with /models:

/models

OpenCode lists models from models.dev, provider integrations, and your configuration. The selector only shows enabled models whose provider is available in the current project. Connect providers in Providers.

Select

Pick an entry from /models instead of guessing its provider or model ID. The selection applies to the current session and does not change your configuration.

anthropic/claude-sonnet-4-5

Availability is project-specific:

The model must be enabled.
Its provider must be available in the current project.
Credentials and configuration from another project do not carry over automatically.

Runs

Use --model to choose a model for one command-line run without changing the configured default:

opencode run --model anthropic/claude-sonnet-4-5 "Refactor parseToken"

Agents and commands can also choose their own model. See Agents and Commands.

Defaults

Set model in opencode.json or opencode.jsonc to choose the default for new work:

opencode.jsonc

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

The configured model becomes the catalog default when it is enabled and its provider is available. Otherwise, OpenCode falls back to the newest available supported model.

A model already selected for a session takes precedence over the configured default.
Switching a session’s model does not rewrite the config file.
The root model currently retains only the default provider and model, not a variant.

See Config for configuration locations and precedence.

Variants

Variants are named options for one model, often used for reasoning effort or token budgets. Add #variant when selecting one for a run, session, agent, or command:

opencode run --model openai/gpt-5.2#high "Review this migration plan"

Variant names come from the selected model’s current catalog metadata. Names such as low, high, and max are not available for every model, and an unknown variant produces a model-resolution error.

Define new variants, or replace catalog variants with the same ID, in the model’s variants array:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "models": {
        "gpt-5.2": {
          "settings": {
            "reasoningEffort": "medium",
          },
          "variants": [
            {
              "id": "fast",
              "settings": {
                "reasoningEffort": "low",
              },
            },
            {
              "id": "deep",
              "settings": {
                "reasoningEffort": "high",
                "reasoningSummary": "auto",
              },
            },
          ],
        },
      },
    },
  },
}

Each variant can contain settings, headers, and body. Its values are applied after provider and model values.

Options

Provider and model entries can customize requests with settings, headers, and body:

opencode.jsonc

{
  "providers": {
    "openai": {
      "settings": {
        "baseURL": "https://api.example.com/v1",
      },
      "headers": {
        "X-Team": "platform",
      },
      "models": {
        "gpt-5.2": {
          "settings": {
            "reasoningEffort": "high",
          },
          "body": {
            "store": false,
          },
        },
      },
    },
  },
}

Field	Purpose
`settings`	Provider-package options such as `baseURL` or `reasoningEffort`.
`headers`	Additional HTTP request headers.
`body`	Provider-specific request body fields.

OpenCode applies provider values first, model values second, and the selected variant last.

Nested settings and body objects are merged.
Later arrays and scalar values replace earlier values.
Header names are matched case-insensitively.
Options are provider-specific and may be ignored or rejected by another provider package.

Aliases

Use modelID to give an API model a friendlier catalog ID:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/coding-default",
  "providers": {
    "openai": {
      "models": {
        "coding-default": {
          "modelID": "gpt-5.2",
          "name": "Coding default",
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"],
          },
          "limit": {
            "context": 200000,
            "output": 32000,
          },
        },
      },
    },
  },
}

Here, openai/coding-default is the selectable reference and gpt-5.2 is sent to the provider. For a model that is not already in the catalog, OpenCode assumes:

Tool support, text and image input, and text output.
A 200,000-token context limit and 32,000-token output limit.
An unspecified input limit.

These are fallback assumptions, not detected capabilities. Set accurate capabilities and limit values when known; explicit values replace the fallbacks. Add disabled: true to hide a model from the available catalog:

opencode.jsonc

{
  "providers": {
    "openai": {
      "models": {
        "legacy-model": {
          "disabled": true,
        },
      },
    },
  },
}

Reasoning

For an OpenAI-compatible model that streams reasoning in a custom assistant-message field, set compatibility.reasoningField:

opencode.jsonc

{
  "providers": {
    "local": {
      "models": {
        "reasoner": {
          "compatibility": {
            "reasoningField": "reasoning_content",
          },
        },
      },
    },
  },
}

OpenCode recognizes reasoning, reasoning_content, and reasoning_text, and also accepts another provider-specific string. It reads streamed reasoning from that field and restores the field when sending prior assistant messages back to the model.

Local

OpenCode automatically discovers models from Ollama, LM Studio, and vLLM at their default local addresses. You can also configure any OpenAI-compatible server manually.

ollama/gemma3:4b
lmstudio/google/gemma-4-26b-a4b
vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct

Ollama

With Ollama listening at http://127.0.0.1:11434, select a discovered model with the ollama provider ID:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/gemma3:4b",
}

OpenCode refreshes the inventory in the background and reads context, vision, and tool-use capabilities from Ollama. Embedding-only models are excluded.

For another host or port, set Ollama’s OpenAI-compatible URL. Discovery still uses the native Ollama API at the same path prefix:

opencode.jsonc

{
  "providers": {
    "ollama": {
      "settings": {
        "baseURL": "http://127.0.0.1:5678/v1",
        "apiKey": "{env:OLLAMA_API_KEY}",
      },
    },
  },
}

Omit apiKey when the endpoint does not require bearer authentication.
Disable discovery with "plugins": ["-opencode.provider.ollama"].

LMStudio

With an unauthenticated LM Studio server at http://127.0.0.1:1234, select a discovered model with the lmstudio provider ID:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "lmstudio/google/gemma-4-26b-a4b",
}

OpenCode refreshes the inventory in the background and reads context, vision, and tool-use capabilities from LM Studio. Embedding models are excluded.

For another host or port, set the OpenAI-compatible URL. Models are still discovered automatically:

opencode.jsonc

{
  "providers": {
    "lmstudio": {
      "settings": {
        "baseURL": "http://127.0.0.1:5678/v1",
        "apiKey": "{env:LMSTUDIO_API_KEY}",
      },
    },
  },
}

Omit apiKey when LM Studio authentication is disabled.
Disable discovery with "plugins": ["-opencode.provider.lmstudio"].

vLLM

With vLLM listening at http://127.0.0.1:8000, select a discovered model with the vllm provider ID:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct",
}

OpenCode checks /health, refreshes /v1/models in the background, uses the reported max_model_len as the context limit, and includes only model cards owned by vllm.

Discovered models advertise text input and output, but not vision or tools. vLLM enables tool calling with server flags such as --enable-auto-tool-choice and --tool-call-parser, which discovery does not report.

For another endpoint or an authenticated server, set its OpenAI-compatible URL:

opencode.jsonc

{
  "providers": {
    "vllm": {
      "settings": {
        "baseURL": "http://127.0.0.1:9000/v1",
        "apiKey": "{env:VLLM_API_KEY}",
      },
    },
  },
}

Omit apiKey when authentication is disabled.
Disable discovery with "plugins": ["-opencode.provider.vllm"].
Path-prefixed proxies are supported. For example, https://example.com/vllm/v1 checks /vllm/health and discovers /vllm/v1/models.

Compatible

For another OpenAI-compatible server, define its provider package, endpoint, and at least one model:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "local/coder",
  "providers": {
    "local": {
      "name": "Local server",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "http://127.0.0.1:1234/v1",
      },
      "models": {
        "coder": {
          "modelID": "model-name-on-server",
          "capabilities": {
            "tools": true,
            "input": ["text"],
            "output": ["text"],
          },
          "limit": {
            "context": 32768,
            "output": 8192,
          },
        },
      },
    },
  },
}

Use the server’s real model name, limits, input and output types, and tool support. OpenCode cannot detect whether the custom-model fallback values are accurate. If the endpoint requires a key, add apiKey to settings with an environment substitution such as "apiKey": "{env:LOCAL_API_KEY}"; do not commit secrets.

References

Model selectors use provider/model with an optional #variant:

openai/gpt-5.2
openai/gpt-5.2#high
openrouter/anthropic/claude-sonnet-4.5#high

Part	Rule
Provider	Ends at the first `/`; cannot contain `/` or `#`.
Model	May contain additional `/` characters; cannot contain `#`.
Variant	Follows `#` when present.
Casing	Provider and model IDs are case-sensitive.

Use catalog IDs rather than provider display names. Root, agent, and command model fields accept the string form above or an expanded object:

{
  "model": {
    "providerID": "openrouter",
    "model": "anthropic/claude-sonnet-4.5",
  },
}

The expanded form is useful for generated or programmatic configuration.

Caveats

Keep these rules in mind when configuring models:

{
  "model": "openai/gpt-5.2"
}

A selector object uses model; a provider catalog entry uses modelID for the ID sent to the provider.
Although the root selection shape accepts a variant, the V2 catalog default does not retain it. Select variants for a session, run, agent, or command instead.
Model options are provider-specific. Another provider package may ignore or reject them.
Catalog data, credentials, and configuration are location-scoped. A model available in one project may be unavailable in another.
Configuration files normally reload automatically. A model request already in progress keeps the settings it started with.