Claude Code 비용, 제1막 — 실제 과금 방식

실제 과금 방식이 어떻게 작동하는지, 비용을 절감하기 위한 다양한 옵션 생태계, 그리고 측정에 근거하여(민간 설화가 아닌) 조용히 돈을 낭비하게 만드는 실수들에 대해 다룹니다.

이 가이드는 Claude Code의 비용 모델을 제1원리(first principles)부터 가르쳐 줍니다. 이 글은 자신의 청구 금액을 **예측(predict)**하고, 의도적으로 낮추며(lower), 프로덕션에 적용하기 전에 안티 패턴(anti-patterns)을 **인지(recognize)**하고자 하는 엔지니어들을 위해 작성되었습니다. 명확하지 않은 모든 주장에는 출처 태그가 붙어 있습니다 — [measured] (네트워크상에서 관찰됨), [docs] (Anthropic의 공개 문서에서 가져옴), 또는 [doc-confirmed] (측정되었으며 문서와 일치함) — 그리고 이를 뒷받침하는 표나 실험 결과가 포함되어 있습니다.

이 가이드를 사용하는 가장 좋은 방법: 읽으면서 옆에 Claude 세션을 열어 두세요. 명확하지 않은 부분이 있으면 내용을 붙여넣고 Claude에게 설명해 달라고 하거나 더 깊이 파고들어 달라고 요청하세요. 더 좋은 방법은 숫자를 그대로 믿지 않는 것입니다. Claude에게 자신의 환경에서 **실험을 재현(reproduce the experiments)**하도록 요청하고, 결과가 무엇을 의미하는지 안내받으며, 각 표 뒤에 있는 가공되지 않은 요청/응답 로그(raw request/response logs)를 보여달라고 하세요. 출처 태그가 존재하는 이유는 여러분이 여기 있는 모든 것을 직접 검증할 수 있도록 하기 위함입니다. 이 가이드를 최종 결론이 아닌, 그러한 대화를 시작하기 위한 출발점으로 삼으세요.

이 글을 읽고 나면 할 수 있는 것들

• Claude Code 대화가 턴(turn)이 진행될수록 왜 더 비싸지는지, 그리고 왜 그것이 버그가 아닌지를 한 문장으로 설명할 수 있습니다.
• 제안된 변경 사항(새로운 MCP 서버, 모델 전환, "압축" 프록시 등)을 보고, 이를 배포하기 전에 청구 금액에 도움이 될지 해가 될지 예측할 수 있습니다.
• usage 블록을 읽고, 활성화된 세션(warm session)과 매 턴마다 조용히 캐시를 재구축하고 있는 세션의 차이를 구분할 수 있습니다.
• 실제로 공격하고자 하는 비용 항목에 맞는 적절한 비용 절감 도구를 선택하고, 상황을 악화시키는 인기 있는 도구들을 피할 수 있습니다.
• 가장 비용이 많이 드는 12가지 실수를 인지하고 각각에 대한 해결책을 적용할 수 있습니다.

읽는 법

이 가이드는 **네 가지 멘탈 모델 (mental models)**을 중심으로 구성되었습니다. 이 모델들을 이해하면 나머지는 자연스럽게 도출할 수 있습니다:

1. 기억상실증에 걸린 계약자 (The amnesiac contractor) — 서버는 아무것도 기억하지 못하며, 요청(request)만이 유일한 상태(state)입니다.
2. 접두사 일치 캐시 (The prefix-match cache) — 캐싱은 엄격한 바이트 접두사(byte-prefix) 일치 방식입니다. 초반부의 바이트 하나만 바뀌어도 그 이후의 모든 것은 무효화됩니다.
3. 모델 범위 키 (The model-scoped key) — 캐시 항목은 정확히 하나의 모델에만 속합니다. 다른 모델은 이를 읽을 수 없습니다.
4. 암호화된 봉투 (The encrypted envelope) — 모델의 추론(reasoning)은 봉인된 채로 당신에게 돌아옵니다. 당신은 그것을 전달받지만 열어볼 수는 없습니다.

