SpyBara
Go Premium

prompt-caching.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 151 additions and 49 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58

Bagaimana Claude Code menggunakan prompt caching

Claude Code mengelola prompt caching secara otomatis. Lihat mengapa perubahan model memicu giliran tanpa cache yang lambat, berapa biaya /compact, mengapa pengeditan CLAUDE.md tidak berlaku di tengah sesi, dan cara memeriksa tingkat cache hit Anda.

Prompt caching membuat Claude Code lebih cepat dan lebih hemat biaya. Tanpa caching, API akan memproses ulang riwayat lengkap Anda pada setiap giliran. Dengan caching, API menggunakan kembali apa yang sudah diproses, menagih pembacaan ulang pada tingkat token cache, dan hanya memproses sepenuhnya apa yang berubah.

Claude Code menangani prompt caching untuk Anda, kecuali Anda menonaktifkannya. Masih berguna untuk mengetahui cara kerja prompt caching, karena beberapa tindakan membatalkan cache dan membuat respons berikutnya lebih lambat dan lebih mahal saat membangun kembali. Halaman ini mencakup tindakan mana yang melakukan itu, mengapa beberapa pengaturan menunggu restart untuk diterapkan, dan cara memeriksa kinerja cache ketika penggunaan terlihat tinggi.

Bagaimana cache diatur

Setiap kali Anda mengirim pesan di Claude Code, aplikasi membuat permintaan API baru. Model tidak mengingat apa pun di antara permintaan, jadi Claude Code mengirim ulang konteks lengkap: prompt sistem, konteks proyek Anda, setiap pesan sebelumnya dan hasil alat, serta pesan baru Anda. Konten baru ditambahkan di akhir, yang berarti sebagian besar dari setiap permintaan identik dengan yang sebelumnya. Prompt caching adalah cara API menghindari pemrosesan ulang bagian yang tidak berubah.

API melakukan cache dengan mencocokkan awal setiap permintaan, yang disebut prefix, terhadap konten yang baru-baru ini diproses. Pada giliran normal, prefix adalah seluruh permintaan sebelumnya dan hanya pertukaran terbaru yang baru. Kecocokan bersifat tepat, jadi perubahan di mana pun dalam prefix menghitung ulang semuanya setelahnya. Tidak ada caching per-file atau per-segment. Lihat cara kerja prompt caching dalam referensi API untuk mekanisme yang mendasarinya.

Empat giliran ditampilkan sebagai batang horizontal yang berkembang. Permintaan setiap giliran berisi semuanya dari giliran sebelumnya ditambah pertukaran terbaru ditambahkan di akhir. Pada giliran dua dan tiga, prefix yang tidak berubah dibaca dari cache dan hanya pertukaran baru yang diproses. Pada giliran empat, prompt sistem berubah, jadi prefix tidak lagi cocok dan seluruh permintaan diproses ulang dan ditulis. Empat giliran ditampilkan sebagai batang horizontal yang berkembang. Permintaan setiap giliran berisi semuanya dari giliran sebelumnya ditambah pertukaran terbaru ditambahkan di akhir. Pada giliran dua dan tiga, prefix yang tidak berubah dibaca dari cache dan hanya pertukaran baru yang diproses. Pada giliran empat, prompt sistem berubah, jadi prefix tidak lagi cocok dan seluruh permintaan diproses ulang dan ditulis.

Untuk mendapatkan hasil maksimal dari pencocokan prefix, Claude Code mengurutkan setiap permintaan sehingga konten yang jarang berubah di antara giliran datang terlebih dahulu:

Layer Konten Berubah ketika
Prompt sistem Instruksi inti, definisi alat, gaya output Set definisi alat yang dimuat berubah, Anda beralih gaya output, atau Claude Code diperbarui
Konteks proyek CLAUDE.md, auto memory, aturan tanpa cakupan Sesi dimulai, atau setelah /clear atau /compact
Percakapan Pesan Anda, respons Claude, hasil alat Setiap giliran

Perubahan pada layer percakapan meninggalkan prompt sistem dan konteks proyek di-cache. Perubahan pada prompt sistem membatalkan semuanya, karena semua konten selanjutnya sekarang berada di belakang prefix yang berbeda. Kolom ketiga memberikan pemicu umum daripada daftar lengkap, dan bagian di bawah mencakup set lengkap.

Aturan pencocokan prefix menjelaskan sebagian besar perilaku di halaman ini. Plan mode dan skill loading, misalnya, menambahkan instruksi mereka sebagai pesan percakapan, jadi prefix yang di-cache tetap utuh.

