Session 修剪

Session 修剪會在每次 LLM 呼叫之前，從記憶體中的上下文裁減舊的工具結果。它不會改寫磁碟上的 Session 歷史紀錄（*.jsonl）。

觸發時機

當 mode: "cache-ttl" 啟用且該 Session 上次的 Anthropic 呼叫已超過 ttl 時觸發。
只影響該次請求傳送給模型的訊息。
僅對 Anthropic API 呼叫生效（包含 OpenRouter Anthropic 模型）。
建議將 ttl 設定為與你的模型 cacheRetention 策略一致（short = 5 分鐘，long = 1 小時），效果最佳。
修剪執行後，TTL 視窗會重設，後續請求可繼續利用快取直到 ttl 再次到期。

智慧預設值（Anthropic）

OAuth 或 setup-token Profile：啟用 cache-ttl 修剪，心跳間隔設為 1h。
API key Profile：啟用 cache-ttl 修剪，心跳間隔設為 30m，並預設 Anthropic 模型的 cacheRetention: "short"。
如果你手動設定了上述任何值，OpenClaw 不會覆蓋。

帶來的改善（成本 + 快取行為）

為什麼要修剪： Anthropic 提示快取只在 TTL 期間有效。如果 Session 閒置超過 TTL，下一次請求會重新快取完整提示——除非你先裁減它。
省在哪裡： 修剪降低了 TTL 過期後首次請求的 cacheWrite 大小。
TTL 重設為什麼重要： 修剪執行後快取視窗重設，後續請求可以重用剛快取好的提示，而不是再次重新快取整個歷史。
它不會做的事： 修剪不會增加 Token 或讓成本「翻倍」；它只改變 TTL 過期後首次請求的快取內容。

可被修剪的內容

只有 toolResult 訊息。
使用者和助理訊息永遠不會被修改。
最後 keepLastAssistants 筆助理訊息受保護；該分界點之後的工具結果不會被修剪。
若助理訊息數不足以建立分界點，則跳過修剪。
包含圖片區塊的工具結果會被跳過（永遠不會被裁減或清除）。

上下文視窗估算

修剪使用估算的上下文視窗大小（字元數 ≈ Token 數 x 4）。基礎視窗依以下順序決定：

models.providers.*.models[].contextWindow 覆蓋值。
模型定義的 contextWindow（來自模型註冊表）。
預設 200000 Token。

若設定了 agents.defaults.contextTokens，會作為解析後視窗大小的上限（取較小值）。

模式

cache-ttl

只在上次 Anthropic 呼叫已超過 ttl（預設 5m）時才執行修剪。
執行時：相同的軟裁減 + 硬清除行為。

軟裁減 vs 硬清除

軟裁減（Soft-trim）：僅針對超大的工具結果。
- 保留頭部 + 尾部，中間插入 ...，並附加原始大小的說明。
- 跳過含有圖片區塊的結果。
硬清除（Hard-clear）：以 hardClear.placeholder 取代整個工具結果。

工具篩選

tools.allow / tools.deny 支援 * 萬用字元。
Deny 優先。
比對不區分大小寫。
Allow 清單為空 => 所有工具皆允許。

與其他限制的交互

內建工具本身已會截斷輸出；Session 修剪是額外的一層防護，避免長時間對話在模型上下文中累積過多工具輸出。
壓縮（Compaction）是獨立機制：壓縮會摘要並持久化，修剪則是每次請求的暫時性處理。參閱 /concepts/compaction。

預設值（啟用時）

ttl: "5m"
keepLastAssistants: 3
softTrimRatio: 0.3
hardClearRatio: 0.5
minPrunableToolChars: 50000
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

範例

預設（關閉）：

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

啟用 TTL 感知修剪：

{
  agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m" } } },
}

限制修剪只針對特定工具：

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

設定參考：Gateway Configuration