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

88
packages/docs/providers.mdx
View file

@ -1,6 +1,6 @@
---
title: "Providers"
description: "Connect LLM providers and configure endpoints, packages, models, and variants."
description: ""
---
OpenCode builds its provider and model catalog from [Models.dev](https://models.dev), then applies the `providers`
@ -57,7 +57,7 @@ When several credential sources exist, OpenCode uses the stored credential first
<Warning>Do not commit API keys or authorization headers to your repository.</Warning>
## Configure providers
## Configure
The `providers` object is keyed by provider ID. Each provider accepts these fields:
@ -75,7 +75,7 @@ Configuration files are applied from lowest to highest precedence. `settings` an
merged case-insensitively. At request time, provider values are inherited by the model, model values override them, and
the selected variant is applied last.
### Custom endpoint
### Endpoint
Override `settings.baseURL` to send an existing provider through a proxy or compatible endpoint. Its existing package,
models, and connection continue to apply:
@ -95,7 +95,7 @@ models, and connection continue to apply:
`settings` is package-specific. A field only has an effect when the selected package supports it.
### Custom headers and body
### Headers and body
Headers and body fields can be set at provider, model, or variant scope:
@ -127,7 +127,7 @@ Headers and body fields can be set at provider, model, or variant scope:
These are request overlays, not a generic authentication scheme. Prefer `/connect`, `env`, or `settings.apiKey` for
provider credentials unless the endpoint explicitly requires a custom header.
## Custom providers and packages
### Provider packages
For an OpenAI-compatible service, use the V2 native compatible package. The model map is explicit because a custom
provider has no Models.dev catalog entries:
@ -179,10 +179,10 @@ not validate package-specific keys.
`package` may also be set on one model to override the provider package for that model.
## Models
### Models
`models` adds a model or overlays an existing catalog model. The object key is the model ID used in OpenCode. Set
`modelID` when the upstream API expects a different ID:
Add a model under a provider's `models` map. The object key is the model ID used in OpenCode; `modelID` is the ID sent to
the provider:
```jsonc title="opencode.jsonc"
{
@ -193,13 +193,7 @@ not validate package-specific keys.
"models": {
"coding": {
"modelID": "gpt-5.2",
"name": "GPT-5.2 Coding",
"family": "gpt-5",
"limit": {
"context": 200000,
"input": 180000,
"output": 32000
}
"name": "GPT-5.2 Coding"
}
}
}
@ -207,66 +201,4 @@ not validate package-specific keys.
}
```
A model supports `modelID`, `family`, `name`, `package`, `settings`, `headers`, `body`, `capabilities`, `variants`,
`cost`, `disabled`, and `limit`. If supplied, `capabilities` requires `tools`, `input`, and `output`. `limit` may set
`context`, `input`, and `output`. Cost values are USD per million tokens:
```jsonc
{
"cost": {
"input": 3,
"output": 15,
"cache": {
"read": 0.3,
"write": 3.75
}
}
}
```
Set `disabled: true` on a model to remove it from the available model list. V2 does not define provider-level
whitelist or blacklist fields.
## Variants
Variants are named request overlays for one model. They can override `settings`, `headers`, and `body`; the selected
package determines which values are meaningful.
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"openai": {
"models": {
"gpt-5.2": {
"variants": [
{
"id": "fast",
"settings": {
"reasoningEffort": "low"
}
},
{
"id": "deep",
"settings": {
"reasoningEffort": "high",
"reasoningSummary": "auto"
}
}
]
}
}
}
}
}
```
Choose a variant with the TUI variant picker or `/variants`. Explicit CLI, agent, and command model references use
`provider/model#variant`; for example:
```bash
opencode2 run --model openai/gpt-5.2#deep "Review this project"
```
The current V2 top-level `model` default does not retain a `#variant` selection, so choose the variant separately.
Selecting an ID that is not defined for the model fails instead of silently using the default request settings.
See [Models](/models) for model selection, defaults, capabilities, limits, costs, and variants.