Caching prompt

Caching prompt memungkinkan penyedia model menggunakan kembali prefiks prompt yang tidak berubah (instruksi sistem/pengembang, definisi alat, konteks stabil lainnya) di antara giliran, alih-alih memprosesnya ulang pada setiap permintaan. Hal ini mengurangi biaya token dan latensi pada sesi yang berjalan lama dengan konteks berulang.

OpenClaw menormalisasi penggunaan penyedia menjadi cacheRead dan cacheWrite jika API hulu menyediakan penghitung tersebut. Ringkasan penggunaan (/status dan yang serupa) menggunakan entri penggunaan transkrip terakhir sebagai fallback ketika snapshot sesi langsung tidak memiliki penghitung cache; nilai langsung yang bukan nol selalu diutamakan daripada fallback.

Referensi penyedia:

• Caching prompt Anthropic
• Caching prompt OpenAI

Pengaturan utama

cacheRetention

Nilai: "none" | "short" | "long". Dapat dikonfigurasi sebagai nilai default global, per model, dan per agen.

agents:  defaults:    params:      cacheRetention: "long" # none | short | long    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # menggantikan nilai default global untuk model ini  list:    - id: "alerts"      params:        cacheRetention: "none" # menggantikan kedua nilai default untuk agen ini

Urutan penggabungan (yang terakhir diutamakan):

1. agents.defaults.params - nilai default global untuk semua model
2. agents.defaults.models["provider/model"].params - penggantian per model
3. agents.list[].params - penggantian per agen, dicocokkan berdasarkan ID agen

Sumber: src/agents/embedded-agent-runner/extra-params.ts (resolveExtraParams).

contextPruning.mode: "cache-ttl"

Memangkas konteks hasil alat lama setelah jendela TTL cache berakhir, sehingga permintaan setelah periode tidak aktif tidak melakukan caching ulang terhadap riwayat yang terlalu besar.

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

Lihat Pemangkasan sesi untuk perilaku lengkap.

Menjaga cache tetap hangat dengan Heartbeat

Heartbeat dapat menjaga jendela cache tetap hangat dan mengurangi penulisan cache berulang setelah jeda tidak aktif. Dapat dikonfigurasi secara global (agents.defaults.heartbeat) atau per agen (agents.list[].heartbeat).

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

Perilaku penyedia

Anthropic (API langsung dan Vertex AI)

• cacheRetention didukung untuk penyedia anthropic dan anthropic-vertex, serta untuk model Claude pada amazon-bedrock dan endpoint khusus yang kompatibel dengan anthropic-messages ketika cacheRetention ditetapkan secara eksplisit.
• Jika tidak ditetapkan, OpenClaw menetapkan nilai awal cacheRetention: "short" untuk Anthropic langsung (hanya penyedia anthropic dan anthropic-vertex; rute keluarga Anthropic lainnya memerlukan nilai eksplisit).
• Respons Anthropic Messages native menyediakan cache_read_input_tokens dan cache_creation_input_tokens, yang dipetakan ke cacheRead dan cacheWrite.
• cacheRetention: "short" dipetakan ke cache sementara default selama 5 menit. cacheRetention: "long" meminta TTL 1 jam (cache_control: { type: "ephemeral", ttl: "1h" }) ketika ditetapkan secara eksplisit. Retensi panjang yang implisit/digerakkan oleh lingkungan (OPENCLAW_CACHE_RETENTION=long tanpa cacheRetention eksplisit) hanya meningkatkan TTL menjadi 1 jam pada host api.anthropic.com atau Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); host lain tetap menggunakan cache 5 menit.

Sumber: src/agents/anthropic-payload-policy.ts (resolveAnthropicEphemeralCacheControl, isLongTtlEligibleEndpoint).

OpenAI (API langsung)