Dua pengaturan tidak muncul dalam tabel layer tetapi masih mempengaruhi apa yang tetap di-cache:

  • Model: setiap model memiliki cache-nya sendiri. Beralih model menghitung ulang seluruh permintaan bahkan ketika kontennya identik. Lihat Beralih model di bawah.
  • Effort level: pada sebagian besar model, setiap effort level memiliki cache-nya sendiri, jadi mengubah effort di tengah sesi menghitung ulang seluruh permintaan. Pada Fable 5.1 dengan API key atau langganan Claude, cache tetap utuh secara default. Lihat Mengubah effort level di bawah.

Tempat cache berada

Caching terjadi di sisi server, dalam infrastruktur apa pun yang melayani model Anda. Tempat itu tergantung pada cara Anda melakukan autentikasi:

  • API key, langganan Claude, atau Claude Platform on AWS: cache berada di infrastruktur Anthropic, diakses melalui Claude API
  • Amazon Bedrock atau Google Cloud's Agent Platform: cache berada di infrastruktur penyajian penyedia cloud Anda
  • Microsoft Foundry: tergantung pada opsi hosting deployment. Deployment yang dihosting di Azure disajikan di infrastruktur Azure; deployment yang dihosting di Anthropic disajikan di infrastruktur Anthropic
  • Custom ANTHROPIC_BASE_URL atau LLM gateway: cache berada di mana pun permintaan Anda diteruskan, dan apakah caching berfungsi tergantung pada gateway

Claude Code juga menambahkan konteks sistem di tengah percakapan, seperti pemberitahuan perubahan file, dan menandai blok itu untuk caching di setiap penyedia dan koneksi.

Di endpoint penyedia sendiri, Amazon Bedrock dan endpoint Mantle-nya, Google Cloud's Agent Platform, dan Microsoft Foundry melakukan cache pada blok dengan cara yang sama seperti Claude API.

Ketika permintaan Anda melewati LLM gateway, custom ANTHROPIC_BASE_URL, atau override base-URL penyedia cloud seperti ANTHROPIC_BEDROCK_BASE_URL, apa yang tetap di-cache tergantung pada cara gateway menangani cache_control markers yang dikirim Claude Code:

  • Meneruskannya tanpa perubahan: blok dan percakapan Anda melakukan cache dengan cara yang sama seperti di endpoint penyedia sendiri.
  • Menolak permintaan yang ditandai dengan error 400 yang menyebutkan cache_control: Claude Code mengirim ulang permintaan dengan marker dipindahkan dari blok ke pesan percakapan terakhir Anda, dan menyimpannya di sana untuk sisa percakapan. Blok ditagih sebagai input yang tidak di-cache; percakapan Anda tetap di-cache.
  • Menghapus marker sambil mengembalikan kesuksesan: seluruh riwayat percakapan Anda ditagih sebagai input yang tidak di-cache pada setiap giliran. Gateway yang mengonversi konten sistem bentuk blok menjadi string biasa menghapus marker dengan cara yang sama.

Untuk apa yang disimpan dan diproses setiap penyedia, lihat data usage. Di mana pun cache berada, entri kedaluwarsa setelah periode tidak aktif, dan Cache lifetime di bawah mencakup TTL dan cara memperpanjangnya.

Tindakan yang membatalkan cache

Tindakan ini menyebabkan permintaan berikutnya kehilangan sebagian atau seluruh cache. Anda melihat satu giliran yang lebih lambat dan lebih mahal, setelah itu prefix baru di-cache. Sebagian besar dapat dihindari di tengah tugas setelah Anda mengetahui biayanya. Perubahan model dapat terasa gratis sampai Anda memperhatikan giliran yang lebih lambat setelahnya.

Beralih model

Setiap model memiliki cache-nya sendiri. Beralih dengan /model berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits, meskipun kontennya identik.

Ketika Anda menjalankan /model di terminal, Claude Code meminta Anda untuk mengonfirmasi perubahan hanya saat cache masih hangat. Cache tetap hangat selama satu cache TTL setelah Claude Code mengirim permintaan terakhir dalam percakapan ini atau Claude merespons. Setelah waktu itu berlalu, cache telah kedaluwarsa, jadi Claude Code beralih tanpa bertanya.

Sebelum v2.1.238, Claude Code tidak memeriksa cache TTL dan bertanya bahkan setelah cache telah kedaluwarsa.

Anda juga dapat memerlukan konfirmasi ini atau melewatkannya dengan PreModelSwitch hook.

