Prompt caching là gì

Prompt caching giúp Claude Code nhanh hơn và rẻ hơn. Không có cơ chế này, API sẽ phải xử lý lại toàn bộ lịch sử của bạn ở mỗi lượt. Có caching, API tái sử dụng phần đã xử lý, tính tiền phần đọc lại đó theo mức giá cache (rẻ hơn nhiều so với input thường), và chỉ xử lý đầy đủ phần thật sự mới.

Claude Code tự quản lý prompt caching, trừ khi bạn tắt nó đi. Dù vậy, hiểu cơ chế này vẫn hữu ích, vì một số hành động sẽ làm mất cache và khiến lượt tiếp theo chậm, tốn hơn trong lúc cache được xây lại. Trang này liệt kê những hành động đó, giải thích vì sao một số thay đổi cấu hình phải đợi khởi động lại mới áp dụng, và cách kiểm tra hiệu năng cache khi thấy mức dùng tăng bất thường.

Cache được tổ chức như thế nào

Mỗi lần bạn gửi một tin nhắn, Claude Code tạo một request API mới. Model không “nhớ” gì giữa các request, nên Claude Code phải gửi lại toàn bộ ngữ cảnh: system prompt, ngữ cảnh dự án, mọi tin nhắn và kết quả tool trước đó, cộng thêm tin nhắn mới của bạn. Nội dung mới được thêm vào cuối, nghĩa là phần lớn mỗi request giống hệt request ngay trước nó. Prompt caching chính là cách API tránh phải xử lý lại phần không đổi đó.

Bốn lượt trao đổi thể hiện bằng các thanh ngang lớn dần. Mỗi request chứa toàn bộ lượt trước cộng thêm phần trao đổi mới nhất ở cuối. Ở lượt hai và ba, phần đầu (prefix) không đổi được đọc từ cache, chỉ phần trao đổi mới được xử lý. Ở lượt bốn, system prompt đổi nên prefix không còn khớp, toàn bộ request phải xử lý và ghi lại từ đầu.

API cache bằng cách khớp (kiểm tra chính xác) phần đầu (prefix) của mỗi request với nội dung nó vừa xử lý gần đây. Ở một lượt request bình thường, phần đầu chính là toàn bộ request trước đó, chỉ có message mới nhất (bao gồm câu trả lời liền trước và câu hỏi mới) là thật sự mới. Việc khớp này là khớp chính xác - chỉ cần một chỗ nào đó trong phần đầu thay đổi, mọi thứ phía sau nó phải tính toán lại từ đầu. Không có kiểu cache theo từng file hay từng đoạn riêng lẻ. Xem thêm cơ chế bên dưới trong tài liệu API nếu muốn hiểu sâu hơn.

Để tận dụng tối đa việc khớp phần đầu, Claude Code sắp xếp mỗi request theo thứ tự: nội dung càng ít đổi giữa các lượt càng đặt lên trước.

Lớp	Nội dung	Đổi khi nào
System prompt	Chỉ dẫn lõi, định nghĩa tool, output style	Bộ tool thay đổi, hoặc Claude Code được nâng cấp
Ngữ cảnh dự án	`CLAUDE.md`, auto memory, rule không giới hạn đường dẫn	Đầu phiên, hoặc sau khi chạy lệnh `/clear`, `/compact`
Hội thoại	Tin nhắn của bạn, câu trả lời của Claude, kết quả tool	Mỗi lượt request

Thay đổi ở lớp hội thoại không ảnh hưởng đến cache của system prompt và ngữ cảnh dự án. Thay đổi ở lớp system prompt làm mất cache của mọi thứ, vì toàn bộ nội dung phía sau giờ nằm sau một phần đầu khác. Cột thứ ba chỉ liệt kê nguyên nhân phổ biến chứ không đầy đủ - các phần bên dưới sẽ nói rõ toàn bộ, kể cả những thứ như output style vốn được cố định ngay từ đầu phiên.

Quy tắc khớp phần đầu giải thích cho hầu hết hành vi trong trang này. Ví dụ, plan mode và việc nạp skill đều chỉ ảnh hưởng đến Lớp Hội thoại, nên phần đầu đã cache vẫn giữ nguyên.

Có hai cấu hình không nằm trong nội dung prompt nhưng vẫn là một phần của “khoá” cache:

Model: mỗi model có cache riêng. Đổi model là tính lại toàn bộ request dù nội dung giống hệt nhau. Xem Đổi model bên dưới.
Effort level: trên hầu hết model, mỗi effort level cũng có cache riêng, nên đổi effort giữa phiên làm tính lại toàn bộ request. Riêng Fable 5.1 khi dùng API key hoặc gói Claude, cache vẫn giữ nguyên theo mặc định. Xem Đổi effort level bên dưới.

Cache nằm ở đâu

