Claude Code 토큰 폭주의 원인과 캐시 패치 적용 방법 정리

Claude Code 토큰 폭주의 원인과
캐시 패치 적용 방법 정리

캐시 적중률 26% → 99%, 유저 패치로 해결한 사례 분석

 

 

Claude Code를 쓰다 보면
세션을 이어갈수록 토큰 소모가 비정상적으로 치솟는 현상을
한 번쯤 경험해봤을 거야.

5시간 사용량이 갑자기 폭주하고,
별로 복잡한 작업을 하지도 않았는데 한도가 순식간에 차버리는 그 현상.

최근에 이 문제의 정확한 원인이 밝혀졌어.
그리고 유저가 직접 만든 패치까지 나왔어.

오늘은 이 버그가 왜 발생하는지,
패치가 어떻게 작동하는지를 정리해볼게.

 

---

증상부터 정리

 

이 버그의 특징은 이래.

 

✔ 새 세션에서는 정상인데, 세션을 이어갈수록 토큰 소모가 급증
✔ 대화 턴이 쌓일수록 점점 심해짐
✔ 특별히 긴 프롬프트를 쓰지 않아도 발생
✔ 사용량 대시보드에서 cache_creation 토큰이 비정상적으로 높게 잡힘

 

GitHub에도 관련 이슈가 두 건 열려 있었어.
#40524, #34629.

사용자들이 "토큰이 비정상적으로 빠진다"고 신고했는데
원인 파악이 안 되고 있었던 상태였지.

 

---

원인: 세션 저장 시 도구 기록이 삭제되는 버그

 

Claude Code의 대화 저장 구조부터 알아야 해.

 

대화 저장 방식

 

Claude Code는 대화를 JSONL 파일로 저장해.
경로는 ~/.claude/projects/ 안에 있어.

세션을 이어갈 때 이 파일을 읽어서
"이전에 어디까지 했는지"를 복원하는 구조야.

 

버그 1 — deferred_tools_delta 삭제 문제

 

문제가 된 건 소스코드의 db8이라는 함수야.

이 함수는 세션을 저장할 때
Anthropic 내부 사용자가 아니면
attachment 타입 메시지를 전부 삭제하는 필터인데,

여기서 deferred_tools_delta라는 기록이 같이 날아가.

 

deferred_tools_delta가 뭐냐면,
"모델한테 이미 안내한 도구 목록" 기록이야.
세션을 재개할 때 Claude Code가 "어떤 도구를 이미 알려줬지?"를
이 기록으로 확인하거든.

 

이 기록이 없으면 어떻게 되냐고?

매 턴마다 전체 도구를 처음부터 다시 안내해.

 

왜 이게 토큰 폭탄으로 이어지는가

 

도구를 다시 안내하면 메시지 배열 구조 자체가 바뀌어.

 

캐시가 깨지는 메커니즘:

1. 도구 재안내 → 메시지 배열에 새 항목 추가됨
2. 원래 messages[0]에 있던 시스템 프롬프트가 messages[N]으로 밀림
3. 과금 해시가 달라짐
4. 캐시 브레이크포인트가 어긋남
5. 전체 대화가 캐시를 못 타고 처음부터 재처리

 

cache_creation 토큰으로 잡히는 거야.
캐시를 읽는 게 아니라 매번 새로 만드는 거지.

대화가 길수록 재처리할 양이 많아지니까
턴이 쌓일수록 토큰 소모가 가속되는 구조야.

 

버그 2 — 바이너리 설치 시 캐시 문자열 충돌

 

두 번째 버그는 설치 방식에 따라 발생해.

~/.local/share/claude/에 설치되는 독립 실행 바이너리가
커스텀 Bun 포크를 쓰는데,
API 요청마다 cch=00000이라는 값을 덮어씀.

대화 내용에 이 문자열이 우연히 포함되면
캐시가 깨져버려.

npm/Node.js로 설치하면 이 문제가 발생하지 않는다고 해.

 

패치 전후 실측 데이터

 

패치를 만든 Reddit 유저 Rangizingo가 직접 측정한 수치야.

 

패치 전 — 캐시 적중률

턴 1: 67%
턴 5: 48%
턴 10: 31%
턴 15: 26%

cache_read가 15,451에서 한 번도 증가하지 않음.
시스템 프롬프트만 캐시 타고, 나머지 전부 새로 처리.

 

패치 후 — 캐시 적중률

턴 1(재개): 13%
턴 2: 99%
턴 3: 99%

첫 턴만 낮고 이후 정상 캐시 동작.

 

같은 대화, 같은 모델에서
26% → 99%.
체감상 토큰 소모량이 완전히 달라지는 수준이야.

 

---

패치 내용과 적용 시 참고사항

 

패치 핵심

 

db8 함수에서
deferred_tools_delta와 mcp_instructions_delta
두 타입을 삭제 대상에서 빼주는 거야.

이 두 기록이 세션 파일에 살아남으면,
재개할 때 "이미 안내한 도구"를 인식해서
다시 안내하지 않아. 캐시 구조가 유지되는 거지.

 

적용 방식

 

1. 기존 Claude Code 설치를 건드리지 않음
2. 별도로 npm 버전을 설치
3. 패치 적용 후 claude-patched라는 래퍼 스크립트로 실행
4. 기존 설치와 완전히 분리되어 운영

 

주의사항

 

⚠ v2.1.81에서만 테스트됨 — 다른 버전에서는 함수 이름이 바뀔 수 있어서 패턴 매칭이 실패할 수 있음

⚠ 함수명이 난독화되어 있음 — 버전 업데이트 시 패치가 무효화될 가능성 있음

⚠ Anthropic 공식 패치가 나오면 — 패치 폴더 삭제하고 원래대로 쓰면 됨

 

패치 리포는 GitHub에 공개되어 있어.
Rangizingo/cc-cache-fix로 검색하면 나와.

 

---

정리

 

원인: 세션 저장 시 도구 안내 기록이 삭제되어, 재개할 때마다 전체 도구를 재안내 → 캐시 구조 파괴 → 전 대화 재처리

결과: 턴이 쌓일수록 캐시 적중률 하락 (26%까지), 토큰 소모 폭증

해결: 유저 패치로 캐시 적중률 99% 복구. 공식 패치는 아직 미출시.

 

Claude Code를 세션 이어가면서 쓰는 사람이라면
꼭 알아둬야 할 내용이야.

Anthropic 공식 수정이 나올 때까지
참고해서 판단하면 좋겠어.

 

궁금한 거 있으면 댓글로 물어봐.
다음에 또 유용한 정보 들고 올게! 👋