English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

Prompt önbellekleme

Prompt önbellekleme, model sağlayıcısının her turda değişmemiş prompt öneklerini (genellikle system/developer talimatları ve diğer kararlı bağlamlar) yeniden işleyip durmak yerine yeniden kullanabilmesi anlamına gelir. OpenClaw, yukarı akış API bu sayaçları doğrudan açığa çıkardığında sağlayıcı kullanımını cacheRead ve cacheWrite olarak normalize eder.

Durum yüzeyleri, canlı oturum anlık görüntüsünde önbellek sayaçları eksik olduğunda bunları en son döküm kullanım günlüğünden de kurtarabilir; böylece /status, kısmi oturum meta verisi kaybından sonra da bir önbellek satırı göstermeye devam edebilir. Mevcut sıfır olmayan canlı önbellek değerleri yine de döküm geri dönüş değerlerine göre önceliklidir.

Bunun önemi: daha düşük token maliyeti, daha hızlı yanıtlar ve uzun süreli oturumlar için daha öngörülebilir performans. Önbellekleme olmadan, tekrar eden prompt'lar girişin büyük kısmı değişmese bile her turda tam prompt maliyetini öder.

Aşağıdaki bölümler prompt yeniden kullanımını ve token maliyetini etkileyen her önbellek düğmesini kapsar.

Sağlayıcı başvuruları:

Birincil düğmeler

cacheRetention (genel varsayılan, model ve aracı başına)

Önbellek tutmayı tüm modeller için genel varsayılan olarak ayarlayın:

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

Model başına geçersiz kılın:

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

Aracı başına geçersiz kılma:

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

Config birleştirme sırası:

  1. agents.defaults.params (genel varsayılan — tüm modellere uygulanır)
  2. agents.defaults.models["provider/model"].params (model başına geçersiz kılma)
  3. agents.list[].params (eşleşen aracı kimliği; anahtara göre geçersiz kılar)

contextPruning.mode: "cache-ttl"

Eski araç sonucu bağlamını önbellek TTL pencerelerinden sonra budar; böylece boşta kalma sonrası istekler aşırı büyük geçmişi yeniden önbelleğe almaz.

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

Tam davranış için bkz. Session Pruning.

Heartbeat keep-warm

Heartbeat, önbellek pencerelerini sıcak tutabilir ve boşta kalma aralarından sonra tekrarlanan önbellek yazımlarını azaltabilir.

agents:
  defaults:
    heartbeat:
      every: "55m"

Aracı başına Heartbeat, agents.list[].heartbeat altında desteklenir.

Sağlayıcı davranışı

Anthropic (doğrudan API)

  • cacheRetention desteklenir.
  • Anthropic API anahtarı kimlik doğrulama profilleriyle OpenClaw, ayarlanmadığında Anthropic model referansları için cacheRetention: "short" tohumlar.
  • Anthropic yerel Messages yanıtları hem cache_read_input_tokens hem cache_creation_input_tokens açığa çıkarır; bu yüzden OpenClaw hem cacheRead hem cacheWrite gösterebilir.
  • Yerel Anthropic isteklerinde cacheRetention: "short", varsayılan 5 dakikalık ephemeral önbelleğe eşlenir; cacheRetention: "long" ise yalnızca doğrudan api.anthropic.com ana makinelerinde 1 saatlik TTL'ye yükseltir.

