ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: expand OpenCode 2 beta guides

Browse source
This commit is contained in:
Dax Raad 2026-07-09 18:00:30 -04:00
commit 1004fbb2f5
24 changed files with 889 additions and 359 deletions
Download patch file Download diff file Expand all files Collapse all files

190
packages/docs/models.mdx
View file

@ -1,49 +1,43 @@
---
title: "Models"
description: "Select, configure, and customize models in OpenCode 2.0."
description: ""
---
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 appear in the model picker.
Connect a provider with `/connect` in the TUI, or configure a provider and its credentials in `opencode.json`.
Connect a provider with `/connect` in the TUI, or configure it in [Providers](/providers).
## Select a model
## Choose a model
Open the model picker with `/models` or the default `<leader>m` keybind. Use `/variants` to choose a variant for the
current model, or press `ctrl+t` to cycle through its variants.
Open the model picker with `/models` or the default `<leader>m` keybind. The picker shows the models available from
providers connected to the current project.
A model reference has this form:
Select a model to use it in the current session. Switching models updates that session without changing your config. Use
the catalog entries shown in the picker rather than guessing a provider or model name.
```text
provider/model#variant
```
## Per-run model
The variant is optional. OpenCode splits at the first `/`, so model IDs may contain additional slashes:
```text
openai/gpt-5.2
openai/gpt-5.2#high
openrouter/anthropic/claude-sonnet-4.5#high
```
Use the catalog IDs shown by `/models`, not a provider's display name. Omit `#variant` to use the model's base settings.
### Command line
Select a model for a non-interactive run with `--model` or `-m`:
Select a model for one non-interactive run with `--model` or `-m`:
```bash
opencode2 run --model openai/gpt-5.2 "Explain this repository"
opencode2 run -m openai/gpt-5.2#high "Review the current changes"
```
<Note>
`opencode2 run` accepts `provider/model#variant`. The current `opencode2 mini --model` option accepts only
`provider/model`; choose its variant from the interactive interface.
</Note>
Agents and commands can also select their own model. See [Agents](/agents) and [Commands](/commands).
## Set the default
## 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; `/variants` shows the valid choices.
Use `/variants` to choose one for the current model, or press `ctrl+t` to cycle through available variants.
## Configure
### Default model
Set `model` in `opencode.json` or `opencode.jsonc`:
@ -54,81 +48,13 @@ Set `model` in `opencode.json` or `opencode.jsonc`:
}
```
The explicit object form is equivalent:
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"model": {
"providerID": "openrouter",
"model": "anthropic/claude-sonnet-4.5"
}
}
```
Root, agent, and command `model` fields accept these same selection forms. See [Config](/config) for configuration
locations and precedence.
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.
## Variants
See [Config](/config) for configuration locations and precedence.
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; `/variants` shows the valid choices.
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"
}
}
]
}
}
}
},
"commands": {
"deep-review": {
"description": "Review with high reasoning effort",
"template": "Review the current changes for correctness and missing tests.",
"model": "openai/gpt-5.2#deep"
}
}
}
```
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.
<Warning>
V2 uses `providers` (plural) and an array of `{ "id": "..." }` variant entries. The V1 `provider` key and
object-shaped `variants` configuration are not the V2 format.
</Warning>
## Configure a model
### Model settings
Provider and model entries can supply three kinds of request configuration:
@ -172,7 +98,46 @@ Here `openai/coding-default` is the selectable catalog reference, while `gpt-5.2
model that is not already in the catalog, set accurate `capabilities` and `limit` values so OpenCode can expose tools and
enforce the correct context limits. Set `disabled: true` on a model entry to hide it from the available catalog.
## Local and compatible models
### 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
For an OpenAI-compatible server, define a provider package, endpoint, and at least one model:
@ -210,9 +175,34 @@ Use the server's real model name, limits, modalities, and tool support. OpenCode
manually. 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.
## Caveats
### Model references
Configuration and CLI options 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 the IDs shown by `/models`, not provider display names.
### Caveats
- Provider and model IDs are case-sensitive. Provider IDs cannot contain `/` or `#`; model IDs cannot contain `#`.
- 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 in the TUI, with `opencode2 run`, or on an agent or command.