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

Caching prompt

Caching prompt berarti penyedia model dapat menggunakan kembali prefiks prompt yang tidak berubah (biasanya instruksi sistem/developer dan konteks stabil lainnya) di antara giliran, alih-alih memprosesnya ulang setiap kali. OpenClaw menormalkan penggunaan penyedia menjadi cacheRead dan cacheWrite ketika API upstream mengekspos penghitung tersebut secara langsung.

Permukaan status juga dapat memulihkan penghitung cache dari log penggunaan transkrip terbaru ketika snapshot sesi langsung tidak memilikinya, sehingga /status tetap dapat menampilkan baris cache setelah sebagian metadata sesi hilang. Nilai cache langsung bukan nol yang ada tetap diprioritaskan dibanding nilai fallback transkrip.

Mengapa ini penting: biaya token lebih rendah, respons lebih cepat, dan performa lebih dapat diprediksi untuk sesi yang berjalan lama. Tanpa caching, prompt berulang membayar biaya prompt penuh pada setiap giliran meskipun sebagian besar input tidak berubah.

Bagian di bawah ini mencakup setiap pengaturan terkait cache yang memengaruhi penggunaan ulang prompt dan biaya token.

Referensi penyedia:

Pengaturan utama

cacheRetention (default global, model, dan per agen)

Tetapkan retensi cache sebagai default global untuk semua model:

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

Timpa per model:

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

Timpa per agen:

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

Urutan penggabungan konfigurasi:

  1. agents.defaults.params (default global — berlaku untuk semua model)
  2. agents.defaults.models["provider/model"].params (timpa per model)
  3. agents.list[].params (ID agen yang cocok; menimpa berdasarkan kunci)

contextPruning.mode: "cache-ttl"

Memangkas konteks hasil alat lama setelah jendela TTL cache sehingga permintaan setelah idle tidak melakukan cache ulang pada riwayat yang terlalu besar.

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

Lihat Pemangkasan Sesi untuk perilaku lengkap.

Heartbeat penjaga kehangatan

Heartbeat dapat menjaga jendela cache tetap hangat dan mengurangi penulisan cache berulang setelah jeda idle.

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

Heartbeat per agen didukung di agents.list[].heartbeat.

Perilaku penyedia

Anthropic (API langsung)

  • cacheRetention didukung.
  • Dengan profil auth kunci API Anthropic, OpenClaw mengisi awal cacheRetention: "short" untuk ref model Anthropic ketika belum diatur.
  • Respons Messages native Anthropic mengekspos cache_read_input_tokens dan cache_creation_input_tokens, sehingga OpenClaw dapat menampilkan cacheRead dan cacheWrite.
  • Untuk permintaan native Anthropic, cacheRetention: "short" dipetakan ke cache ephemeral default 5 menit, dan cacheRetention: "long" ditingkatkan ke TTL 1 jam hanya pada host langsung api.anthropic.com.

OpenAI (API langsung)

  • Caching prompt otomatis pada model terbaru yang didukung. OpenClaw tidak perlu menyisipkan marker cache tingkat blok.
  • OpenClaw menggunakan prompt_cache_key untuk menjaga perutean cache tetap stabil di antara giliran. Host OpenAI langsung menggunakan prompt_cache_retention: "24h" ketika cacheRetention: "long" dipilih.
  • Penyedia Completions yang kompatibel dengan OpenAI menerima prompt_cache_key hanya ketika konfigurasi modelnya secara eksplisit menetapkan compat.supportsPromptCacheKey: true. Penerusan retensi panjang adalah kapabilitas terpisah: cacheRetention: "long" eksplisit mengirim prompt_cache_retention: "24h" hanya ketika entri compat tersebut juga mendukung retensi cache panjang. Penyedia seperti Mistral dapat ikut memakai kunci cache sambil menetapkan compat.supportsLongCacheRetention: false untuk menekan field retensi panjang. cacheRetention: "none" menekan kedua field.
  • Respons OpenAI mengekspos token prompt yang di-cache melalui usage.prompt_tokens_details.cached_tokens (atau input_tokens_details.cached_tokens pada event Responses API). OpenClaw memetakannya ke cacheRead.
  • Penggunaan Responses GPT-5.6 juga dapat mengekspos input_tokens_details.cache_write_tokens. OpenClaw memetakannya ke cacheWrite dan menetapkan harganya berdasarkan tarif tulis-cache model; Responses yang menghilangkan field tersebut mempertahankan cacheWrite pada 0.
  • OpenAI mengembalikan header pelacakan dan batas laju yang berguna seperti x-request-id, openai-processing-ms, dan x-ratelimit-*, tetapi akuntansi cache-hit harus berasal dari payload penggunaan, bukan dari header.
  • Dalam praktiknya, OpenAI sering berperilaku seperti cache prefiks awal, bukan penggunaan ulang riwayat penuh bergerak ala Anthropic. Giliran teks prefiks panjang yang stabil dapat mendekati plateau token yang di-cache 4864 dalam probe langsung saat ini, sementara transkrip yang berat alat atau bergaya MCP sering plateau di sekitar 4608 token yang di-cache bahkan pada pengulangan persis.