Việc cache diễn ra ở phía server, tại hạ tầng đang phục vụ model của bạn. Nơi đó là đâu phụ thuộc vào cách bạn xác thực (authenticate):

API key, gói Claude, hoặc Claude Platform trên AWS: cache nằm trên hạ tầng của Anthropic, truy cập qua Claude API.
Amazon Bedrock hoặc Google Cloud Agent Platform: cache nằm trên hạ tầng của nhà cung cấp cloud tương ứng.
Microsoft Foundry: tuỳ vào hình thức triển khai - triển khai “Hosted on Azure” phục vụ trên hạ tầng Azure, còn “Hosted on Anthropic” phục vụ trên hạ tầng Anthropic.
**ANTHROPIC_BASE_URL tuỳ chỉnh hoặc LLM gateway**: cache nằm ở bất cứ đâu request của bạn được chuyển tới, và việc cache có hoạt động hay không phụ thuộc vào gateway đó.

Claude Code cũng thêm ngữ cảnh hệ thống vào giữa hội thoại (ví dụ thông báo file thay đổi), và luôn đánh dấu khối đó để cache trên mọi nhà cung cấp và mọi kiểu kết nối. Ở endpoint riêng của từng nhà cung cấp, Amazon Bedrock (kể cả qua Mantle endpoint), Google Cloud Agent Platform, và Microsoft Foundry cache khối đó giống hệt Claude API.

Khi request của bạn đi qua LLM gateway, ANTHROPIC_BASE_URL tuỳ chỉnh, hoặc một base URL override của nhà cung cấp cloud như ANTHROPIC_BEDROCK_BASE_URL, việc gì còn được cache phụ thuộc vào cách gateway xử lý các marker cache_control mà Claude Code gửi kèm:

Chuyển tiếp nguyên vẹn: khối đó và hội thoại của bạn được cache giống hệt như ở endpoint gốc của nhà cung cấp.
Từ chối request có marker bằng lỗi 400 nhắc tới cache_control: Claude Code gửi lại request với marker chuyển từ khối đó sang tin nhắn hội thoại cuối cùng của bạn, và giữ nguyên vị trí đó cho phần còn lại của cuộc hội thoại. Khối đó tính phí như input chưa cache; hội thoại của bạn vẫn được cache.
Xoá marker nhưng vẫn trả về thành công: toàn bộ lịch sử hội thoại của bạn tính phí như input chưa cache ở mọi lượt. Một gateway chuyển system content dạng khối thành chuỗi văn bản thuần cũng làm mất marker theo cách tương tự.

Muốn biết mỗi nhà cung cấp lưu trữ/xử lý những gì, xem trang data usage. Dù cache nằm ở đâu, các mục cache đều hết hạn sau một khoảng thời gian không hoạt động - phần Thời gian sống của cache bên dưới nói rõ TTL và cách kéo dài nó.

Những hành động làm mất cache

Các hành động dưới đây khiến lượt request tiếp theo bị mất một phần hoặc toàn bộ cache. Bạn sẽ thấy một lượt chậm hơn, tốn hơn (chỉ một lần), sau đó phần đầu mới sẽ được cache lại. Hầu hết đều có thể tránh được giữa chừng một tác vụ, một khi bạn biết chúng có “giá” phải trả. Đổi model có thể cảm giác miễn phí cho đến khi bạn nhận ra lượt tiếp theo chậm hẳn đi.

Đổi model
Đổi effort level
Bật fast mode
Kết nối/ngắt kết nối MCP server
Bật/tắt plugin
Chặn hẳn một tool
Nén hội thoại
Tích luỹ nhiều hình ảnh
Nâng cấp Claude Code

Đổi model

Mỗi model có cache riêng. Đổi model bằng /model nghĩa là request tiếp theo phải đọc lại toàn bộ lịch sử hội thoại mà không trúng cache chỗ nào, dù nội dung hoàn toàn giống nhau.

Khi bạn chạy /model trong terminal, Claude Code chỉ hỏi xác nhận việc đổi model trong lúc cache còn hiệu lực. Cache còn hiệu lực trong một khoảng bằng đúng TTL của cache tính từ lần cuối Claude Code gửi request hoặc Claude trả lời trong hội thoại này. Qua khỏi mốc đó, cache coi như đã hết hạn, nên Claude Code đổi model luôn mà không hỏi.

Bạn cũng có thể bắt buộc luôn phải xác nhận, hoặc bỏ qua bước xác nhận đó, bằng một hook PreModelSwitch.

Cấu hình model opusplan (dùng Opus ở plan mode, Sonnet khi thực thi) khiến mỗi lần bật/tắt plan mode là một lần đổi model, và mở ra một cache hoàn toàn mới.

