Как Claude Code использует prompt caching

Claude Code управляет prompt caching автоматически. Узнайте, почему переключение модели вызывает медленный ход без кэша, что стоит /compact, почему изменения CLAUDE.md не применяются во время сеанса и как проверить коэффициент попадания в кэш.

Prompt caching делает Claude Code быстрее и экономичнее. Без кэширования API переобрабатывал бы вашу полную историю на каждом ходу. С кэшированием он повторно использует то, что уже обработал, выставляет счет за повторное чтение по кэшированному тарифу токенов и полностью обрабатывает только то, что изменилось.

Claude Code управляет prompt caching для вас, если вы его не отключите. Тем не менее полезно знать, как работает prompt caching, потому что некоторые действия инвалидируют кэш и делают следующий ответ медленнее и дороже, пока он перестраивается. На этой странице рассматривается, какие действия это делают, почему некоторые параметры ждут перезагрузки для применения и как проверить производительность кэша, когда использование выглядит высоким.

Как организован кэш

Каждый раз, когда вы отправляете сообщение в Claude Code, он делает новый запрос API. Модель ничего не помнит между запросами, поэтому Claude Code повторно отправляет полный контекст: системный промпт, контекст вашего проекта, все предыдущие сообщения и результаты инструментов, а также ваше новое сообщение. Новое содержимое добавляется в конец, что означает, что большая часть каждого запроса идентична предыдущему. Prompt caching — это то, как API избегает переобработки части, которая не изменилась.

API кэширует, сопоставляя начало каждого запроса, называемое префиксом, с содержимым, которое он недавно обработал. На обычном ходу префикс — это весь предыдущий запрос, и только последний обмен является новым. Сопоставление точное, поэтому изменение где-либо в префиксе пересчитывает всё после него. Нет кэширования по отдельным файлам или сегментам. Подробнее о механизме см. в разделе как работает prompt caching в справочнике API.

Чтобы максимально использовать сопоставление префиксов, Claude Code упорядочивает каждый запрос так, чтобы содержимое, которое редко изменяется между ходами, шло первым:

Изменение слоя разговора оставляет системный промпт и контекст проекта в кэше. Изменение системного промпта делает недействительным всё, потому что всё последующее содержимое теперь находится за другим префиксом. Третий столбец приводит распространённые триггеры, а не исчерпывающий список, и разделы ниже охватывают полный набор.

Правило сопоставления префиксов объясняет большинство поведений на этой странице. Plan Mode и загрузка skills, например, добавляют свои инструкции как сообщения разговора, поэтому кэшированный префикс остаётся нетронутым.

Два параметра не отображаются в таблице слоёв, но всё ещё влияют на то, что остаётся в кэше:

• Model: каждая модель имеет свой кэш. Переключение моделей пересчитывает весь запрос даже когда содержимое идентично. Подробнее см. в разделе Переключение моделей ниже.
• Effort level: на большинстве моделей каждый уровень усилий имеет свой кэш, поэтому изменение усилий во время сеанса пересчитывает весь запрос. На Opus 5.5 и Fable 5.1 с API ключом или подпиской Claude кэш по умолчанию остаётся нетронутым. Подробнее см. в разделе Изменение уровня усилий ниже.

Где находится кэш

Кэширование происходит на стороне сервера в инфраструктуре, которая обслуживает вашу модель. Где именно это находится, зависит от того, как вы аутентифицируетесь:

• API ключ, подписка Claude или Claude Platform on AWS: кэш находится в инфраструктуре Anthropic, доступ через Claude API
• Amazon Bedrock или Agent Platform Google Cloud: кэш находится в инфраструктуре обслуживания вашего облачного провайдера
• Microsoft Foundry: зависит от опции хостинга развёртывания. Развёртывания, размещённые на Azure, обслуживаются на инфраструктуре Azure; развёртывания, размещённые на Anthropic, обслуживаются на инфраструктуре Anthropic
• Пользовательский ANTHROPIC_BASE_URL или LLM gateway: кэш находится там, куда перенаправляются ваши запросы, и работает ли кэширование, зависит от шлюза

