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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Claude Code가 시스템 프롬프트에 동적 데이터를 삽입하여 로컬 KV 캐시를 깨뜨리는 문제를 설정 변경으로 해결하여 추론 속도를 15배 향상시켰다.

배경

Claude Code를 로컬 LLM 서버와 연동하여 사용하던 중, 매 요청마다 발생하는 극심한 지연 시간을 해결하기 위해 프롬프트 캐시 무효화 원인을 파악하고 해결책을 공유했다.

의미 / 영향

로컬 LLM 환경에서 상용 CLI 도구를 사용할 때 프롬프트의 미세한 동적 변화가 성능에 치명적일 수 있음을 확인했다. 개발자는 추론 엔진의 캐시 메커니즘을 이해하고 도구 설정을 최적화함으로써 로컬 환경에서도 상용 서비스 수준의 반응 속도를 확보할 수 있다.

커뮤니티 반응

대체로 긍정적이며, 로컬 환경에서 Claude Code를 사용하려는 사용자들에게 필수적인 팁으로 받아들여졌다.

주요 논점

01찬성다수

Claude Code의 동적 프롬프트 주입이 로컬 KV 캐시를 파괴하므로 이를 비활성화해야 한다.

합의점 vs 논쟁점

합의점

Claude Code의 기본 설정은 로컬 추론 엔진의 KV 캐시 메커니즘과 호환되지 않는다.
설정 파일 수정을 통해 프롬프트를 정적으로 유지하면 성능이 대폭 향상된다.

논쟁점

Anthropic이 이러한 동적 주입을 문서화하지 않고 강제하는 것에 대한 비판적 시각이 존재한다.

실용적 조언

로컬 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에서도 로컬 도구 호출이 즉각적으로 이루어지는 성능 향상을 기록했다.

실무 Takeaway

Claude Code는 기본적으로 매 요청마다 동적 헤더와 Git 상태를 프롬프트에 삽입하여 로컬 엔진의 KV 캐시를 무효화한다.
~/.claude/settings.json에서 텔레메트리와 Git 연동 기능을 끄면 시스템 프롬프트를 정적으로 유지하여 캐시 재사용률을 극대화할 수 있다.
이 최적화를 통해 2만 토큰 이상의 대규모 컨텍스트에서도 도구 호출 지연 시간을 1분에서 4초 수준으로 획기적으로 줄였다.

언급된 도구

Claude Code추천

Anthropic의 CLI 코딩 에이전트 도구

llama.cpp추천

로컬 LLM 추론 엔진 및 서버

LM Studio추천

로컬 LLM 실행 및 관리 도구