Cơ chế fallback model tự động trên Fable 5.1, Fable 5, và Opus 5 cũng tính là đổi model: khi một bộ phân loại an toàn gắn cờ request và category đó có model fallback, Claude Code chạy lại request trên model đó và phiên tiếp tục ở model mới.

Đổi effort level

Trên hầu hết model, đổi effort level giữa phiên bằng /effort khiến request tiếp theo đọc lại toàn bộ lịch sử mà không trúng cache. Trong lúc cache còn ấm, Claude Code sẽ hỏi bạn xác nhận trước khi áp dụng thay đổi.

Riêng trên Fable 5.1 khi dùng API key hoặc gói Claude, đổi effort level vẫn giữ nguyên cache, và Claude Code áp dụng mức mới luôn mà không hỏi. Ngoại lệ này không áp dụng trên Amazon Bedrock, Google Cloud Agent Platform, hay Claude apps gateway, cũng như khi bạn đặt CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, hoặc tổ chức của bạn có cấu hình HIPAA.

Bật fast mode

Bật fast mode thêm một header vào request, mà header này cũng là một phần của khoá cache, nên request đầu tiên Claude Code gửi kèm fast mode đọc lại toàn bộ lịch sử hội thoại mà không trúng cache. Claude Code đặt header này một lần khi lượt bắt đầu và giữ nguyên cho cả lượt, nên nếu bạn bật fast mode trong lúc Claude đang xử lý, việc mất cache do header chỉ xảy ra ở request đầu tiên của lượt kế tiếp. Số token chưa cache đó được tính theo mức giá của fast mode, đây là lý do bật fast mode ngay từ đầu phiên rẻ hơn bật giữa một phiên đã dài. Nếu model hiện tại của bạn không hỗ trợ fast mode, việc bật fast mode cũng đồng thời đổi model, và bản thân việc đổi model đó đã mở ra một cache hoàn toàn mới kể từ request tiếp theo trong lượt đang chạy.

Chi phí này chỉ xảy ra một lần cho mỗi hội thoại. Sau lượt fast mode đầu tiên, Claude Code tiếp tục gửi header đó và chỉ thay đổi tốc độ xử lý của request - phần này không nằm trong khoá cache. Tắt fast mode, cơ chế tự động rơi về tốc độ chuẩn khi bị giới hạn rate limit, rồi bật lại sau đó - tất cả đều giữ nguyên cache. Nếu bạn hết hạn mức sử dụng giữa phiên, Claude Code cũng thử lại các request fast mode bị từ chối ở tốc độ chuẩn theo cách tương tự, nên fallback này cũng không làm mất cache. /clear và /compact sẽ reset lại tất cả, vì hai lệnh này vốn đã xây lại cache ở điểm đó.

Kết nối/ngắt kết nối MCP server

Định nghĩa tool nằm ở lớp system prompt, nên cache mất khi tập định nghĩa tool trong request thay đổi giữa các lượt. Bật/tắt advisor tool là ngoại lệ: định nghĩa của nó nằm sau cache breakpoint, nên bật/tắt không ảnh hưởng phần đầu đã cache. Việc thay đổi một MCP server có làm mất cache hay không phụ thuộc vào việc tool của nó được nạp trễ (deferred, qua tool search) hay nạp thẳng vào phần đầu:

Tool nạp trễ (mặc định trên các model hỗ trợ): server kết nối, ngắt kết nối, hay đổi danh sách tool chỉ thêm nội dung mới vào cuối, không đụng đến phần đã cache.
Tool nạp thẳng vào phần đầu: bất kỳ thay đổi nào cũng làm mất cache. Tình huống này xảy ra khi tool search không khả dụng hoặc bị tắt - ví dụ trên các model đời trước Claude 4.5 ở Google Cloud Agent Platform, khi dùng gateway ANTHROPIC_BASE_URL tuỳ chỉnh, hoặc trên deployment Microsoft Foundry “Hosted on Azure” một khi Claude Code phát hiện deployment đó từ chối tool search. Cũng xảy ra với server/tool được đánh dấu alwaysLoad, hoặc định nghĩa được giữ sẵn ở phần đầu do cơ chế nạp theo ngưỡng (threshold-based loading).

Khi tool nạp thẳng vào phần đầu, nguyên nhân phổ biến nhất gây mất cache là một server kết nối/ngắt kết nối giữa phiên - điều này có thể xảy ra mà bạn không hề chủ động: process của một stdio server thoát, session HTTP hết hạn, hoặc server tự kết nối lại sau một lỗi tạm thời. Một server đang kết nối cũng có thể đẩy một cập nhật tool động làm đổi danh sách tool của nó.

Việc chỉnh sửa file cấu hình MCP tự nó không làm đổi cache. Cấu hình mới chỉ có hiệu lực sau khi khởi động lại - đó là lúc server thật sự kết nối hoặc ngắt kết nối.

