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

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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: не является частью ключа кэша или запроса, поэтому изменение его в середине сеанса не влияет на кэш.

​

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

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

• API ключ, подписка Claude или Claude Platform on AWS: кэш находится в инфраструктуре Anthropic, доступ через Claude API
• Bedrock или Vertex AI: кэш находится в инфраструктуре обслуживания вашего облачного провайдера
• Foundry: запросы маршрутизируются в инфраструктуру Anthropic
• Пользовательский ANTHROPIC_BASE_URL или LLM gateway: кэш находится там, где перенаправляются ваши запросы, и работает ли кэширование, зависит от шлюза

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

​

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

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

• Переключение моделей
• Подключение или отключение MCP сервера
• Отказ от всего инструмента
• Сжатие разговора
• Обновление Claude Code

​

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

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

​

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

Определения инструментов находятся в слое системного запроса, поэтому кэш инвалидируется, когда набор инструментов MCP, доступных Claude, изменяется между ходами. Наиболее частая причина — MCP сервер, подключающийся или отключающийся в середине сеанса, что может произойти без каких-либо действий с вашей стороны: процесс stdio сервера выходит, сеанс HTTP истекает, или сервер автоматически переподключается после временного сбоя. Подключённый сервер также может отправить динамическое обновление инструмента, которое изменяет его список инструментов. Редактирование конфигурации MCP само по себе не изменяет кэш. Новая конфигурация вступает в силу только после перезагрузки, когда сервер подключается или отключается. Поиск инструментов MCP уменьшает, насколько каждый инструмент способствует префиксу, отложив полные определения инструментов, но набор имён инструментов всё ещё должен оставаться стабильным, чтобы кэш оставался действительным.

​

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

Добавление простого имени инструмента, такого как Bash или WebFetch, в качестве правила отказа удаляет этот инструмент из контекста Claude полностью. Определения инструментов находятся в слое системного запроса, поэтому добавление или удаление одного из этих правил в середине сеанса инвалидирует кэш так же, как подключение или отключение MCP сервера. Изменение вступает в силу в следующем ходе, добавляете ли вы его через /permissions или путём прямого редактирования файла параметров. Только простое имя инструмента или эквивалентная форма Bash(*) имеет этот эффект. Правила отказа с областью действия, такие как Bash(rm *), и все правила разрешения и запроса, не изменяют, какие инструменты видит Claude. Claude Code проверяет их, когда Claude пытается выполнить вызов, оставляя префикс нетронутым.

​

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

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

​

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

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

​

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

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

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

​

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

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

​

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

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

​

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

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

​

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

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

​

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

Skills и команды вводят свои инструкции как сообщения пользователя в точке вызова. Ничего более раннего в разговоре не изменяется.

​

Запуск /recap

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

​

Перемотка разговора

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

​

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

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

​

На подписке Claude

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

​

На API ключе или стороннем провайдере

На API ключе, Bedrock, Vertex, Foundry или Claude Platform on AWS, вы платите по ставкам за токен, поэтому TTL остаётся по умолчанию дешевле пять минут. Чтобы выбрать одночасовой TTL, установите ENABLE_PROMPT_CACHING_1H=1. На Bedrock, поддержка prompt caching, минимальная длина кэшируемого префикса и доступность одночасового TTL варьируются по модели. Если счётчики токенов кэша остаются на нуле, проверьте поддерживаемые модели, регионы и лимиты в документации Bedrock.

​

Переопределить TTL

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

​

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

В Claude Code кэш эффективно ограничен одной машиной и каталогом. Системный запрос встраивает рабочий каталог, платформу, оболочку, версию ОС и пути автоматической памяти, поэтому два сеанса в разных каталогах строят разные префиксы и пропускают кэш друг друга. Это включает worktrees одного и того же репозитория, поскольку каждый worktree имеет свой рабочий каталог. Сеансы, которые вы запускаете параллельно в одном каталоге, строят совпадающие префиксы и читают кэш друг друга. Последовательные сеансы совпадают с префиксом только когда снимок статуса git при запуске совпадает, поскольку системный запрос также захватывает ветвь и недавние коммиты. Базовый кэш API шире. Кэши изолированы между организациями и на некоторых провайдерах между рабочими пространствами в организации. В этих границах любые два запроса с одной и той же моделью и префиксом читают один и тот же кэш. Для вызывающих Agent SDK, запускающих флоты автоматизированных процессов, см. улучшение prompt caching между пользователями и машинами для подавления разделов системного запроса для каждой машины и совместного использования кэша между машинами.

​

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

Производительность кэша отображается как два счётчика токенов, которые API сообщает при каждом ответе. Наиболее прямой способ наблюдать их в реальном времени — это скрипт строки состояния, который читает объект current_usage: Высокое соотношение чтения к созданию означает, что кэширование работает хорошо. Если создание остаётся высоким ход за ходом, что-то изменяется в вашем префиксе. Раздел действия, которые инвалидируют кэш перечисляет обычные причины. Для видимости по организации, экспортер OpenTelemetry сообщает токены чтения и создания кэша на пользователя и сеанс. См. Мониторинг использования для справочника метрик и атрибутов событий.

​

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

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

​

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

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

​

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

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