SpyBara
Go Premium

prompt-caching.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 155 additions and 47 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58

Como Claude Code usa prompt caching

Claude Code gerencia prompt caching automaticamente. Veja por que uma mudança de modelo dispara um turno lento sem cache, o que /compact custa, por que edições de CLAUDE.md não se aplicam no meio da sessão e como verificar sua taxa de acerto de cache.

Prompt caching torna Claude Code mais rápido e eficiente em termos de custo. Sem caching, a API reprocessaria seu histórico completo a cada turno. Com caching, ela reutiliza o que já processou, cobra a releitura na taxa de token em cache e processa completamente apenas o que mudou.

Claude Code gerencia prompt caching para você, a menos que você desative-o. Ainda é útil saber como o prompt caching funciona, porque algumas ações invalidam o cache e tornam a próxima resposta mais lenta e cara enquanto ele se reconstrói. Esta página cobre quais ações são essas, por que algumas configurações aguardam uma reinicialização para serem aplicadas e como verificar o desempenho do cache quando o uso parece alto.

Como o cache é organizado

Cada vez que você envia uma mensagem em Claude Code, ele faz uma nova solicitação de API. O modelo não se lembra de nada entre solicitações, então Claude Code reenvia o contexto completo: o prompt do sistema, seu contexto de projeto, cada mensagem anterior e resultado de ferramenta, e sua nova mensagem. Novo conteúdo é anexado ao final, o que significa que a maior parte de cada solicitação é idêntica à anterior. Prompt caching é como a API evita reprocessar a parte que não mudou.

A API faz cache correspondendo ao início de cada solicitação, chamado de prefixo, contra conteúdo que processou recentemente. Em um turno normal, o prefixo é a solicitação anterior inteira e apenas a troca mais recente é nova. A correspondência é exata, então uma mudança em qualquer lugar no prefixo recomputa tudo depois dela. Não há caching por arquivo ou por segmento. Veja como o prompt caching funciona na referência da API para o mecanismo subjacente.

Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita. Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita.

Para aproveitar ao máximo a correspondência de prefixo, Claude Code ordena cada solicitação para que o conteúdo que raramente muda entre turnos venha primeiro:

Camada Conteúdo Muda quando
Prompt do sistema Instruções principais, definições de ferramentas, estilo de saída O conjunto de definições de ferramentas carregadas muda, você muda o estilo de saída, ou Claude Code é atualizado
Contexto do projeto CLAUDE.md, memória automática, regras sem escopo A sessão começa, ou após /clear ou /compact
Conversa Suas mensagens, respostas de Claude, resultados de ferramentas A cada turno

Uma mudança na camada de conversa deixa o prompt do sistema e o contexto do projeto em cache. Uma mudança no prompt do sistema invalida tudo, porque todo o conteúdo posterior agora fica atrás de um prefixo diferente. A terceira coluna fornece gatilhos comuns em vez de uma lista exaustiva, e as seções abaixo cobrem o conjunto completo.

A regra de correspondência de prefixo explica a maioria dos comportamentos nesta página. Plan mode e carregamento de skills, por exemplo, anexam suas instruções como mensagens de conversa, então o prefixo em cache permanece intacto.

Duas configurações não aparecem na tabela de camadas, mas ainda afetam o que fica em cache:

  • Model: cada modelo tem seu próprio cache. Trocar modelos recomputa toda a solicitação mesmo quando o conteúdo é idêntico. Veja Trocar modelos abaixo.
  • Effort level: na maioria dos modelos, cada nível de esforço tem seu próprio cache, então alterar o esforço no meio da sessão recomputa toda a solicitação. No Fable 5.1 com uma chave de API ou uma assinatura Claude, o cache permanece intacto por padrão. Veja Alterando nível de esforço abaixo.

Onde o cache reside