Bật/tắt plugin

Khi bạn bật hoặc tắt một plugin, chi phí phải trả phụ thuộc vào loại thành phần mà plugin đó cung cấp.

Thành phần plugin giữ nguyên cache

Skill, command, subagent, hook, monitor, theme của một plugin không bao giờ làm mất cache: bất cứ thứ gì chúng thêm vào đều được nối vào cuối hội thoại hiện có, nên request tiếp theo chỉ trả tiền cho phần mới, còn phần trước đó vẫn đọc từ cache.

Plugin cung cấp MCP server

Bật/tắt một plugin cung cấp MCP server tuân theo đúng quy tắc ở phần kết nối/ngắt kết nối MCP server phía trên:

Nếu Claude Code nạp trễ tool của server, cache vẫn còn nguyên.
Nếu Claude Code nạp tool đó thẳng vào phần đầu, request tiếp theo phải đọc lại toàn bộ hội thoại.

Plugin code intelligence

Khi bạn bật một plugin code intelligence, Claude được cấp thêm LSP tool - đây cũng là một thay đổi ở lớp system prompt, nên áp dụng đúng quy tắc như mọi thay đổi định nghĩa tool khác.

Khi nào thay đổi plugin có hiệu lực

Claude Code áp dụng một thay đổi plugin khi bạn chạy /reload-plugins hoặc bắt đầu phiên mới. Chi phí - dù là vài thông báo được nối thêm hay đọc lại toàn bộ - xuất hiện ở lượt đầu tiên sau khi thay đổi có hiệu lực, chứ không phải ngay lúc bạn chạy /plugin enable hay /plugin disable. Claude Code cũng có thể tự áp dụng thay đổi trong ba trường hợp:

Với plugin có nguồn dạng command, Claude Code có thể tự reload plugin đó.
Khi bạn cài một plugin từ giao diện /plugin, Claude Code có thể kích hoạt plugin ngay lúc cài. Tóm tắt sau khi cài sẽ cho biết plugin đã được kích hoạt hay bạn cần chạy /reload-plugins.
Khi bạn chuyển phiên bằng /cd trên bản v2.1.246 trở lên, Claude Code áp dụng luôn các plugin mà cấu hình của thư mục mới bật, như một phần của việc chuyển thư mục, không kèm cảnh báo đọc lại toàn bộ như khi chạy /reload-plugins.

Khi bạn chạy /reload-plugins và việc reload đó sẽ kích hoạt đọc lại toàn bộ, Claude Code sẽ hiện cảnh báo và không áp dụng ngay. Chạy lại kèm --force để áp dụng dù vậy.

Bật rồi tắt plugin trong cùng một phiên

Tắt một plugin bạn vừa bật trước đó trong cùng phiên sẽ khôi phục lại hình dạng request trước đây. Nếu phần đầu đó vẫn còn trong thời gian sống của cache, request tiếp theo sẽ trúng cache cũ thay vì phải xây lại.

Chặn hẳn một tool

Thêm một rule deny với tên tool trần (ví dụ Bash hoặc WebFetch) trong cấu hình quyền hạn sẽ loại bỏ hẳn tool đó khỏi ngữ cảnh của Claude. Định nghĩa các tool tích hợp sẵn nằm ở lớp system prompt, nên thêm/bớt loại rule này giữa phiên làm mất cache. Claude Code áp dụng thay đổi ngay từ request kế tiếp, dù bạn thêm qua /permissions hay sửa trực tiếp file settings - kể cả khi rule đó được thêm qua /permissions ngay giữa một lượt.

Chỉ rule deny khớp ở vị trí tên tool mới gây ra hiệu ứng này: tên tool trần, dạng tương đương Bash(*), hoặc một wildcard tên tool như "*". Một wildcard chỉ khớp tool MCP, ví dụ "mcp__*", cũng loại bỏ các tool đó theo cùng cách nhưng để nguyên cache nếu các tool bị khớp đang ở dạng nạp trễ (mặc định) - vì định nghĩa nạp trễ vốn chưa từng nằm trong phần đầu đã cache. Rule deny có phạm vi hẹp như Bash(rm *), cùng mọi rule allow và ask, không làm đổi tập tool mà Claude nhìn thấy - Claude Code chỉ kiểm tra chúng khi Claude thật sự gọi tool, nên phần đầu vẫn nguyên vẹn.

Nén hội thoại (`/compact`)

Compaction thay thế lịch sử tin nhắn của bạn bằng một bản tóm tắt. Theo đúng thiết kế, điều này làm mất cache của lớp hội thoại, vì request tiếp theo có một lịch sử mới, ngắn hơn, không còn chung phần đầu với lịch sử cũ. Claude Code vẫn tái sử dụng lớp system prompt và nạp lại ngữ cảnh dự án từ đĩa - phần này chỉ trúng cache nếu CLAUDE.md và memory không đổi kể từ đầu phiên.