• Caching prompt berlangsung otomatis pada model terbaru yang didukung; OpenClaw tidak menyisipkan penanda cache tingkat blok.
• OpenClaw mengirim prompt_cache_key agar perutean cache tetap stabil di antara giliran. Host langsung api.openai.com mendapatkannya secara otomatis. Proksi yang kompatibel dengan OpenAI (oMLX, llama.cpp, endpoint khusus) harus menetapkan compat.supportsPromptCacheKey: true dalam konfigurasi model untuk mengaktifkannya—hal ini tidak pernah terdeteksi secara otomatis untuk proksi.
• prompt_cache_retention: "24h" hanya ditambahkan ketika cacheRetention: "long" dipilih dan endpoint yang diresolusi mendukung kunci cache serta retensi panjang (compat.supportsLongCacheRetention, secara default bernilai true; profil kompatibilitas Together AI dan Cloudflare menonaktifkannya). cacheRetention: "none" meniadakan kedua bidang tersebut.
• Cache hit muncul melalui usage.prompt_tokens_details.cached_tokens (Chat Completions) atau input_tokens_details.cached_tokens (Responses API), yang dipetakan ke cacheRead.
• Payload Responses API juga dapat menyediakan input_tokens_details.cache_write_tokens, yang dipetakan ke cacheWrite dan dihargai sesuai tarif penulisan cache model; payload Responses yang tidak menyertakan bidang tersebut mempertahankan cacheWrite pada 0. Chat Completions API OpenAI tidak mendokumentasikan atau menghasilkan penghitung cache_write_tokens, tetapi OpenClaw tetap membaca prompt_tokens_details.cache_write_tokens di sana untuk proksi yang kompatibel dengan OpenRouter dan bergaya DeepSeek yang melaporkan jumlah penulisan terpisah.
• Dalam praktiknya, OpenAI lebih menyerupai cache prefiks awal daripada penggunaan ulang seluruh riwayat bergerak milik Anthropic—lihat ekspektasi langsung OpenAI di bawah.

Amazon Bedrock