O caching acontece no lado do servidor, na infraestrutura que serve seu modelo. Onde fica depende de como você se autentica:

  • Chave de API, assinatura Claude ou Claude Platform on AWS: o cache reside na infraestrutura da Anthropic, acessado através da Claude API
  • Amazon Bedrock ou Google Cloud's Agent Platform: o cache reside na infraestrutura de serviço do seu provedor de nuvem
  • Microsoft Foundry: depende da opção de hospedagem da implantação. Implantações hospedadas no Azure são servidas na infraestrutura do Azure; implantações hospedadas na Anthropic são servidas na infraestrutura da Anthropic
  • ANTHROPIC_BASE_URL personalizado ou LLM gateway: o cache reside onde suas solicitações são encaminhadas, e se o caching funciona depende do gateway

Claude Code também anexa contexto do sistema no meio da conversa, como notificações de mudança de arquivo, e marca esse bloco para caching em todos os provedores e conexões.

No endpoint próprio do provedor, Amazon Bedrock e seu endpoint Mantle, Google Cloud's Agent Platform e Microsoft Foundry fazem cache do bloco da mesma forma que a Claude API faz.

Quando suas solicitações passam por um LLM gateway, um ANTHROPIC_BASE_URL personalizado, ou uma substituição de URL base do provedor de nuvem como ANTHROPIC_BEDROCK_BASE_URL, o que fica em cache depende de como o gateway lida com os marcadores cache_control que Claude Code envia:

  • Encaminha-os inalterados: o bloco e sua conversa fazem cache da mesma forma que no endpoint próprio do provedor.
  • Rejeita a solicitação marcada com um erro 400 nomeando cache_control: Claude Code reenvia a solicitação com o marcador movido do bloco para sua última mensagem de conversa, e o mantém lá pelo resto da conversa. O bloco é cobrado como entrada não armazenada em cache; sua conversa permanece em cache.
  • Remove os marcadores enquanto retorna sucesso: todo o seu histórico de conversa é cobrado como entrada não armazenada em cache a cada turno. Um gateway que converte conteúdo de sistema em forma de bloco para uma string simples remove o marcador da mesma forma.

Para o que cada provedor armazena e processa, veja uso de dados. Onde quer que o cache resida, as entradas expiram após um período de inatividade, e Cache lifetime abaixo cobre o TTL e como estendê-lo.

Ações que invalidam o cache

Essas ações fazem com que a próxima solicitação perca parte ou todo o cache. Você vê um turno mais lento e mais caro uma única vez, após o qual o novo prefixo é armazenado em cache. A maioria delas é evitável no meio da tarefa uma vez que você sabe que têm um custo. Uma mudança de modelo pode parecer gratuita até você notar o turno mais lento que se segue.

Trocar modelos

Cada modelo tem seu próprio cache. Trocar com /model significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache, mesmo que o conteúdo seja idêntico.

Quando você executa /model no terminal, Claude Code pede que você confirme a mudança apenas enquanto o cache ainda está quente. O cache permanece quente por um cache TTL após Claude Code enviar a última solicitação nesta conversa ou Claude responder. Depois que esse tempo passa, o cache expirou, então Claude Code muda sem perguntar.

Antes da v2.1.238, Claude Code não verificava o cache TTL e perguntava mesmo após o cache ter expirado.

Você também pode exigir essa confirmação ou ignorá-la com um hook PreModelSwitch.

A configuração de modelo opusplan resolve para Opus durante o modo de plano e Sonnet durante a execução, então cada alternância de modo de plano é uma mudança de modelo e inicia um cache novo.

Fallback automático de modelo em modelos Fable e Opus 5 também é uma mudança de modelo. Quando um classificador de segurança sinaliza uma solicitação em uma categoria que tem um modelo de fallback, Claude Code executa a solicitação novamente naquele modelo e a sessão continua lá.

Quando uma skill ou comando nomeia um model diferente do modelo atual da sessão em seu frontmatter, esse turno também é uma mudança de modelo: a próxima solicitação lê todo o histórico de conversa sem acertos de cache. O modelo da sessão retoma no seu próximo prompt. Uma skill context: fork define o modelo do subagente bifurcado em vez disso.

Alterar nível de esforço