Anthropic Vertex

  • Model Anthropic di Vertex AI (anthropic-vertex/*) mendukung cacheRetention dengan cara yang sama seperti Anthropic langsung.
  • cacheRetention: "long" dipetakan ke TTL cache prompt 1 jam nyata pada endpoint Vertex AI.
  • Retensi cache default untuk anthropic-vertex cocok dengan default Anthropic langsung.
  • Permintaan Vertex dirutekan melalui pembentukan cache yang sadar batas sehingga penggunaan ulang cache tetap selaras dengan apa yang benar-benar diterima penyedia.

Amazon Bedrock

  • Ref model Anthropic Claude (amazon-bedrock/*anthropic.claude*) mendukung pass-through cacheRetention eksplisit.
  • Model Bedrock non-Anthropic dipaksa ke cacheRetention: "none" saat runtime.

Model OpenRouter

Untuk ref model openrouter/anthropic/*, OpenClaw menyisipkan cache_control Anthropic pada blok prompt sistem/developer untuk meningkatkan penggunaan ulang cache prompt hanya ketika permintaan masih menargetkan rute OpenRouter terverifikasi (openrouter pada endpoint defaultnya, atau penyedia/base URL apa pun yang resolve ke openrouter.ai).

Untuk ref model openrouter/deepseek/*, openrouter/moonshot*/*, dan openrouter/zai/*, contextPruning.mode: "cache-ttl" diizinkan karena OpenRouter menangani caching prompt sisi penyedia secara otomatis. OpenClaw tidak menyisipkan marker cache_control Anthropic ke dalam permintaan tersebut.

Konstruksi cache DeepSeek bersifat upaya-terbaik dan dapat memakan beberapa detik. Tindak lanjut langsung mungkin masih menampilkan cached_tokens: 0; verifikasi dengan permintaan prefiks sama yang diulang setelah jeda singkat dan gunakan usage.prompt_tokens_details.cached_tokens sebagai sinyal cache-hit.

Jika Anda mengarahkan ulang model ke URL proxy arbitrer yang kompatibel dengan OpenAI, OpenClaw berhenti menyisipkan marker cache Anthropic khusus OpenRouter tersebut.

Penyedia lain

Jika penyedia tidak mendukung mode cache ini, cacheRetention tidak berpengaruh.

API langsung Google Gemini

  • Transport Gemini langsung (api: "google-generative-ai") melaporkan cache hit melalui cachedContentTokenCount upstream; OpenClaw memetakannya ke cacheRead.
  • Ketika cacheRetention diatur pada model Gemini langsung, OpenClaw secara otomatis membuat, menggunakan kembali, dan menyegarkan resource cachedContents untuk prompt sistem pada run Google AI Studio. Ini berarti Anda tidak lagi perlu membuat handle cached-content sebelumnya secara manual.
  • Anda tetap dapat meneruskan handle cached-content Gemini yang sudah ada sebagai params.cachedContent (atau legacy params.cached_content) pada model yang dikonfigurasi.
  • Ini terpisah dari caching prefiks-prompt Anthropic/OpenAI. Untuk Gemini, OpenClaw mengelola resource cachedContents native penyedia, bukan menyisipkan marker cache ke dalam permintaan.

Penggunaan Gemini CLI

  • Output stream-json Gemini CLI dapat menampilkan cache hit melalui stats.cached; OpenClaw memetakannya ke cacheRead. Override legacy --output-format json menggunakan normalisasi penggunaan yang sama.
  • Jika CLI menghilangkan nilai stats.input langsung, OpenClaw menurunkan token input dari stats.input_tokens - stats.cached.
  • Ini hanya normalisasi penggunaan. Ini tidak berarti OpenClaw membuat marker cache prompt bergaya Anthropic/OpenAI untuk Gemini CLI.

Batas cache prompt sistem

OpenClaw membagi prompt sistem menjadi prefiks stabil dan sufiks volatil yang dipisahkan oleh batas prefiks-cache internal. Konten di atas batas (definisi alat, metadata Skills, file workspace, dan konteks lain yang relatif statis) diurutkan agar tetap identik byte demi byte di antara giliran. Konten di bawah batas (misalnya HEARTBEAT.md, timestamp runtime, dan metadata per giliran lainnya) boleh berubah tanpa membatalkan prefiks yang di-cache.

Pilihan desain utama:

  • File konteks-proyek workspace yang stabil diurutkan sebelum HEARTBEAT.md sehingga perubahan Heartbeat tidak merusak prefiks stabil.
  • Batas diterapkan di seluruh pembentukan transport keluarga Anthropic, keluarga OpenAI, Google, dan CLI sehingga semua penyedia yang didukung mendapatkan manfaat dari stabilitas prefiks yang sama.
  • Permintaan Codex Responses dan Anthropic Vertex dirutekan melalui pembentukan cache yang sadar batas sehingga penggunaan ulang cache tetap selaras dengan apa yang benar-benar diterima penyedia.
  • Sidik jari prompt sistem dinormalkan (spasi putih, akhiran baris, konteks yang ditambahkan hook, pengurutan kapabilitas runtime) sehingga prompt yang tidak berubah secara semantik berbagi KV/cache di antara giliran.

Jika Anda melihat lonjakan cacheWrite yang tidak terduga setelah perubahan konfigurasi atau workspace, periksa apakah perubahan tersebut berada di atas atau di bawah batas cache. Memindahkan konten volatil ke bawah batas (atau menstabilkannya) sering menyelesaikan masalah.

Guard stabilitas cache OpenClaw

OpenClaw juga menjaga beberapa bentuk payload yang sensitif cache tetap deterministik sebelum permintaan mencapai penyedia:

  • Katalog alat Bundle MCP diurutkan secara deterministik sebelum registrasi alat, sehingga perubahan urutan listTools() tidak mengubah blok alat dan merusak prefiks cache prompt.
  • Sesi legacy dengan blok gambar yang dipersisten mempertahankan 3 giliran selesai terbaru tetap utuh; blok gambar lama yang sudah diproses dapat diganti dengan marker sehingga tindak lanjut yang berat gambar tidak terus mengirim ulang payload usang yang besar.

Pola penyetelan

Trafik campuran (default yang direkomendasikan)

Pertahankan baseline berumur panjang pada agen utama Anda, nonaktifkan caching pada agen notifier yang bursty:

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"

Baseline mengutamakan biaya

  • Tetapkan baseline cacheRetention: "short".
  • Aktifkan contextPruning.mode: "cache-ttl".
  • Pertahankan Heartbeat di bawah TTL Anda hanya untuk agen yang mendapat manfaat dari cache hangat.

Diagnostik cache

OpenClaw mengekspos diagnostik trace cache khusus untuk run agen tertanam.

Untuk diagnostik normal yang terlihat oleh pengguna, /status dan ringkasan penggunaan lain dapat menggunakan entri penggunaan transkrip terbaru sebagai sumber fallback untuk cacheRead / cacheWrite ketika entri sesi langsung tidak memiliki penghitung tersebut.

Uji regresi langsung

OpenClaw mempertahankan satu gate regresi cache langsung gabungan untuk prefiks berulang, giliran alat, giliran gambar, transkrip alat bergaya MCP, dan kontrol tanpa-cache Anthropic.

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

Jalankan gate langsung yang sempit dengan:

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

File baseline menyimpan angka live terbaru yang diamati beserta ambang minimum regresi khusus penyedia yang digunakan oleh pengujian. Runner juga menggunakan ID sesi per-run yang segar dan namespace prompt agar status cache sebelumnya tidak mencemari sampel regresi saat ini.

Pengujian ini sengaja tidak menggunakan kriteria keberhasilan yang identik di seluruh penyedia.

Ekspektasi live Anthropic

  • Harapkan penulisan pemanasan eksplisit melalui cacheWrite.
  • Harapkan penggunaan ulang hampir seluruh riwayat pada giliran berulang karena kontrol cache Anthropic memajukan breakpoint cache melalui percakapan.
  • Asersi live saat ini masih menggunakan ambang tingkat hit yang tinggi untuk jalur stabil, tool, dan gambar.

Ekspektasi live OpenAI

  • Harapkan hanya cacheRead. cacheWrite tetap 0.
  • Perlakukan penggunaan ulang cache pada giliran berulang sebagai plateau khusus penyedia, bukan sebagai penggunaan ulang seluruh riwayat bergerak bergaya Anthropic.
  • Asersi live saat ini menggunakan pemeriksaan ambang minimum konservatif yang diturunkan dari perilaku live yang diamati pada gpt-5.4-mini:
    • prefiks stabil: cacheRead >= 4608, tingkat hit >= 0.90
    • transkrip tool: cacheRead >= 4096, tingkat hit >= 0.85
    • transkrip gambar: cacheRead >= 3840, tingkat hit >= 0.82
    • transkrip bergaya MCP: cacheRead >= 4096, tingkat hit >= 0.85

Verifikasi live gabungan yang segar pada 2026-04-04 mencapai:

  • prefiks stabil: cacheRead=4864, tingkat hit 0.966
  • transkrip tool: cacheRead=4608, tingkat hit 0.896
  • transkrip gambar: cacheRead=4864, tingkat hit 0.954
  • transkrip bergaya MCP: cacheRead=4608, tingkat hit 0.891

Waktu wall-clock lokal terbaru untuk gate gabungan sekitar 88s.

Mengapa asersi berbeda:

  • Anthropic mengekspos breakpoint cache eksplisit dan penggunaan ulang riwayat percakapan yang bergerak.
  • Caching prompt OpenAI masih sensitif terhadap prefiks persis, tetapi prefiks efektif yang dapat digunakan ulang dalam lalu lintas live Responses dapat mencapai plateau lebih awal daripada prompt penuh.
  • Karena itu, membandingkan Anthropic dan OpenAI dengan satu ambang persentase lintas penyedia akan menghasilkan regresi palsu.

Konfigurasi diagnostics.cacheTrace

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

Default:

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

Toggle env (debugging satu kali)

  • OPENCLAW_CACHE_TRACE=1 mengaktifkan penelusuran cache.
  • OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl menimpa jalur output.
  • OPENCLAW_CACHE_TRACE_MESSAGES=0|1 mengalihkan pengambilan payload pesan penuh.
  • OPENCLAW_CACHE_TRACE_PROMPT=0|1 mengalihkan pengambilan teks prompt.
  • OPENCLAW_CACHE_TRACE_SYSTEM=0|1 mengalihkan pengambilan prompt sistem.

Yang perlu diperiksa

  • Peristiwa penelusuran cache adalah JSONL dan menyertakan snapshot bertahap seperti session:loaded, prompt:before, stream:context, dan session:after.
  • Dampak token cache per giliran terlihat di permukaan penggunaan normal melalui cacheRead dan cacheWrite (misalnya /usage tokens, /status, ringkasan penggunaan sesi, dan tata letak messages.usageTemplate kustom).
  • Untuk Anthropic, harapkan cacheRead dan cacheWrite saat caching aktif.
  • Untuk OpenAI, harapkan cacheRead pada hit cache. GPT-5.6 Responses juga dapat melaporkan cacheWrite saat segmen prompt ditulis; payload Responses lain yang menghilangkan penghitung penulisan mempertahankannya pada 0.
  • Jika Anda memerlukan penelusuran permintaan, catat ID permintaan dan header batas laju secara terpisah dari metrik cache. Output cache-trace OpenClaw saat ini berfokus pada bentuk prompt/sesi dan penggunaan token yang dinormalisasi, bukan header respons penyedia mentah.

Pemecahan masalah cepat

  • cacheWrite tinggi pada sebagian besar giliran: periksa input prompt sistem yang volatil dan verifikasi model/penyedia mendukung pengaturan cache Anda.
  • cacheWrite tinggi pada Anthropic: sering berarti breakpoint cache mendarat pada konten yang berubah di setiap permintaan.
  • cacheRead OpenAI rendah: verifikasi prefiks stabil berada di depan, prefiks berulang setidaknya 1024 token, dan prompt_cache_key yang sama digunakan ulang untuk giliran yang seharusnya berbagi cache.
  • Tidak ada efek dari cacheRetention: konfirmasi kunci model cocok dengan agents.defaults.models["provider/model"].
  • Permintaan Bedrock Nova/Mistral dengan pengaturan cache: pemaksaan runtime yang diharapkan ke none.

Dokumentasi terkait:

Terkait

Was this useful?
On this page

On this page