Pengaturan model opusplan diselesaikan ke Opus selama plan mode dan Sonnet selama eksekusi, jadi setiap toggle plan-mode adalah perubahan model dan memulai cache segar.

Fallback model otomatis pada Fable 5.1, Fable 5, dan Opus 5 juga merupakan perubahan model. Ketika pengklasifikasi keamanan menandai permintaan dan kategori yang ditandai memiliki model fallback, Claude Code menjalankan kembali permintaan pada model tersebut dan sesi berlanjut di sana.

Mengubah tingkat effort

Pada sebagian besar model, mengubah tingkat effort di tengah sesi berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits. Saat cache masih hangat, Claude Code meminta Anda untuk mengonfirmasi perubahan terlebih dahulu.

Pada Fable 5.1 dengan API key atau langganan Claude, mengubah effort menjaga cache, dan Claude Code menerapkan level baru tanpa bertanya. Ini tidak berlaku pada Amazon Bedrock, Google Cloud's Agent Platform, atau Claude apps gateway, atau ketika Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS atau organisasi Anda memiliki konfigurasi HIPAA.

Sebelum v2.1.260, mengubah effort pada Fable 5.1 dengan API key atau langganan Claude juga membatalkan cache.

Mengaktifkan fast mode

Mengaktifkan fast mode menambahkan header permintaan yang merupakan bagian dari cache key, jadi permintaan pertama yang Claude Code kirim dengan fast mode aktif membaca seluruh riwayat percakapan tanpa cache hits. Claude Code menetapkan header itu sekali ketika giliran dimulai dan menyimpannya untuk seluruh giliran, jadi ketika Anda mengaktifkan fast mode saat Claude sedang bekerja, cache miss dari header terjadi pada permintaan pertama giliran Anda berikutnya. Token input yang tidak di-cache tersebut ditagih dengan fast mode rates, itulah mengapa mengaktifkannya di awal sesi lebih murah daripada mengaktifkannya jauh ke dalam sesi yang panjang. Jika model Anda saat ini tidak mendukung fast mode, mengaktifkan fast mode juga beralih model Anda, dan perubahan itu memulai cache segar pada permintaan berikutnya dalam giliran yang sedang berjalan.

Biaya berlaku sekali per percakapan. Setelah giliran fast mode pertama, Claude Code terus mengirim header dan hanya memvariasikan pengaturan kecepatan permintaan, yang bukan bagian dari cache key. Mengaktifkan fast mode, fallback otomatis ke kecepatan standar setelah rate limit, dan mengaktifkannya kembali nanti semua menjaga cache. Jika Anda kehabisan kredit penggunaan di tengah sesi, Claude Code mencoba ulang setiap permintaan fast mode yang ditolak dengan kecepatan standar dengan cara yang sama, jadi fallback ini juga menjaga cache. /clear dan /compact mengatur ulang ini, karena mereka membangun kembali cache di titik-titik tersebut bagaimanapun.

Menghubungkan atau memutuskan server MCP

Definisi tool berada di layer prompt sistem, jadi cache membatalkan ketika set definisi tool dalam permintaan berubah di antara giliran. Mengalihkan advisor tool adalah pengecualian: definisinya berada setelah breakpoint cache, jadi mengaktifkan atau menonaktifkan /advisor menjaga prefix yang di-cache tetap utuh. Apakah perubahan server MCP melakukan ini tergantung pada apakah tool-nya ditunda oleh tool search atau dimuat ke dalam prefix:

  • Tool yang ditunda, default pada model yang didukung: server yang terhubung, terputus, atau mengubah daftar tool-nya hanya menambahkan konten baru dan tidak mengganggu apa pun yang sudah di-cache.
  • Tool yang dimuat ke dalam prefix: perubahan apa pun pada mereka membatalkan cache. Ini terjadi ketika tool search tidak tersedia atau dinonaktifkan, seperti pada model Google Cloud's Agent Platform yang lebih awal dari generasi Claude 4.5, dengan gateway ANTHROPIC_BASE_URL kustom, atau pada deployment Microsoft Foundry yang dihosting di Azure setelah Claude Code mendeteksi bahwa deployment menolak tool search. Ini juga terjadi untuk server atau tool yang ditandai alwaysLoad, dan untuk definisi yang disimpan di depan oleh threshold-based loading.

