Problem

When cacheRetention: "long" is explicitly configured for Anthropic models routed through OpenRouter, the resulting requests carry cache_control: { type: "ephemeral" } without ttl: "1h". This means only 5-minute prompt cache lifetime instead of the expected 1 hour — a significant cost regression for heavy users. Additionally, cacheRetention: "none" was also silently ignored — the OpenRouter wrapper always injected ephemeral cache markers regardless.

The same cacheRetention: "long" config works correctly when using the direct Anthropic API.

Root Cause

Three bugs in sequence:

1. resolveCacheRetention() — early return ignores explicit config

src/agents/pi-embedded-runner/prompt-cache-retention.ts

The function checked resolveAnthropicCacheRetentionFamily() first. For provider: "openrouter", this returns undefined (not a recognized Anthropic/Google cache family). The subsequent early return:

if (!family && !googleEligible) {
  return undefined;
}

exited before ever checking extraParams.cacheRetention. Even with cacheRetention: "long" explicitly set in config, the function never reached that check.

Fix: Move explicit-config checks (cacheRetention / legacy cacheControlTtl) before the family-based early return, so operator-specified retention always wins.

2. applyAnthropicEphemeralCacheControlMarkers() — hardcoded no-TTL markers

src/agents/anthropic-payload-policy.ts

Called by createOpenRouterSystemCacheWrapper, this function always wrote { type: "ephemeral" } — even if the wrapper had resolved a cacheControl with ttl: "1h", the TTL was discarded.

Fix: Accept an optional cacheControl: AnthropicEphemeralCacheControl parameter (defaults to { type: "ephemeral" } for backward compat). Also export resolveAnthropicEphemeralCacheControl() so the wrapper can build the proper marker with TTL.

3. cacheRetention: "none" still injected markers

src/agents/pi-embedded-runner/proxy-stream-wrappers.ts

When cacheRetention is "none", resolveAnthropicEphemeralCacheControl correctly returns undefined, but the wrapper's cacheControl ?? { type: "ephemeral" } fallback still injected a short-cache marker — contradicting the operator's explicit opt-out.

Fix: Skip marker insertion entirely when cacheRetention === "none".

Before / After

Before (OpenRouter→Anthropic, cacheRetention: "long"):

"cache_control": { "type": "ephemeral" }

After (same config):

"cache_control": { "type": "ephemeral", "ttl": "1h" }

After (cacheRetention: "none"): no cache_control markers at all.

Review Fix: endpoint-class gate in resolveCacheRetention

Initial patch checked provider === "openrouter" in resolveCacheRetention(), but this did not account for baseUrl. If a user repoints the OpenRouter provider at a custom OpenAI-compatible proxy, the system wrapper correctly skips markers via the endpoint-class gate, but resolveCacheRetention() would still pass cacheRetention through to pi-ai — leaking cache_control with TTL to that proxy path.

Fix: resolveCacheRetention() now accepts an optional baseUrl parameter and uses resolveProviderRequestPolicy to determine endpointClass, mirroring the same gate as createOpenRouterSystemCacheWrapper. Both call sites in extra-params.ts pass model.baseUrl / callModel.baseUrl.

Regression tests added:

• OpenRouter provider + non-OpenRouter baseUrl → undefined (no leak)
• OpenRouter provider + default (unset) baseUrl → honoured
• OpenRouter provider + openrouter.ai baseUrl → honoured

Real Behavior Proof

Behavior or issue addressed: cacheRetention: "long" config was silently ignored for OpenRouter→Anthropic models. Requests always got 5-minute ephemeral cache markers instead of 1-hour TTL. cacheRetention: "none" was also ignored — markers were always injected.

Real environment tested: Self-hosted OpenClaw v2026.5.7 on VMware VM (Linux Mint), OpenRouter provider, model openrouter/anthropic/claude-haiku-4.5 with params.cacheRetention: "long". Outbound request payloads captured via HTTPS logging proxy.

Exact steps or command run after the patch:

1. Built patched dist from fork branch cherry-picked onto v2026.5.7 tag
2. Replaced dist/ in production install and restarted gateway
3. Sent test message to Haiku model via Telegram
4. Captured outbound request payload through logging proxy

Evidence after fix:

=== Captured request payload (after patch, v2026.5.7) ===
model: anthropic/claude-haiku-4.5
system message: cache_control: { "type": "ephemeral", "ttl": "1h" }
last user message: cache_control: { "type": "ephemeral", "ttl": "1h" }
last tool definition: cache_control: { "type": "ephemeral", "ttl": "1h" }

Observed result after the fix: All 3 cache_control markers in the Anthropic-format payload now include "ttl": "1h". Before the patch (same config, unpatched v2026.5.7), all 3 markers had only { "type": "ephemeral" } without ttl. The fix restores the expected 1-hour prompt cache lifetime on the Anthropic backend, matching the direct Anthropic API behavior. When cacheRetention: "none" is set, no cache markers are injected.

What was not tested: Cache hit/miss ratio on the Anthropic backend side (only verified outbound cache_control markers). Did not test with provider: "anthropic" direct API (already working). Did not test cacheRetention: "none" end-to-end (unit test coverage only).

Changes

Tests

Related

• PR Respect cacheRetention for OpenRouter Anthropic models #42961 — addressed similar issue but targeted an older code architecture before the endpoint-class gating refactor
• PR fix(openrouter): gate prompt cache markers by endpoint #60761 — gates cache markers by endpoint class (orthogonal to this fix which is about TTL preservation)