English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

İstem önbelleğe alma

İstem önbelleğe alma, model sağlayıcısının değişmeyen istem öneklerini (genellikle sistem/geliştirici talimatları ve diğer kararlı bağlam) her seferinde yeniden işlemek yerine turlar arasında yeniden kullanabilmesi anlamına gelir. OpenClaw, üst API bu sayaçları doğrudan sunduğunda sağlayıcı kullanımını cacheRead ve cacheWrite olarak normalleştirir.

Durum yüzeyleri, canlı oturum anlık görüntüsünde eksik olduklarında en son transkript kullanım günlüğünden önbellek sayaçlarını da 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, transkript geri dönüş değerlerine göre yine önceliklidir.

Bunun neden önemli olduğu: daha düşük token maliyeti, daha hızlı yanıtlar ve uzun süre çalışan oturumlar için daha öngörülebilir performans. Önbelleğe alma olmadan, girdinin çoğu değişmese bile tekrarlanan istemler her turda tam istem maliyetini öder.

Aşağıdaki bölümler, istem yeniden kullanımını ve token maliyetini etkileyen önbellekle ilgili her ayarı kapsar.

Sağlayıcı başvuruları:

Birincil ayarlar

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

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

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

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

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

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

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

Yapılandırma 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 ajan kimliği; anahtara göre geçersiz kılar)

contextPruning.mode: "cache-ttl"

Boşta kalma sonrası isteklerin aşırı büyük geçmişi yeniden önbelleğe almaması için önbellek TTL pencerelerinden sonra eski araç sonucu bağlamını budar.

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

Tam davranış için Oturum Budama bölümüne bakın.

Heartbeat sıcak tutma

Heartbeat, önbellek pencerelerini sıcak tutabilir ve boşta kalma aralıklarından sonra tekrarlanan önbellek yazmalarını azaltabilir.

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

Ajan başına heartbeat agents.list[].heartbeat konumunda desteklenir.

Sağlayıcı davranışı

Anthropic (doğrudan API)

  • cacheRetention desteklenir.
  • Anthropic API anahtarı kimlik doğrulama profilleriyle, ayarlanmamışsa OpenClaw Anthropic model referansları için cacheRetention: "short" tohumlar.
  • Anthropic yerel Messages yanıtları hem cache_read_input_tokens hem de cache_creation_input_tokens değerlerini sunar; bu nedenle OpenClaw hem cacheRead hem de cacheWrite gösterebilir.
  • Yerel Anthropic isteklerinde cacheRetention: "short" varsayılan 5 dakikalık geçici önbelleğe eşlenir ve cacheRetention: "long" yalnızca doğrudan api.anthropic.com hostlarında 1 saatlik TTL’ye yükseltilir.

