Session Pruning

Session pruning cắt bỏ kết quả tool cũ khỏi context trong bộ nhớ ngay trước mỗi lần gọi LLM. Nó không ghi đè lịch sử session trên ổ đĩa (*.jsonl).

Khi nào nó chạy

  • Khi mode: "cache-ttl" được bật và lần gọi Anthropic cuối cùng của session cũ hơn ttl.
  • Chỉ ảnh hưởng đến các message gửi cho model trong request đó.
  • Chỉ hoạt động với Anthropic API (và các model Anthropic trên OpenRouter).
  • Để có kết quả tốt nhất, hãy đặt ttl khớp với cacheControlTtl của model.
  • Sau khi prune, cửa sổ TTL được reset nên các request tiếp theo giữ cache cho đến khi ttl hết hạn lần nữa.

Cài đặt mặc định thông minh (Anthropic)

  • OAuth hoặc setup-token profiles: bật cache-ttl pruning và đặt heartbeat thành 1h.
  • API key profiles: bật cache-ttl pruning, đặt heartbeat thành 30m, và mặc định cacheControlTtl thành 1h trên các model Anthropic.
  • Nếu các bạn đặt bất kỳ giá trị nào trong số này một cách rõ ràng, OpenClaw sẽ không ghi đè chúng.

Điều này cải thiện gì (chi phí + hành vi cache)

  • Tại sao cần prune: Anthropic prompt caching chỉ áp dụng trong TTL. Nếu session không hoạt động quá TTL, request tiếp theo sẽ cache lại toàn bộ prompt trừ khi các bạn cắt bớt nó trước.
  • Cái gì rẻ hơn: pruning giảm kích thước cacheWrite cho request đầu tiên sau khi TTL hết hạn.
  • Tại sao việc reset TTL quan trọng: một khi pruning chạy, cửa sổ cache được reset, nên các request tiếp theo có thể tái sử dụng prompt vừa được cache thay vì cache lại toàn bộ lịch sử.
  • Nó không làm gì: pruning không thêm token hay “nhân đôi” chi phí; nó chỉ thay đổi cái gì được cache trong request đầu tiên sau TTL đó.

Cái gì có thể bị prune

  • Chỉ các message toolResult.
  • Message của user + assistant không bao giờ bị sửa đổi.
  • keepLastAssistants message assistant cuối cùng được bảo vệ; kết quả tool sau ngưỡng đó không bị prune.
  • Nếu không có đủ message assistant để thiết lập ngưỡng, pruning sẽ bị bỏ qua.
  • Kết quả tool chứa image blocks sẽ bị bỏ qua (không bao giờ bị trim/xóa).

Ước tính cửa sổ context

Pruning sử dụng cửa sổ context ước tính (ký tự ≈ token × 4). Cửa sổ cơ bản được xác định theo thứ tự sau:

  1. Override models.providers.*.models[].contextWindow.
  2. contextWindow định nghĩa model (từ model registry).
  3. Mặc định 200000 token.

Nếu agents.defaults.contextTokens được đặt, nó được coi là giới hạn (min) trên cửa sổ đã xác định.

Mode

cache-ttl

  • Pruning chỉ chạy nếu lần gọi Anthropic cuối cùng cũ hơn ttl (mặc định 5m).
  • Khi nó chạy: hành vi soft-trim + hard-clear giống như trước.

Soft vs hard pruning

  • Soft-trim: chỉ dành cho kết quả tool quá lớn.
    • Giữ đầu + đuôi, chèn ..., và thêm ghi chú với kích thước gốc.
    • Bỏ qua kết quả có image blocks.
  • Hard-clear: thay thế toàn bộ kết quả tool bằng hardClear.placeholder.

Chọn tool

  • tools.allow / tools.deny hỗ trợ wildcard *.
  • Deny thắng.
  • Matching không phân biệt chữ hoa chữ thường.
  • Danh sách allow rỗng => tất cả tool được phép.

Tương tác với các giới hạn khác

  • Các tool built-in đã tự cắt ngắn output của chúng; session pruning là một lớp bổ sung ngăn các cuộc trò chuyện dài tích lũy quá nhiều output tool trong context của model.
  • Compaction là riêng biệt: compaction tóm tắt và lưu trữ, pruning là tạm thời cho mỗi request. Xem /concepts/compaction.

Giá trị mặc định (khi được bật)

  • 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]" }

Ví dụ

Mặc định (tắt):

{
  agent: {
    contextPruning: { mode: "off" },
  },
}

Bật pruning theo TTL:

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

Giới hạn pruning cho các tool cụ thể:

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

Xem tài liệu cấu hình: Gateway Configuration