Để tạo bản tóm tắt, Claude Code gửi một request riêng với cùng system prompt, tool, và lịch sử như hội thoại của bạn, cộng thêm một chỉ dẫn tóm tắt được thêm vào cuối như một tin nhắn user. Trong lúc cache còn “ấm”, request này đọc phần đầu từ cache, nên một lượt /compact giữa phiên chỉ tốn một phần nhỏ so với kích thước ngữ cảnh gợi ý, và phần lớn thời gian dành để sinh ra bản tóm tắt.

Sau một khoảng nghỉ dài hơn thời gian sống của cache, không còn gì để đọc từ cache, nên request tóm tắt phải xử lý lại toàn bộ lịch sử như input chưa cache. Đây là lý do /compact tốn nhiều nhất khi bạn resume một phiên cũ. Trong cả hai trường hợp (cache còn ấm hay đã nguội), lượt ngay sau khi nén chỉ xây lại cache cho bản tóm tắt ngắn hơn nhiều - nên lượt đó không phải là phần chậm.

Tích luỹ nhiều hình ảnh

API giới hạn số ảnh và PDF mà mỗi request có thể mang theo. Xem Request limits trong tài liệu API để biết con số hiện tại. Claude Code cũng giới hạn tổng dung lượng ảnh và PDF trong một request, nên ảnh chụp màn hình lớn chạm giới hạn với số lượng ít hơn so với ảnh nhỏ.

Khi request tiếp theo sẽ vượt một trong hai giới hạn đó, Claude Code loại bỏ một loạt ảnh/PDF cũ nhất khỏi nội dung gửi đi, để có chỗ trống trước khi phải loại bỏ tiếp. Claude không còn “nhìn thấy” những ảnh đã bị loại. Nếu Claude cần lại một ảnh trong số đó, hãy chia sẻ lại.

Việc loại bỏ ảnh làm thay đổi chính những tin nhắn từng chứa chúng, nên request tiếp theo phải xử lý lại hội thoại kể từ tin nhắn sớm nhất bị đụng tới. Vì Claude Code loại bỏ theo từng đợt, bạn sẽ thấy một lượt chậm hơn mỗi đợt, chứ không phải mỗi lần thêm một ảnh mới.

Nâng cấp Claude Code

Một bản Claude Code mới thường cập nhật system prompt hoặc định nghĩa tool, nên request đầu tiên sau khi nâng cấp phải xây lại cache từ đầu. Auto-update tải bản mới ở nền nhưng chỉ áp dụng ở lần khởi động kế tiếp, không bao giờ áp dụng giữa phiên - nên bạn sẽ thấy đây là một lượt đầu chưa cache sau khi khởi động lại, chứ không phải một bất ngờ giữa phiên đang làm việc. Đặt DISABLE_AUTOUPDATER=1 nếu muốn tự kiểm soát thời điểm nâng cấp.

Những hành động không làm mất cache

Các hành động dưới đây hoặc chỉ nối thêm vào cuối hội thoại, hoặc không hề đụng đến request. Một vài trong số đó - như sửa CLAUDE.md hay đổi output style - cũng chính là lý do vì sao một thay đổi cấu hình phải đợi khởi động lại mới áp dụng.

Sửa file trong dự án
Sửa CLAUDE.md giữa phiên
Đổi output style
Đổi chế độ quyền hạn
Gọi skill và slash command
Chạy /recap
Tua lại hội thoại
Gọi subagent

Sửa file trong dự án

Nội dung file chỉ đi vào ngữ cảnh khi Claude đọc nó, và việc đọc luôn được nối vào cuối hội thoại. Sửa một file mà Claude đã đọc trước đó không làm thay đổi ngược lại lần đọc cũ trong lịch sử. Thay vào đó, Claude Code nối thêm một <system-reminder> báo file đã đổi, và Claude sẽ đọc lại nếu cần.

Sửa `CLAUDE.md` giữa phiên

File CLAUDE.md ở gốc dự án và ở cấp user chỉ được đọc một lần lúc đầu phiên rồi giữ trong bộ nhớ. Sửa các file này giữa phiên không làm mất cache, nhưng thay đổi cũng không có hiệu lực - Claude vẫn dùng bản đã nạp từ đầu phiên. Nội dung mới chỉ được nạp ở lần /clear, /compact, hoặc khởi động lại kế tiếp.

Các file CLAUDE.md lồng trong thư mục con, và rule có paths: trong frontmatter, được nạp muộn hơn - ngay khi Claude đọc file khớp điều kiện lần đầu. Sửa các file này trước khi chúng được nạp thì thay đổi có hiệu lực. Sau khi đã nạp, nội dung trở thành một phần của lịch sử hội thoại, nên sửa giữa phiên lúc này cũng không còn tác dụng ngược.

