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 упорядочивает каждый запрос так, чтобы содержимое, которое редко изменяется между ходами, шло первым:
| Слой | Содержимое | Изменяется когда |
|---|
| Системный запрос | Основные инструкции, определения инструментов, стиль вывода | Набор загруженных определений инструментов изменяется, или Claude Code обновляется |
| Контекст проекта | CLAUDE.md, автоматическая память, правила без области действия | Сеанс начинается, или после /clear или /compact |
| Разговор | Ваши сообщения, ответы Claude, результаты инструментов | При каждом ходе |
- Model: каждая модель имеет свой кэш. Переключение моделей пересчитывает весь запрос даже когда содержимое идентично. См. Переключение моделей ниже.
- Effort level: каждый уровень усилий имеет свой кэш для одной и той же модели. Изменение его в середине сеанса пересчитывает весь запрос, и Claude Code просит вас подтвердить перед применением изменения. См. Изменение уровня усилий ниже.
Выберите вашу модель и уровень усилий в начале сеанса, затем сохраните /compact для естественных перерывов между задачами. Чем меньше изменений вы делаете в середине задачи, тем выше коэффициент попаданий в кэш.
Где находится кэш
Кэширование происходит на стороне сервера в инфраструктуре, которая обслуживает вашу модель. Где это находится, зависит от того, как вы аутентифицируетесь:
- API ключ, подписка Claude или Claude Platform on AWS: кэш находится в инфраструктуре Anthropic, доступ через Claude API
- Bedrock или Vertex AI: кэш находится в инфраструктуре обслуживания вашего облачного провайдера
- Foundry: запросы маршрутизируются в инфраструктуру Anthropic
- Пользовательский
ANTHROPIC_BASE_URL или LLM gateway: кэш находится там, где перенаправляются ваши запросы, и работает ли кэширование, зависит от шлюза
Для информации о том, что хранит и обрабатывает каждый провайдер, см. использование данных. Где бы ни находился кэш, записи истекают после периода неактивности, и Время жизни кэша ниже охватывает TTL и как его продлить.
Действия, которые инвалидируют кэш
Эти действия вызывают пропуск части или всего кэша в следующем запросе. Вы видите один раз медленный, более дорогой ход, после чего новый префикс кэшируется. Большинство из них можно избежать в середине задачи, как только вы узнаете, что они имеют стоимость. Переключение модели может казаться бесплатным, пока вы не заметите медленный ход, который следует.
Переключение моделей
Каждая модель имеет свой кэш. Переключение с помощью /model означает, что следующий запрос читает всю историю разговора без попаданий в кэш, даже если содержимое идентично.
Параметр модели opusplan разрешается в Opus во время режима плана и Sonnet во время выполнения, поэтому каждое переключение режима плана — это переключение модели и запускает свежий кэш.
Автоматический откат модели на Fable 5 также является переключением модели. Когда классификатор безопасности помечает запрос, Claude Code повторно запускает его на модели Opus по умолчанию и сеанс продолжается там.
Изменение уровня усилий
Кэш индексируется по уровню усилий, а также по модели, поэтому переключение с помощью /effort означает, что следующий запрос читает всю историю разговора без попаданий в кэш. После начала разговора Claude Code показывает диалог подтверждения перед применением изменения усилий, которое инвалидировало бы кэш. Изменение, которое разрешается на тот же уровень, уже действующий, например явное установление значения по умолчанию модели, пропускает диалог и сохраняет кэш.
Включение быстрого режима
Включение быстрого режима добавляет заголовок запроса, который является частью ключа кэша, поэтому следующий запрос читает всю историю разговора без попаданий в кэш. Эти некэшированные входные токены выставляются по тарифам быстрого режима, поэтому включение его в начале сеанса стоит дешевле, чем включение его глубоко в длинный сеанс. Включение быстрого режима из модели, отличной от Opus, также переключает вашу модель, что само по себе запускает свежий кэш.
Стоимость применяется один раз за разговор. После первого хода в быстром режиме Claude Code продолжает отправлять заголовок и варьирует только параметр скорости запроса, который не является частью ключа кэша. Отключение быстрого режима, автоматический откат к стандартной скорости после ограничения скорости и повторное включение позже все сохраняют кэш. /clear и /compact сбрасывают это, поскольку они перестраивают кэш в этих точках в любом случае.
Сохранение заголовка при переключениях требует Claude Code v2.1.86 или позже. В более ранних версиях каждое переключение быстрого режима и откат после ограничения скорости инвалидируют кэш.
Подключение или отключение MCP сервера
Определения инструментов находятся в слое системного запроса, поэтому кэш инвалидируется, когда набор определений инструментов в запросе изменяется между ходами. Переключение инструмента advisor является исключением: его определение находится после точки разрыва кэша, поэтому включение или отключение /advisor сохраняет кэшированный префикс нетронутым. Зависит ли изменение MCP сервера от этого, зависит от того, отложены ли его инструменты поиском инструментов или загружены в префикс:
- Отложенные инструменты, по умолчанию на поддерживаемых моделях: подключение, отключение сервера или изменение его списка инструментов только добавляет новое содержимое и не нарушает ничего, что уже кэшировано.
- Инструменты, загруженные в префикс: любое изменение их инвалидирует кэш. Это происходит, когда поиск инструментов недоступен или отключен, например на моделях Haiku, на Vertex AI или с пользовательским шлюзом
ANTHROPIC_BASE_URL. Это также происходит для сервера или инструмента, отмеченного alwaysLoad, и для определений, сохраняемых впереди загрузкой на основе порога.
Когда инструменты загружаются в префикс, наиболее частая причина инвалидации — это подключение или отключение сервера в середине сеанса, что может произойти без каких-либо действий с вашей стороны: процесс stdio сервера выходит, сеанс HTTP истекает, или сервер автоматически переподключается после временного сбоя. Подключённый сервер также может отправить динамическое обновление инструмента, которое изменяет его список инструментов.
Редактирование конфигурации MCP само по себе не изменяет кэш. Новая конфигурация вступает в силу только после перезагрузки, когда сервер подключается или отключается.
Включение или отключение плагина
Плагины объединяют несколько типов компонентов, и стоимость изменения зависит от того, какие компоненты предоставляет плагин. Skills, команды, агенты, hooks, LSP серверы, мониторы и темы никогда не инвалидируют кэш: все, что они добавляют в запрос, добавляется после существующего разговора, поэтому следующий запрос платит за новое содержимое, но все еще читает все, что было до него, из кэша.
Исключение — это плагин, который предоставляет MCP серверы. Включение или отключение одного следует тем же правилам, что и подключение или отключение MCP сервера: кэш сохраняется, когда инструменты сервера отложены, и следующий запрос повторно читает весь разговор, когда они загружаются в префикс.
Изменения плагина применяются при запуске /reload-plugins или при запуске нового сеанса. Стоимость, будь то добавленные объявления или полное повторное чтение, отображается на первом ходе после перезагрузки, а не когда вы запускаете /plugin install, /plugin enable или /plugin disable. Начиная с v2.1.163, когда перезагрузка вызовет полное повторное чтение, /reload-plugins показывает предупреждение и не применяет перезагрузку. Передайте --force для применения в любом случае.
Отключение плагина, который вы включили ранее в сеансе, восстанавливает предыдущую форму запроса. Если этот префикс все еще находится в пределах своего времени жизни кэша, следующий запрос читает более старую запись кэша вместо перестроения.
Добавление простого имени инструмента, такого как Bash или WebFetch, в качестве правила отказа удаляет этот инструмент из контекста Claude полностью. Встроенные определения инструментов загружаются в слой системного запроса, поэтому добавление или удаление одного из этих правил в середине сеанса инвалидирует кэш. Изменение вступает в силу в следующем ходе, добавляете ли вы его через /permissions или путём прямого редактирования файла параметров.
Только правило отказа, которое совпадает в позиции имени инструмента, имеет этот эффект: простое имя инструмента, эквивалентная форма Bash(*) или глоб имени инструмента как "*". Глоб, который совпадает только с инструментами MCP, такой как "mcp__*", удаляет эти инструменты так же, но оставляет кэш нетронутым, когда совпадающие инструменты отложены, по умолчанию, поскольку отложенные определения никогда не были в кэшированном префиксе. Правила отказа с областью действия, такие как Bash(rm *), и все правила разрешения и запроса, не изменяют, какие инструменты видит Claude. Claude Code проверяет их, когда Claude пытается выполнить вызов, оставляя префикс нетронутым.
Сжатие разговора
Сжатие заменяет историю ваших сообщений резюме. По замыслу, это инвалидирует слой разговора, поскольку следующий запрос имеет новую, более короткую историю, которая не совпадает с префиксом старой. Claude Code повторно использует слой системного запроса и перезагружает контекст проекта с диска, который кэш-попадает только если CLAUDE.md и память не изменились с начала сеанса.
Чтобы создать резюме, Claude Code отправляет одноразовый запрос с тем же системным запросом, инструментами и историей, что и ваш разговор, плюс инструкция суммирования, добавленная как финальное сообщение пользователя. Поскольку он совпадает с вашим префиксом, этот запрос читает существующий кэш, а не переобрабатывает полную историю. Большая часть времени сжатия идёт на создание резюме, а не на пропуск кэша. Ход, который следует, перестраивает кэш разговора только для намного более короткого резюме, поэтому ход после сжатия — это не медленная часть.
Сжатие работает в вашу пользу, когда контекст, который вы отбрасываете, — это содержимое, которое вам больше не нужно. Чтобы выбрать, когда его накладные расходы происходят, запустите /compact в естественном перерыве в вашей работе, например между задачами, вместо того чтобы ждать, пока автоматическое сжатие сработает в середине задачи. Если вы пошли по пути, который хотите полностью отказать, используйте /rewind к более раннему ходу вместо этого. Перемотка усекает назад к префиксу, который уже кэширован, а не строит новый, как это делает сжатие. Обновление Claude Code
Новая версия Claude Code обычно обновляет системный запрос или определения инструментов, поэтому первый запрос после обновления перестраивает кэш с начала. Auto-update загружает новые версии в фоне, но применяет их при следующем запуске, никогда в середине сеанса, поэтому вы видите это как первый ход без кэша после перезагрузки, а не как сюрприз во время сеанса. Установите DISABLE_AUTOUPDATER=1 для управления тем, когда применяются обновления.
Возобновление сеанса после обновления переобрабатывает всю историю разговора без попаданий в кэш, поскольку история теперь находится за другим системным запросом. Стоимость масштабируется с тем, как долго возобновляемый разговор, поэтому первый ход обратно в длинный сеанс может быть самым дорогим запросом, который вы отправляете. Действия, которые сохраняют кэш
Эти действия либо добавляют в конец разговора, либо вообще не трогают запрос. Некоторые из них, такие как редактирование CLAUDE.md или изменение стиля вывода, также являются причиной того, почему изменение параметра ждёт перезагрузки для применения.
Редактирование файлов в вашем репозитории
Содержимое файлов входит в контекст только когда 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:
| Поле | Значение |
|---|
cache_creation_input_tokens | Токены, записанные в кэш при этом ходе, выставленные счётом по ставке записи кэша |
cache_read_input_tokens | Токены, обслуживаемые из кэша при этом ходе, выставленные счётом примерно в 10% от стандартной ставки ввода |
Подагенты и кэш
Подагент начинает свой собственный разговор со своим собственным системным запросом и набором инструментов, отдельно от родительского. Он строит свой собственный кэш, начиная без попаданий в кэш при первом вызове и прогреваясь через свои собственные ходы. Подагенты используют пятиминутный TTL даже на подписке, поскольку автоматический одночасовой TTL применяется к основному разговору.
Кэш родителя не затронут. Со стороны родителя, вызов подагента и результат добавляются в разговор, оставляя префикс родителя нетронутым.
Ветвление, напротив, наследует системный запрос родителя, инструменты и историю разговора точно, поэтому его первый запрос читает кэш родителя. Вызов суммирования сжатия, описанный в Сжатие разговора, использует тот же подход совпадения префиксов.
Отключение 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 только |
env управляемых параметров. Для нормального использования оставьте кэширование включённым.
