Models

OpenCode builds its model catalog from models.dev, provider integrations, and your configuration. Only enabled models whose provider is available for the current project are available for selection.

Configure provider availability in Providers.

Choose a model

Clients can select any model available from providers connected to the current project. Selecting a model updates the current session without changing configuration. Use an available catalog entry rather than guessing a provider or model name.

Per-run model

Command-line runs can select a model without changing the configured default.

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

Variants

Variants are named request overlays for one model, commonly used for reasoning effort or token budgets. Available names are model-specific and are derived from current catalog metadata. Do not assume that names such as low, high, or max exist for every model. Clients should present only the variants available for the selected model.

Configure

Default model

Set model in opencode.json or opencode.jsonc:

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

The configured model becomes the catalog default when its provider is available and the model is enabled. Otherwise, session execution falls back to the newest available supported model. An explicit model already selected on a session takes precedence over the default; switching models changes that session and does not rewrite your config.

See Config for configuration locations and precedence.

Model settings

Provider and model entries can supply three kinds of request configuration:

• settings contains provider-package options such as baseURL, reasoningEffort, or thinkingConfig.
• headers adds HTTP request headers.
• body adds provider-specific fields to the request body.

These values are provider-specific JSON. OpenCode applies provider values first, then model values, then the selected variant. Nested settings and body objects are merged; later array and scalar values replace earlier values. Header names are matched case-insensitively.

You can also map a friendly catalog ID to a different API model ID with modelID:

{
  "$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 catalog reference, while gpt-5.2 is sent to the provider. A model that is not already in the catalog receives fallback metadata:

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

These values are assumptions, not model discovery. Configure accurate capabilities and limit values whenever they are known; explicit values override the fallbacks. Set disabled: true on a model entry to hide it from the available catalog.

OpenAI-compatible models that stream reasoning through a custom assistant-message field can set compatibility.reasoningField:

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

OpenCode recognizes reasoning, reasoning_content, and reasoning_text, and accepts any provider-specific string. It reads streamed reasoning from this field and includes the field when replaying assistant messages to the model.

Custom variants

Add a variant, or override a catalog variant with the same ID, under the model’s variants array:

{
  "$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",
              },
            },
          ],
        },
      },
    },
  },
}

Variant entries support settings, headers, and body. Selecting one deeply overlays its values on the effective provider and model configuration. An unknown variant fails model resolution instead of silently using the base model.

Local models

Ollama

OpenCode automatically discovers language models from an Ollama server listening on its default address, http://127.0.0.1:11434. Discovered models use the ollama provider ID and Ollama’s model name:

{
  "$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 because they cannot drive a session. Disable discovery with "plugins": ["-opencode.provider.ollama"].

For a different host or port, configure Ollama’s OpenAI-compatible base URL. Models are still discovered through the native Ollama API at the same path prefix:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "ollama": {
      "settings": {
        "baseURL": "http://127.0.0.1:5678/v1",
        "apiKey": "{env:OLLAMA_API_KEY}",
      },
    },
  },
}

Omit apiKey when the Ollama endpoint does not require bearer authentication.

LM Studio

OpenCode automatically discovers language models from an unauthenticated LM Studio server listening on its default address, http://127.0.0.1:1234. Discovered models use the lmstudio provider ID and LM Studio’s model key:

{
  "$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 because they cannot drive a session. Disable discovery with "plugins": ["-opencode.provider.lmstudio"].

For a different host or port, configure the OpenAI-compatible base URL. Models are still discovered automatically:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "lmstudio": {
      "settings": {
        "baseURL": "http://127.0.0.1:5678/v1",
        "apiKey": "{env:LMSTUDIO_API_KEY}",
      },
    },
  },
}

Omit apiKey when LM Studio authentication is disabled.

vLLM

OpenCode automatically discovers models from a vLLM server listening on its default address, http://127.0.0.1:8000. Discovered models use the vllm provider ID and the model ID reported by vLLM:

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

OpenCode checks vLLM’s /health endpoint and refreshes /v1/models in the background. It uses the reported max_model_len as the context limit and only includes model cards owned by vllm. Discovered vLLM models advertise text input and output, but not vision or tools. Tool calling is conservative because vLLM enables it with server-level flags such as --enable-auto-tool-choice and --tool-call-parser, which model discovery does not report. Disable discovery with "plugins": ["-opencode.provider.vllm"].

For a different endpoint or an authenticated server, configure its OpenAI-compatible base URL:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "vllm": {
      "settings": {
        "baseURL": "http://127.0.0.1:9000/v1",
        "apiKey": "{env:VLLM_API_KEY}",
      },
    },
  },
}

Omit apiKey when authentication is disabled. Path-prefixed proxy URLs are supported; for example, https://example.com/vllm/v1 checks /vllm/health and discovers /vllm/v1/models.

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

{
  "$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, modalities, and tool support. OpenCode applies the custom-model capability defaults described above but cannot infer the server’s actual limits or whether those defaults are accurate. If the endpoint requires a key, add apiKey to provider settings using an environment substitution such as "apiKey": "{env:LOCAL_API_KEY}"; do not commit secrets.

Model references

Configuration fields and model-selection inputs identify a model as provider/model, with an optional #variant:

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

OpenCode splits the reference at the first /, so model IDs may contain additional slashes. Provider and model IDs are case-sensitive. Provider IDs cannot contain / or #, and model IDs cannot contain #.

The expanded config form is equivalent when generated or programmatic configuration is more convenient:

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

Root, agent, and command model fields accept both forms. Use IDs from the available catalog, not provider display names.

Caveats

• The selector object uses model, while a provider catalog entry uses modelID for the upstream API identifier.
• The root model currently sets the default provider and model only. Although its selection shape accepts a variant, the V2 catalog default does not retain it; select a variant for the session, run, agent, or command instead.
• Model options are provider-specific. A setting accepted by one provider package may be ignored or rejected by another.
• Catalog data, credentials, and config are location-scoped. A model available in one project may be unavailable in another.
• Configuration files are watched and normally reload automatically, but an in-flight model request keeps the settings with which it started.