Đổi output style

Output style nằm trong system prompt, thứ Claude Code chỉ đọc một lần lúc đầu phiên. Đổi qua /config hoặc setting outputStyle giữa phiên không làm mất cache, nhưng thay đổi cũng không áp dụng ngay - Claude vẫn dùng style đã nạp từ đầu phiên. Style mới chỉ nạp ở lần /clear hoặc khởi động lại kế tiếp.

Đổi chế độ quyền hạn (permission mode)

Chuyển giữa các chế độ quyền hạn (ví dụ từ default sang accept-edits) không đổi system prompt hay định nghĩa tool, nên việc đổi mode an toàn với cache. Ngoại lệ là plan mode kết hợp với cấu hình model opusplan - trường hợp này đổi cả model khi bạn vào/ra plan mode, tức là một lần đổi model như đã nói ở trên.

Gọi skill và slash command

Skill và slash command chèn chỉ dẫn của chúng dưới dạng tin nhắn user ngay tại thời điểm gọi. Không có gì trước đó trong hội thoại bị thay đổi.

Chạy `/recap`

/recap sinh một bản tóm tắt để hiển thị ngay trong terminal. Khác với /compact, nó nối bản tóm tắt vào như output của một lệnh, thay vì thay thế lịch sử tin nhắn, nên phần đầu đã cache vẫn nguyên vẹn.

Tua lại hội thoại (`/rewind`)

/rewind cắt hội thoại của bạn về một lượt trước đó. Phần lịch sử còn lại chính là nội dung mà cache từng được xây dựng từ đó, còn lớp system prompt và ngữ cảnh dự án không đổi, nên request tiếp theo trúng đúng mục cache cũ. Mọi lượt kể từ đó tới giờ đều đã “đi qua” phần đầu này, nên mục cache vẫn ấm dù lượt gốc có thể đã xảy ra lâu hơn cả TTL.

Khôi phục checkpoint file song song với hội thoại không có tác động riêng lên cache - nội dung file chỉ vào ngữ cảnh khi Claude đọc nó, giống hệt như sửa file trong dự án ở trên.

Thời gian sống của cache (TTL)

Các phần đầu đã cache sẽ hết hạn sau một khoảng thời gian không hoạt động. Mỗi request trúng cache sẽ reset lại bộ đếm, nên cache vẫn còn hiệu lực chừng nào bạn còn làm việc liên tục. Sau một khoảng nghỉ đủ dài, request tiếp theo phải tính lại toàn bộ input và xây lại cache - đây là lý do lượt đầu tiên sau khi rời máy một lúc thường chậm hẳn.

Trên gói Pro hoặc Max, khi bạn resume một phiên lớn sau một khoảng nghỉ dài, Claude Code sẽ đề nghị resume từ bản tóm tắt để các request sau đó không phải mang theo toàn bộ lịch sử.

API cung cấp hai mức TTL: 5 phút, và TTL 1 giờ - giữ cache còn hiệu lực qua những khoảng nghỉ dài hơn nhưng tính phí ghi cache (cache write) cao hơn. TTL dài hơn có lợi khi bạn để một phiên nghỉ rồi quay lại, vì bạn tránh được chi phí xử lý lại một phần đầu đã hết hạn. Ngược lại, nó tốn hơn với những đợt làm việc ngắn không bao giờ nghỉ quá 5 phút - nơi mức phí ghi cao hơn phải trả trong khi thời gian sống dài hơn chẳng dùng tới.

Bucket nào dùng TTL nào

Claude Code quyết định TTL theo từng request, và mọi request đều rơi vào một trong hai nhóm cố định:

Hội thoại chính: các lượt tương tác của bạn, các lượt chạy non-interactive -p, và các lượt Agent SDK, cộng thêm những request phụ trợ mà Claude Code chạy kèm ngay trong các lượt đó.
Mọi thứ còn lại: các request Claude Code thực hiện bên ngoài hội thoại chính, như subagent, workflow, teammate chạy trong cùng process, fork, compaction, và việc đặt tiêu đề phiên.

Trừ khi bạn tự chọn TTL, Claude Code chỉ yêu cầu TTL 1 giờ khi bạn dùng gói Claude và còn trong hạn mức gói. Khi đó, Claude Code yêu cầu TTL 1 giờ cho hội thoại chính, cộng thêm một số request phụ trợ do Anthropic kiểm soát phía server. Bảng dưới đây liệt kê TTL mặc định của từng nhóm theo hai kiểu tính phí.

Nhóm request	Gói Claude, trong hạn mức	Usage credits, API key, hoặc nhà cung cấp cloud
Hội thoại chính	1 giờ	5 phút
Mọi thứ còn lại	5 phút, trừ các request phụ trợ do server kiểm soát được 1 giờ	5 phút

