Corrigindo a Invalidação do Cache KV do Claude Code com Backends Locais

As versões 2.1.36 e superiores do Claude Code injetam conteúdo dinâmico nos prompts do sistema a cada solicitação, causando invalidação do cache KV ao usar backends de inferência locais como llama.cpp, llama-server ou LM Studio. Isso força o hardware a reprocessar prompts do sistema de 20 mil tokens do zero para chamadas de ferramentas menores.

O Problema

O llama.cpp depende de correspondência exata de strings para reutilização do cache KV. Quando o início de um prompt muda, todo o cache é limpo e o prompt completo deve ser reprocessado. O Claude Code introduz dois elementos dinâmicos que alteram os prompts a cada turno:

• Hash de Telemetria: Injeta um cabeçalho de cobrança/telemetria (x-anthropic-billing-header: cch=xxxxx) com um hash que muda a cada solicitação
• Snapshot do Git: Injeta a saída do git status no bloco de ambiente, alterando o prompt sempre que arquivos são modificados

Isso resulta em logs do servidor mostrando "forçando reprocessamento completo do prompt devido à falta de dados em cache" e tempos de processamento de mais de 60 segundos para o que deveriam ser operações menores.

A Solução

Configure o Claude Code para desativar elementos dinâmicos de prompt e rotear para seu hardware local. Abra ~/.claude/settings.json (ou a configuração local do seu projeto) e garanta a seguinte configuração:

{
  "includeGitInstructions": false,
  "env": {
    "ANTHROPIC_BASE_URL": "<your-llama-server-here>",
    "ANTHROPIC_API_KEY": "<any-string>",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Após reiniciar o Claude Code, os logs do llama-server devem mostrar melhor reconhecimento do cache. Em vez de processar 24.000 tokens, você verá mensagens como "selected slot by LCP similarity, sim_best = 0.973" seguidas de "prompt processing progress, n_tokens = 24270, batch.n_tokens = 4" - indicando apenas 600 tokens de processamento delta em vez de reprocessamento completo.

Isso reduz os tempos de chamadas de ferramentas locais de mais de um minuto para aproximadamente 4 segundos em hardware como o Quadro RTX-8000 da era Turing.