The plugin handles three wire formats: the Anthropic Messages API (POST …/messages), OpenAI Chat Completions (POST …/chat/completions) and the OpenAI Responses API (POST …/responses, used by OpenCode's native openai provider). On every wire it needs to know which cache profile a model belongs to, except for the two Anthropic provider IDs (anthropic, omniroute-anthropic), which are always Claude:
Claude (anthropic) |
GPT-5.6+ (openai) |
Everything else (implicit) |
|
|---|---|---|---|
| Cache control it rewrites | cache_control breakpoints |
prompt_cache_breakpoint on text parts |
none |
| TTL by mode | 5m / 1h / hybrid | 30m (automatic) / 12h / 12h breakpoint on the prefix with the automatic 30m tail | none |
| Breakpoint injection when OpenCode sent none | yes (your prompts and compaction, not pings or titles) | only the 12h breakpoint for 1h / hybrid |
no |
| One-off calls (titles and other one-off generate calls) | unchanged | sent with prompt_cache_options: { mode: "explicit" } and no breakpoints, so they write nothing to the cache |
unchanged |
x-cache-ttl sentinel header stripped |
yes | yes | yes |
Cache usage observed (sidebar cached row) |
yes | yes | yes |
| Keepalive pings | yes (5m, 1h; hybrid follows its 5m tail) | yes (30m, 12h; hybrid follows its 30m tail) | never |
The Claude column applies on the Anthropic Messages and Chat Completions wires, for any provider ID once the model is classified as Claude; a Claude model on the Responses API is only observed, like an implicit one. Claude models cache only where a request marks a breakpoint. OpenCode's openrouter provider marks them for anthropic/* models, but its openai-compatible provider marks none, so the plugin adds the same three (the last tool, the system prompt, the last message) when the request has no cache_control at all. Other models, such as DeepSeek's, cache on the provider's side with no breakpoints to rewrite. The plugin only reads the usage in their responses.
| Mode | Chat Completions | Responses |
|---|---|---|
5m |
nothing (automatic 30m cache) | nothing (automatic 30m cache) |
1h |
prompt_cache_breakpoint: { mode: "explicit", ttl: "12h" } on the last text part of the last user, system, developer or tool message |
the same breakpoint on the last input_text part of a user or system message, or of a trailing tool output (function_call_output, whose string output is turned into an input_text part first), walking back past tool calls and assistant output |
hybrid |
the 12h breakpoint on the last text part of the leading system messages; the tail keeps the automatic 30m cache | the same breakpoint on the first input item, whatever its role: instructions is a plain string that can't carry one, and the prefix up to that item (instructions, tools, the first message) is the same every turn |
| titles and other one-off generate calls | prompt_cache_options: { mode: "explicit" }, no breakpoints |
the same |
The plugin never sends a request-level prompt_cache_options.ttl. It is ignored on Chat Completions and OpenRouter rejects it with a 400 on Responses unless mode is "explicit", and explicit mode on a normal turn would disable the automatic cache for the message tail. The 12h lifetime is always a ttl on the breakpoint itself. Pings are never changed beyond aligning their messages with the session's last request.
OpenAI's usage reports how many tokens were read and written but not the lifetime, so the sidebar shows ttl 30m (requested) or ttl 12h (requested).
Older models such as gpt-5 answer 400 to prompt_cache_options and prompt_cache_breakpoint, so the plugin never sends them. A model counts as GPT-5.6+ only when its name matches (gpt-5.6 and up, gpt-6 and up) or when you map it yourself with "openai" in cacheProfiles.
On the Messages wire, requests to the anthropic and omniroute-anthropic providers are always Claude and skip the list below. Any other provider ID on any wire goes through it. Examples of Anthropic-compatible endpoints under another provider ID:
| Endpoint, model | Profile | Result |
|---|---|---|
Claude model on a proxy's /messages (name contains claude, or starts with anthropic/) |
anthropic |
The session's TTL mode and the beta header are applied, and keepalive pings |
DeepSeek, Kimi, MiniMax or GLM on their /messages endpoint, or OpenRouter /api/v1/messages with a non-Claude model |
implicit |
Observed only: nothing is rewritten and no pings are sent |
A Claude alias without "claude" in its name (auto/fast) |
implicit until a response or a cacheProfiles entry says otherwise |
Learned from the model the latest response reported |
A model counts as Claude or GPT-5.6+, in this order:
- Your
cacheProfilespatterns (see Settings):"anthropic","openai"or"implicit". On the Messages wire (/messages) an"openai"entry has no effect: the OpenAI profile doesn't apply to that wire, so the model falls back toimplicit(observed only). - Its name: the OpenCode model ID or the
modelin the request body containsclaude, or has ananthropic/prefix (as inopenrouter/anthropic/…) for Claude; matches the GPT-5.6+ pattern above for OpenAI. - What the latest response said it ran on, for Claude only: the response's
modelorproviderfield names Anthropic or Claude (on the Messages wire, themodelthe response reports). This is how an alias such asauto/opus-5gets picked up. The result applies from the next request and is remembered across restarts, so a Claude alias is unmanaged for its first turn only. A router alias that switches models runs one turn behind, and on the Messages wire a request it rejects (status 400 or 422) drops the learned entry; rate-limit and server errors keep it. A response naming a GPT-5.6+ model never makes an aliasopenai: a router alias can send its next turn to an older model, which answers the OpenAI cache fields with a 400. Map an alias that always lands on GPT-5.6+ yourself with"openai"incacheProfiles, for example"auto/coding": "openai".
Anything else is treated as implicit. A -1h variant on an implicit model has its x-cache-ttl header stripped and nothing else changed.
On Chat Completions, Claude requests in 1h and hybrid carry the same anthropic-beta: extended-cache-ttl-2025-04-11 header as on the Anthropic wire. OpenRouter adds it itself, but some proxies need it before they honour the 1h TTL. GPT requests never get that header. The OpenAI usage format doesn't say which TTL the provider granted, so the sidebar shows ttl 1h (requested) for Claude there, and 30m or 12h for GPT.
OmniRoute forwards prompt_cache_options but currently drops prompt_cache_breakpoint. Through it, caching turned off on one-off calls works, while the 12h lifetime (1h and hybrid modes) does not reach OpenAI yet: the request is expected to be billed as the automatic 30m cache (observed in the probe, not measured for every route). This is fixed upstream in OmniRoute PR #18255 (issue #18254, merged 2026-10-27) but not yet in a release (the latest is v3.8.52); until a release includes it, reach GPT-5.6+ through OpenRouter or OpenAI directly if you want 12h. In 1h keepalive still pings on the 12h schedule, so on OmniRoute those pings are expected to arrive after the 30m cache is gone and miss (expected, not measured). Use 5m for GPT sessions on such a proxy until a release includes the fix.
Example provider configs with -1h variants:
- examples/opencode.anthropic.jsonc: Claude through an Anthropic Messages endpoint
- examples/opencode.openrouter.jsonc: Claude and a non-Claude model through OpenCode's built-in
openrouterprovider - examples/opencode.openai-compatible.jsonc: a generic OpenAI-compatible proxy
- examples/opencode.openai.jsonc: GPT-5.6+ through OpenCode's native
openaiprovider (Responses)
The claude-agent provider runs the claude CLI as a subprocess, so its requests skip OpenCode's HTTP layer and the plugin's hooks never fire. The plugin can't rewrite these requests, change their TTL or ping them, and /cache-manager has no effect on them.
The sidebar reads the session's model and token counts from OpenCode instead. Those counts have no TTL split, so the ttl row is a fixed 1h (detected): it comes from the CLI's own usage, which reported only 1h cache writes when this was checked, and isn't read per session. If the CLI changes its TTL, the row won't follow.
Providers change their caching often. This table reflects their documentation as of October 2026; check the sources below for the current rules.
| Provider | How it caches | Cache lifetime | Cache writes cost | This plugin |
|---|---|---|---|---|
| Anthropic (Claude) | Explicit cache_control breakpoints (up to 4), or one top-level cache_control |
5m or 1h, chosen per breakpoint | 1.25x input (5m), 2x input (1h) | Managed: TTL, breakpoints, keepalive |
| OpenAI, GPT-5.6 and later | Automatic by default. Optional explicit prompt_cache_breakpoint on text blocks (with its own ttl), and prompt_cache_options: { mode } on the request |
At least 30m (default) or 12h | 1.25x input (30m), 2.5x input (12h), also when caching is automatic | Managed: 12h breakpoints, caching off for one-off calls, keepalive |
| OpenAI, before GPT-5.6 | Automatic. prompt_cache_key helps route related requests to the same cache |
prompt_cache_retention: in_memory (about 5 to 10 minutes idle, up to 1 hour) or 24h |
Free | Observed only |
| Alibaba (Qwen, and some DeepSeek models on OpenRouter) | Explicit cache_control breakpoints, same syntax as Anthropic |
5m | 1.25x input | Observed only. Can be opted in with cacheProfiles ("anthropic"), but the plugin then also applies Claude's TTL handling |
| Google Gemini 2.5 and later | Automatic. On OpenRouter, a cache_control breakpoint also works, and only the last one is used |
Automatic: 3 to 5 minutes on average. Breakpoint: 5m, not extended by reads | Free (automatic). Input price plus 5 minutes of storage (breakpoint) | Observed only |
| DeepSeek | Automatic, on disk | Cleared when unused, usually within a few hours to a few days | Same as input | Observed only |
| Grok, Moonshot, Groq, Z.AI | Automatic | Not documented | Free | Observed only |
A few details that matter for long agent sessions:
- OpenAI GPT-5.6 and later bill every cache write, even with automatic caching. A one-off prompt of 1,024 tokens or more therefore costs more with caching on. Setting
prompt_cache_options.modeto"explicit"with no breakpoints turns caching off for that request. A request-levelprompt_cache_options.ttlis ignored on Chat Completions and rejected on Responses through OpenRouter (it requiresmode: "explicit", which turns off the automatic cache for the tail); the 12h lifetime works through attlonprompt_cache_breakpoint, which is what the plugin sends. Older models such asgpt-5answer 400. - OpenRouter keeps a session on the same provider (sticky routing) while caching pays off, for up to 10 idle minutes. It uses the
session_idbody field orx-session-idheader as the key when present, which OpenCode sends.
- OpenRouter: Prompt caching (all providers above, sticky routing,
session_id) - Anthropic: Prompt caching
- OpenAI: Prompt caching
- DeepSeek: Context caching
- Google: Gemini context caching and implicit caching announcement
- Z.AI: Context caching
- Groq: Prompt caching