Khi bạn vượt hạn mức gói và Claude Code phải dùng usage credits, bạn bị tính phí cho phần dùng đó, nên Claude Code hạ hội thoại chính về TTL 5 phút rẻ hơn. Muốn giữ TTL 1 giờ trong trường hợp này, hãy tự chọn TTL.

Tự chọn TTL

Bạn có thể đặt TTL riêng cho từng nhóm. Mỗi tuỳ chọn nhận giá trị 5m hoặc 1h, Claude Code bỏ qua mọi giá trị khác.

Hội thoại chính: setting promptCacheTtl, hoặc biến môi trường CLAUDE_CODE_PROMPT_CACHE_TTL.
Mọi thứ còn lại: setting subagentPromptCacheTtl, hoặc biến môi trường CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL.

Nếu bạn đăng nhập bằng API key hoặc dùng nhà cung cấp cloud, đặt promptCacheTtl thành 1h để hội thoại chính có cache 1 giờ. Các request nằm ngoài nhóm đó vẫn giữ mặc định 5 phút cho tới khi bạn chọn TTL riêng cho nhóm đó.

Khi có nhiều tuỳ chọn cùng áp dụng, Claude Code chọn theo thứ tự ưu tiên sau:

FORCE_PROMPT_CACHING_5M=1 - buộc dùng 5 phút cho cả hai nhóm.
Biến môi trường riêng của nhóm request đó.
Setting riêng của nhóm request đó.
Với request của subagent, giá trị cacheTtl trong field experimental ở frontmatter của subagent (yêu cầu Claude Code v2.1.248 trở lên). Claude Code bỏ qua giá trị 1h ở đây trong lúc gói Claude của bạn đang dùng usage credits.
ENABLE_PROMPT_CACHING_1H=1 - yêu cầu 1 giờ cho cả hai nhóm.
Mặc định của nhóm request đó, như bảng ở trên.

Đặt FORCE_PROMPT_CACHING_5M=1 khi bạn đang debug hành vi cache, so sánh hai mức TTL, hoặc muốn ghi đè một TTL dài hơn đã đặt trong managed settings.

Muốn kiểm tra request ghi cache của hội thoại chính đang dùng TTL nào, chạy claude -p "hello" --output-format json và đọc usage.cache_creation trong kết quả. Claude Code báo cáo phần ghi cache 1 giờ dưới ephemeral_1h_input_tokens, và phần ghi cache 5 phút dưới ephemeral_5m_input_tokens.

Khi đi qua một LLM gateway đặt bằng ANTHROPIC_BASE_URL, một phần của request TTL 1 giờ nằm trong header anthropic-beta, nên hãy cấu hình gateway chuyển tiếp nguyên vẹn header đó. TTL 1 giờ không khả dụng qua Claude apps gateway. Trên Amazon Bedrock, việc hỗ trợ prompt caching, độ dài phần đầu tối thiểu có thể cache, và TTL 1 giờ đều khác nhau tuỳ model. Nếu số token cache luôn bằng 0, kiểm tra lại danh sách model/region/giới hạn được hỗ trợ trong tài liệu Amazon Bedrock.

Phạm vi của cache

Trong Claude Code, cache về cơ bản được giới hạn theo một máy và một thư mục. System prompt nhúng cả working directory, platform, shell, phiên bản OS, và các đường dẫn auto-memory - nên hai phiên chạy ở hai thư mục khác nhau sẽ xây hai phần đầu khác nhau, và không trúng cache của nhau. Điều này bao gồm cả các worktree của cùng một repository, vì mỗi worktree có working directory riêng.

Các phiên bạn chạy song song trong cùng một thư mục sẽ xây phần đầu khớp nhau, và đọc được cache của nhau. Các phiên chạy tuần tự chỉ dùng chung phần đầu nếu snapshot git status lúc khởi động khớp nhau, vì system prompt còn ghi lại cả branch hiện tại và các commit gần đây.

Cache của API bên dưới thì rộng hơn: cache được cách ly giữa các tổ chức, và ở một số nhà cung cấp, giữa các workspace trong cùng một tổ chức. Trong phạm vi đó, hai request bất kỳ có cùng model và cùng phần đầu sẽ đọc chung một cache. Nếu bạn dùng Agent SDK để chạy hàng loạt tiến trình tự động, xem cách cải thiện prompt caching giữa nhiều user và máy - có cách để loại bỏ các đoạn system prompt riêng theo từng máy, giúp chia sẻ cache giữa nhiều máy.

Kiểm tra hiệu năng cache

Hiệu năng cache thể hiện qua hai chỉ số token mà API trả về ở mỗi response. Cách trực tiếp nhất để theo dõi theo thời gian thực là một script statusline đọc object current_usage.

