클로드 코드 토큰 낭비 해결: 캐시 적중률 향상을 위한 어트리뷰션 헤더 비활성화

Claude Code는 2.1.69 버전 이후로 프롬프트 캐싱을 방해하는 청구 속성 헤더로 인해 모든 새 세션에서 토큰을 낭비해 왔습니다. 이 문제는 여러 GitHub 이슈(#40652, #34629, #40524)에 문서화되어 있으며, 출처 발행 시점 기준으로 Anthropic의 공식 답변은 없습니다.

무슨 일이 일어나고 있나요

v2.1.69 이후로 Claude Code는 시스템 프롬프트의 첫 번째 블록에 청구 속성 문자열을 삽입합니다: x-anthropic-billing-header: cc_version=2.1.88.a3f; cc_entrypoint=cli; cch=00000;

.a3f 부분은 각 대화의 첫 번째 메시지에서 이 함수를 사용해 계산된 3자리 해시입니다:

function computeHash(firstUserMessage, version) {
  const chars = [4, 7, 20].map(i => firstUserMessage[i] || "0").join("");
  return sha256("59cf53e54c78" + chars + version).slice(0, 3);
}

다른 첫 번째 메시지를 가진 다른 대화는 매번 다른 해시를 생성합니다.

이것이 캐싱을 방해하는 이유

Anthropic의 캐싱은 100% 동일한 프롬프트 세그먼트를 요구합니다. 캐시는 세션별이 아닌 전체 조직 또는 작업 공간에서 공유됩니다. 청구 헤더는 약 23K 토큰 시스템 프롬프트의 앞부분에 위치하며, 대화마다 변경되므로 접두사가 일치하지 않아 모든 새 채팅에서 캐시 미스가 발생합니다.

벤치마크 결과

통제된 A/B 테스트 결과:

• 헤더 켜짐 (기본값): 48% 캐시 적중률, 세션당 약 12K 토큰 재구성
• 헤더 꺼짐: 99.98% 캐시 적중률, 4개 세션 중 3개에서 캐시 생성 없음

결과적으로 시스템 프롬프트 처리 비용이 세션당 7배 저렴해집니다.

해결 방법

셸 구성에 다음을 추가하세요:

export CLAUDE_CODE_ATTRIBUTION_HEADER=false

zsh 사용자의 경우:

echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=false' >> ~/.zshrc
source ~/.zshrc

새 세션은 자동으로 이를 인식합니다. 기존 세션은 재시작할 필요가 없습니다—해시는 대화 중간에 변경되지 않으며, 새 세션에 간섭하지 않습니다.

안전성 및 배경

이는 해킹이 아닙니다—환경 변수는 적절한 기능 토글으로 소스 코드에 존재합니다. claude-code-router와 CLIProxyAPI는 이 기능을 비활성화한 상태로 프로덕션에 배포되었으며 보고된 문제는 없습니다.

Anthropic은 아마도 각 API 호출이 어떤 버전과 진입점(CLI 대 SDK 대 GitHub Action)에서 이루어졌는지 추적하기 위해 이를 구현했을 것이며, Bedrock/Vertex가 사용자 정의 헤더를 전달하지 않기 때문에 시스템 프롬프트에 배치했습니다.