Na maioria dos modelos, alterar o nível de esforço no meio da sessão significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache. Enquanto o cache ainda está quente, Claude Code pede que você confirme a mudança primeiro.

No Fable 5.1 com uma chave de API ou uma assinatura Claude, alterar o esforço mantém o cache, e Claude Code aplica o novo nível sem perguntar. Isso não se aplica no Amazon Bedrock, na plataforma de agentes do Google Cloud, ou em um gateway de aplicativos Claude, ou quando você define CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS ou sua organização tem uma configuração HIPAA.

Antes da v2.1.260, alterar o esforço no Fable 5.1 com uma chave de API ou uma assinatura Claude também invalidava o cache.

Ativar modo rápido

Ativar modo rápido adiciona um cabeçalho de solicitação que faz parte da chave de cache, então a primeira solicitação que Claude Code envia com modo rápido ativado lê todo o histórico de conversa sem acertos de cache. Claude Code define esse cabeçalho uma vez quando um turno começa e o mantém para o turno inteiro, então quando você ativa modo rápido enquanto Claude está trabalhando, a perda de cache do cabeçalho acontece na primeira solicitação do seu próximo turno. Esses tokens de entrada sem cache são cobrados com taxas de modo rápido, e é por isso que ativá-lo no início de uma sessão custa menos do que ativá-lo profundamente em uma longa. Se seu modelo atual não suportar modo rápido, ativar modo rápido também muda seu modelo, e essa mudança inicia um cache novo por conta própria a partir da próxima solicitação no turno em execução.

O custo se aplica uma vez por conversa. Após o primeiro turno de modo rápido, Claude Code continua enviando o cabeçalho e varia apenas a configuração de velocidade da solicitação, que não faz parte da chave de cache. Desativar modo rápido, o fallback automático para velocidade padrão após um limite de taxa, e ativá-lo novamente mais tarde mantêm o cache. Se você ficar sem créditos de uso no meio da sessão, Claude Code tenta novamente cada solicitação de modo rápido rejeitada em velocidade padrão da mesma forma, então esse fallback também mantém o cache. /clear e /compact redefinem isso, já que reconstruem o cache nesses pontos de qualquer forma.

Conectar ou desconectar um servidor MCP

As definições de ferramentas ficam na camada de prompt do sistema, então o cache se invalida quando o conjunto de definições de ferramentas na solicitação muda entre turnos. Alternar a ferramenta advisor é uma exceção: sua definição fica após o ponto de quebra do cache, então ativar ou desativar /advisor mantém o prefixo em cache intacto. Se uma mudança de servidor MCP faz isso depende se suas ferramentas são adiadas por busca de ferramentas ou carregadas no prefixo:

  • Ferramentas adiadas, o padrão em modelos suportados: um servidor se conectando, desconectando ou alterando sua lista de ferramentas apenas anexa novo conteúdo e não perturba nada já armazenado em cache.
  • Ferramentas carregadas no prefixo: qualquer mudança nelas invalida o cache. Isso acontece quando a busca de ferramentas não está disponível ou está desativada, como em modelos da plataforma de agentes do Google Cloud anteriores à geração Claude 4.5, com um gateway ANTHROPIC_BASE_URL customizado, ou em uma implantação do Microsoft Foundry hospedada no Azure uma vez que Claude Code detecta que a implantação rejeita busca de ferramentas. Também acontece para um servidor ou ferramenta marcada alwaysLoad e para definições mantidas na frente por carregamento baseado em limite.

Quando as ferramentas carregam no prefixo, a causa mais comum de uma invalidação é um servidor se conectando ou desconectando no meio da sessão, o que pode acontecer sem nenhuma ação da sua parte: o processo de um servidor stdio sai, uma sessão HTTP expira ou um servidor se reconecta automaticamente após uma falha transitória. Um servidor conectado também pode enviar uma atualização de ferramenta dinâmica que muda sua lista de ferramentas.

Editar sua configuração de MCP não muda o cache por si só. A nova configuração entra em vigor apenas após uma reinicialização, que é quando o servidor se conecta ou desconecta.