Ketika tool dimuat ke dalam prefix, penyebab paling umum dari pembatalan adalah server yang terhubung atau terputus di tengah sesi, yang dapat terjadi tanpa tindakan apa pun dari pihak Anda: proses server stdio keluar, sesi HTTP kedaluwarsa, atau server reconnects secara otomatis setelah kegagalan sementara. Server yang terhubung juga dapat mendorong dynamic tool update yang mengubah daftar tool-nya.

Mengedit konfigurasi MCP Anda tidak dengan sendirinya mengubah cache. Konfigurasi baru berlaku hanya setelah restart, yaitu ketika server terhubung atau terputus.

Mengaktifkan atau menonaktifkan plugin

Ketika Anda mengaktifkan atau menonaktifkan plugin, biaya perubahan tergantung pada jenis komponen mana yang disediakan plugin. Kasus di bawah ini mencakup setiap jenis komponen, kapan Claude Code menerapkan perubahan, dan apa yang terjadi ketika Anda menonaktifkan plugin lagi dalam sesi yang sama.

Komponen plugin yang menjaga cache

Claude Code tidak pernah membatalkan cache untuk skills, commands, agents, hooks, monitors, atau themes plugin. Ini menambahkan konten mereka setelah percakapan yang ada, jadi permintaan berikutnya membayar untuk konten itu dan masih membaca semuanya sebelumnya dari cache.

Plugin yang menyediakan server MCP

Ketika Anda mengaktifkan atau menonaktifkan plugin yang menyediakan server MCP, Claude Code mengikuti aturan yang sama seperti ketika Anda menghubungkan atau memutuskan server MCP:

  • Jika Claude Code menunda tool server, itu menjaga cache.
  • Jika Claude Code memuat mereka ke dalam prefix, permintaan berikutnya membaca ulang seluruh percakapan.

Plugin code intelligence

Ketika Anda mengaktifkan plugin code intelligence, Claude mendapatkan LSP tool.

Kapan perubahan plugin berlaku

Claude Code menerapkan perubahan plugin ketika Anda menjalankan /reload-plugins atau memulai sesi baru. Anda membayar biaya, baik pengumuman yang ditambahkan atau pembacaan ulang penuh, pada giliran pertama setelah perubahan berlaku, bukan ketika Anda menjalankan /plugin enable atau /plugin disable. Claude Code juga dapat menerapkan perubahan dengan sendirinya dalam tiga kasus:

  • Untuk plugin dengan sumber command, Claude Code dapat memuat ulang plugin itu sendiri.
  • Ketika Anda menginstal plugin dari antarmuka /plugin, Claude Code dapat mengaktifkannya selama instalasi. Claude Code memberi tahu Anda dalam ringkasan instalasi apakah itu dilakukan atau untuk menjalankan /reload-plugins.
  • Ketika Anda memindahkan sesi dengan /cd pada v2.1.246 atau lebih baru, Claude Code menerapkan plugin yang diaktifkan pengaturan direktori baru sebagai bagian dari perpindahan, tanpa peringatan pembacaan ulang penuh yang menahan /reload-plugins.

Ketika Anda menjalankan /reload-plugins dan reload akan memicu pembacaan ulang penuh, Claude Code menampilkan peringatan dan tidak menerapkan reload. Jalankan ulang dengan --force untuk menerapkan reload bagaimanapun.

Plugin yang Anda aktifkan dan kemudian nonaktifkan dalam satu sesi

Ketika Anda menonaktifkan plugin yang Anda aktifkan sebelumnya dalam sesi, Claude Code mengembalikan bentuk permintaan sebelumnya. Jika prefix itu masih dalam cache lifetime-nya, permintaan berikutnya membaca entri cache yang lebih lama daripada membangun kembali.

Menolak seluruh tool

Menambahkan nama tool yang sederhana seperti Bash atau WebFetch sebagai deny rule menghapus tool tersebut dari konteks Claude sepenuhnya. Claude Code memuat definisi tool bawaan ke layer prompt sistem, jadi menambah atau menghapus salah satu aturan ini di tengah sesi membatalkan cache. Claude Code menerapkan perubahan pada permintaan berikutnya, baik Anda menambahkannya melalui /permissions atau dengan mengedit file pengaturan secara langsung. Itu termasuk aturan yang Anda tambahkan melalui /permissions di tengah giliran.

Hanya deny rule yang cocok di posisi nama-tool yang memiliki efek ini: nama tool yang sederhana, bentuk setara Bash(*), atau tool-name glob seperti "*". Glob yang cocok hanya dengan tool MCP, seperti "mcp__*", menghapus tool tersebut dengan cara yang sama tetapi menjaga cache tetap utuh ketika tool yang cocok ditunda, default, karena definisi yang ditunda tidak pernah ada di prefix yang di-cache. Deny rules yang dibatasi seperti Bash(rm *), dan semua allow dan ask rules, tidak mengubah tool mana yang Claude lihat. Claude Code memeriksanya ketika Claude mencoba melakukan panggilan, meninggalkan prefix tetap utuh.