Trường	Ý nghĩa
`cache_creation_input_tokens`	Số token được ghi vào cache ở lượt này, tính phí theo mức giá ghi cache
`cache_read_input_tokens`	Số token được đọc từ cache ở lượt này, tính phí chỉ khoảng 10% mức giá input thường

Tỉ lệ đọc/ghi cao nghĩa là caching đang hoạt động tốt. Nếu số token ghi cache cứ cao đều ở mọi lượt, có gì đó đang thay đổi trong phần đầu request của bạn - xem lại phần những hành động làm mất cache ở trên để tìm nguyên nhân thường gặp.

Muốn xem tóm tắt theo từng phiên, chạy /usage. Sau câu trả lời đầu tiên của hội thoại chính, Claude Code thêm một dòng Prompt cache (main) vào khối Session, cho biết tỉ lệ cache hit, số lần miss, và cache có đang ấm ngay lúc đó hay không. Một script statusline cũng có thể đọc cùng những con số đó từ object prompt_cache. Cả hai yêu cầu Claude Code v2.1.251 trở lên.

Dòng Prompt cache (main) còn nêu nguyên nhân khả dĩ của lần miss gần nhất khi Claude Code xác định được, ví dụ likely cause: tool definitions changed. Phần văn bản nêu nguyên nhân này yêu cầu Claude Code v2.1.260 trở lên.

Nếu cần theo dõi ở cấp tổ chức, bộ export OpenTelemetry báo cáo số token đọc/ghi cache theo từng user và từng phiên - xem Theo dõi usage để biết chi tiết metric và event attribute.

Subagent và cache

Một subagent khởi tạo một hội thoại riêng, với system prompt và tập tool riêng, tách biệt hoàn toàn với phiên cha. Nó xây cache riêng - không trúng cache nào ở lần gọi đầu, rồi “ấm” dần qua các lượt của chính nó. Subagent nằm ngoài nhóm TTL của hội thoại chính, nên luôn dùng TTL 5 phút, kể cả khi phiên cha đang ở gói subscription với TTL 1 giờ tự động, trừ khi bạn tự chọn một TTL dài hơn.

Cache của phiên cha không bị ảnh hưởng. Từ góc nhìn của phiên cha, lệnh gọi subagent và kết quả trả về chỉ được nối thêm vào cuối hội thoại, phần đầu của phiên cha vẫn nguyên vẹn.

Ngược lại, một fork (nhân bản hội thoại hiện tại) kế thừa nguyên vẹn system prompt, tool, và lịch sử hội thoại của phiên cha, nên request đầu tiên của nó đọc thẳng từ cache của phiên cha. Ngoài fork, một số request khác cũng có thể đọc phần đầu mà một request trước đó đã cache:

Bản sao phiên: một phiên bạn sao chép bằng /fork nhận chỉ dẫn cô lập của nó dưới dạng một tin nhắn nối vào cuối bản hội thoại được sao chép, nên cache mà hội thoại gốc đã xây vẫn nguyên vẹn.
Compaction: lệnh gọi tóm tắt được nói ở phần nén hội thoại dùng đúng cách chia sẻ phần đầu này.
Workflow fan-out: khi một workflow toả ra nhiều agent dùng chung phần đầu, Claude Code giữ tất cả trừ agent đầu tiên chờ tối đa 5 giây theo mặc định, để request đầu tiên của chúng có thể đọc phần đầu mà agent đầu tiên đã cache.

Tắt prompt caching

Việc tắt caching thỉnh thoảng hữu ích khi bạn đang debug hành vi cache với một model hoặc nhà cung cấp cụ thể. Đặt một trong các biến môi trường sau bằng 1 để tắt:

Biến	Hiệu ứng
`DISABLE_PROMPT_CACHING`	Tắt cho mọi model
`DISABLE_PROMPT_CACHING_HAIKU`	Chỉ tắt cho Haiku
`DISABLE_PROMPT_CACHING_SONNET`	Chỉ tắt cho Sonnet
`DISABLE_PROMPT_CACHING_OPUS`	Chỉ tắt cho Opus
`DISABLE_PROMPT_CACHING_FABLE`	Chỉ tắt cho Fable

Muốn áp dụng chính sách caching cho cả tổ chức, đặt các biến này (hoặc các biến TTL ở trên) trong khối env của managed settings. Với việc dùng bình thường, cứ để caching bật như mặc định.

Đọc thêm

Cửa sổ ngữ cảnh - cái gì nạp vào ngữ cảnh và khi nào
Best practices - chiến lược khác ngoài caching để quản lý kích thước ngữ cảnh
Theo dõi chi phí và usage với Agent SDK - theo dõi token cache và cấu hình TTL khi gọi qua Agent SDK
Token, model & chi phí - cách chi phí token nói chung được tính