로컬 백엔드로 Claude Code의 KV 캐시 무효화 문제 해결하기

Claude Code 버전 2.1.36 이상은 모든 요청에서 시스템 프롬프트에 동적 콘텐츠를 주입하여 llama.cpp, llama-server 또는 LM Studio와 같은 로컬 추론 백엔드를 사용할 때 KV 캐시 무효화를 유발합니다. 이로 인해 사소한 도구 호출에도 하드웨어가 20K+ 토큰 시스템 프롬프트를 처음부터 재처리해야 합니다.

문제점

llama.cpp는 KV 캐시 재사용을 위해 정확한 문자열 매칭에 의존합니다. 프롬프트 시작 부분이 변경되면 전체 캐시가 플러시되고 전체 프롬프트를 재처리해야 합니다. Claude Code는 매 턴마다 프롬프트를 변형시키는 두 가지 동적 요소를 도입합니다:

• 원격 측정 해시: 모든 요청마다 변경되는 해시가 포함된 청구/원격 측정 헤더(x-anthropic-billing-header: cch=xxxxx)를 주입합니다
• Git 스냅샷: 환경 블록에 git status 출력을 주입하여 파일이 수정될 때마다 프롬프트를 변경합니다

이로 인해 서버 로그에 "캐시 데이터 부족으로 인한 전체 프롬프트 재처리 강제" 메시지가 표시되고 사소한 작업에도 60초 이상의 처리 시간이 발생합니다.

해결 방법

Claude Code를 구성하여 동적 프롬프트 요소를 비활성화하고 로컬 하드웨어로 라우팅하세요. ~/.claude/settings.json(또는 프로젝트의 로컬 구성)을 열고 다음 구성을 확인하세요:

{
  "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"
  }
}

Claude Code를 재시작한 후, llama-server 로그에 향상된 캐시 인식이 표시되어야 합니다. 24,000개의 토큰을 처리하는 대신 "selected slot by LCP similarity, sim_best = 0.973"과 같은 메시지 뒤에 "prompt processing progress, n_tokens = 24270, batch.n_tokens = 4"가 표시되어 전체 재처리 대신 600개의 토큰 델타 처리만 수행됨을 나타냅니다.

이렇게 하면 Turing-era Quadro RTX-8000과 같은 하드웨어에서 로컬 도구 호출 시간이 1분 이상에서 약 4초로 단축됩니다.