Claude Code также добавляет системный контекст во время разговора, такой как уведомления об изменении файлов, и отмечает этот блок для кэширования на каждом провайдере и соединении, если вы не установили CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, в этом случае этот блок отправляется без кэширования.

На собственной конечной точке провайдера, Amazon Bedrock и его конечная точка Mantle, Agent Platform Google Cloud и Microsoft Foundry кэшируют блок так же, как это делает Claude API.

Когда ваши запросы проходят через LLM gateway, пользовательский ANTHROPIC_BASE_URL или переопределение базового URL облачного провайдера, такое как ANTHROPIC_BEDROCK_BASE_URL, то, что остаётся в кэше, зависит от того, как шлюз обрабатывает маркеры cache_control, которые отправляет Claude Code:

• Перенаправляет их без изменений: блок и ваш разговор кэшируются так же, как на собственной конечной точке провайдера.
• Отклоняет отмеченный запрос с ошибкой 400, указывающей на cache_control: Claude Code повторно отправляет запрос с маркером, перемещённым с блока на ваше последнее сообщение разговора, и сохраняет его там для остальной части разговора. Блок выставляется счётом как некэшированный ввод; ваш разговор остаётся в кэше.
• Удаляет маркеры при возврате успеха: вся история вашего разговора выставляется счётом как некэшированный ввод на каждом ходу. Шлюз, который преобразует системное содержимое в форме блока в простую строку, удаляет маркер так же.

Для информации о том, что хранит и обрабатывает каждый провайдер, см. использование данных. Где бы ни находился кэш, записи истекают после периода неактивности, и раздел Время жизни кэша ниже охватывает TTL и способы его продления.

Действия, которые инвалидируют кэш

Эти действия приводят к тому, что следующий запрос пропускает часть или весь кэш. Вы видите одноразовый более медленный и дорогостоящий ход, после чего новый префикс кэшируется. Большинство из них можно избежать во время выполнения задачи, если вы знаете, что они имеют стоимость. Переключение модели может казаться бесплатным, пока вы не заметите более медленный ход, который следует за ним.

• Переключение моделей
• Изменение уровня усилий
• Включение быстрого режима
• Подключение или отключение MCP сервера
• Включение или отключение плагина
• Отказ от всего инструмента
• Сжатие разговора
• Накопление большого количества изображений
• Обновление Claude Code

Переключение моделей

Каждая модель имеет свой собственный кэш. Переключение с помощью /model означает, что следующий запрос читает всю историю разговора без попаданий в кэш, даже если содержимое идентично.

Когда вы запускаете /model в терминале, Claude Code просит вас подтвердить переключение только пока кэш еще теплый и новая модель не является той, которая создала последний ответ. Кэш остается теплым в течение одного cache TTL после того, как Claude Code в последний раз отправил запрос в этом разговоре или Claude в последний раз ответил. После истечения этого времени кэш истекает, поэтому Claude Code переключается без запроса.

До версии v2.1.238 Claude Code не проверял cache TTL и спрашивал даже после истечения кэша.

Вы также можете требовать это подтверждение или пропустить его с помощью PreModelSwitch hook.

Параметр модели opusplan разрешается в Opus во время режима плана и Sonnet во время выполнения, поэтому каждое переключение режима плана является переключением модели и запускает свежий кэш.

Automatic model fallback на моделях Fable, Opus 5.5 и Opus 5 также является переключением модели. Когда классификатор безопасности помечает запрос в категории, которая имеет резервную модель, Claude Code повторно запускает запрос на этой модели и сеанс продолжается там.

Когда frontmatter навыка или команды указывает model, отличный от текущей модели сеанса, этот ход также является переключением модели: следующий запрос читает всю историю разговора без попаданий в кэш. Модель сеанса возобновляется при вашем следующем запросе. Навык context: fork устанавливает модель разветвленного подагента вместо этого.

Изменение уровня усилий

На большинстве моделей изменение уровня усилий в середине сеанса означает, что следующий запрос читает всю историю разговора без попаданий в кэш. Пока кэш еще теплый, Claude Code просит вас сначала подтвердить изменение.

