docs: document cache.ttl and per-model cache.warming (#62829)

This commit is contained in:
Aiden Cline
2026-11-08 23:53:57 -06:00
committed by GitHub
Unverified
parent 894e30395c
commit 8e756809a1
3 changed files with 65 additions and 4 deletions
+4 -2
View File
@@ -409,8 +409,10 @@ interval and 30-minute active window.
}
```
See the [warming guide](/warming) for request behavior, customization,
and cost considerations.
A provider's or model's `settings.cache.warming` overrides it, and
`settings.cache.ttl` sets how long the provider keeps the cache. See the
[warming guide](/warming) for request behavior, customization, and cost
considerations, and [cache lifetime](/models#cache-lifetime) for `cache.ttl`.
### Skills
+33
View File
@@ -308,6 +308,39 @@ for Alibaba Model Studio models, which accept the same markers but ignore them o
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. See
[Compatibility](#compatibility) for the other fields.
### Cache lifetime
OpenCode doesn't send a cache lifetime by default, so each provider uses its own default, such as five minutes on
Anthropic. Set `settings.cache.ttl` on a provider or model to request a different one. A model setting overrides the
provider setting.
```jsonc title="opencode.jsonc"
{
"providers": {
"anthropic": {
"settings": { "cache": { "ttl": "1h" } },
"models": {
"claude-haiku-5-5": { "settings": { "cache": { "ttl": "5m" } } },
},
},
},
}
```
`ttl` takes a number and a unit: `ms`, `s`, `m`, `h` or `d`, such as `"5m"`, `"1h"` or `"24h"`. OpenCode sends it as
given, so use a value the provider accepts:
| API | Where the lifetime goes |
| --- | --- |
| Anthropic Messages | `cache_control.ttl` on each cache marker. Anthropic accepts `"5m"` and `"1h"`. |
| Bedrock Converse | `ttl` on each `cachePoint`. Older Claude models that only cache for five minutes ignore `"1h"`. |
| OpenAI Chat and Responses | `"24h"` goes to `prompt_cache_retention`; other values go to `prompt_cache_options.ttl`. |
Providers that cache automatically without markers, such as Gemini, ignore it. A longer lifetime usually costs more to
write: Anthropic charges 2× the input price for a one-hour cache write and 1.25× for a five-minute one.
[Warming](/warming) can use the lifetime to time its requests with `interval: "auto"`.
## Compatibility
`compatibility` describes request and response quirks of the API a model is served through, such as which field carries
+28 -2
View File
@@ -55,7 +55,7 @@ interval:
## Automatic interval
Set `interval` to `"auto"` to warm just before each model's prompt cache
expires. OpenCode uses 90% of the model's [`cache.ttl`](/config) setting, so a
expires. OpenCode uses 90% of the model's [`cache.ttl`](/models#cache-lifetime) setting, so a
`"5m"` cache is warmed every 4.5 minutes. Models without a `cache.ttl` are not
warmed.
@@ -72,6 +72,31 @@ The interval must be shorter than `duration`, so raise `duration` for long
cache lifetimes such as `"1h"`. Otherwise OpenCode skips warming and logs a
warning.
## Per provider and model
Set `settings.cache.warming` on a provider or model to warm only its sessions,
or to give them their own timing. It takes the same values as the top-level
`warming`, except `prompt`, and overrides it. A model setting overrides the
provider setting.
```jsonc title="opencode.jsonc"
{
"providers": {
"anthropic": {
"settings": { "cache": { "ttl": "5m", "warming": { "interval": "auto" } } },
"models": {
"claude-haiku-5-5": { "settings": { "cache": { "warming": false } } },
},
},
},
}
```
Here Anthropic sessions are warmed every 4.5 minutes, except on Claude Haiku
5.5, and other providers aren't warmed. Fields left out of the object form come
from the top-level `warming`, then the defaults. An invalid setting logs a
warning and falls back to the top-level `warming`.
## Durations
`interval` and `duration` accept duration strings. Both must resolve to finite
@@ -89,7 +114,8 @@ otherwise OpenCode skips warming and logs a warning.
## Timing
Warming starts after a non-warming model request. After a warming request
Warming starts after a non-warming model request in a top-level session.
Subagent sessions are not warmed. After a warming request
finishes, the next idle interval starts, but the active window is not extended.
```text