Ativar ou desativar um plugin

Quando você ativa ou desativa um plugin, o que a mudança custa depende de quais tipos de componentes o plugin fornece. Os casos abaixo cobrem cada tipo de componente, quando Claude Code aplica a mudança e o que acontece quando você desativa um plugin novamente na mesma sessão.

Componentes de plugin que mantêm o cache

Claude Code nunca invalida o cache para skills, comandos, agentes, hooks, monitores ou temas de um plugin. Ele anexa seu conteúdo após a conversa existente, então a próxima solicitação paga por esse conteúdo e ainda lê tudo antes dele do cache.

Plugins que fornecem servidores MCP

Quando você ativa ou desativa um plugin que fornece servidores MCP, Claude Code segue as mesmas regras que quando você conecta ou desconecta um servidor MCP:

  • Se Claude Code adia as ferramentas do servidor, ele mantém o cache.
  • Se Claude Code as carrega no prefixo, a próxima solicitação relê toda a conversa.

Plugins de inteligência de código

Quando você ativa um plugin de inteligência de código, Claude obtém a ferramenta LSP.

Quando as mudanças de plugin se aplicam

Claude Code aplica uma mudança de plugin quando você executa /reload-plugins ou inicia uma nova sessão. Você paga o custo, seja anúncios anexados ou uma releitura completa, no primeiro turno após a mudança se aplicar, não quando você executa /plugin enable ou /plugin disable. Claude Code também pode aplicar uma mudança por conta própria em três casos:

  • Para um plugin com uma fonte command, Claude Code pode recarregar o plugin em si.
  • Quando você instala um plugin da interface /plugin, Claude Code pode ativá-lo durante a instalação. Claude Code informa no resumo da instalação se fez isso ou se você deve executar /reload-plugins.
  • Quando você move a sessão com /cd na v2.1.246 ou posterior, Claude Code aplica os plugins que as configurações do novo diretório habilitam como parte da mudança, sem o aviso de releitura completa que acompanha um /reload-plugins.

Quando você executa /reload-plugins e o recarregamento acionaria uma releitura completa, Claude Code mostra um aviso e não aplica o recarregamento. Execute novamente com --force para aplicar o recarregamento mesmo assim.

/reload-plugins também é executado em sessões sem um terminal interativo, como o aplicativo desktop, o Agent SDK e modo não-interativo com -p, quando você o digita diretamente na sessão. Requer Claude Code v2.1.260 ou posterior.

Nessas sessões o recarregamento aplica tudo exceto mudanças de servidor MCP de plugin, que entram em vigor na sua próxima sessão e portanto nunca custam uma releitura completa no meio da sessão.

Plugins que você ativa e depois desativa em uma sessão

Quando você desativa um plugin que ativou anteriormente na sessão, Claude Code restaura a forma de solicitação anterior. Se esse prefixo ainda estiver dentro de seu tempo de vida do cache, a próxima solicitação lê a entrada de cache mais antiga em vez de reconstruir.

Negar uma ferramenta inteira

Adicionar um nome de ferramenta simples como Bash ou WebFetch como uma regra de negação remove essa ferramenta do contexto de Claude completamente. Claude Code carrega definições de ferramentas integradas na camada de prompt do sistema, então adicionar ou remover uma dessas regras no meio da sessão invalida o cache. Claude Code aplica a mudança na próxima solicitação, quer você a adicione através de /permissions ou editando um arquivo de configurações diretamente. Isso inclui uma regra que você adiciona através de /permissions no meio de um turno.

Apenas uma regra de negação que corresponde na posição do nome da ferramenta tem esse efeito: um nome de ferramenta simples, a forma equivalente Bash(*), ou um glob de nome de ferramenta como "*". Um glob que corresponde apenas a ferramentas MCP, como "mcp__*", remove essas ferramentas da mesma forma mas deixa o cache intacto quando as ferramentas correspondidas são adiadas, o padrão, já que definições adiadas nunca estiveram no prefixo em cache. Regras de negação com escopo como Bash(rm *) e todas as regras de permissão e pergunta não mudam quais ferramentas Claude vê. Claude Code as verifica quando Claude tenta fazer uma chamada, deixando o prefixo intacto.