Mengubah gaya output

Output style adalah bagian dari prompt sistem. Ketika Anda beralih gaya di tengah sesi dengan /config atau pengaturan outputStyle, Claude menggunakan gaya baru mulai dari pesan Anda berikutnya, dan permintaan itu membaca seluruh riwayat percakapan tanpa cache hits. Untuk menjaga biaya itu tetap kecil, alihkan gaya sebelum pesan pertama Anda dalam sesi atau tepat setelah /clear atau /compact, ketika ada sedikit atau tidak ada riwayat percakapan untuk dibaca ulang.

Sebelum v2.1.251, perubahan gaya di tengah sesi menjaga cache tetapi tidak berlaku sampai Anda menjalankan /clear atau memulai sesi baru.

Memadatkan percakapan

Compaction menggantikan riwayat pesan Anda dengan ringkasan. Dengan desain, ini membatalkan layer percakapan, karena permintaan berikutnya memiliki riwayat baru yang lebih pendek yang tidak berbagi prefix dengan yang lama. Claude Code menggunakan kembali layer prompt sistem dan memuat ulang konteks proyek dari disk, yang cache-hits hanya jika CLAUDE.md dan memory tidak berubah sejak sesi dimulai.

Untuk menghasilkan ringkasan, Claude Code mengirim permintaan terpisah dengan prompt sistem, tool, dan riwayat yang sama dengan percakapan Anda, ditambah instruksi summarisasi ditambahkan sebagai pesan pengguna akhir. Saat cache masih hangat, permintaan itu membaca prefix Anda dari cache, jadi compaction di tengah sesi biaya sebagian kecil dari apa yang ukuran konteks sarankan dan menghabiskan sebagian besar waktunya menghasilkan ringkasan.

Setelah istirahat lebih lama dari cache lifetime, tidak ada cache yang tersisa untuk dibaca, jadi permintaan summarisasi memproses ulang riwayat lengkap sebagai input yang tidak di-cache. Ini adalah mengapa /compact biaya paling banyak ketika Anda melanjutkan sesi lama. Dalam kedua kasus hangat dan dingin, giliran setelah compaction membangun kembali cache percakapan hanya untuk ringkasan yang jauh lebih pendek, jadi giliran itu bukan bagian yang lambat.

Mengumpulkan banyak gambar

API membatasi berapa banyak gambar dan PDF yang dapat dibawa setiap permintaan. Untuk angka saat ini, lihat Request limits dalam dokumentasi API. Claude Code juga membatasi ukuran total gambar dan PDF dalam permintaan, jadi screenshot besar mencapai batas dengan lebih sedikit gambar daripada yang kecil.

Ketika permintaan berikutnya akan melewati salah satu batas, Claude Code menghapus batch gambar dan PDF tertua dari apa yang dikirimnya, yang membuat ruang untuk lebih banyak sebelum perlu menghapus lagi. Claude tidak lagi dapat melihat gambar yang dihapus. Jika Claude membutuhkan salah satu dari mereka lagi, bagikan lagi.

Menghapus gambar mengubah pesan yang menahannya, jadi permintaan berikutnya memproses ulang percakapan dari yang paling awal dari pesan tersebut ke depan. Karena Claude Code menghapus batch sekaligus, Anda melihat satu giliran yang lebih lambat per batch daripada satu dengan setiap screenshot baru.

Meningkatkan Claude Code

Versi Claude Code baru biasanya memperbarui prompt sistem atau definisi tool, jadi permintaan pertama setelah upgrade membangun kembali cache dari atas. Auto-update mengunduh versi baru di latar belakang tetapi menerapkannya pada peluncuran berikutnya, tidak pernah di tengah sesi, jadi Anda melihat ini sebagai giliran pertama tanpa cache setelah restart daripada kejutan selama sesi. Atur DISABLE_AUTOUPDATER=1 untuk mengontrol kapan upgrade diterapkan.

Tindakan yang menjaga cache

Tindakan ini baik menambahkan ke akhir percakapan atau tidak menyentuh permintaan sama sekali. Beberapa di antaranya, seperti mengedit CLAUDE.md, menjaga cache untuk alasan yang sama mengapa perubahan tidak mencapai sesi yang berjalan sampai /clear, /compact, atau restart.