OpenAI (doğrudan API)

  • Prompt önbellekleme, desteklenen yeni modellerde otomatiktir. OpenClaw'ın blok düzeyinde önbellek işaretçileri enjekte etmesi gerekmez.
  • OpenClaw, turlar arasında önbellek yönlendirmesini kararlı tutmak için prompt_cache_key kullanır ve cacheRetention: "long" doğrudan OpenAI ana makinelerinde seçildiğinde yalnızca prompt_cache_retention: "24h" kullanır.
  • OpenAI uyumlu Completions sağlayıcıları, prompt_cache_key değerini yalnızca model config'i açıkça compat.supportsPromptCacheKey: true ayarladığında alır; cacheRetention: "none" bunu yine de bastırır.
  • OpenAI, önbelleğe alınmış prompt token'larını usage.prompt_tokens_details.cached_tokens (veya Responses API olaylarında input_tokens_details.cached_tokens) üzerinden açığa çıkarır. OpenClaw bunu cacheRead alanına eşler.
  • OpenAI ayrı bir önbellek-yazma token sayacı açığa çıkarmaz; bu nedenle sağlayıcı önbelleği ısıtıyor olsa bile OpenAI yollarında cacheWrite 0 kalır.
  • OpenAI, x-request-id, openai-processing-ms ve x-ratelimit-* gibi yararlı izleme ve rate-limit başlıkları döndürür, ancak önbellek isabeti hesabı başlıklardan değil kullanım yükünden gelmelidir.
  • Uygulamada OpenAI, Anthropic tarzı kayan tam geçmiş yeniden kullanımı yerine genellikle ilk önek önbelleği gibi davranır. Kararlı uzun önekli metin turları geçerli canlı problarda 4864 önbelleğe alınmış token platosuna yaklaşabilirken, araç ağırlıklı veya MCP tarzı dökümler tam tekrarlar üzerinde bile genellikle 4608 önbelleğe alınmış token civarında plato yapar.