На Opus 5.5 и Fable 5.1 с ключом API или подпиской Claude изменение усилий сохраняет кэш, и Claude Code применяет новый уровень без запроса. Это не применяется на Amazon Bedrock, платформе Google Cloud Agent Platform или Claude apps gateway, или когда вы установили CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS или ваша организация имеет конфигурацию HIPAA.

До версии v2.1.260 изменение усилий на Fable 5.1 с ключом API или подпиской Claude также инвалидировало кэш.

Включение быстрого режима

Включение fast mode добавляет заголовок запроса, который является частью ключа кэша, поэтому первый запрос, который Claude Code отправляет с включенным fast mode, читает всю историю разговора без попаданий в кэш. Claude Code устанавливает этот заголовок один раз при запуске хода и сохраняет его для всего хода, поэтому когда вы включаете fast mode во время работы Claude, пропуск кэша из заголовка происходит при первом запросе вашего следующего хода. Эти некэшированные входные токены выставляются по fast mode rates, поэтому включение его в начале сеанса стоит меньше, чем включение его глубоко в длинный сеанс. Если ваша текущая модель не поддерживает fast mode, включение fast mode также переключает вашу модель, и это переключение запускает свежий кэш самостоятельно с следующего запроса в текущем ходе.

Стоимость применяется один раз за разговор. После первого хода fast mode Claude Code продолжает отправлять заголовок и варьирует только параметр скорости запроса, который не является частью ключа кэша. Отключение fast mode, автоматический откат к стандартной скорости после ограничения скорости и повторное включение позже все сохраняют кэш. Если вы исчерпаете кредиты использования в середине сеанса, Claude Code повторяет каждый отклоненный запрос fast mode на стандартной скорости таким же образом, поэтому этот откат также сохраняет кэш. /clear и /compact сбрасывают это, так как они все равно перестраивают кэш в этих точках.

Подключение или отключение MCP сервера

Определения инструментов находятся в слое системной подсказки, поэтому кэш инвалидируется, когда набор определений инструментов в запросе изменяется между ходами. Переключение advisor tool является исключением: его определение находится после точки разрыва кэша, поэтому включение или отключение /advisor сохраняет кэшированный префикс нетронутым. Зависит ли изменение MCP server от этого от того, отложены ли его инструменты tool search или загружены в префикс:

• Deferred tools, по умолчанию на поддерживаемых моделях: подключение, отключение сервера или изменение его списка инструментов только добавляет новое содержимое и не нарушает ничего уже кэшированного.
• Tools loaded into the prefix: любое изменение их инвалидирует кэш. Это происходит, когда tool search недоступен или отключен, например на моделях Google Cloud Agent Platform более ранних, чем поколение Claude 4.5, с пользовательским шлюзом ANTHROPIC_BASE_URL или на развертывании Microsoft Foundry размещенном на Azure после того, как Claude Code обнаружит, что развертывание отклоняет tool search. Это также происходит для сервера или инструмента, отмеченного alwaysLoad, и для определений, сохраняемых впереди threshold-based loading.

Когда инструменты загружаются в префикс, наиболее частой причиной инвалидации является подключение или отключение сервера в середине сеанса, что может произойти без каких-либо действий с вашей стороны: процесс stdio сервера завершается, сеанс HTTP истекает или сервер автоматически переподключается после временного сбоя. Подключенный сервер также может отправить dynamic tool update, который изменяет его список инструментов.

Редактирование конфигурации MCP само по себе не изменяет кэш. Новая конфигурация вступает в силу только после перезагрузки, когда сервер подключается или отключается.

Включение или отключение плагина

Когда вы включаете или отключаете plugin, стоимость изменения зависит от того, какие типы компонентов предоставляет плагин. Случаи ниже охватывают каждый тип компонента, когда Claude Code применяет изменение и что происходит, когда вы отключаете плагин снова в том же сеансе.

Компоненты плагина, которые сохраняют кэш

Claude Code никогда не инвалидирует кэш для навыков, команд, агентов, hooks, мониторов или тем плагина. Он добавляет их содержимое после существующего разговора, поэтому следующий запрос платит за это содержимое и все еще читает все, что было до него, из кэша.

