"Claude Code 토큰·캐시 비용 완전 해부 2026 — 5분 1.25× vs 1시간 2× 배수의 함정"
공식 가격표 · 캐시 최소 토큰 · /usage 추적 · 비용 줄이는 10가지 실전
핵심 요약
- 대상 독자: Claude Code를 쓰다가 월말 청구서 보고 놀란 적 있거나, 팀 도입 전에 예산 산정이 필요한 사용자.
- 얻을 것: 공식 pricing 기준 2026년 4월 현재 모델 가격 + 캐시 배수(1.25× / 2× / 0.1×) + 모델별 최소 캐시 토큰 +
/usage로 실시간 추적 + 공식 권장 비용 절감 10가지 + 숨은 비용(확장 사고·에이전트 팀·백그라운드). - 선행 조건: Claude Code 설치(설치 완전판). Pro/Max 정액 구독자는 이 글의 수치가 청구와 직접 관련 없음 — 세션 비용은 참고값일 뿐 구독료가 우선.
1. 두 가지 과금 축 — 토큰과 캐시
Claude Code는 Anthropic API 토큰 소비에 기반해 과금된다. 비용은 두 개의 축에서 발생한다.
- 입력·출력 토큰 — 대화 한 턴마다 프롬프트(입력)와 응답(출력)이 각각 과금된다.
- 프롬프트 캐시 — 시스템 프롬프트·CLAUDE.md·긴 컨텍스트를 캐시에 저장하면 같은 내용의 재전송이 0.1× 가격으로 내려간다. 단 캐시 쓰기는 표준가보다 비싸다 (1.25× 또는 2×).
이 두 축을 이해하지 못하면 "왜 두 번째 응답이 첫 번째보다 싸지?" 같은 현상을 해석할 수 없다.
Pro/Max/Team/Enterprise 구독자는 월 정액이므로 개별 API 비용이 청구와 무관. 대신 플랜별 사용량 한도(usage bar)가 존재. 아래 표는 Anthropic Console(pay-as-you-go) 기준.
2. 2026년 4월 현재 공식 가격표 (100만 토큰당)
Anthropic 공식 pricing 페이지 기준.
| 모델 | 입력 | 5분 캐시 쓰기 | 1시간 캐시 쓰기 | 캐시 읽기 | 출력 |
|---|---|---|---|---|---|
| Opus 4.7 | $5 | $6.25 | $10 | $0.50 | $25 |
| Opus 4.6 | $5 | $6.25 | $10 | $0.50 | $25 |
| Opus 4.5 | $5 | $6.25 | $10 | $0.50 | $25 |
| Sonnet 4.6 | $3 | $3.75 | $6 | $0.30 | $15 |
| Sonnet 4.5 | $3 | $3.75 | $6 | $0.30 | $15 |
| Haiku 4.5 | $1 | $1.25 | $2 | $0.10 | $5 |
| Haiku 3.5 | $0.80 | $1.00 | $1.60 | $0.08 | $4 |
관찰 포인트: - 출력이 입력의 5배. 긴 응답이 비용을 가장 빠르게 늘린다. - 캐시 쓰기는 "한 번만 내는 프리미엄". 대신 이후 같은 내용 재전송은 0.1×. - Opus ↔ Sonnet은 5배 가격 차이. 적절한 모델 선택이 큰 레버리지.
3. 캐시 배수의 구조 — 1.25× vs 2× vs 0.1×
공식 규칙:
| 동작 | 배수 | 의미 |
|---|---|---|
| 5분 TTL 쓰기 (기본 ephemeral) | 1.25× 입력가 | 5분 안에 재사용하면 이득 |
| 1시간 TTL 쓰기 (extended) | 2× 입력가 | 5분~1시간 간격이면 유리 |
| 캐시 읽기 (hit/refresh) | 0.1× 입력가 | 같은 내용 재전송의 90% 할인 |
예시 — Sonnet 4.6으로 50,000 토큰 컨텍스트를 한 세션에서 10번 재사용한다고 가정.
- 캐시 없음: 50,000 × 10 × $3/MTok = $1.50 (입력만)
- 5분 캐시: 첫 쓰기 50,000 × $3.75/MTok + 읽기 50,000 × 9 × $0.30/MTok = $0.19 + $0.135 = $0.325 (약 78% 절감)
- 1시간 캐시: 첫 쓰기 50,000 × $6/MTok + 읽기 50,000 × 9 × $0.30/MTok = $0.30 + $0.135 = $0.435 (약 71% 절감)
5분 안에 활용할 수 있다면 5분 TTL이 항상 유리. 그러나 유휴 시간이 5분을 넘으면 캐시가 무효화되어 다시 전액 쓰기 비용이 발생 — 그 상황에서는 1시간이 이득.
3.1 Claude Code의 캐시 TTL
주의: 공식
/costs문서는 Claude Code가 기본으로 어떤 TTL을 쓰는지 명시하지 않는다. 관찰적으로 Claude Code는 세션 간 재개 사용을 전제한 1시간 TTL 전용 동작을 보인다. 즉 예산 계산 시 캐시 쓰기는 2× 배수로 산정하는 것이 안전.
따라서 Claude Code의 장점은 "세션이 길어도 캐시 히트가 유지된다"는 것이고, 단점은 "캐시 쓰기 프리미엄이 1.25×가 아니라 2×"라는 것.
4. 모델별 캐시 최소 토큰
요청의 캐시 대상 토큰이 최소값 미만이면 캐시 자체가 작동하지 않는다 (에러 없이 조용히 비캐시 처리됨).
| 모델 | 최소 캐시 토큰 |
|---|---|
| Opus 4.7 / 4.6 / 4.5 | 4,096 |
| Sonnet 4.6 | 2,048 |
| Sonnet 4.5 | 1,024 |
| Haiku 4.5 | 4,096 |
| Haiku 3.5 | 2,048 |
CLAUDE.md가 짧은 프로젝트에서 Opus를 쓰면 캐시 효과가 거의 없다는 뜻 (4K 토큰 미만 흔함). 이 경우 Sonnet이 더 나은 경제.
4.1 캐시 breakpoint 제한
한 요청당 cache_control breakpoint는 최대 4개. 시스템 프롬프트·도구 정의·긴 파일 등 어느 지점에서 캐시 경계를 잡을지 의식적으로 설계해야 한다. 일반 사용자는 Claude Code 내부가 알아서 처리하므로 직접 신경 쓸 일은 없다.
5. /usage 명령으로 비용 추적
세션 안에서 /usage(별칭 /cost, /stats)를 치면 현재 세션의 토큰·비용·코드 변경량이 뜬다.
공식 문서 예시:
Total cost: $0.55
Total duration (API): 6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes: 0 lines added, 0 lines removed
여기 표시되는 달러는 로컬에서 토큰 수로 추정한 값이다. 실제 청구는 Anthropic Console Usage 페이지에서 확인.
5.1 상태 바에 상시 표시
statusline 설정으로 컨텍스트·토큰·비용을 터미널 하단에 상시 표시할 수 있다. 공식 권장.
/statusline
대화형으로 설정되며, 셸 프롬프트를 분석해 자동 구성도 가능.
5.2 엔터프라이즈 평균 (참고)
공식 문서가 공개한 수치: - 평균 약 $13/개발자/active day - 월 $150~250/개발자 - 90%의 사용자는 $30/active day 미만
이 값은 엔터프라이즈 API 배포 기준. 개인 Pro/Max 구독자의 실제 경험과 차이 크다.
6. 비용을 줄이는 공식 권장 10가지
6.1 /clear로 컨텍스트 리셋
관계없는 작업으로 넘어갈 때 /clear. 쓰레기 컨텍스트는 이후 모든 메시지에서 토큰을 먹는다.
6.2 /compact + 포커스 지시
/compact Focus on code samples and API usage
요약 시 무엇을 유지할지 명시하면 중요한 맥락을 잃지 않는다.
CLAUDE.md에 기본 지시 추가도 가능:
When you are using compact, please focus on test output and code changes
6.3 모델 선택 — Sonnet 기본, Opus는 복잡할 때
Sonnet이 코딩 작업의 대부분을 처리하며 Opus보다 5배 싸다. Opus는 아키텍처 결정·다단계 추론에만.
6.4 MCP 서버 오버헤드 줄이기
MCP 도구 정의는 기본적으로 deferred — 도구 이름만 컨텍스트에 들어가고 실제 호출 때 정의가 로드. /context로 뭐가 공간을 차지하는지 확인. /mcp로 쓰지 않는 서버 비활성화.
CLI 툴(gh, aws, gcloud, sentry-cli)을 우선. MCP보다 컨텍스트 효율이 높다.
6.5 코드 인텔리전스 플러그인
타입 있는 언어에서는 Code Intelligence 플러그인으로 심볼 네비게이션을 정밀하게 — grep + 여러 파일 읽기 대신 "go to definition" 한 번.
6.6 훅으로 전처리
Claude가 10,000줄 로그를 읽기 전에 훅이 ERROR만 grep해서 전달. 공식 예 — 테스트 출력을 실패만 남기는 PreToolUse 훅:
.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "~/.claude/hooks/filter-test-output.sh"}]
}
]
}
}
filter-test-output.sh:
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
echo "{}"
fi
수만 토큰이 수백 토큰으로 줄어든다. 훅 전반은 훅 완전 가이드 참고.
6.7 CLAUDE.md를 스킬로 이동
CLAUDE.md는 매 세션 로드 — 특정 워크플로(PR 리뷰·DB 마이그레이션 등)의 상세 지침은 스킬로 빼면 호출될 때만 로드. CLAUDE.md는 200줄 아래 유지.
6.8 확장 사고(Extended Thinking) 조절
확장 사고는 기본 on. thinking 토큰은 출력 토큰으로 과금된다 — 기본 예산은 수만 토큰/요청. 단순 작업에는 낭비.
/effort low
/config에서 thinking 끄기
MAX_THINKING_TOKENS=8000 claude
6.9 서브에이전트로 verbose 작업 격리
테스트 실행·문서 fetch·로그 파싱 같은 verbose 작업은 서브에이전트에 위임. 긴 출력은 서브에이전트 컨텍스트에 머물고 요약만 메인 대화로 리턴.
6.10 구체적 프롬프트
"이 코드베이스를 개선해줘"는 광범위 스캔을 유발. "auth.ts의 login 함수에 input 검증 추가해줘"는 최소 파일 읽기로 끝난다.
7. 숨은 비용 — 세 가지
7.1 백그라운드
Claude Code는 idle 상태에서도 일부 토큰을 쓴다:
- 대화 요약 백그라운드 잡 (claude --resume용)
- 일부 명령 상태 체크
공식: 세션당 $0.04 미만. 크지 않지만 여러 세션을 열어두면 누적.
7.2 에이전트 팀 (Agent Teams)
기능 플래그(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)로 활성화되는 멀티 인스턴스 기능. 각 teammate가 자체 컨텍스트 윈도우를 가지므로 plan 모드 기준 약 7× 토큰 소비.
완화: - teammate는 Sonnet 사용 (Opus 금지) - 팀 크기 작게 - spawn 프롬프트 집중 - 작업 완료 시 정리
7.3 모델별 Extended Thinking 기본값
Opus 4.7에서 복잡 작업은 thinking이 수십만 토큰까지 올라갈 수 있음. /usage로 확인하는 습관.
8. 팀 배포 — TPM/RPM 권장값
공식 문서의 조직 크기별 사용자당 권장값 (Anthropic API 플랜):
| 팀 크기 | TPM/사용자 | RPM/사용자 |
|---|---|---|
| 1-5명 | 200k-300k | 5-7 |
| 5-20명 | 100k-150k | 2.5-3.5 |
| 20-50명 | 50k-75k | 1.25-1.75 |
| 50-100명 | 25k-35k | 0.62-0.87 |
| 100-500명 | 15k-20k | 0.37-0.47 |
| 500+명 | 10k-15k | 0.25-0.35 |
팀 커질수록 동시 사용률이 떨어지는 현실을 반영. 조직 레벨 한도로 설정되므로 개별 사용자는 일시적 초과 가능.
9. PostToolUse 훅으로 비용 로깅
/usage는 현재 세션만 보여준다. 장기 추적이 필요하면 훅으로 파일에 누적.
.claude/hooks/log-cost.sh:
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
TS=$(date +%s)
echo "$TS | $SESSION_ID | $TOOL_NAME" >> "$CLAUDE_PROJECT_DIR/tasks/log/tool-usage.tsv"
exit 0
.claude/settings.local.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-cost.sh"}
]
}
]
}
}
도구 호출 횟수만 로깅한 예지만 PostToolBatch나 Stop 훅에서 /usage 출력을 파싱하면 더 정밀한 월말 통계를 만들 수 있다.
10. 반대 시나리오 — 이 최적화가 불필요한 경우
- 개인 Pro/Max 구독자 → 월 정액이므로 개별 토큰 비용 무의미. 한도(usage bar)에만 신경 쓰면 된다. Pro는 월 한도 도달 시 대기/업그레이드.
- 짧은 세션 위주 → 캐시 최소 토큰(Opus 4K, Sonnet 2K)에 미달하면 캐시가 아예 작동 안 함. 최적화해도 효과 없음.
- 프로토타입·탐색 단계 → 비용보다 속도가 중요.
/compact나 모델 스위칭을 과용하면 오히려 사고 흐름 끊김. - 엔터프라이즈 API 배포 → 개인 훅보다 LiteLLM 등 게이트웨이로 팀 전체 추적이 더 견고.
/costs문서가 언급한 접근.
11. 다음 단계
비용 구조가 보였다면:
- 훅(Hooks) 완전 가이드 — 비용 절감 훅(전처리, 비용 로깅)의 기반.
- CLAUDE.md 작성 가이드 — 200줄 아래 유지, 상세 지침은 스킬로.
- 슬래시 커맨드 총정리 —
/usage,/context,/compact,/clear,/model,/effort전체 레퍼런스.
참고
이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 5/15 편입니다. last verified: 2026-04-25 (Anthropic 공식 pricing 및 Claude Code Costs 문서 기준).
댓글
댓글 쓰기