OpenAI (doğrudan API)

  • İstem önbelleğe alma, desteklenen güncel modellerde otomatiktir. OpenClaw’ın blok düzeyinde önbellek işaretleyicileri enjekte etmesi gerekmez.
  • OpenClaw, önbellek yönlendirmesini turlar arasında kararlı tutmak için prompt_cache_key kullanır. Doğrudan OpenAI hostları, cacheRetention: "long" seçildiğinde prompt_cache_retention: "24h" kullanır.
  • OpenAI uyumlu Completions sağlayıcıları, prompt_cache_key değerini yalnızca model yapılandırmaları açıkça compat.supportsPromptCacheKey: true ayarladığında alır. Uzun saklama iletimi ayrı bir yetenektir: açık cacheRetention: "long", prompt_cache_retention: "24h" değerini yalnızca ilgili uyumluluk girdisi uzun önbellek saklamayı da desteklediğinde gönderir. Mistral gibi sağlayıcılar, uzun saklama alanını bastırmak için compat.supportsLongCacheRetention: false ayarlarken önbellek anahtarlarına katılabilir. cacheRetention: "none" her iki alanı da bastırır.
  • OpenAI yanıtları, önbelleğe alınmış istem tokenlarını usage.prompt_tokens_details.cached_tokens üzerinden (veya Responses API olaylarında input_tokens_details.cached_tokens üzerinden) sunar. OpenClaw bunu cacheRead değerine eşler.
  • GPT-5.6 Responses kullanımı ayrıca input_tokens_details.cache_write_tokens sunabilir. OpenClaw bunu cacheWrite değerine eşler ve modelin önbellek yazma oranıyla fiyatlandırır; alanı atlayan Responses, cacheWrite değerini 0 olarak tutar.
  • OpenAI, x-request-id, openai-processing-ms ve x-ratelimit-* gibi yararlı izleme ve hız sınırı üst bilgileri döndürür; ancak önbellek isabeti muhasebesi üst bilgilerden değil, kullanım yükünden gelmelidir.
  • Pratikte OpenAI çoğu zaman Anthropic tarzı hareketli tam geçmiş yeniden kullanımı yerine ilk önek önbelleği gibi davranır. Kararlı uzun önekli metin turları mevcut canlı problarda 4864 önbelleğe alınmış token platosuna yaklaşabilirken, araç ağırlıklı veya MCP tarzı transkriptler tam tekrarlarda bile genellikle 4608 önbelleğe alınmış token civarında plato yapar.