Alterar estilo de saída

Estilo de saída faz parte do prompt do sistema. Quando você muda de estilos no meio da sessão com /config ou a configuração outputStyle, Claude usa o novo estilo começando com sua próxima mensagem, e essa solicitação lê todo o histórico de conversa sem acertos de cache. Para manter esse custo pequeno, mude de estilos antes de sua primeira mensagem em uma sessão ou logo após /clear ou /compact, quando há pouco ou nenhum histórico de conversa para releitura.

Antes da v2.1.251, uma mudança de estilo no meio da sessão mantinha o cache mas não se aplicava até você executar /clear ou iniciar uma nova sessão.

Compactar a conversa

Compactação substitui seu histórico de mensagens por um resumo. Por design, isso invalida a camada de conversa, já que a próxima solicitação tem um histórico novo e mais curto que não compartilha um prefixo com o antigo. Claude Code reutiliza a camada de prompt do sistema e recarrega o contexto do projeto do disco, que acerta o cache apenas se CLAUDE.md e memória não mudaram desde o início da sessão.

Para produzir o resumo, Claude Code envia uma solicitação separada com o mesmo prompt do sistema, ferramentas e histórico que sua conversa, mais uma instrução de resumo anexada como uma mensagem de usuário final. Enquanto o cache está quente, essa solicitação lê seu prefixo do cache, então um /compact no meio da sessão custa uma fração do que o tamanho do contexto sugere e gasta a maior parte de seu tempo gerando o resumo.

Após uma pausa mais longa que o tempo de vida do cache, não há cache deixado para ler, então a solicitação de resumo reprocessa o histórico completo como entrada sem cache. É por isso que /compact custa mais quando você retoma uma sessão antiga. Em ambos os casos quente e frio, o turno após compactação reconstrói o cache de conversa apenas para o resumo muito mais curto, então esse turno não é a parte lenta.

Acumular muitas imagens

A API limita quantas imagens e PDFs cada solicitação pode carregar. Para os números atuais, veja Limites de solicitação na documentação da API. Claude Code também limita o tamanho total das imagens e PDFs em uma solicitação, então capturas de tela grandes atingem o limite com menos imagens do que pequenas.

Quando a próxima solicitação passaria de qualquer limite, Claude Code remove um lote das imagens e PDFs mais antigas do que envia, o que deixa espaço para mais antes de precisar remover novamente. Claude não pode mais ver as imagens removidas. Se Claude precisar de uma delas novamente, compartilhe-a novamente.

Remover imagens muda as mensagens que as continham, então a próxima solicitação reprocessa a conversa a partir da mais antiga dessas mensagens em diante. Como Claude Code remove um lote por vez, você vê um turno mais lento por lote em vez de um com cada nova captura de tela.

Atualizar Claude Code

Uma nova versão de Claude Code normalmente atualiza o prompt do sistema ou definições de ferramentas, então a primeira solicitação após uma atualização reconstrói o cache do início. Auto-update baixa novas versões em segundo plano mas as aplica no próximo lançamento, nunca no meio da sessão, então você vê isso como um primeiro turno sem cache após reiniciar em vez de uma surpresa durante uma sessão. Defina DISABLE_AUTOUPDATER=1 para controlar quando as atualizações se aplicam.

Ações que mantêm o cache

Essas ações ou anexam ao final da conversa ou não tocam a solicitação. Algumas delas, como editar CLAUDE.md, mantêm o cache pela mesma razão pela qual a mudança não chega à sessão em execução até /clear, /compact ou uma reinicialização.

Editar arquivos em seu repositório

O conteúdo do arquivo entra em contexto apenas quando Claude o lê, e as leituras se anexam à conversa. Editar um arquivo que Claude leu anteriormente não muda retroativamente a leitura anterior no histórico. Em vez disso, Claude Code anexa um <system-reminder> observando que o arquivo mudou, e Claude o relê se necessário.

