Claude Code를 Anthropic 없이 사용하기: 60초 로컬 KV 캐시 무효화 문제 해결 방법

실용적 조언

로컬 LLM 서버를 사용할 경우 ~/.claude/settings.json에서 includeGitInstructions를 false로 설정하고 텔레메트리를 차단할 것.

섹션별 상세

Claude Code를 llama.cpp와 같은 로컬 추론 서버와 연동할 때 심각한 성능 저하가 발생한다는 사실이 확인됐다. 매 도구 호출마다 2만 토큰 이상의 시스템 프롬프트를 처음부터 다시 처리하며 60초 이상의 지연이 발생한다. 이는 로컬 하드웨어의 한계가 아니라 소프트웨어의 프롬프트 구성 방식에 기인한 문제이다.

문제의 핵심은 Claude Code가 매 요청마다 시스템 프롬프트에 동적인 텔레메트리 헤더와 Git 상태 정보를 주입하는 데 있다. llama.cpp 엔진은 프롬프트의 문자열이 이전과 완벽히 일치해야 KV 캐시를 재사용하는데, 단 몇 글자의 변화만으로도 캐시가 무효화된다. 이로 인해 전체 컨텍스트를 매번 새로 계산하는 비효율이 초래됐다.

사용자는 ~/.claude/settings.json 설정 파일을 수정하여 텔레메트리와 Git 연동 기능을 비활성화함으로써 이 문제를 해결했다. includeGitInstructions를 false로 두고 환경 변수에서 DISABLE_TELEMETRY 등을 1로 설정하면 프롬프트의 정적 부분이 유지된다. 이를 통해 엔진이 프롬프트의 대부분을 동일한 것으로 인식하도록 유도했다.

json

{ "includeGitInstructions": false, "env": { "ANTHROPIC_BASE_URL": "", "ANTHROPIC_API_KEY": "", "CLAUDE_CODE_ATTRIBUTION_HEADER": "0", "DISABLE_TELEMETRY": "1", "DISABLE_ERROR_REPORTING": "1", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" } }

Claude Code의 동적 프롬프트 생성을 억제하고 로컬 서버 연동을 설정하는 JSON 구성

설정 적용 후 24,000 토큰의 프롬프트 처리 시간이 60초에서 약 4초로 단축되는 결과가 나타났다. 서버 로그에서 LCP similarity가 0.973으로 측정되며 캐시가 정상적으로 작동함이 증명됐다. 구형 GPU인 Quadro RTX-8000에서도 로컬 도구 호출이 즉각적으로 이루어지는 성능 향상을 기록했다.

용어 해설

KV 캐시(KV Cache): — LLM 추론 시 이전 토큰들의 연산 결과를 메모리에 저장해 두었다가 다음 토큰 생성 시 재사용하는 기술이다. 이를 통해 중복 계산을 피하고 생성 속도를 비약적으로 높일 수 있어 대규모 컨텍스트 처리에 필수적이다.
프리픽스 매칭(Prefix Matching): — 프롬프트의 앞부분이 이전에 처리했던 내용과 얼마나 일치하는지 확인하는 기법이다. llama.cpp와 같은 엔진은 문자열이 정확히 일치할 때만 저장된 캐시를 불러오므로, 프롬프트 중간에 동적인 데이터가 삽입되면 캐시 효율이 급격히 떨어진다.
텔레메트리(Telemetry): — 소프트웨어가 사용자의 이용 방식이나 시스템 상태 정보를 자동으로 수집하여 개발사 서버로 전송하는 기능이다. Claude Code에서는 이 정보가 프롬프트 헤더에 포함되어 매번 바뀌기 때문에 로컬 환경에서의 캐시 재사용을 방해하는 원인이 된다.

언급된 도구

Claude Code추천

Anthropic의 CLI 코딩 에이전트 도구

llama.cpp추천

로컬 LLM 추론 엔진 및 서버

LM Studio추천

로컬 LLM 실행 및 관리 도구