Плагины, которые предоставляют MCP серверы

Когда вы включаете или отключаете плагин, который предоставляет MCP servers, Claude Code следует тем же правилам, что и при подключении или отключении MCP server:

• Если Claude Code откладывает инструменты сервера, он сохраняет кэш.
• Если Claude Code загружает их в префикс, следующий запрос повторно читает весь разговор.

Плагины анализа кода

Когда вы включаете code intelligence plugin, Claude получает LSP tool.

Когда применяются изменения плагинов

Изменение, которое вы вносите в меню /plugin, проходит через /reload-plugins, которое Claude Code запускает для вас при закрытии меню. Вы платите стоимость, будь то добавленные объявления или полное повторное чтение, при первом ходе после применения изменения. Claude Code также может применить изменение самостоятельно:

• Для плагина с источником command Claude Code может перезагрузить плагин самостоятельно.
• Когда вы устанавливаете плагин из интерфейса /plugin, Claude Code может активировать его во время установки. Сводка установки сообщит вам, сделал ли он это.
• Когда вы перемещаете сеанс с помощью /cd на v2.1.246 или позже, Claude Code применяет плагины, которые включают параметры нового каталога, как часть перемещения, без полного предупреждения повторного чтения, которое удерживает /reload-plugins.
• В интерактивных сеансах, когда вы добавляете или удаляете плагин в folder of plugins который вы передали с --plugin-dir, изменение применяется сразу же. Если применение его вызовет полное повторное чтение, Claude Code удерживает изменение и показывает уведомление для запуска /reload-plugins. Требует Claude Code v2.1.265 или позже.

Когда /reload-plugins запускается и перезагрузка вызовет полное повторное чтение, Claude Code показывает предупреждение и не применяет перезагрузку. Запустите /reload-plugins --force для применения в любом случае.

/reload-plugins также запускается в сеансах без интерактивного терминала, таких как настольное приложение, Agent SDK и non-interactive mode с -p, когда вы вводите его непосредственно в сеанс. Требует Claude Code v2.1.260 или позже.

В этих сеансах перезагрузка применяет все, кроме изменений MCP сервера плагина, которые вступают в силу в вашем следующем сеансе и поэтому никогда не стоят полного повторного чтения в середине сеанса.

Плагины, которые вы включаете, а затем отключаете в одном сеансе

Когда вы отключаете плагин, который вы включили ранее в сеансе, Claude Code восстанавливает предыдущую форму запроса. Если этот префикс все еще находится в пределах его cache lifetime, следующий запрос читает более старую запись кэша вместо перестройки.

Отказ от всего инструмента

Если вы добавляете простое имя инструмента, такое как Bash или WebFetch, как deny rule, Claude не может вызвать этот инструмент с вашего следующего запроса, независимо от того, добавляете ли вы правило через /permissions или путем редактирования файла параметров напрямую. Это включает правило, которое вы добавляете через /permissions в середине хода.

Когда tool search активен, что является стандартным на поддерживаемых моделях, определения инструментов в запросе не изменяются и кэшированный префикс выживает. Когда tool search недоступен или отключен, Claude Code удаляет определение из следующего запроса, что инвалидирует кэш, и то же самое происходит при удалении правила позже.

Только правило отрицания, которое совпадает в позиции имени инструмента, блокирует инструмент таким образом: простое имя инструмента, эквивалентная форма Bash(*) или tool-name glob как "*". Glob, который совпадает только с инструментами MCP, такой как "mcp__*", блокирует эти инструменты таким же образом. Правила отрицания с областью действия, такие как Bash(rm *), и все правила разрешения и запроса не изменяют, какие инструменты видит Claude. Claude Code проверяет их, когда Claude пытается выполнить вызов, оставляя префикс нетронутым.

Сжатие разговора

Compaction заменяет историю ваших сообщений на сводку. По замыслу, это инвалидирует слой разговора, так как следующий запрос имеет новую, более короткую историю, которая не делит префикс со старой. Claude Code повторно использует слой системной подсказки, если разговор не был возобновлен при сохранении системной подсказки, которая иначе изменилась бы; в этом случае первая компактизация переключается на текущую подсказку и этот слой перестраивается один раз. Он перезагружает контекст проекта с диска, который кэшируется только если CLAUDE.md и память не изменились с начала сеанса.