Mengedit file di repositori Anda

Konten file memasuki konteks hanya ketika Claude membacanya, dan pembacaan ditambahkan ke percakapan. Mengedit file yang sebelumnya dibaca Claude tidak secara retroaktif mengubah pembacaan sebelumnya dalam riwayat. Sebaliknya, Claude Code menambahkan <system-reminder> mencatat file berubah, dan Claude membacanya kembali jika diperlukan.

Mengedit CLAUDE.md di tengah sesi

File CLAUDE.md tingkat akar proyek dan tingkat pengguna dibaca sekali pada awal sesi dan disimpan dalam memori. Mengedit mereka di tengah sesi tidak membatalkan cache, tetapi edit juga tidak berlaku. Claude terus bekerja dengan versi yang dimuat pada awal sesi. Konten baru dimuat pada /clear, /compact, atau restart berikutnya.

File CLAUDE.md bersarang di subdirektori dan aturan dengan frontmatter paths: dimuat nanti, ketika Claude pertama kali membaca file yang cocok. Mengedit satu sebelum dimuat memang berlaku. Setelah dimuat, konten adalah bagian dari riwayat percakapan, jadi edit di tengah sesi tidak secara retroaktif mengubahnya.

Mengubah mode izin

Beralih di antara permission modes, seperti dari Manual ke accept edits, tidak mengubah prompt sistem atau definisi alat, jadi perubahan mode aman cache. Pengecualiannya adalah plan mode dengan pengaturan model opusplan, yang beralih model di antara Opus dan Sonnet saat Anda memasuki atau meninggalkan plan mode. Itu membuat toggle mode menjadi model switch.

Memanggil skills dan commands

Skills dan commands menyuntikkan instruksi mereka sebagai pesan pengguna pada titik invokasi. Tidak ada yang lebih awal dalam percakapan yang berubah.

Menjalankan `/recap`

/recap menghasilkan ringkasan untuk ditampilkan di terminal Anda. Tidak seperti /compact, ini menambahkan ringkasan sebagai output perintah daripada menggantikan riwayat pesan Anda, jadi prefix yang di-cache tetap utuh.

Memutar ulang percakapan

/rewind memotong percakapan Anda kembali ke giliran sebelumnya. Riwayat yang tersisa adalah konten yang sama yang cache dibangun darinya pada saat itu, dan layer prompt sistem dan konteks proyek tidak berubah, jadi permintaan berikutnya mencapai entri cache sebelumnya. Setiap giliran sejak saat itu telah membaca melalui prefix itu, yang menjaga entri tetap hangat bahkan jika giliran asli lebih lama dari TTL.

Memulihkan checkpoint file bersama percakapan tidak memiliki efek terpisah pada cache. Konten file memasuki konteks hanya ketika Claude membacanya, sama seperti mengedit file di repositori Anda.

Cache lifetime

Prefix yang di-cache kedaluwarsa setelah periode tidak aktif. Setiap permintaan yang mencapai cache mengatur ulang timer, jadi cache tetap hangat selama Anda terus bekerja. Setelah jeda yang cukup lama, permintaan berikutnya menghitung ulang input penuh dan membangun kembali cache, itulah mengapa giliran pertama kembali setelah menjauh dapat terasa jauh lebih lambat.

Pada paket Pro atau Max, ketika Anda melanjutkan sesi besar setelah istirahat lama, Claude Code menawarkan untuk melanjutkan dari ringkasan sehingga permintaan nanti tidak membawa riwayat penuh.

Time to live (TTL) mengontrol berapa lama jeda yang cache bertahan. API menawarkan dua: TTL lima menit, dan TTL satu jam yang menjaga cache tetap hangat melalui istirahat yang lebih lama tetapi menagih penulisan cache dengan tarif lebih tinggi. TTL yang lebih lama membantu ketika Anda meninggalkan sesi idle dan kembali ke sana, karena Anda melewati pemrosesan ulang yang dikenakan prefix yang kedaluwarsa. Ini lebih mahal pada ledakan pekerjaan singkat yang tidak pernah idle melampaui lima menit, di mana tarif penulisan yang lebih tinggi berlaku dan masa pakai cache yang lebih lama tidak digunakan.

TTL mana yang diterima setiap permintaan

