Bug Summary

OpenClaw's built-in safeguard compaction (compaction.mode: "safeguard") does not fire when using Anthropic models (Claude Opus, Sonnet) with prompt caching enabled. The API's usage response reports reduced token counts for cached content, causing OpenClaw to underestimate the actual context size. The session grows past the context window with no compaction triggered.

Reproduction

Environment:

• OpenClaw v2026.2.26
• Model: anthropic/claude-opus-4.6 (200K context) via OpenRouter
• Config: compaction.mode: "safeguard", reserveTokensFloor: 30000, contextPruning.mode: "off"

What happened:

1. Bot (Aria) was in active conversation. Session file grew steadily.
2. At ~96% context (~192K tokens based on session file size), the bot reported its context percentage.
3. Shortly after, the bot reported context had "dropped" from 96% to 77% — no compaction fired, no session reset, no tier generation.
4. Session file continued growing past 200K tokens (101%+ of context window) with zero safeguard intervention.
5. Session file reached 806KB (~201K tokens) before a manual /new was issued.
6. Safeguard compaction, which should fire when only reserveTokensFloor (30K) tokens remain free (~85% context), never triggered.

Session file evidence:

84ec093c-....jsonl: 814,708 bytes (~203,677 tokens, ~101%) — no compaction event in gateway logs

Gateway logs show zero compaction-related entries during the entire session.

Root Cause Analysis

Anthropic's prompt caching returns reduced token counts in the API usage response. Cached tokens are reported differently (lower effective count) than the actual tokens present in the session. OpenClaw appears to use the API's reported token usage to determine context fullness rather than measuring the actual session file size or counting tokens sent.

This means:

• Actual context: 200K+ tokens (session file: 806KB)
• API-reported context: ~154K tokens (77%) due to cache optimization
• OpenClaw's view: "We're at 77%, safeguard threshold not reached"
• Reality: Session has overflowed the context window

The "drop" from 96% to 77% was the prompt cache kicking in mid-session, not any actual reduction in context size.

Impact

• Every bot using Anthropic models with prompt caching has a non-functional safeguard compaction safety net
• Sessions can silently overflow the context window
• No warning, no compaction, no memory flush — the bot runs until the API starts truncating or erroring
• Particularly dangerous for bots handling sensitive data (vault-classified content) where graceful compaction is critical for memory preservation

Expected Behavior

Safeguard compaction should use the actual session token count (measured from session file size or total tokens sent) rather than relying on the API's cached usage response. The session file is the source of truth — it contains every message, tool call, and bootstrap injection regardless of what the API caches.

Suggested Fix

Use session file size estimation (e.g., file_size_bytes * 0.65 / 4 — accounting for JSONL overhead) as the primary metric for safeguard threshold checks, or at minimum as a cross-check against API-reported usage. If the session file estimate exceeds the threshold even when API usage doesn't, safeguard should fire.

Environment Details

• OS: Ubuntu 24.04.4 LTS
• Node: v22.22.0
• OpenClaw: v2026.2.26
• Provider: OpenRouter (Anthropic Claude Opus 4.6)
• Prompt caching: enabled (Anthropic default)