docs: document cacheRetention parameter (#6270)

* docs: document cacheRetention parameter (#6240)

* docs: standardize cacheRetention value quoting style

* style: format anthropic.md table

* Docs: align cacheRetention inline example

---------

Co-authored-by: Sebastian <sebslight@gmail.com>

docs/concepts/session-pruning.md

@@ -15,13 +15,13 @@ Session pruning trims **old tool results** from the in-memory context right befo
 - When `mode: "cache-ttl"` is enabled and the last Anthropic call for the session is older than `ttl`.
 - Only affects the messages sent to the model for that request.
 - Only active for Anthropic API calls (and OpenRouter Anthropic models).
-- For best results, match `ttl` to your model `cacheControlTtl`.
+- For best results, match `ttl` to your model `cacheRetention`.
 - After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again.
 
 ## Smart defaults (Anthropic)
 
 - **OAuth or setup-token** profiles: enable `cache-ttl` pruning and set heartbeat to `1h`.
-- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheControlTtl` to `1h` on Anthropic models.
+- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheRetention: "short"` on Anthropic models.
 - If you set any of these values explicitly, OpenClaw does **not** override them.
 
 ## What this improves (cost + cache behavior)

docs/providers/anthropic.md

@@ -37,10 +37,17 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
 
 ## Prompt caching (Anthropic API)
 
-OpenClaw does **not** override Anthropic’s default cache TTL unless you set it.
+OpenClaw supports Anthropic's prompt caching feature. This is **API-only**; subscription auth does not honor cache settings.
-This is **API-only**; subscription auth does not honor TTL settings.
 
-To set the TTL per model, use `cacheControlTtl` in the model `params`:
+### Configuration
+
+Use the `cacheRetention` parameter in your model config:
+
+| Value   | Cache Duration | Description                         |
+| ------- | -------------- | ----------------------------------- |
+| `none`  | No caching     | Disable prompt caching              |
+| `short` | 5 minutes      | Default for API Key auth            |
+| `long`  | 1 hour         | Extended cache (requires beta flag) |
 
 ```json5
 {
@@ -48,7 +55,7 @@ To set the TTL per model, use `cacheControlTtl` in the model `params`:
     defaults: {
       models: {
         "anthropic/claude-opus-4-5": {
-          params: { cacheControlTtl: "5m" }, // or "1h"
+          params: { cacheRetention: "long" },
         },
       },
     },
@@ -56,6 +63,19 @@ To set the TTL per model, use `cacheControlTtl` in the model `params`:
 }
 ```
 
+### Defaults
+
+When using Anthropic API Key authentication, OpenClaw automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config.
+
+### Legacy parameter
+
+The older `cacheControlTtl` parameter is still supported for backwards compatibility:
+
+- `"5m"` maps to `short`
+- `"1h"` maps to `long`
+
+We recommend migrating to the new `cacheRetention` parameter.
+
 OpenClaw includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
 requests; keep it if you override provider headers (see [/gateway/configuration](/gateway/configuration)).
 

docs/token-use.md

@@ -97,7 +97,7 @@ agents:
     models:
       "anthropic/claude-opus-4-5":
         params:
-          cacheControlTtl: "1h"
+          cacheRetention: "long"
     heartbeat:
       every: "55m"
 ```