이 가이드는 당신이 시도하려는 작업에 맞춰 네 개의 막(act)으로 구성되어 있습니다: 제1막 — 과금 방식; 제2막 — 숨겨진 큰 비용이 발생하는 지점 (모델 전환 및 사고 블록 (thinking blocks)); 제3막 — 비용 절감을 위한 옵션 생태계; 제4막 — 종합적인 실수 목록 및 한 페이지 요약본(cheat sheet).

측정 방식에 관한 참고 사항

이 모든 과정은 내부 접근 권한에 의존하지 않습니다. Claude Code는 ANTHROPIC_BASE_URL 환경 변수를 준수하므로, 각 /v1/messages 요청 본문을 기록하고 이를 https://api.anthropic.com으로 전달하는 일반 HTTP 로컬 리버스 프록시(reverse proxy)를 가리킬 수 있습니다. TLS 인터셉션(interception)은 발생하지 않습니다. OAuth Authorization: Bearer 토큰과 anthropic-beta 헤더는 수정 없이 그대로 통과하며, 프록시는 실험적 기능이 필요할 때만 JSON의 model 필드를 재작성합니다. 프록시는 스트리밍된 (SSE) 응답에서 usage 블록을 파싱하고 cache_control 마커를 계산합니다. 리플레이 하네스(replay harness)는 캡처된 실제 요청을 (실제 헤더를 포함하여) 단일 변수 변화를 주어 그대로 다시 전송하므로, 각 발견 사항은 하나의 원인을 격리하여 보여줍니다.

전 과정에 걸친 정직한 제약 사항: API는 "사고(thinking)가 누락되었습니다" 또는 "캐시가 깨졌습니다"라고 알려주는 필드를 제공하지 않습니다. 여기의 모든 결론은 HTTP 상태 코드, 거의 동일한 요청 간의 토큰 수 차이(delta), 그리고 응답 검사를 통해 _추론(inferred)_된 것입니다. 주장이 직접 보고된 것이 아니라 추론된 경우, 그 사실을 명시합니다.

측정은 Sonnet 4.6, Opus 4.7/4.8, 그리고 Haiku 4.5를 사용하는 Claude Code 2.1.150 (OAuth 인증, 2026년 중반)을 대상으로 수행되었습니다. Fable 5와 Mythos 제품군은 테스트 호스트에서 접근이 차단(HTTP 404)되었으므로, 해당 모델들에 대한 주장은 문서상 정보에만 근거합니다. 가격과 정확한 동작 방식은 **버전별로 상이(version-specific)**하므로, 사용 중인 모델과 클라이언트 버전에 대해 반드시 재확인하시기 바랍니다.

과금률에 관한 주의사항, 한 번 명시하며 전체에 걸쳐 적용됩니다. Claude Code가 자체 보고하는 total_cost_usd (/cost 명령과 상태 표시줄에 나타나는 값)는 캐시 쓰기(cache-write) 비용을 **과소 보고(under-report)**할 수 있습니다. 이 값은 1시간 TTL(Time-To-Live) 쓰기 작업에 대해 5분 기준인 1.25배 요율을 적용합니다. 하지만 Anthropic이 발표한 1시간 TTL 쓰기에 대한 요율은 기본 입력값의 2배이며, 본 가이드에서는 이 요율을 모든 곳에 사용합니다. 따라서 표시되는 세션 비용이 본 가이드의 수치보다 낮게 나타날 수 있음을 인지하십시오. 실제 과금에 대해서는 Anthropic Console을 최종 권위 있는 기준으로 간주하십시오. 이 격차 자체가 제4막에서 다룰 실수 중 하나입니다.

전체 비용 모델은 하나의 아키텍처적 사실로부터 도출됩니다. 이 사실과 세 가지 비용 범주(cost buckets)를 이해하면, 청구서의 대부분을 이미 예측할 수 있습니다.

단 하나의 사실: Claude Code는 상태가 없는(stateless) API 클라이언트입니다

