From 8e756809a11ad58df6b60c1a3c9df17907ae83d8 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Sun, 8 Nov 2026 23:53:57 -0600 Subject: [PATCH] docs: document cache.ttl and per-model cache.warming (#62829) --- services/site/src/docs/content/config.mdx | 6 ++-- services/site/src/docs/content/models.mdx | 33 ++++++++++++++++++++++ services/site/src/docs/content/warming.mdx | 30 ++++++++++++++++++-- 3 files changed, 65 insertions(+), 4 deletions(-) diff --git a/services/site/src/docs/content/config.mdx b/services/site/src/docs/content/config.mdx index 8aded5ef72b..c8aa28427c4 100644 --- a/services/site/src/docs/content/config.mdx +++ b/services/site/src/docs/content/config.mdx @@ -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 diff --git a/services/site/src/docs/content/models.mdx b/services/site/src/docs/content/models.mdx index 05cfd7734c7..f65262b2fc1 100644 --- a/services/site/src/docs/content/models.mdx +++ b/services/site/src/docs/content/models.mdx @@ -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 diff --git a/services/site/src/docs/content/warming.mdx b/services/site/src/docs/content/warming.mdx index 797e79ad6fd..912b19194a9 100644 --- a/services/site/src/docs/content/warming.mdx +++ b/services/site/src/docs/content/warming.mdx @@ -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