Editar CLAUDE.md no meio da sessão

Seus arquivos CLAUDE.md de raiz de projeto e nível de usuário são lidos uma vez no início da sessão e mantidos na memória. Editá-los no meio da sessão não invalida o cache, mas a edição também não se aplica. Claude continua trabalhando com a versão que foi carregada no início da sessão. O novo conteúdo carrega no próximo /clear, /compact ou reinicialização.

Arquivos CLAUDE.md aninhados em subdiretórios e regras com frontmatter paths: carregam depois, quando Claude primeiro lê um arquivo correspondente. Editar um antes de carregar tem efeito. Depois de carregar, o conteúdo faz parte do histórico de conversa, então uma edição no meio da sessão não muda retroativamente.

Alterar modo de permissão

Alternar entre modos de permissão, como de Manual para aceitar edições, não muda o prompt do sistema ou definições de ferramentas, então mudanças de modo são seguras para cache. A exceção é o modo de plano com a configuração de modelo opusplan, que alterna o modelo entre Opus e Sonnet conforme você entra ou sai do modo de plano. Isso torna a alternância de modo uma mudança de modelo.

Invocar skills e comandos

Skills e comandos injetam suas instruções como mensagens de usuário no ponto de invocação. Nada anterior na conversa muda. Uma skill ou comando cujo frontmatter nomeia um model pode ser uma mudança de modelo para aquele turno.

Executar `/recap`

/recap gera um resumo para exibição em seu terminal. Ao contrário de /compact, ele anexa o resumo como saída de comando em vez de substituir seu histórico de mensagens, então o prefixo em cache permanece intacto.

Rewind da conversa

/rewind trunca sua conversa de volta para um turno anterior. O histórico restante é o mesmo conteúdo do qual o cache foi construído naquele ponto, e as camadas de prompt do sistema e contexto do projeto não mudam, então a próxima solicitação acerta a entrada de cache anterior. Cada turno desde então leu através desse prefixo, que manteve a entrada aquecida mesmo se o turno original foi há mais tempo do que o TTL.

Restaurar checkpoints de arquivo junto com a conversa não tem efeito separado no cache. O conteúdo do arquivo entra em contexto apenas quando Claude o lê, o mesmo que editar arquivos em seu repositório.

Tempo de vida do cache

Prefixos em cache expiram após um período de inatividade. Cada solicitação que acerta o cache redefine o temporizador, então o cache permanece aquecido enquanto você continua trabalhando. Após um intervalo longo o suficiente, a próxima solicitação recomputa a entrada completa e reestabelece o cache, o que é por que o primeiro turno de volta após se afastar pode ser notavelmente mais lento.

Em um plano Pro ou Max, quando você retoma uma sessão grande após um longo intervalo, Claude Code oferece retomar de um resumo para que solicitações posteriores não carreguem o histórico completo.

O tempo de vida (TTL) controla quanto tempo um intervalo o cache sobrevive. A API oferece dois: um TTL de cinco minutos e um TTL de uma hora que mantém o cache aquecido através de pausas mais longas, mas cobra gravações de cache a uma taxa mais alta. O TTL mais longo ajuda quando você deixa uma sessão ociosa e volta a ela, porque você pula o reprocessamento que um prefixo expirado custa. Custa mais em rajadas curtas de trabalho que nunca ficam ociosas por mais de cinco minutos, onde a taxa de gravação mais alta se aplica e o tempo de vida do cache mais longo não é utilizado.

Qual TTL cada solicitação obtém

Claude Code decide o TTL por solicitação, e cada solicitação se enquadra em um dos dois buckets fixos:

  • Conversa principal: seus turnos interativos, execuções não-interativas -p e turnos do Agent SDK, mais os auxiliares que Claude Code executa inline com eles
  • Tudo mais: as solicitações que Claude Code faz fora dessa conversa, como subagentes, workflows, colegas em processo, forks, compactação e títulos de sessão