Claude Code memutuskan TTL per permintaan, dan setiap permintaan jatuh dalam salah satu dari dua bucket tetap:

  • Main conversation: giliran interaktif Anda, run -p non-interaktif, dan giliran Agent SDK, ditambah pembantu yang Claude Code jalankan inline dengan mereka
  • Everything else: permintaan yang Claude Code buat di luar percakapan itu, seperti subagents, workflows, teammates dalam proses, fork, compaction, dan judul sesi

Kecuali Anda memilih TTL sendiri, Claude Code meminta TTL satu jam hanya pada langganan Claude dalam penggunaan yang disertakan paket Anda. Di sana ia meminta jam untuk percakapan utama, ditambah serangkaian kecil permintaan pembantu yang Anthropic kontrol di sisi server. Tabel ini memberikan TTL default setiap bucket di bawah kedua jenis penagihan.

Request bucket Claude subscription, within plan usage Usage credits, API key, or cloud provider
Main conversation One hour Five minutes
Everything else Five minutes, except the server-controlled helper requests, which get one hour Five minutes

Setelah Anda melampaui batas penggunaan paket Anda dan Claude Code menggunakan usage credits, Anda ditagih untuk penggunaan itu, jadi Claude Code menurunkan percakapan utama ke TTL lima menit yang lebih murah. Untuk menjaga TTL satu jam di sana, pilih TTL sendiri.

Pilih TTL sendiri

Anda dapat mengatur TTL untuk salah satu bucket. Setiap kontrol mengambil 5m atau 1h, dan Claude Code mengabaikan nilai lainnya.

Kedua pengaturan dan kedua variabel lingkungan memerlukan Claude Code v2.1.242 atau lebih baru. Jika Anda masuk dengan API key atau menggunakan penyedia cloud, atur promptCacheTtl ke 1h untuk memberikan percakapan utama cache satu jam. Permintaan di luar itu menjaga default lima menit sampai Anda memilih TTL untuk bucket itu juga.

Ketika lebih dari satu kontrol berlaku, Claude Code mengambil kecocokan pertama dalam urutan ini:

  1. FORCE_PROMPT_CACHING_5M=1, yang memaksa lima menit untuk kedua bucket
  2. Variabel lingkungan bucket
  3. Pengaturan bucket
  4. Untuk permintaan subagent, nilai cacheTtl dalam field frontmatter experimental subagent, yang memerlukan Claude Code v2.1.248 atau lebih baru. Claude Code mengabaikan 1h di sana sementara langganan Claude Anda menggunakan usage credits
  5. ENABLE_PROMPT_CACHING_1H=1, yang meminta satu jam untuk kedua bucket
  6. Default untuk bucket permintaan

Atur FORCE_PROMPT_CACHING_5M=1 ketika Anda men-debug perilaku cache, membandingkan dua TTL, atau mengganti TTL yang lebih lama yang ditetapkan dalam managed settings.

Untuk mengonfirmasi TTL mana yang digunakan penulisan cache percakapan utama Anda, jalankan claude -p "hello" --output-format json dan baca usage.cache_creation dalam hasilnya. Claude Code melaporkan penulisan cache satu jam di bawah ephemeral_1h_input_tokens dan penulisan cache lima menit di bawah ephemeral_5m_input_tokens.

Melalui gateway LLM yang Anda atur dengan ANTHROPIC_BASE_URL, bagian dari permintaan satu jam bepergian dalam header anthropic-beta, jadi konfigurasikan gateway untuk meneruskan header itu tanpa perubahan. TTL satu jam tidak tersedia melalui gateway aplikasi Claude. Di Amazon Bedrock, dukungan prompt caching, panjang prefix yang dapat di-cache minimum, dan ketersediaan TTL satu jam semuanya bervariasi menurut model. Jika hitungan token cache tetap di nol, periksa model yang didukung, wilayah, dan batas dalam dokumentasi Amazon Bedrock.

Cakupan cache

Di Claude Code, cache secara efektif dicakup ke satu mesin dan direktori. Prompt sistem menyematkan direktori kerja, platform, shell, versi OS, dan jalur auto-memory, jadi dua sesi di direktori berbeda membangun prefix berbeda dan melewatkan cache satu sama lain. Itu termasuk worktrees dari repositori yang sama, karena setiap worktree memiliki direktori kerjanya sendiri.

Sesi yang Anda jalankan secara paralel di direktori yang sama membangun prefix yang cocok dan membaca cache satu sama lain. Sesi berurutan berbagi prefix hanya ketika snapshot status git pada startup cocok, karena prompt sistem juga menangkap cabang dan commit terbaru.

