opencode-agent[bot]
339 lines
11 KiB
Plaintext
339 lines
11 KiB
Plaintext
---
|
|
title: "Models"
|
|
---
|
|
|
|
OpenCode builds its model catalog from [models.dev](https://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](/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](/agents) and [Commands](/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`:
|
|
|
|
```jsonc title="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](/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`:
|
|
|
|
```jsonc title="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 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`:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"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:
|
|
|
|
```jsonc title="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",
|
|
},
|
|
},
|
|
],
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
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:
|
|
|
|
```jsonc title="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 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:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$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:
|
|
|
|
```jsonc title="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 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:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$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:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$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:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$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:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"model": "local/coder",
|
|
"providers": {
|
|
"local": {
|
|
"name": "Local server",
|
|
"package": "@opencode-ai/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`:
|
|
|
|
```text
|
|
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:
|
|
|
|
```jsonc
|
|
{
|
|
"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.
|