A menos que você escolha um TTL você mesmo, Claude Code solicita o TTL de uma hora apenas em uma assinatura Claude dentro do uso incluído do seu plano. Lá ele solicita a hora para a conversa principal, mais um pequeno conjunto de solicitações auxiliares que a Anthropic controla no lado do servidor. Esta tabela fornece o TTL padrão de cada bucket sob ambos os tipos de cobrança.

Bucket de solicitação Assinatura Claude, dentro do uso do plano Créditos de uso, chave de API ou provedor de nuvem
Conversa principal Uma hora Cinco minutos
Tudo mais Cinco minutos, exceto as solicitações auxiliares controladas pelo servidor, que obtêm uma hora Cinco minutos

Depois que você ultrapassa o limite de uso do seu plano e Claude Code usa créditos de uso, você é cobrado por esse uso, então Claude Code reduz a conversa principal para o TTL de cinco minutos mais barato. Para manter o TTL de uma hora lá, escolha o TTL você mesmo.

Escolha o TTL você mesmo

Você pode definir um TTL para qualquer bucket. Cada controle leva 5m ou 1h, e Claude Code ignora qualquer outro valor.

Ambas as configurações e ambas as variáveis de ambiente exigem Claude Code v2.1.242 ou posterior. Se você se conectar com uma chave de API ou usar um provedor de nuvem, defina promptCacheTtl para 1h para dar à conversa principal um cache de uma hora. As solicitações fora dela mantêm o padrão de cinco minutos até que você escolha um TTL para esse bucket também.

Quando mais de um controle se aplica, Claude Code leva a primeira correspondência nesta ordem:

  1. FORCE_PROMPT_CACHING_5M=1, que força cinco minutos para ambos os buckets
  2. A variável de ambiente do bucket
  3. A configuração do bucket
  4. Para as solicitações de um subagente, o valor cacheTtl no campo frontmatter experimental do subagente, que exige Claude Code v2.1.248 ou posterior. Claude Code ignora um 1h lá enquanto sua assinatura Claude está usando créditos de uso
  5. ENABLE_PROMPT_CACHING_1H=1, que solicita uma hora para ambos os buckets
  6. O padrão para o bucket da solicitação

Defina FORCE_PROMPT_CACHING_5M=1 quando você está depurando o comportamento do cache, comparando os dois TTLs ou substituindo um TTL mais longo definido em configurações gerenciadas.

Para confirmar qual TTL as gravações de cache da sua conversa principal usaram, execute claude -p "hello" --output-format json e leia usage.cache_creation no resultado. Claude Code relata gravações de cache de uma hora em ephemeral_1h_input_tokens e gravações de cache de cinco minutos em ephemeral_5m_input_tokens.

Através de um gateway LLM que você define com ANTHROPIC_BASE_URL, parte da solicitação de uma hora viaja no cabeçalho anthropic-beta, então configure o gateway para encaminhar esse cabeçalho inalterado. O TTL de uma hora não está disponível através do gateway de aplicativos Claude. No Amazon Bedrock, suporte a prompt caching, comprimento mínimo de prefixo armazenável em cache e disponibilidade de TTL de uma hora variam por modelo. Se as contagens de tokens de cache permanecerem em zero, verifique modelos, regiões e limites suportados na documentação do Amazon Bedrock.

Escopo do cache

Em Claude Code, o cache é efetivamente limitado a uma máquina e diretório. O prompt do sistema incorpora o diretório de trabalho, plataforma, shell, versão do SO e caminhos de memória automática, então duas sessões em diretórios diferentes constroem prefixos diferentes e perdem o cache uma da outra. Isso inclui worktrees do mesmo repositório, já que cada worktree tem seu próprio diretório de trabalho.

Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e leem o cache uma da outra. Sessões sequenciais compartilham o prefixo apenas quando o snapshot de status git na inicialização corresponde, já que o prompt do sistema também captura branch e commits recentes.