Для создания сводки Claude Code отправляет отдельный запрос с той же системной подсказкой, инструментами и историей, что и ваш разговор, плюс инструкция суммирования, добавленная как финальное сообщение пользователя. Пока кэш теплый, этот запрос читает ваш префикс из кэша, поэтому /compact в середине сеанса стоит часть того, что предполагает размер контекста, и тратит большую часть времени на создание сводки.

После перерыва, превышающего cache lifetime, кэша не осталось для чтения, поэтому запрос суммирования повторно обрабатывает полную историю как некэшированный ввод. Вот почему /compact стоит больше всего, когда вы возобновляете старый сеанс. В обоих случаях, теплом и холодном, ход после компактизации перестраивает кэш разговора только для намного более короткой сводки, поэтому этот ход не является медленной частью.

Накопление большого количества изображений

API ограничивает количество изображений и PDF-файлов, которые может содержать каждый запрос. Для текущих чисел см. Request limits в документации API. Claude Code также ограничивает общий размер изображений и PDF-файлов в запросе, поэтому большие снимки экрана достигают лимита с меньшим количеством изображений, чем маленькие.

Когда следующий запрос превысит любой лимит, Claude Code удаляет партию самых старых изображений и PDF-файлов из того, что он отправляет, что освобождает место для большего количества, прежде чем ему нужно удалять снова. Claude больше не может видеть удаленные изображения. Если Claude нужно одно из них снова, поделитесь им снова.

Удаление изображений изменяет сообщения, которые их содержали, поэтому следующий запрос повторно обрабатывает разговор с самого раннего из этих сообщений. Поскольку Claude Code удаляет партию за раз, вы видите один более медленный ход за партию, а не один с каждым новым снимком экрана.

Обновление Claude Code

Новая версия Claude Code обычно обновляет системную подсказку или определения инструментов, поэтому первый разговор, который вы начинаете после обновления, строит свой кэш с нуля. Auto-update загружает новые версии в фоновом режиме, но применяет их при следующем запуске, никогда в середине сеанса, поэтому вы видите это как некэшированный первый ход после перезагрузки, а не сюрприз во время сеанса. Установите DISABLE_AUTOUPDATER=1 для управления тем, когда применяются обновления.

Действия, которые сохраняют кэш

Эти действия либо добавляют информацию в конец разговора, либо вообще не трогают запрос. Некоторые из них, такие как редактирование CLAUDE.md, сохраняют кэш по той же причине, по которой изменение не достигает запущенной сессии до /clear, /compact или перезагрузки.

• Редактирование файлов в вашем репозитории
• Редактирование CLAUDE.md во время сессии
• Изменение режима разрешений
• Изменение стиля вывода
• Вызов skills и команд
• Запуск /recap
• Откат разговора
• Создание подагента

Редактирование файлов в вашем репозитории

Содержимое файлов попадает в контекст только когда Claude их читает, а чтения добавляются в разговор. Редактирование файла, который Claude ранее прочитал, не изменяет ретроактивно более раннее чтение в истории. Вместо этого Claude Code добавляет <system-reminder>, отмечая, что файл изменился, и Claude перечитывает его при необходимости.

Редактирование CLAUDE.md во время сессии

Ваши файлы CLAUDE.md на уровне корня проекта и пользователя читаются один раз при запуске сессии и хранятся в памяти. Редактирование их во время сессии не инвалидирует кэш, но редактирование также не применяется. Claude продолжает работать с версией, которая была загружена при запуске сессии. Новое содержимое загружается при следующем /clear, /compact или перезагрузке.

Вложенные файлы CLAUDE.md в подпапках и правила с фронтматтером paths: загружаются позже, когда Claude впервые читает соответствующий файл. Редактирование одного до его загрузки действительно вступает в силу. После загрузки содержимое становится частью истории разговора, поэтому редактирование во время сессии не изменяет его ретроактивно.

