개발수양록

Claude Code 토큰 비용과 프롬프트 캐싱

Claude Code의 토큰 과금 구조를 이해하고 비용을 최적화하는 실용적인 팁을 정리합니다.

Claude Code는 Anthropic의 API를 호출하는 CLI 도구입니다. Enterprise Plan에서는 API 사용량에 따라 과금되므로, 과금 구조를 이해하면 같은 작업을 더 적은 비용으로 할 수 있습니다.

과금의 기본 단위: 토큰

Claude API는 토큰 단위로 과금됩니다. 토큰 종류별로 가격이 다릅니다.

토큰 종류 설명

Input 토큰

모델에게 보내는 모든 텍스트 (시스템 프롬프트, 대화 히스토리, 도구 정의 등)

Output 토큰

모델이 생성한 응답 텍스트

Thinking 토큰

Extended thinking 모드에서 모델이 내부적으로 추론하는 데 쓰는 토큰. Output과 같은 가격으로 과금

모델별 가격표

2026년 3월 기준으로 백만(1M) 토큰당 가격은 다음과 같습니다.

모델 Input Output Cache Write Cache Read

Sonnet 4/4.6

$3

$15

$3.75

$0.30

Opus 4/4.6

$15

$75

$18.75

$1.50

Haiku 4.5

$0.80

$4

$1.00

$0.08

Opus는 Sonnet 대비 모든 항목이 5배입니다. Haiku는 Sonnet의 약 1/4 수준입니다.

Prompt Caching의 효과

Claude API는 stateless입니다. 매 턴마다 시스템 프롬프트, 도구 정의, 이전 대화 히스토리를 모두 다시 보내야 합니다. 여기서 '턴’은 사용자가 한 번 입력하고 Claude가 한 번 답변하는 단위가 아닙니다. Claude Code는 agentic하게 동작하기 때문에, 사용자가 한 번 입력하더라도 Claude가 파일 읽기, 편집, 명령 실행 등 도구를 호출할 때마다 API 호출이 발생합니다. 즉 한 번의 사용자 입력이 여러 턴에 해당할 수 있습니다.

턴이 진행될수록 입력 토큰이 누적되어 증가합니다. 공식으로 표현하면 다음과 같습니다.

턴 n의 입력 토큰:
  input(n) = B + n·T + (O + Th)·(n − 1)

  B  = 시스템 프롬프트 + 도구 정의 (매 턴 고정)
  T  = 턴당 새 사용자 입력 토큰
  O  = 턴당 출력 토큰 (히스토리 누적)
  Th = 턴당 thinking 토큰 (히스토리 누적)

N턴까지의 총 입력 토큰:
  총 입력 = N·B + T·N(N+1)/2 + (O+Th)·N(N−1)/2

N(N+1)/2 는 삼각수 공식입니다. 즉 총 입력 토큰은 턴 수에 대해 이차(quadratic)로 증가합니다. 10턴 대화의 뒷쪽 턴은 앞쪽 턴보다 훨씬 많은 입력 토큰을 소비하며, 대화가 길어질수록 이 격차는 더 벌어집니다.

Prompt Caching은 이 삼각수 효과를 완화하는 핵심 수단입니다. 이전 턴까지의 히스토리는 대부분 캐시에 남아있으므로, 캐시가 적중하면 반복 전송되는 입력 토큰의 비용이 정가의 10%로 줄어듭니다. 캐싱 없이는 뒷쪽 턴의 비용이 급격히 올라가지만, 캐싱이 잘 적중하면 누적 비용 곡선을 크게 낮출 수 있습니다. 캐시가 잘 적중하면 입력 토큰 비용을 90%까지 절약할 수 있습니다.

캐시 유형 설명 가격(Input 대비)

Cache Write

새로운 내용을 캐시에 저장

125%

Cache Read

캐시된 내용을 재사용

10%

Cache Miss

캐시 만료 후 다시 저장

125% (Cache Write와 동일)

캐시 히트율을 높이기 위해서 다음을 의식해야 합니다.

  • 5분 안에 다음 턴 진행: 입력을 보내고 나서 다음 턴까지 5분 이내로 유지하면 캐시가 살아있습니다.

  • 세션 중간에 모델을 전환하지 않기: 모델을 바꾸면 캐시가 완전히 초기화됩니다. 하나의 대화 세션에서는 가능하면 하나의 모델을 유지합니다.

  • 가급적 대화 중 CLAUDE.md를 수정하지 않기: CLAUDE.md는 시스템 프롬프트의 일부로 매 턴 전송됩니다. 대화 중에 이 파일을 수정하면 시스템 프롬프트의 prefix가 달라져 기존의 모든 캐시가 무효화됩니다. 특히 턴이 많이 진행된 세션에서는 삼각수 효과로 쌓인 대량의 히스토리 토큰이 전부 Cache Write(125%)로 재과금되어 비용 타격이 큽니다. 수정이 필요하다면 새 세션에서 시작하는 것이 비용 면에서 유리합니다.

직접 시뮬레이션해보기

위의 내용을 바탕으로 자신의 사용 패턴에 맞는 비용을 직접 계산해볼 수 있는 시뮬레이터를 Claude Code로 만들었습니다. 세션 내의 턴 수, 토큰량, 캐시 히트율 등을 조절하면서 모델별 비용 차이와 누적 비용 곡선을 확인할 수 있습니다.

Claude Code Token Cost Simulator로 이동 →

참고 자료

Ubuntu에서의 OEM 커널 설치 Claude Code의 '/model opusplan’과 showClearContextOnPlanAccept 옵션