O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, entre workspaces dentro de uma organização. Dentro desses limites, quaisquer duas solicitações com o mesmo modelo e prefixo leem o mesmo cache. Para chamadores do Agent SDK executando frotas de processos automatizados, veja melhorar prompt caching entre usuários e máquinas para suprimir as seções por máquina do prompt do sistema e compartilhar o cache entre máquinas.

Verificar desempenho do cache

O desempenho do cache aparece como duas contagens de tokens que a API relata em cada resposta. A forma mais direta de observá-los ao vivo é um script de statusline que lê o objeto current_usage:

Campo Significado
cache_creation_input_tokens Tokens escritos no cache neste turno, cobrados à taxa de gravação de cache
cache_read_input_tokens Tokens servidos do cache neste turno, cobrados em aproximadamente 10% da taxa de entrada padrão

Uma alta proporção de leitura para criação significa que o caching está funcionando bem. Se a criação permanecer alta turno após turno, algo está mudando em seu prefixo. A seção ações que invalidam o cache lista as causas usuais.

Para um resumo por sessão, execute /usage. Após a primeira resposta da conversa principal, Claude Code adiciona uma linha Prompt cache (main) ao bloco Session, mostrando a taxa de acerto da sessão, contagem de falhas e se o cache está aquecido neste momento. Um script de statusline pode ler os mesmos números do objeto prompt_cache. Ambos requerem Claude Code v2.1.251 ou posterior.

A linha Prompt cache (main) também nomeia a provável causa da última falha quando Claude Code consegue identificar uma, por exemplo likely cause: tool definitions changed. O texto de causa provável requer Claude Code v2.1.260 ou posterior.

Para visibilidade em toda uma organização, o exportador OpenTelemetry relata tokens de leitura e criação de cache por usuário e sessão. Veja Monitorar uso para a referência de métrica e atributo de evento.

Subagents e o cache

Um subagent inicia sua própria conversa com seu próprio prompt do sistema e conjunto de ferramentas, separado do pai. Sua primeira solicitação não lê o cache do pai, porque os dois prefixos diferem, e aquece um cache próprio ao longo de seus turnos. Subagents ficam fora do bucket TTL da conversa principal, então recebem cinco minutos mesmo em uma assinatura até você escolher um mais longo.

O cache do pai não é afetado. Do lado do pai, a chamada e resultado do subagent se anexam à conversa, deixando o prefixo do pai intacto.

Um fork, por contraste, herda o prompt do sistema, ferramentas e histórico de conversa do pai exatamente, então sua primeira solicitação lê o cache do pai.

Outras solicitações também podem ler um prefixo que uma solicitação anterior armazenou em cache:

  • Cópias de sessão: uma sessão que você copia com /fork recebe sua instrução de isolamento como uma mensagem no final da conversa copiada, então o cache que a conversa original construiu permanece intacto.
  • Compactação: a chamada de resumo descrita em Compactando a conversa usa a mesma abordagem de compartilhamento de prefixo.
  • Workflow fan-outs: em um workflow fan-out de agentes com o mesmo prefixo, Claude Code mantém todos exceto o primeiro por até 5 segundos por padrão, então suas primeiras solicitações podem ler o prefixo que o primeiro agente armazenou em cache.

Desabilitar prompt caching

Desabilitar caching é ocasionalmente útil ao depurar comportamento de caching com um modelo ou provedor específico. Para desativá-lo, defina uma dessas variáveis de ambiente como 1:

Variável Efeito
DISABLE_PROMPT_CACHING Desabilitar para todos os modelos
DISABLE_PROMPT_CACHING_HAIKU Desabilitar para Haiku apenas
DISABLE_PROMPT_CACHING_SONNET Desabilitar para Sonnet apenas
DISABLE_PROMPT_CACHING_OPUS Desabilitar para Opus apenas
DISABLE_PROMPT_CACHING_FABLE Desabilitar para Fable apenas

Para definir a política de caching em toda uma organização, coloque qualquer uma dessas ou as variáveis de TTL no bloco env de configurações gerenciadas. Para uso normal, deixe o caching habilitado.