Anthropic Vertex

  • Vertex AI üzerindeki Anthropic modelleri (anthropic-vertex/*), doğrudan Anthropic ile aynı şekilde cacheRetention destekler.
  • cacheRetention: "long", Vertex AI uç noktalarında gerçek 1 saatlik istem önbelleği TTL’sine eşlenir.
  • anthropic-vertex için varsayılan önbellek saklama, doğrudan Anthropic varsayılanlarıyla eşleşir.
  • Vertex istekleri, önbellek yeniden kullanımının sağlayıcıların gerçekten aldığı içerikle hizalı kalması için sınır farkındalıklı önbellek şekillendirmesinden geçirilir.

Amazon Bedrock

  • Anthropic Claude model referansları (amazon-bedrock/*anthropic.claude*) açık cacheRetention iletimini destekler.
  • Anthropic olmayan Bedrock modelleri çalışma zamanında cacheRetention: "none" değerine zorlanır.

OpenRouter modelleri

openrouter/anthropic/* model referansları için OpenClaw, istem önbelleği yeniden kullanımını iyileştirmek amacıyla sistem/geliştirici istem bloklarına Anthropic cache_control enjekte eder; bunu yalnızca istek hâlâ doğrulanmış bir OpenRouter rotasını hedefliyorsa yapar (openrouter varsayılan uç noktasında veya openrouter.ai adresine çözümlenen herhangi bir sağlayıcı/temel URL).

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

DeepSeek önbellek oluşturma en iyi çaba esasına dayanır ve birkaç saniye sürebilir. Anında gelen takip isteği yine de cached_tokens: 0 gösterebilir; kısa bir gecikmeden sonra tekrarlanan aynı önekli bir istekle doğrulayın ve önbellek isabeti sinyali olarak usage.prompt_tokens_details.cached_tokens değerini kullanın.

Modeli rastgele bir OpenAI uyumlu proxy URL’sine yeniden yönlendirirseniz OpenClaw bu OpenRouter’a özgü Anthropic önbellek işaretleyicilerini enjekte etmeyi durdurur.

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 üst kaynak cachedContentTokenCount üzerinden bildirir; OpenClaw bunu cacheRead değerine eşler.
  • Doğrudan Gemini modelinde cacheRetention ayarlandığında OpenClaw, Google AI Studio çalıştırmalarındaki sistem istemleri için cachedContents kaynaklarını otomatik olarak oluşturur, yeniden kullanır ve yeniler. Bu, artık önbelleğe alınmış içerik tanıtıcısını elle önceden oluşturmanız gerekmediği anlamına gelir.
  • Yine de önceden var olan bir Gemini önbelleğe alınmış içerik tanıtıcısını yapılandırılmış modelde params.cachedContent (veya eski params.cached_content) olarak geçirebilirsiniz.
  • Bu, Anthropic/OpenAI istem öneki önbelleğe almadan ayrıdır. Gemini için OpenClaw, isteğe önbellek işaretleyicileri enjekte etmek yerine sağlayıcıya özgü bir cachedContents kaynağını yönetir.

Gemini CLI kullanımı

  • Gemini CLI stream-json çıktısı, önbellek isabetlerini stats.cached üzerinden gösterebilir; OpenClaw bunu cacheRead değerine eşler. Eski --output-format json geçersiz kılmaları aynı kullanım normalleştirmesini kullanır.
  • CLI doğrudan bir stats.input değerini atlıyorsa OpenClaw giriş tokenlarını stats.input_tokens - stats.cached değerinden türetir.
  • Bu yalnızca kullanım normalleştirmesidir. OpenClaw’ın Gemini CLI için Anthropic/OpenAI tarzı istem önbelleği işaretleyicileri oluşturduğu anlamına gelmez.

Sistem istemi önbellek sınırı

OpenClaw, sistem istemini dahili bir önbellek öneki sınırıyla ayrılan kararlı önek ve değişken 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ğlam), turlar arasında byte düzeyinde aynı kalacak şekilde sıralanır. Sınırın altındaki içeriğin (örneğin HEARTBEAT.md, çalışma zamanı zaman damgaları ve diğer tur başına meta veriler), önbelleğe alınmış öneki geçersiz kılmadan değişmesine izin verilir.

Temel tasarım seçimleri:

  • Kararlı çalışma alanı proje bağlamı dosyaları HEARTBEAT.md öncesinde sıralanır; böylece heartbeat değişkenliği kararlı öneki bozmaz.
  • Sınır, Anthropic ailesi, OpenAI ailesi, Google ve CLI aktarım şekillendirmesi genelinde uygulanır; böylece desteklenen tüm sağlayıcılar aynı önek kararlılığından yararlanır.
  • Codex Responses ve Anthropic Vertex istekleri, önbellek yeniden kullanımının sağlayıcıların gerçekten aldığı içerikle hizalı kalması için sınır farkındalıklı önbellek şekillendirmesinden geçirilir.
  • Sistem istemi parmak izleri normalleştirilir (boşluk, satır sonları, hook ile eklenen bağlam, çalışma zamanı yetenek sıralaması); böylece anlamsal olarak değişmeyen istemler turlar arasında KV/önbellek paylaşır.

Bir yapılandırma veya çalışma alanı değişikliğinden sonra beklenmeyen 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. Değişken içeriği sınırın altına taşımak (veya 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ı birkaç yük şeklini deterministik tutar:

  • Bundle MCP araç katalogları, araç kaydından önce deterministik olarak sıralanır; böylece listTools() sıra değişiklikleri araçlar bloğunu değiştirmez ve istem önbelleği öneklerini bozmaz.
  • Kalıcı görüntü blokları olan eski oturumlar en son tamamlanan 3 turu olduğu gibi tutar; daha eski, zaten işlenmiş görüntü blokları bir işaretleyiciyle değiştirilebilir, böylece görüntü ağırlıklı takip istekleri büyük eski yükleri yeniden göndermeye devam etmez.

Ayarlama örüntüleri

Karma trafik (önerilen varsayılan)

Ana ajanınızda uzun ömürlü bir taban çizgisi tutun, ani bildirim ajanlarında önbelleğe almayı devre dışı bırakın:

yaml
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 taban çizgisi

  • Taban çizgisi cacheRetention: "short" ayarlayın.
  • contextPruning.mode: "cache-ttl" etkinleştirin.
  • Heartbeat değerini yalnızca sıcak önbelleklerden yararlanan ajanlar için TTL’nizin altında tutun.

Önbellek tanılama

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

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

Canlı regresyon testleri

OpenClaw, tekrarlanan önekler, araç turları, görüntü turları, MCP tarzı araç transkriptleri ve Anthropic önbelleksiz kontrol için tek bir birleşik canlı önbellek regresyon kapısı tutar.

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

Dar canlı kapıyı şu komutla çalıştırın:

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

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

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

Anthropic canlı beklentileri

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

OpenAI canlı beklentileri

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

2026-04-04 tarihinde yapılan yeni birleşik canlı doğrulama şu değerlere ulaştı:

  • kararlı önek: cacheRead=4864, isabet oranı 0.966
  • araç transkripti: cacheRead=4608, isabet oranı 0.896
  • görüntü transkripti: cacheRead=4864, isabet oranı 0.954
  • MCP tarzı transkript: cacheRead=4608, isabet oranı 0.891

Birleşik kapı için yakın tarihli yerel duvar saati süresi yaklaşık 88s idi.

Doğrulamaların farklı olmasının nedeni:

  • Anthropic, açık önbellek kesme noktalarını ve hareketli konuşma geçmişi yeniden kullanımını sunar.
  • OpenAI istem önbelleğe alma hâlâ tam önek duyarlıdır, ancak canlı Responses trafiğinde etkili yeniden kullanılabilir önek, tam istemden daha erken bir platoya ulaşabilir.
  • Bu nedenle Anthropic ve OpenAI'yi tek bir sağlayıcılar arası yüzde eşiğiyle karşılaştırmak yanlış regresyonlar oluşturur.

diagnostics.cacheTrace yapılandırması

yaml
diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional    includeMessages: false # default true    includePrompt: false # default true    includeSystem: false # default true

Varsayılanlar:

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

Ortam geçişleri (tek seferlik hata ayıklama)

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

Neleri incelemeli

  • Önbellek izleme olayları JSONL biçimindedir ve session:loaded, prompt:before, stream:context ve session:after gibi aşamalı anlık görüntüler içerir.
  • Tur başına önbellek belirteci etkisi, normal kullanım yüzeylerinde cacheRead ve cacheWrite üzerinden görünür (örneğin /usage tokens, /status, oturum kullanım özetleri ve özel messages.usageTemplate düzenleri).
  • Anthropic için, önbelleğe alma etkinken hem cacheRead hem de cacheWrite bekleyin.
  • OpenAI için, önbellek isabetlerinde cacheRead bekleyin. GPT-5.6 Responses, istem segmentleri yazılırken cacheWrite da bildirebilir; yazma sayacını atlayan diğer Responses yükleri bunu 0 olarak tutar.
  • İstek izlemeye ihtiyacınız varsa, istek kimliklerini ve hız sınırı başlıklarını önbellek metriklerinden ayrı olarak günlüğe kaydedin. OpenClaw'ın geçerli önbellek izleme çıktısı, ham sağlayıcı yanıt başlıklarından ziyade istem/oturum şekline ve normalleştirilmiş belirteç kullanımına odaklanır.

Hızlı sorun giderme

  • Çoğu turda yüksek cacheWrite: değişken sistem istemi girdilerini denetleyin ve modelin/sağlayıcının önbellek ayarlarınızı desteklediğini doğrulayın.
  • Anthropic üzerinde yüksek cacheWrite: çoğu zaman önbellek kesme noktasının her istekte değişen içeriğe denk geldiği anlamına gelir.
  • Düşük OpenAI cacheRead: kararlı önekin en başta olduğunu, tekrarlanan önekin en az 1024 belirteç olduğunu ve önbelleği 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 ayarlarıyla Bedrock Nova/Mistral istekleri: çalışma zamanının none değerine zorlaması beklenir.

İlgili belgeler:

İlgili

Was this useful?
On this page

On this page