Claude Code는 Anthropic의 /v1/messages HTTP API를 사용하는 _클라이언트(client)_입니다. 이 클라이언트는 모델에 대한 특권 채널이나 특별한 서버 측 세션을 보유하지 않습니다. 매 턴(turn)은 모델이 보게 될 전체 컨텍스트, 즉 도구 정의(tool definitions), 시스템 프롬프트(system prompt), 그리고 지금까지의 대화에 포함된 모든 메시지를 담은 **하나의 완전한 HTTP 요청(HTTP request)**입니다. 서버는 응답을 생성한 후 모든 것을 잊어버립니다 — 세션도, 메모리도, "대화(conversation)" 객체도 없습니다. 다음 턴에서는 한 턴이 더 길어진 채로 전체 내용을 다시 전송합니다.

이 단 하나의 사실 — 요청(request)이 유일한 상태(state)라는 점 — 이 본 가이드의 모든 비용 변수를 결정합니다:

• 클라이언트가 매 턴(turn)마다 전체 대화 내용을 다시 전송하기 때문에, 비용은 대화와 함께 증가합니다: 매 턴마다 전체 이력을 다시 처리하는 비용을 지불해야 합니다.
• 서버가 상태를 유지하지 않는(stateless) 방식이기 때문에, 해당 이력을 다시 처리하는 것을 피할 수 있는 유일한 방법은 프롬프트 캐시 (prompt cache) (제1막의 나머지 부분)뿐입니다.
• 요청이 하나의 타겟 모델에 맞춰 공동 설계되었기 때문에, 대화 도중에 모델을 전환하면 캐시가 폐기되며 누적된 추론(reasoning) 비용이 다시 청구됩니다 (제2막).

멘탈 모델 1: 기억상실증에 걸린 계약직 직원

장기 기억력이 없는 아주 유능한 계약직 직원을 상상해 보세요. 당신이 그에게 상담할 때마다, 당신은 완전한 서류철(dossier)을 건네주어야 합니다. 그가 사용할 수 있는 도구, 상시 지침, 그리고 지금까지 진행된 프로젝트의 전체 이력이 담긴 서류 말입니다. 그는 서류를 읽고 훌륭한 조언을 해주지만, 당신이 떠나는 즉시 모든 업무 내용을 잊어버립니다. 다음에 다시 만날 때는 기존 서류철에 오늘 작성된 새로운 페이지를 추가해서 가져가야 합니다.

이것이 바로 Claude Code와 API 사이의 관계입니다. Claude Code에서 발생하는 모든 비용 문제는 "매번 서류철 전체를 처음부터 다시 읽어야 한다"는 사실에서 비롯됩니다.

증거: 서버는 아무것도 기억하지 못함 [측정됨]

서버가 턴(turn)을 가로질러 사실을 기억하는지 확인하기 위해, 동일한 세션 설계로 두 개의 요청을 보냈습니다:

전송된 요청	모델의 답변
"내 비밀은 42야" + 확인 + "내 비밀이 뭐야?" (페이로드(payload)에 사실이 포함됨)	"42"
오직 "내 비밀이 뭐야?" 만 전송 (페이로드에서 이전 턴이 누락됨)	"메모리에 저장된 비밀 번호가 없습니다..."

모델은 오직 _현재 요청(current request)_이 담고 있는 내용만을 알고 있습니다. 요청 본문(request body)에서 이전 턴이 누락되면 비밀은 사라집니다. 그것을 회상할 세션 자체가 존재하지 않기 때문입니다. 채팅에서 당신이 경험하는 "기억"은 클라이언트가 이력을 계속 다시 전송함으로써 유지되는 환상일 뿐입니다.

사고(Thinking) 과정 또한 물리적으로 다시 전송됩니다 [측정됨]