Изменение режима разрешений

Переключение между режимами разрешений, например с Manual на принятие редактирования, не изменяет системный запрос или определения инструментов, поэтому изменения режима безопасны для кэша. Исключением является режим плана с параметром модели opusplan, который переключает модель между Opus и Sonnet при входе или выходе из режима плана. Это делает переключение режима переключением модели.

Изменение стиля вывода

Когда вы переключаете стили вывода во время сессии с помощью /output-style, /config или параметра outputStyle, Claude использует новый стиль начиная со следующего сообщения. Claude Code доставляет инструкции нового стиля как сообщение в разговоре, поэтому этот запрос по-прежнему читает системный запрос и более ранний разговор из кэша.

До версии 2.1.251 переключение стиля во время сессии сохраняло кэш, но не применялось до запуска /clear или начала новой сессии.

Вызов skills и команд

Skills и команды вводят свои инструкции как пользовательские сообщения в точке вызова. Ничего более раннего в разговоре не изменяется. Skill или команда, чей фронтматтер называет model, может быть переключением модели для этого хода.

Запуск `/recap`

/recap генерирует сводку для отображения в вашем терминале. В отличие от /compact, она добавляет сводку как вывод команды, а не заменяет историю ваших сообщений, поэтому кэшированный префикс остается нетронутым.

Откат разговора

/rewind усекает ваш разговор до более раннего хода. Оставшаяся история — это то же содержимое, из которого был построен кэш в этот момент, и системный запрос и слои контекста проекта не изменяются, поэтому следующий запрос попадает на более раннюю запись кэша. Каждый ход с тех пор читал через этот префикс, что держал запись в тепле даже если исходный ход был давно, чем TTL.

Восстановление контрольных точек файлов вместе с разговором не имеет отдельного эффекта на кэш. Содержимое файлов попадает в контекст только когда Claude их читает, так же как редактирование файлов в вашем репозитории.

Возобновление сеанса

Когда вы возобновляете сеанс, Claude Code отправляет всю беседу снова, и запрос читает из кэша ту часть своего префикса, которая не изменилась и все еще находится в пределах времени жизни кэша. Таблица слоев в верхней части этой страницы показывает, что изменяется в каждом слое.

Системный запрос изменится после обновления Claude Code или с другим текстом --append-system-prompt при возобновлении. По умолчанию возобновленная беседа сохраняет системный запрос, с которого она началась, поэтому его история по-прежнему находится за тем же запросом, и изменение вступает в силу после компактификации беседы или в новой беседе. Флаги системного запроса в возобновленных беседах охватывает случаи, когда Claude Code перестраивает запрос при каждом запросе вместо этого.

Время жизни кэша

Кэшированные префиксы истекают после периода неактивности. Каждый запрос, который попадает в кэш, сбрасывает таймер, поэтому кэш остаётся активным, пока вы продолжаете работать. После достаточно длительного перерыва следующий запрос пересчитывает полный ввод и переустанавливает кэш, поэтому первый ход после перерыва может быть заметно медленнее.

В плане Pro или Max, когда вы возобновляете большую сессию после длительного перерыва, Claude Code предлагает возобновить работу из сводки, чтобы последующие запросы не несли полную историю.

Время жизни (TTL) контролирует, как долго кэш может пережить перерыв. API предлагает два варианта: пятиминутный TTL и одночасовой TTL, который поддерживает кэш в активном состоянии во время более длительных перерывов, но выставляет счета за записи в кэш по более высокому тарифу. Более длительный TTL помогает, когда вы оставляете сессию неактивной и возвращаетесь к ней, потому что вы избегаете переобработки, которая стоит истекшему префиксу. Это стоит дороже при коротких всплесках работы, которые никогда не простаивают более пяти минут, где применяется более высокий тариф записи и более длительное время жизни кэша остаётся неиспользованным.

Какой TTL получает каждый запрос

Claude Code определяет TTL для каждого запроса, и каждый запрос попадает в один из двух фиксированных наборов:

