SpyBara
Go Premium

prompt-caching.md 2026-10-06 23:59 UTC to 2026-10-07 20:01 UTC

This page contains 79 additions and 79 deletions.

2026
Tue 6 23:59 Wed 7 20:57

Как 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 повторно отправляет полный контекст: системный промпт, контекст вашего проекта, все предыдущие сообщения и результаты инструментов, а также ваше новое сообщение. Новое содержимое добавляется в конец, что означает, что большая часть каждого запроса идентична предыдущему. Кэширование промптов — это то, как API избегает повторной обработки части, которая не изменилась.

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

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

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

Слой Содержимое Изменяется когда
Системный промпт Основные инструкции, определения инструментов Набор загруженных определений инструментов изменяется
Контекст проекта CLAUDE.md, автоматическая память, правила без области видимости Сессия начинается или после /clear или /compact
Диалог Ваши сообщения, ответы Claude, результаты инструментов Каждый ход

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

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

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

  • Модель: каждая модель имеет свой кэш. Переключение моделей пересчитывает весь запрос, даже когда содержимое идентично. Подробнее см. в разделе Переключение моделей ниже.
  • Уровень усилий: на большинстве моделей каждый уровень усилий имеет свой кэш, поэтому изменение усилий во время сессии пересчитывает весь запрос. На Opus 5.5, Sonnet 5.5, Haiku 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-шлюз: кэш находится там, куда перенаправляются ваши запросы, и работает ли кэширование, зависит от шлюза

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Изменение уровня effort

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

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

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

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

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

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

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

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

  • Инструменты отложены: Claude Code сохраняет список инструментов из первого запроса диалога на протяжении всего диалога, поэтому подключение или отключение сервера в середине сессии не затрагивает ничего из уже кэшированного. Сервер, который завершает подключение после первого запроса, предоставляет свои инструменты как отложенные определения, которые Claude загружает по требованию.
  • Инструменты загружаются заранее: добавление определения инвалидирует кэш, как и намеренное удаление определения. Это происходит, когда поиск инструментов находится ниже порога auto, отключён или недоступен, например на моделях Google Cloud Agent Platform до поколения Claude 4.5, с пользовательским шлюзом ANTHROPIC_BASE_URL или на развёртывании Microsoft Foundry, размещённом в Azure, после того как Claude Code обнаружит, что развёртывание отклоняет поиск инструментов.

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

Изменение в середине сессии Кэш Определения инструментов в следующем запросе
Сервер подключается, или динамическое обновление инструментов добавляет инструменты Инвалидируется Новые определения добавляются
Сервер отключается без каких-либо действий с вашей стороны, например когда завершается процесс stdio-сервера Сохраняется Определения сервера остаются неизменными. Вызов одного из его инструментов возвращает ошибку вместо выполнения
Удалённый сервер автоматически переподключается после разрыва соединения Сохраняется, если только запрос, отправленный во время переподключения сервера, не добавляет инструмент WaitForMcpServers, что однократно инвалидирует кэш Определения сервера остаются неизменными. Запрос, отправленный во время переподключения сервера, может добавить WaitForMcpServers, если в диалоге он ещё не был указан, и после этого инструмент остаётся в списке до конца диалога
Вы намеренно удаляете инструмент, например с помощью правила запрета или отключив его сервер в /mcp Инвалидируется Определение удаляется

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

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

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

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

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

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

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

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

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

Когда вы включаете плагин анализа кода, Claude получает инструмент LSP.

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

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

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

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

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

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

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

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

Запрет инструмента целиком

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

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

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

Сжатие диалога

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Переключение между режимами разрешений, например с 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, в рамках использования плана Кредиты использования, API ключ или облачный провайдер
Основной разговор Один час Пять минут
Всё остальное Пять минут, кроме контролируемых сервером вспомогательных запросов, которые получают один час Пять минут

Как только вы превышаете лимит использования вашего плана и 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 кэш фактически ограничен одной машиной и директорией. Системный запрос встраивает пути вашей автоматической памяти, и разговор открывается объявлением рабочей директории, платформы, оболочки и версии ОС. Две сессии в разных директориях поэтому создают разные префиксы и не попадают в кэш друг друга.

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

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

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

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

Поле Значение
cache_creation_input_tokens Токены, записанные в кэш на этом ходу, выставляются по ставке записи в кэш
cache_read_input_tokens Токены, обслуживаемые из кэша на этом ходу, выставляются по кэшированной ставке токенов модели, ниже стандартной ставки ввода

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

Для сводки по сеансу запустите /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:

Переменная Эффект
DISABLE_PROMPT_CACHING Отключить для всех моделей
DISABLE_PROMPT_CACHING_HAIKU Отключить для модели Haiku по умолчанию
DISABLE_PROMPT_CACHING_SONNET Отключить для модели Sonnet по умолчанию
DISABLE_PROMPT_CACHING_OPUS Отключить для модели Opus по умолчанию
DISABLE_PROMPT_CACHING_FABLE Отключить только для Fable

DISABLE_PROMPT_CACHING_HAIKU применяется к модели Haiku по умолчанию, модели, на которую разрешается псевдоним haiku. Он отключает кеширование везде, где работает эта модель, включая основной диалог, когда это ваша основная модель. Охват основного диалога требует Claude Code версии 2.1.283 или более поздней.

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

Другая версия Haiku, которую вы закрепляете как вашу основную модель, сохраняет кеширование; установите DISABLE_PROMPT_CACHING для отключения кеширования для неё.

DISABLE_PROMPT_CACHING_SONNET и DISABLE_PROMPT_CACHING_OPUS каждый применяется к модели, на которую разрешаются псевдонимы sonnet или opus. Если вы установите любой другой ID модели Sonnet или Opus как вашу основную модель, эта модель сохраняет кеширование. Например, сеанс на claude-sonnet-5 сохраняет кеширование, пока sonnet разрешается на claude-sonnet-5-5. Чтобы отключить кеширование для этой модели, установите DISABLE_PROMPT_CACHING.

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