Cache API yang mendasarinya lebih luas. Cache diisolasi di antara organisasi, dan pada beberapa penyedia, di antara workspace dalam organisasi. Dalam batas-batas itu, setiap dua permintaan dengan model dan prefix yang sama membaca cache yang sama. Untuk pemanggil Agent SDK yang menjalankan armada proses otomatis, lihat improve prompt caching across users and machines untuk menekan bagian per-mesin dari prompt sistem dan berbagi cache di seluruh mesin.

Periksa kinerja cache

Kinerja cache muncul sebagai dua hitungan token yang dilaporkan API pada setiap respons. Cara paling langsung untuk menontonnya secara langsung adalah statusline script yang membaca objek current_usage:

Field Arti
cache_creation_input_tokens Token yang ditulis ke cache pada giliran ini, ditagih dengan tarif penulisan cache
cache_read_input_tokens Token yang disajikan dari cache pada giliran ini, ditagih dengan kira-kira 10% dari tarif input standar

Rasio baca-ke-kreasi yang tinggi berarti caching berfungsi dengan baik. Jika kreasi tetap tinggi giliran demi giliran, sesuatu berubah dalam prefix Anda. Bagian actions that invalidate the cache mencantumkan penyebab umum.

Untuk ringkasan per-sesi, jalankan /usage. Setelah respons pertama percakapan utama, Claude Code menambahkan baris Prompt cache (main) ke blok Sesi, menampilkan rasio hit sesi, jumlah miss, dan apakah cache sedang hangat sekarang. Skrip statusline dapat membaca angka yang sama dari objek prompt_cache. Keduanya memerlukan Claude Code v2.1.251 atau lebih baru.

Baris Prompt cache (main) juga menamai kemungkinan penyebab miss terakhir ketika Claude Code dapat mengidentifikasinya, misalnya likely cause: tool definitions changed. Teks kemungkinan-penyebab memerlukan Claude Code v2.1.260 atau lebih baru.

Untuk visibilitas di seluruh organisasi, exporter OpenTelemetry melaporkan token baca dan kreasi cache per pengguna dan sesi. Lihat Monitor usage untuk referensi metrik dan atribut acara.

Subagents dan cache

Subagent memulai percakapannya sendiri dengan prompt sistem dan set alat-nya sendiri, terpisah dari induk. Permintaan pertamanya tidak membaca cache induk, karena kedua prefix berbeda, dan itu menghangatkan cache-nya sendiri di seluruh giliran-nya. Subagents berada di luar bucket TTL percakapan utama, jadi mereka mendapatkan lima menit bahkan pada langganan sampai Anda memilih yang lebih lama.

Cache induk tidak terpengaruh. Dari sisi induk, panggilan dan hasil subagent ditambahkan ke percakapan, meninggalkan prefix induk utuh.

Fork, sebaliknya, mewarisi prompt sistem induk, alat, dan riwayat percakapan dengan tepat, jadi permintaan pertamanya membaca cache induk.

Permintaan lain juga dapat membaca prefix yang di-cache oleh permintaan sebelumnya:

  • Session copies: sesi yang Anda salin dengan /fork menerima instruksi isolasinya sebagai pesan di akhir percakapan yang disalin, jadi cache yang dibangun oleh percakapan asli tetap utuh.
  • Compaction: panggilan summarisasi yang dijelaskan dalam Compacting the conversation menggunakan pendekatan berbagi prefix yang sama.
  • Workflow fan-outs: dalam workflow fan-out dari agen dengan prefix yang sama, Claude Code menahan semua kecuali yang pertama selama hingga 5 detik secara default, jadi permintaan pertama mereka dapat membaca prefix yang di-cache oleh agen pertama.

Nonaktifkan prompt caching

Menonaktifkan caching kadang-kadang berguna saat men-debug perilaku caching dengan model atau penyedia tertentu. Untuk mematikannya, atur salah satu variabel lingkungan ini ke 1:

Variable Efek
DISABLE_PROMPT_CACHING Nonaktifkan untuk semua model
DISABLE_PROMPT_CACHING_HAIKU Nonaktifkan untuk Haiku saja
DISABLE_PROMPT_CACHING_SONNET Nonaktifkan untuk Sonnet saja
DISABLE_PROMPT_CACHING_OPUS Nonaktifkan untuk Opus saja
DISABLE_PROMPT_CACHING_FABLE Nonaktifkan untuk Fable saja

Untuk menetapkan kebijakan caching di seluruh organisasi, masukkan salah satu dari ini atau TTL variables dalam blok env dari managed settings. Untuk penggunaan normal, biarkan caching diaktifkan.