• Основной разговор: ваши интерактивные ходы, неинтерактивные запуски -p и ходы Agent SDK, плюс помощники, которые Claude Code запускает встроенно с ними
• Всё остальное: запросы, которые Claude Code делает вне этого разговора, такие как подагенты, рабочие процессы, встроенные товарищи по команде, форки, компактизация и названия сессий

Если вы не выбираете TTL самостоятельно, Claude Code запрашивает одночасовой TTL только в подписке Claude в рамках включённого использования вашего плана. Там он запрашивает час для основного разговора, плюс небольшой набор вспомогательных запросов, которые Anthropic контролирует на стороне сервера. Эта таблица показывает стандартный TTL каждого набора при обоих видах выставления счётов.

Как только вы превышаете лимит использования вашего плана и Claude Code использует кредиты использования, вам выставляется счёт за это использование, поэтому Claude Code переводит основной разговор на более дешёвый пятиминутный TTL. Чтобы сохранить одночасовой TTL там, выберите TTL самостоятельно.

Выберите TTL самостоятельно

Вы можете установить TTL для любого набора. Каждый элемент управления принимает 5m или 1h, и Claude Code игнорирует любое другое значение.

• Основной разговор: параметр promptCacheTtl или переменная окружения CLAUDE_CODE_PROMPT_CACHE_TTL environment variable
• Всё остальное: параметр subagentPromptCacheTtl или переменная окружения CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL

Оба параметра и обе переменные окружения требуют Claude Code v2.1.242 или более поздней версии. Если вы входите с помощью API ключа или используете облачного провайдера, установите promptCacheTtl на 1h, чтобы дать основному разговору кэш на один час. Запросы вне его сохраняют пятиминутное значение по умолчанию, пока вы не выберете TTL для этого набора тоже.

Когда применяется более одного элемента управления, Claude Code берёт первое совпадение в этом порядке:

1. FORCE_PROMPT_CACHING_5M=1, который принудительно устанавливает пять минут для обоих наборов
2. Переменная окружения набора
3. Параметр набора
4. Для запросов подагента значение cacheTtl в поле frontmatter experimental подагента, которое требует Claude Code v2.1.248 или более поздней версии. Claude Code игнорирует 1h там, пока ваша подписка Claude использует кредиты использования
5. ENABLE_PROMPT_CACHING_1H=1, который запрашивает один час для обоих наборов
6. Значение по умолчанию для набора запроса

Установите FORCE_PROMPT_CACHING_5M=1, когда вы отлаживаете поведение кэша, сравниваете два TTL или переопределяете более длительный TTL, установленный в управляемых параметрах.

Чтобы подтвердить, какой TTL использовали записи в кэш вашего основного разговора, запустите claude -p "hello" --output-format json и прочитайте usage.cache_creation в результате. Claude Code сообщает одночасовые записи в кэш под ephemeral_1h_input_tokens и пятиминутные записи в кэш под ephemeral_5m_input_tokens.

Через шлюз LLM, который вы установили с помощью ANTHROPIC_BASE_URL, часть одночасового запроса проходит в заголовке anthropic-beta, поэтому настройте шлюз на пересылку этого заголовка без изменений. Одночасовой TTL недоступен через шлюз приложений Claude. На Amazon Bedrock поддержка кэширования подсказок, минимальная длина кэшируемого префикса и доступность одночасового TTL варьируются в зависимости от модели. Если счётчики токенов кэша остаются на нуле, проверьте поддерживаемые модели, регионы и ограничения в документации Amazon Bedrock.

Область действия кэша

В Claude Code кэш фактически ограничен одной машиной и директорией. Каждый разговор содержит рабочую директорию, платформу, оболочку и версию ОС, а системный запрос называет пути вашей автоматической памяти, поэтому две сессии в разных директориях создают разные префиксы и не попадают в кэш друг друга. Это включает worktrees одного и того же репозитория, поскольку каждый worktree имеет свою собственную рабочую директорию.

Сессии, которые вы запускаете параллельно в одной директории, создают совпадающие префиксы и читают кэш друг друга. Последовательные сессии совместно используют префикс только когда снимок состояния git, сделанный при запуске, совпадает, поскольку каждый разговор также содержит ветку и недавние коммиты из этого снимка.

