Default Anthropic cacheRetention to 1 hour for OAuth (subscription) accounts #7294

Area

Provider adapters

What are you trying to accomplish?

Use Claude models through opencodex (OAuth / Claude subscription) in Codex sessions without re-paying the whole context every time I pause for more than 5 minutes. Codex turns often pause longer than that: reading output, a long tool run, a coffee.

What prevents this today?

With the default cacheRetention: "short", every Anthropic cache entry expires 5 minutes after its last use, so the next turn rewrites the whole context. On large chats that is hundreds of thousands of tokens per pause.

What I measured (one user, ~78k Anthropic requests through opencodex 2.73, Sep 23 – Oct 16, Claude OAuth):

• The 5-minute expiry is sharp: requests 290–300 s after the previous one read the cache 91–96% of the time; at 320–360 s, 0–9%.
• Claude Code on the same accounts writes its main-chat cache at 1 hour (its own setting text: "Unset = automatic: 1 hour on a Claude subscription within its usage limits, 5 minutes on an API key"). In its transcripts it still finds the cache 79% of the time after 15–60 minute breaks.
• Replaying three weeks of this traffic with Anthropic's price ratios (write 1.25x for 5 m, 2x for 1 h, read 0.05x on Opus 5.5, output 5x), with a replay checked against the cache reads actually logged (within 0.6%): the 1 h cache used 13% less quota than 5 m over the last two weeks. Week by week it ranged from 27% less to about even (1% more). The 1 h write costs 0.75x extra on every turn's new tokens and pays back only when a turn is followed by a 5–60 minute pause, so it wins when more than about 2.4% of turns are (mine: 3.4%). Live over 44 hours after switching: 8% less. Script: https://github.com/brunoqgalvao/claude-cache-keepalive/blob/main/analysis/backtest_walkforward.py
• After switching to long, a 7-minute pause read 513k of 515k tokens from cache instead of rewriting them.

What should OpenCodex do?

1. When cacheRetention is unset, use long (1 hour) for OAuth/subscription Anthropic accounts and keep short for API-key providers, matching Claude Code. API-key users pay real money for the 2x write, and their traffic may differ.
2. Document that changing the setting makes each open conversation rewrite its cache once. 5-minute and 1-hour entries are separate: a request marked 1 h does not read a prefix written at 5 m (in a controlled test it read 0 of 48k tokens and rewrote all of them at 2x, while a 5 m control read 36.5k).

Example usage or interface

Today, to get this I have to set it by hand:

// ~/.opencodex/config.json
{ "cacheRetention": "long" }

Proposed: with no cacheRetention in the config, a request from a Claude OAuth account is sent with cache_control: { "type": "ephemeral", "ttl": "1h" }; a request through an API-key Anthropic provider keeps the 5-minute default. An explicit "short" or "long" still wins.

Before / after on my traffic: a 7-minute pause on a 515k-token chat rewrote the whole context at 1.25x with short; with long it read 513k from cache at 0.05x.

Alternatives or workarounds

• Setting cacheRetention: "long" manually works, but almost nobody knows to do it, and the 5-minute default silently costs subscription users quota on every pause.
• Keeping caches warm past 1 hour with periodic re-reads helps further on long-idle chats, but it is a separate, optional add-on and not part of this proposal.

Additional context

Measurements and method: https://github.com/brunoqgalvao/claude-cache-keepalive/blob/main/analysis/RESULTS.md

Happy to send the PR for this.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.