단순히 눈에 보이는 메시지만이 아닙니다. 캡처된 Opus의 연속성을 보면, 메시지 [17]은 ['thinking(sig=yes, len=0)', 'text', 'tool_use(Grep)']로 나타나며, 이어서 [18]이 tool_result로 나타납니다. 사고(Thinking) 블록은 요청 본문(request body) 내에 존재합니다. 즉, 클라이언트가 모델 자신의 이전 추론 내용을 모델에게 다시 보내고 있는 것입니다. (이 블록들이 무엇을 포함하는지, 어떻게 과금되는지, 그리고 모델을 전환할 때 이 블록들이 어떻게 되는지는 제2막 후반부의 핵심 내용입니다. 지금은 이것만 기억하세요: 이들은 문서(dossier)의 일부이며, 문서의 일부는 비용이 발생합니다.)

초기에 반드시 숙지해야 할 미묘한 차이점이 있습니다: 이 구성에서 사고(thinking) 과정을 다시 전송하는 것이 엄격하게 필수적인 것은 아닙니다. 사고 블록을 (a) 유지한 채, (b) 마지막 어시스턴트 턴에서 제거한 채, 그리고 (c) 모든 곳에서 제거한 채로 캡처된 연속성을 다시 실행했을 때 모두 HTTP 200이 반환되었습니다 [측정됨]. 서버는 오류를 발생시키지 않으며, 기억된 복사본으로 대체하지도 않습니다. 왜냐하면 서버에는 그런 것이 없기 때문입니다. 사고 과정을 다시 전송하는 것은 _클라이언트_가 모델에게 추론의 연속성을 제공하는 방식이지, 서버가 상태(state)를 유지하는 방식이 아닙니다. 서버는 어떠한 상태도 유지하지 않습니다.

렌더링 순서: 안정적인 콘텐츠를 먼저, 가변적인 콘텐츠를 마지막에

모든 요청은 다음 순서로 조립됩니다:

tools  →  system  →  messages

도구(Tool) 정의가 0바이트 위치에 오고, 그다음 시스템 프롬프트(system prompt), 마지막으로 대화(conversation)가 옵니다. 이는 단순히 외관상의 문제가 아닙니다. 이는 비용 측면에서 가장 중요한 레이아웃(layout) 결정이며, 한 가지 규칙을 따릅니다:

안정적인 콘텐츠를 먼저, 가변적인 콘텐츠를 마지막에.

캐싱(caching) 단계에 도달하는 순간, 왜 이 순서가 구조적으로 중요한지 알게 될 것입니다. 캐시는 접두사(prefix) 일치 방식이므로, 가장 적게 변하는 것들이 먼저 와야 합니다. 그렇지 않으면 가장 많이 변하는 것들 때문에 캐시가 계속 무효화될 것입니다.

나중에 캐시 동작(cache behavior)을 결정짓는 요소이기에, 구조적 특징을 하나 더 살펴보겠습니다. messages 계층은 **메시지(messages)**의 순서가 있는 리스트입니다. 이는 대화의 차례(conversation turns)를 의미하며, 각 메시지는 role과 콘텐츠를 가집니다. 그리고 각 메시지의 콘텐츠는 그 자체로 타입이 지정된 **콘텐츠 블록(content blocks)**의 순서가 있는 리스트입니다. 여기에는 텍스트 블록, tool_use 블록(모델이 도구를 호출하는 것), tool_result 블록(그에 대한 사용자의 답변), thinking 블록, 이미지가 포함됩니다. 하나의 메시지는 여러 개의 블록을 가질 수 있습니다. 예를 들어, 10개의 병렬 도구를 실행하는 어시스턴트 턴은 단일 메시지이지만 20개 이상의 블록을 가집니다. 메시지(message)와 블록(block)의 구분을 명심하세요. 캐시의 역방향 재연결(backward re-link)은 메시지가 아니라 _블록_을 기준으로 계산하며, 이것이 바로 대규모 도구 폭발(tool burst) 시 발생하는 문제의 원인입니다 (Agentic tool bursts overflow the 20-block lookback 참조).

비용이 발생하는 세 가지 요소

