Something went wrong. Try again.
opencode v2 mirror
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430---title: "Models"---
Choose a model for the current session with `/models`:
```text/models```
OpenCode lists models from [models.dev](https://models.dev), provider integrations, and your configuration. The selectoronly shows enabled models whose provider is available in the current project. Connect providers in[Providers](/providers).
## Select
Pick an entry from `/models` instead of guessing its provider or model ID. The selection applies to the current sessionand does not change your configuration.
```textanthropic/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:
```bashopencode run --model anthropic/claude-sonnet-4-5 "Refactor parseToken"```
Agents and commands can also choose their own model. See [Agents](/agents) and [Commands](/commands).
## Defaults
Set `model` in `opencode.json` or `opencode.jsonc` to choose the default for new work:
```jsonc title="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, OpenCodefalls 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](/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 selectingone for a run, session, agent, or command:
```bashopencode 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 notavailable 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:
```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", }, }, ], }, }, }, },}```
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`:
```jsonc title="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:
```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 reference and `gpt-5.2` is sent to the provider. For a model that is notalready 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:
```jsonc title="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`:
```jsonc title="opencode.jsonc"{ "providers": { "local": { "models": { "reasoner": { "compatibility": { "reasoningField": "reasoning_content", }, }, }, }, },}```
OpenCode recognizes `reasoning`, `reasoning_content`, and `reasoning_text`, and also accepts another provider-specificstring. It reads streamed reasoning from that field and restores the field when sending prior assistant messages back tothe model.
## Local
OpenCode automatically discovers models from Ollama, LM Studio, and vLLM at their default local addresses. You can alsoconfigure any OpenAI-compatible server manually.
```textollama/gemma3:4blmstudio/google/gemma-4-26b-a4bvllm/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:
```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.
For another host or port, set Ollama's OpenAI-compatible URL. Discovery still uses the native Ollama API at the samepath prefix:
```jsonc title="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:
```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.
For another host or port, set the OpenAI-compatible URL. Models are still discovered automatically:
```jsonc title="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:
```jsonc title="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 contextlimit, 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 flagssuch 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:
```jsonc title="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:
```jsonc title="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 thecustom-model fallback values are accurate. If the endpoint requires a key, add `apiKey` to `settings` with an environmentsubstitution such as `"apiKey": "{env:LOCAL_API_KEY}"`; do not commit secrets.
## References
Model selectors use `provider/model` with an optional `#variant`:
```textopenai/gpt-5.2openai/gpt-5.2#highopenrouter/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 aboveor an expanded object:
```jsonc{ "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:
```jsonc{ "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.