Anthropic Vertex

  • Vertex AI üzerindeki Anthropic modelleri (anthropic-vertex/*), cacheRetention desteğini doğrudan Anthropic ile aynı şekilde sunar.
  • cacheRetention: "long", Vertex AI uç noktalarında gerçek 1 saatlik prompt önbellek TTL'sine eşlenir.
  • anthropic-vertex için varsayılan önbellek tutma, doğrudan Anthropic varsayılanlarıyla eşleşir.
  • Vertex istekleri sınır farkında önbellek şekillendirmesi üzerinden yönlendirilir; böylece önbellek yeniden kullanımı sağlayıcıların gerçekten aldıklarıyla hizalı kalır.

Amazon Bedrock

  • Anthropic Claude model referansları (amazon-bedrock/*anthropic.claude*) açık cacheRetention geçiş desteği sunar.
  • Anthropic olmayan Bedrock modelleri çalışma zamanında zorla cacheRetention: "none" yapılır.

OpenRouter modelleri

openrouter/anthropic/* model referansları için OpenClaw, Anthropic cache_control değerini yalnızca istek hâlâ doğrulanmış bir OpenRouter yolunu hedefliyorsa (openrouter varsayılan uç noktasında veya openrouter.ai'ye çözümlenen herhangi bir sağlayıcı/base URL üzerinde) sistem/geliştirici prompt bloklarına enjekte eder; bu, prompt önbelleği yeniden kullanımını iyileştirir.

openrouter/deepseek/*, openrouter/moonshot*/* ve openrouter/zai/* model referansları için contextPruning.mode: "cache-ttl" izinlidir çünkü OpenRouter sağlayıcı tarafı prompt önbelleklemesini otomatik yönetir. OpenClaw bu isteklere Anthropic cache_control işaretçileri enjekte etmez.

DeepSeek önbellek oluşturma en iyi çaba esaslıdır ve birkaç saniye sürebilir. Hemen gelen takip isteği yine de cached_tokens: 0 gösterebilir; kısa bir gecikmeden sonra aynı önekli tekrarlı istekle doğrulayın ve önbellek isabet sinyali olarak usage.prompt_tokens_details.cached_tokens kullanın.

Modeli keyfi bir OpenAI uyumlu proxy URL'sine yeniden yönlendirirseniz, OpenClaw bu OpenRouter'a özgü Anthropic önbellek işaretçilerini enjekte etmeyi bırakır.

Diğer sağlayıcılar

Sağlayıcı bu önbellek modunu desteklemiyorsa cacheRetention etkisizdir.

Google Gemini doğrudan API

  • Doğrudan Gemini aktarımı (api: "google-generative-ai"), önbellek isabetlerini yukarı akış cachedContentTokenCount üzerinden bildirir; OpenClaw bunu cacheRead alanına eşler.
  • Doğrudan bir Gemini modelinde cacheRetention ayarlandığında, OpenClaw Google AI Studio çalıştırmalarında sistem prompt'ları için cachedContents kaynaklarını otomatik olarak oluşturur, yeniden kullanır ve yeniler. Bu, artık önbelleğe alınmış içerik tutamacını önceden manuel oluşturmanız gerekmediği anlamına gelir.
  • Yine de daha önce var olan bir Gemini önbelleğe alınmış içerik tutamacını yapılandırılmış model üzerinde params.cachedContent (veya eski params.cached_content) olarak geçebilirsiniz.
  • Bu, Anthropic/OpenAI prompt önek önbelleklemesinden ayrıdır. Gemini için OpenClaw, isteğe önbellek işaretçileri enjekte etmek yerine sağlayıcıya özgü bir cachedContents kaynağı yönetir.

Gemini CLI JSON kullanımı

  • Gemini CLI JSON çıktısı ayrıca önbellek isabetlerini stats.cached üzerinden de gösterebilir; OpenClaw bunu cacheRead alanına eşler.
  • CLI doğrudan stats.input değeri vermezse OpenClaw giriş token'larını stats.input_tokens - stats.cached üzerinden türetir.
  • Bu yalnızca kullanım normalizasyonudur. OpenClaw'ın Gemini CLI için Anthropic/OpenAI tarzı prompt önbellek işaretçileri oluşturduğu anlamına gelmez.

Sistem prompt'u önbellek sınırı

OpenClaw, sistem prompt'unu dahili bir önbellek önek sınırı ile ayrılmış kararlı önek ve oynak sonek olarak böler. Sınırın üstündeki içerik (araç tanımları, Skills meta verileri, çalışma alanı dosyaları ve diğer görece statik bağlamlar) turlar arasında bayt düzeyinde özdeş kalacak şekilde sıralanır. Sınırın altındaki içerik (örneğin HEARTBEAT.md, çalışma zamanı zaman damgaları ve tur başına diğer meta veriler) önbelleğe alınmış öneği geçersiz kılmadan değişebilir.

Temel tasarım tercihleri:

  • Kararlı çalışma alanı proje bağlamı dosyaları HEARTBEAT.md öncesine sıralanır; böylece Heartbeat dalgalanması kararlı öneği bozmaz.
  • Sınır, Anthropic ailesi, OpenAI ailesi, Google ve CLI aktarım şekillendirmesi boyunca uygulanır; böylece desteklenen tüm sağlayıcılar aynı önek kararlılığından yararlanır.
  • Codex Responses ve Anthropic Vertex istekleri sınır farkında önbellek şekillendirmesi üzerinden yönlendirilir; böylece önbellek yeniden kullanımı sağlayıcıların gerçekten aldığıyla hizalı kalır.
  • Sistem prompt fingerprint'leri normalize edilir (boşluk, satır sonları, kanca ile eklenmiş bağlam, çalışma zamanı yetenek sıralaması); böylece anlamsal olarak değişmemiş prompt'lar turlar arasında KV/önbellek paylaşır.

Bir config veya çalışma alanı değişikliğinden sonra beklenmedik cacheWrite sıçramaları görürseniz, değişikliğin önbellek sınırının üstüne mi altına mı düştüğünü kontrol edin. Oynak içeriği sınırın altına taşımak (veya onu kararlı hâle getirmek) çoğu zaman sorunu çözer.

OpenClaw önbellek kararlılığı korumaları

OpenClaw ayrıca istek sağlayıcıya ulaşmadan önce önbelleğe duyarlı çeşitli yük biçimlerini deterministik tutar:

  • Paket MCP araç katalogları, araç kaydından önce deterministik olarak sıralanır; böylece listTools() sırası değişiklikleri araç bloğunu dalgalandırıp prompt önbelleği öneklerini bozmaz.
  • Kalıcı görsel blokları içeren eski oturumlar en son tamamlanmış 3 turu bozulmadan tutar; daha eski, zaten işlenmiş görsel blokları görsel ağırlıklı takiplerin büyük bayat yükleri yeniden gönderip durmaması için bir işaretçiyle değiştirilebilir.

Ayarlama desenleri

Karışık trafik (önerilen varsayılan)

Ana aracınızda uzun ömürlü bir temel koruyun, patlamalı bildirim aracıları için önbelleği kapatın:

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

Önce maliyet temeli

  • Temel olarak cacheRetention: "short" ayarlayın.
  • contextPruning.mode: "cache-ttl" etkinleştirin.
  • Heartbeat'i yalnızca sıcak önbelleklerden faydalanan aracılar için TTL'nizin altında tutun.

Önbellek tanılaması

OpenClaw, gömülü aracı çalıştırmaları için özel önbellek izleme tanılamaları sunar.

Normal kullanıcıya dönük tanılamalar için /status ve diğer kullanım özetleri, canlı oturum girdisinde bu sayaçlar yoksa cacheRead / cacheWrite için geri dönüş kaynağı olarak en son döküm kullanım girdisini kullanabilir.

Canlı regresyon testleri

OpenClaw, tekrarlanan önekler, araç turları, görsel turları, MCP tarzı araç dökümleri ve Anthropic önbelleksiz denetimi için tek birleşik canlı önbellek regresyon geçidi tutar.

  • src/agents/live-cache-regression.live.test.ts
  • src/agents/live-cache-regression-baseline.ts

Dar canlı geçidi şununla çalıştırın:

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

Temel dosya, gözlemlenen en son canlı sayıları ve test tarafından kullanılan sağlayıcıya özgü regresyon tabanlarını saklar. Çalıştırıcı ayrıca önceki önbellek durumunun geçerli regresyon örneğini kirletmemesi için çalıştırma başına yeni oturum kimlikleri ve prompt ad alanları kullanır.

Bu testler, sağlayıcılar arasında kasıtlı olarak özdeş başarı ölçütleri kullanmaz.

Anthropic canlı beklentileri

  • cacheWrite üzerinden açık ısınma yazımları bekleyin.
  • Anthropic önbellek denetimi konuşma boyunca önbellek kırılma noktasını ilerlettiği için tekrarlanan turlarda neredeyse tam geçmiş yeniden kullanımı bekleyin.
  • Geçerli canlı doğrulamalar, kararlı, araç ve görsel yolları için hâlâ yüksek isabet oranı eşiklerini kullanır.

OpenAI canlı beklentileri

  • Yalnızca cacheRead bekleyin. cacheWrite 0 kalır.
  • Tekrarlanan tur önbellek yeniden kullanımını Anthropic tarzı kayan tam geçmiş yeniden kullanımı olarak değil, sağlayıcıya özgü bir plato olarak değerlendirin.
  • Geçerli canlı doğrulamalar, gpt-5.4-mini üzerinde gözlemlenen canlı davranıştan türetilmiş korumacı taban kontrollerini kullanır:
    • kararlı önek: cacheRead >= 4608, isabet oranı >= 0.90
    • araç dökümü: cacheRead >= 4096, isabet oranı >= 0.85
    • görsel dökümü: cacheRead >= 3840, isabet oranı >= 0.82
    • MCP tarzı döküm: cacheRead >= 4096, isabet oranı >= 0.85

2026-04-04 tarihindeki yeni birleşik canlı doğrulama şu değerlerle sonuçlandı:

  • kararlı önek: cacheRead=4864, isabet oranı 0.966
  • araç dökümü: cacheRead=4608, isabet oranı 0.896
  • görsel dökümü: cacheRead=4864, isabet oranı 0.954
  • MCP tarzı döküm: cacheRead=4608, isabet oranı 0.891

Birleşik geçit için son yerel duvar saati süresi yaklaşık 88s idi.

Doğrulamaların neden farklı olduğu:

  • Anthropic açık önbellek kırılma noktalarını ve kayan konuşma geçmişi yeniden kullanımını açığa çıkarır.
  • OpenAI prompt önbelleklemesi hâlâ tam önek duyarlıdır, ancak canlı Responses trafiğinde etkili yeniden kullanılabilir önek tam prompt'tan daha erken plato yapabilir.
  • Bu nedenle Anthropic ve OpenAI'ı tek bir sağlayıcılar arası yüzde eşiğiyle karşılaştırmak sahte regresyonlar oluşturur.

diagnostics.cacheTrace config

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # isteğe bağlı
    includeMessages: false # varsayılan true
    includePrompt: false # varsayılan true
    includeSystem: false # varsayılan true

Varsayılanlar:

  • filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
  • includeMessages: true
  • includePrompt: true
  • includeSystem: true

Env düğmeleri (tek seferlik hata ayıklama)

  • OPENCLAW_CACHE_TRACE=1, önbellek izlemesini etkinleştirir.
  • OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl, çıktı yolunu geçersiz kılar.
  • OPENCLAW_CACHE_TRACE_MESSAGES=0|1, tam mesaj yükü yakalamayı açıp kapatır.
  • OPENCLAW_CACHE_TRACE_PROMPT=0|1, prompt metni yakalamayı açıp kapatır.
  • OPENCLAW_CACHE_TRACE_SYSTEM=0|1, sistem prompt'u yakalamayı açıp kapatır.

Neye bakılmalı

  • Önbellek izleme olayları JSONL biçimindedir ve session:loaded, prompt:before, stream:context ve session:after gibi aşamalı anlık görüntüleri içerir.
  • Tur başına önbellek token etkisi normal kullanım yüzeylerinde cacheRead ve cacheWrite üzerinden görünür (örneğin /usage full ve oturum kullanım özetleri).
  • Anthropic için önbellekleme etkinken hem cacheRead hem cacheWrite bekleyin.
  • OpenAI için önbellek isabetlerinde cacheRead bekleyin ve cacheWrite değerinin 0 kalmasını bekleyin; OpenAI ayrı bir önbellek-yazma token alanı yayımlamaz.
  • İstek izleme gerekiyorsa istek kimliklerini ve rate-limit başlıklarını önbellek ölçümlerinden ayrı günlüğe kaydedin. OpenClaw'ın geçerli önbellek izleme çıktısı ham sağlayıcı yanıt başlıklarından ziyade prompt/oturum biçimine ve normalize edilmiş token kullanımına odaklanır.

Hızlı sorun giderme

  • Çoğu turda yüksek cacheWrite: oynak sistem prompt girdilerini kontrol edin ve modelin/sağlayıcının önbellek ayarlarınızı desteklediğini doğrulayın.
  • Anthropic'te yüksek cacheWrite: çoğu zaman önbellek kırılma noktasının her istekte değişen içeriğe denk geldiği anlamına gelir.
  • Düşük OpenAI cacheRead: kararlı öneğin başta olduğunu, tekrar eden öneğin en az 1024 token olduğunu ve önbellek paylaşması gereken turlar için aynı prompt_cache_key değerinin yeniden kullanıldığını doğrulayın.
  • cacheRetention etkisiz: model anahtarının agents.defaults.models["provider/model"] ile eşleştiğini doğrulayın.
  • Önbellek ayarlı Bedrock Nova/Mistral istekleri: çalışma zamanında none değerine zorlanması beklenen davranıştır.

İlgili belgeler:

İlgili