Базовый кэш API шире. Кэши изолированы между организациями и на некоторых поставщиках, между рабочими пространствами в организации. В этих границах любые два запроса с одной и той же моделью и префиксом читают один и тот же кэш. Для вызывающих Agent SDK, запускающих флоты автоматизированных процессов, см. улучшение кэширования запросов для нескольких пользователей и машин, чтобы подавить разделы системного запроса для каждой машины и совместно использовать кэш на разных машинах.

Проверка производительности кэша

Производительность кэша отображается в виде двух подсчётов токенов, которые API сообщает в каждом ответе. Наиболее прямой способ отслеживать их в реальном времени — это скрипт строки состояния, который читает объект current_usage:

Высокое соотношение чтения к созданию означает, что кэширование работает хорошо. Если создание остаётся высоким ход за ходом, что-то меняется в вашем префиксе. В разделе действия, которые инвалидируют кэш перечислены обычные причины.

Для сводки по сеансу запустите /usage. После первого ответа основного разговора Claude Code добавляет строку Prompt cache (main) в блок сеанса, показывающую коэффициент попаданий сеанса, количество промахов и то, горячий ли кэш прямо сейчас. Скрипт строки состояния может читать те же числа из объекта prompt_cache. Оба требуют Claude Code v2.1.251 или позже.

Строка Prompt cache (main) также называет вероятную причину последнего промаха, когда Claude Code может её определить, например likely cause: tool definitions changed. Текст вероятной причины требует Claude Code v2.1.260 или позже.

Для видимости в масштабах организации экспортер OpenTelemetry сообщает токены чтения и создания кэша для каждого пользователя и сеанса. Справку по метрикам и атрибутам событий см. в разделе Мониторинг использования.

Подагенты и кэш

Подагент начинает свой собственный разговор со своим собственным системным приглашением и набором инструментов, отдельно от родительского. Его первый запрос не читает кэш родителя, потому что два префикса отличаются, и он прогревает свой собственный кэш на протяжении своих ходов. Подагенты находятся вне основного разговора TTL bucket, поэтому они получают пять минут даже по подписке, пока вы не выберете более длительный.

Кэш родителя не затронут. Со стороны родителя, вызов подагента и результат добавляются к разговору, оставляя префикс родителя нетронутым.

Ветвь, напротив, наследует системное приглашение родителя, инструменты и историю разговора точно, поэтому её первый запрос читает кэш родителя.

Другие запросы также могут читать префикс, который более ранний запрос поместил в кэш:

• Копии сеанса: сеанс, который вы копируете с помощью /fork, получает свою инструкцию изоляции как сообщение в конце скопированного разговора, поэтому кэш, который построил исходный разговор, остаётся нетронутым.
• Компактизация: вызов суммаризации, описанный в Компактизация разговора, использует тот же подход совместного использования префикса.
• Возобновленные подагенты: когда Claude возобновляет подагента, первый запрос возобновленного запуска может читать кэш, который прогрел исходный запуск.
• Развертывания рабочего процесса: в развертывании рабочего процесса агентов с одинаковым префиксом Claude Code удерживает все, кроме первого, до 5 секунд по умолчанию, поэтому их первые запросы могут читать префикс, который поместил в кэш первый агент.

Отключение prompt caching

Отключение кеширования иногда полезно при отладке поведения кеширования с конкретной моделью или провайдером. Чтобы отключить его, установите одну из этих переменных окружения на 1:

Чтобы установить политику кеширования в масштабах организации, поместите любую из этих переменных или переменные TTL в блок env управляемых параметров. Для обычного использования оставьте кеширование включенным.

Связанные ресурсы

• Уроки из создания Claude Code: Prompt caching — это всё: обоснование дизайна для режима плана, отложенной загрузки инструментов и сжатия
• Изучите окно контекста: что загружается в контекст и когда
• Уменьшите использование токенов: стратегии помимо кэширования для управления размером контекста
• Отслеживайте и уменьшайте затраты: отслеживание токенов кэша и конфигурация TTL для вызывающих Agent SDK
• Prompt caching: базовый механизм API, точки разрыва и цены