Claude Code Costs, Act I — How the billing actually works

개요

Claude Code의 비용 모델은 각 대화 턴마다 전체 대화 기록을 재전송하는 상태 비저장 API 아키텍처에 기반하며, 캐싱은 비용 절감의 핵심 요소입니다.

주요 내용

• Claude Code의 비용 구조:
• Claude Code는 상태 비저장 HTTP API 클라이언트로서, 각 요청마다 전체 대화 기록, 도구 정의, 시스템 프롬프트를 포함하여 모델에게 전달합니다.
• 비용은 주로 (1) 대화 기록 재처리, (2) 모델 출력 생성 두 가지 요소로 구성됩니다.
• 비용 버킷: cache_read_input_tokens(0.1배), cache_creation_input_tokens(2배, 1시간 TTL), input_tokens(1배, 캐시되지 않은 처리), output_tokens(5배)로 나뉩니다.
• 출력 토큰은 가장 비싸며(입력의 5배) 캐싱되지 않습니다.
• 캐시 히트 시 비용은 캐시되지 않은 처리보다 약 10배 저렴합니다.
• 캐시 쓰기는 2배 비용이 발생하지만, 3회 이상 재사용 시 캐시되지 않은 처리보다 경제적입니다.
• total_cost_usd는 실제 캐시 쓰기 비용을 과소평가할 수 있습니다.

• 캐싱 메커니즘:
• 캐싱은 모델이 프롬프트를 처리할 때 생성하는 Key/Value(KV) 벡터를 저장하는 방식으로 작동합니다.
• 캐시는 엄격한 바이트 접두사 일치(prefix-match) 기반으로 작동하며, 접두사의 작은 변화에도 캐시가 무효화됩니다.
• 캐시는 대화 기록의 시작 부분(도구 정의 → 시스템 프롬프트 → 메시지)에만 적용됩니다.
• 각 턴마다 마지막 캐시 중단점(breakpoint)이 다음 턴으로 슬라이딩되며, 새로운 토큰만 비용이 발생하는 델타 방식으로 처리됩니다.
• 캐시 항목은 불변하며, 오래된 항목은 삭제되지 않고 시간이 지나면 만료됩니다.
• 캐시 중단점은 20개 콘텐츠 블록의 범위 내에서만 유효하며, 이를 초과하는 툴 사용은 캐시를 무효화합니다.

• 캐시 무효화 요인:
• 도구 정의 변경: MCP 서버의 도구 정의가 변경되거나 동적으로 추가/제거될 때, 캐시의 시작 부분(바이트 0)이 변경되어 전체 접두사가 재계산됩니다. --strict-mcp-config 사용으로 안정화 가능합니다.
• 모델 전환: 캐시는 모델별로 격리되므로 모델 변경 시 전체 캐시가 무효화됩니다.
• 긴 에이전트 툴 버스트: 단일 턴에서 20개 이상의 툴 사용/결과 블록이 발생하면 API의 20개 블록 미리보기 창을 초과하여 캐시 무효화가 발생합니다.
• CLAUDE.md 파일 수정: 세션 재시작 또는 재개 시 파일 내용이 변경되면 캐시가 재계산될 수 있습니다.
• 시스템 프롬프트 변경: 드물지만, 시스템 프롬프트가 변경될 경우 전체 캐시가 무효화될 수 있습니다.
• 플러그인/MCP 서버의 동적 도구: 동적 도구 탐색 모드(--dynamic-toolsets)를 사용하는 MCP 서버는 런타임에 도구가 변경될 때 바이트 0에서 캐시를 무효화합니다.
• 주입된 컨텍스트: Claude Code 클라이언트는 날짜, Git 상태, 시스템 알림 등은 캐시 무효화를 최소화하도록 처리하지만, 직접 API를 사용할 경우 이러한 요소들도 캐시를 무효화할 수 있습니다.

• Claude Code 클라이언트 vs. Raw API:
• Claude Code 클라이언트는 캐시 중단점 관리, TTL 설정 등을 자동으로 처리합니다.
• Raw API를 직접 사용할 경우, cache_control 직접 설정, 적절한 TTL 선택, 올바른 렌더링 순서, 직렬화 일관성 유지 등이 필요합니다.
• 최소 캐시 가능 접두사 크기(모델별 1,024–4,096 토큰) 미만에서는 캐시 마커가 작동하지 않을 수 있습니다.

시사점

Claude Code 사용 시 발생하는 비용은 대화 기록 재처리 및 출력 생성에 집중되며, API 요청 시 전체 기록을 재전송하는 상태 비저장 특성으로 인해 캐싱 전략이 비용 절감의 핵심입니다. 도구 정의 안정화, 모델 전환 최소화, 긴 툴 버스트 방지 등의 최적화는 비용 효율성을 크게 향상시킬 수 있으며, Raw API 사용 시에는 더욱 세심한 캐싱 관리가 요구됩니다.