• Referensi model Anthropic Claude (amazon-bedrock/*anthropic.claude*, beserta prefiks profil inferensi sistem AWS us./eu./global.anthropic.claude*) mendukung penerusan cacheRetention eksplisit.
• Model Bedrock non-Anthropic (misalnya amazon.nova-*) diresolusi tanpa retensi cache saat runtime, terlepas dari nilai cacheRetention yang dikonfigurasi.
• ARN profil inferensi aplikasi Bedrock yang buram (ID profil yang tidak memuat claude) juga diresolusi tanpa retensi cache kecuali cacheRetention ditetapkan secara eksplisit, karena keluarga model tidak dapat disimpulkan hanya dari ARN.

OpenRouter

Untuk referensi model openrouter/anthropic/*, OpenClaw menyisipkan penanda cache_control Anthropic pada blok prompt sistem/pengembang, tetapi hanya ketika permintaan masih menargetkan rute OpenRouter yang terverifikasi (openrouter pada endpoint default-nya, atau penyedia/URL dasar apa pun yang diresolusi ke openrouter.ai). Mengarahkan ulang model ke URL proksi kompatibel OpenAI yang arbitrer akan menghentikan penyisipan ini.

contextPruning.mode: "cache-ttl" diizinkan untuk referensi model openrouter/anthropic/*, openrouter/deepseek/*, openrouter/moonshot/*, openrouter/moonshotai/*, dan openrouter/zai/*, karena rute-rute ini menangani caching prompt di sisi penyedia tanpa memerlukan penanda yang disisipkan OpenClaw.

Sumber: extensions/openrouter/index.ts (OPENROUTER_CACHE_TTL_MODEL_PREFIXES).

Pembuatan cache DeepSeek pada OpenRouter bersifat upaya terbaik dan dapat memerlukan beberapa detik; permintaan lanjutan langsung mungkin masih menampilkan cached_tokens: 0. Verifikasi dengan permintaan berulang yang memiliki prefiks sama setelah jeda singkat, menggunakan usage.prompt_tokens_details.cached_tokens sebagai sinyal cache hit.

Google Gemini (API langsung)

• Transport Gemini langsung (api: "google-generative-ai") melaporkan cache hit melalui cachedContentTokenCount hulu, yang dipetakan ke cacheRead.
• Keluarga model yang memenuhi syarat: gemini-2.5* dan gemini-3* (tidak mencakup varian Live/pratinjau di luar kecocokan prefiks tersebut, misalnya gemini-live-2.5-flash-preview).
• Ketika cacheRetention ditetapkan pada model yang memenuhi syarat, OpenClaw secara otomatis membuat, menggunakan kembali, dan menyegarkan sumber daya cachedContents untuk prompt sistem—tidak memerlukan handle konten cache manual. TTL adalah 300s untuk cacheRetention: "short" dan 3600s untuk "long".
• Anda tetap dapat meneruskan handle konten cache Gemini yang sudah ada melalui params.cachedContent (atau params.cached_content lama); handle eksplisit sepenuhnya melewati jalur pengelolaan cache otomatis.
• Hal ini terpisah dari caching prefiks prompt Anthropic/OpenAI: OpenClaw mengelola sumber daya cachedContents native penyedia untuk Gemini, alih-alih menyisipkan penanda cache inline.

Sumber: src/agents/embedded-agent-runner/google-prompt-cache.ts.

Penyedia harness CLI (Claude Code, Gemini CLI)

Backend CLI yang menghasilkan peristiwa penggunaan JSONL (jsonlDialect: "claude-stream-json" atau "gemini-stream-json") melewati parser penggunaan bersama yang mengenali beberapa varian nama bidang, termasuk penghitung biasa cached yang dipetakan ke cacheRead. Ketika payload JSON CLI tidak menyertakan bidang token input langsung, OpenClaw menurunkannya sebagai input_tokens - cached. Ini hanya normalisasi penggunaan—hal ini tidak membuat penanda cache prompt bergaya Anthropic/OpenAI untuk model yang digerakkan CLI tersebut.

Sumber: src/agents/cli-output.ts (toCliUsage).

Penyedia lainnya

Jika penyedia tidak mendukung mode cache mana pun di atas, cacheRetention tidak berpengaruh.

Batas cache prompt sistem

OpenClaw membagi prompt sistem menjadi prefiks stabil dan sufiks volatil pada batas prefiks cache internal. Konten di atas batas (definisi alat, metadata Skills, file ruang kerja) diurutkan agar tetap identik secara bita di antara giliran. Konten di bawah batas (misalnya HEARTBEAT.md, stempel waktu runtime, metadata per giliran lainnya) dapat berubah tanpa membatalkan prefiks yang di-cache.

Pilihan desain utama:

• File konteks proyek ruang kerja yang stabil diurutkan sebelum HEARTBEAT.md agar perubahan Heartbeat tidak merusak prefiks stabil.
• Batas tersebut berlaku di seluruh pembentukan transport keluarga Anthropic, keluarga OpenAI, Google, dan CLI, sehingga semua penyedia yang didukung memperoleh manfaat dari stabilitas prefiks yang sama.
• Permintaan Codex Responses dan Anthropic Vertex dirutekan melalui pembentukan cache yang memahami batas agar penggunaan ulang cache tetap selaras dengan apa yang benar-benar diterima penyedia.
• Sidik jari prompt sistem dinormalisasi (spasi kosong, akhir baris, konteks yang ditambahkan hook, urutan kapabilitas runtime) agar prompt yang secara semantik tidak berubah berbagi cache di antara giliran.

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

Pelindung stabilitas cache OpenClaw

• Katalog alat MCP yang dibundel diurutkan secara deterministik (berdasarkan nama server, lalu nama alat) sebelum pendaftaran alat, sehingga perubahan urutan listTools() tidak mengubah blok alat dan merusak prefiks cache prompt.
• Sesi lama dengan blok gambar persisten mempertahankan 3 giliran selesai terbaru secara utuh (menghitung semua giliran yang selesai, bukan hanya yang memuat gambar). Blok gambar lama yang telah diproses diganti dengan penanda teks agar permintaan lanjutan yang sarat gambar tidak terus mengirim ulang payload lama berukuran besar.

Pola penyetelan

Lalu lintas campuran (default yang direkomendasikan)

Pertahankan baseline berumur panjang pada agen utama Anda dan nonaktifkan caching pada agen pemberi notifikasi yang bekerja secara tiba-tiba:

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 yang mengutamakan biaya

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

Pengujian regresi langsung

OpenClaw menjalankan satu gerbang regresi cache langsung gabungan yang mencakup 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-runner.ts
• src/agents/live-cache-regression-baseline.ts

Jalankan dengan:

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

File baseline menyimpan angka langsung yang terakhir diamati beserta batas bawah regresi khusus penyedia yang diperiksa oleh pengujian. Setiap eksekusi menggunakan ID sesi dan namespace prompt baru per eksekusi agar status cache sebelumnya tidak mencemari sampel saat ini. Anthropic dan OpenAI menggunakan penegakan yang berbeda: kegagalan memenuhi batas bawah Anthropic merupakan regresi keras (pengujian gagal), sedangkan kegagalan memenuhi batas bawah OpenAI hanya untuk pemantauan (dicatat sebagai peringatan, tidak menggagalkan eksekusi). Keduanya tidak berbagi satu ambang lintas penyedia.

Ekspektasi langsung Anthropic

• Harapkan penulisan pemanasan eksplisit melalui cacheWrite.
• Harapkan penggunaan ulang riwayat yang hampir penuh pada giliran berulang, karena kontrol cache Anthropic memajukan titik henti cache sepanjang percakapan.
• Batas minimum dasar untuk jalur stabil, alat, gambar, dan bergaya MCP merupakan gerbang regresi yang ketat.

Ekspektasi langsung OpenAI

• Harapkan hanya cacheRead; cacheWrite tetap 0 pada Chat Completions.
• Perlakukan penggunaan ulang cache pada giliran berulang sebagai kondisi stabil yang spesifik untuk penyedia, bukan penggunaan ulang riwayat penuh bergerak seperti Anthropic.
• Batas minimum hanya untuk pemantauan (ketidaktercapaian dicatat sebagai peringatan, bukan kegagalan pengujian), yang diturunkan dari perilaku langsung yang diamati pada gpt-5.4-mini:

Angka dasar yang terakhir diamati (dari live-cache-regression-baseline.ts) mencapai: prefiks stabil cacheRead=4864, tingkat hit 0.966; transkrip alat cacheRead=4608, tingkat hit 0.896; transkrip gambar cacheRead=4864, tingkat hit 0.954; transkrip bergaya MCP cacheRead=4608, tingkat hit 0.891.

Alasan asersi berbeda: Anthropic menyediakan titik henti cache eksplisit dan penggunaan ulang riwayat percakapan yang bergerak, sedangkan prefiks efektif yang dapat digunakan ulang oleh OpenAI dalam lalu lintas langsung dapat mencapai kondisi stabil sebelum seluruh prompt. Membandingkan kedua penyedia dengan satu ambang persentase lintas penyedia menghasilkan regresi palsu.

Konfigurasi diagnostics.cacheTrace

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

Nilai bawaan:

Pengalih variabel lingkungan (debugging sekali pakai)

Hal yang perlu diperiksa

• Peristiwa pelacakan cache berbentuk JSONL dengan snapshot bertahap seperti session:loaded, prompt:before, stream:context, dan session:after.
• Dampak token cache per giliran terlihat pada permukaan penggunaan normal: cacheRead dan cacheWrite muncul di /usage tokens, /status, ringkasan penggunaan sesi, dan tata letak khusus messages.usageTemplate.
• Untuk Anthropic, harapkan cacheRead dan cacheWrite saat caching aktif.
• Untuk OpenAI, harapkan cacheRead saat cache berhasil ditemukan; cacheWrite hanya diisi pada muatan Responses API yang menyertakannya (lihat OpenAI di atas).
• OpenAI juga mengembalikan header pelacakan dan batas laju seperti x-request-id, openai-processing-ms, dan x-ratelimit-*; gunakan header tersebut untuk melacak permintaan, tetapi penghitungan keberhasilan cache tetap harus berasal dari muatan penggunaan, bukan dari header.

Pemecahan masalah cepat

• cacheWrite tinggi pada sebagian besar giliran: periksa masukan prompt sistem yang berubah-ubah; pastikan model/penyedia mendukung pengaturan cache Anda.
• cacheWrite tinggi pada Anthropic: sering kali berarti titik henti cache berada pada konten yang berubah di setiap permintaan.
• cacheRead OpenAI rendah: pastikan prefiks stabil berada di bagian depan, prefiks berulang setidaknya berjumlah 1024 token, dan prompt_cache_key yang sama digunakan ulang untuk giliran yang seharusnya berbagi cache.
• cacheRetention tidak memberikan efek: pastikan kunci model cocok dengan agents.defaults.models["provider/model"].
• Permintaan Bedrock Nova dengan pengaturan cache: sesuai harapan—permintaan ini ditetapkan tanpa retensi cache saat runtime.

Dokumentasi terkait:

• Anthropic
• Penggunaan dan biaya token
• Pemangkasan sesi
• Referensi konfigurasi Gateway

Terkait

• Penggunaan dan biaya token
• Penggunaan dan biaya API