모든 요청의 usage 블록은 입력을 출력 외에 세 가지 범주(bucket)로 나눕니다. 각 범주가 _기본 입력 대비 얼마의 비용이 드는지_를 파악하는 것이 중요합니다. 그 비율이 핵심이기 때문입니다.

범주 (usage.*)	의미	기본 입력 대비 가격
cache_read_input_tokens	기존 캐시 엔트리에서 제공됨	0.1×
...

반드시 기억해야 할 두 가지 사실이 있습니다:

1. 캐시 히트(cache hit)는 동일한 토큰을 콜드 프로세싱(cold processing)하는 것보다 약 10배 저렴합니다 (0.1× vs 1×). 이것이 핵심 이점입니다.
2. 출력(Output)은 가장 비싼 클래스입니다 — 모든 모델에서 입력 가격의 5배로 청구되며, 절대로 캐싱되지 않습니다. 모델이 작성하는 토큰은 생성 작업이 많은 턴에서 비용의 대부분을 차지합니다.

요금표 (Anthropic이 발표한 리스트 가격, 1M 토큰당, 2026-06-15 기준)

claude.com/pricing에서 다시 확인하십시오. 캐시 읽기(Cache read) = 입력의 0.1×; 1시간 캐시 쓰기(Cache write) = 입력의 2×; 출력(Output) = 입력의 5×.

모델	입력 (1×)	캐시 읽기 (0.1×)	캐시 쓰기, 1h (2×)	출력 (5×)
Fable 5	$10.00	$1.00	$20.00	$50.00
...

비율은 명확하며 암기할 가치가 있습니다: Sonnet = Opus의 0.6×, Haiku = Opus의 0.2×, Sonnet = Haiku의 3×. 이는 라우팅 옵션을 비교할 때 중요하게 작용할 것입니다.

손익분기점: 언제 캐시에 쓰는 것이 이득인가?

캐싱은 트레이드오프(trade)입니다. 한 번의 비싼 쓰기 작업(write, 입력 가격의 2배)을 수행하여 이후 요청들이 저렴한 읽기 작업(read, 0.1배)으로 처리되게 하는 것입니다. 이 거래가 성공하는지 여부는 캐시된 접두사(prefix)를 몇 번 재읽는지에 달려 있습니다.

같은 접두사를 N개의 요청에 대해 두 가지 방식으로 처리해 보겠습니다:

• 캐시 없음: 모든 요청이 전체 입력 가격을 지불합니다 → 총 N × 1×.
• 캐시 사용: 첫 번째 요청이 쓰기(write)를 수행하고 (2배); 이후 각 요청은 읽기(read)만 합니다 (0.1배) → 총 2× + (N−1) × 0.1×.

캐싱은 2 + 0.1(N−1) < N이 되는 순간, 즉 3번째 요청부터 이득을 보기 시작합니다. 계산해 보면 다음과 같습니다:

• 요청 3회 기준: 캐시 비용은 2 + 0.1 + 0.1 = 2.2× vs 비캐시 시 3×. ✅ 캐시 사용이 유리합니다.
• 요청 10회 기준: 2.9× vs 10×. ✅ 캐시 사용이 확실히 유리합니다.

왜 '3번째 요청'이고 '2번째 요청'이 아닐까요? TTL(Time To Live)이 쓰기 가격을 설정하며, 이 부분이 Claude Code가 원본 API와 정확하게 다른 지점입니다. 기본적으로 Anthropic은 5분의 캐시 TTL을 사용하며, 이때 쓰기 비용은 단지 **1.25×**에 불과하여 캐싱이 요청 2회차부터 손익분기점을 넘깁니다. 하지만 Claude Code 클라이언트는 이 기본값을 무시하고 모든 브레이크포인트(breakpoint)에서 1시간 TTL을 요청하며 (이 장 후반부에서 측정됨), 이때 쓰기 비용은 **2×**가 됩니다. 따라서 손익분기점은 3번째 요청으로 밀리게 됩니다. 본 가이드에서는 Claude Code가 실제로 전송하는 방식에 맞춰 2× / 1시간 TTL을 사용합니다.