클로드 코드 토큰 사용량 확인: 명령어부터 콘솔까지

Claude Code에서 토큰 사용량은 세션이 끝날 때 입력·출력 토큰 수와 예상 비용이 자동으로 표시됩니다. 세션 도중에도 슬래시 명령어로 현재 누적 사용량을 즉시 확인할 수 있습니다. 더 상세한 기간별·모델별 내역은 Anthropic 콘솔(console.anthropic.com)의 Usage 탭에서 조회할 수 있습니다. 이 글에서는 CLI 명령어부터 콘솔, API 레벨 추출까지 단계별로 정리합니다.

Claude Code에서 토큰 사용량을 즉시 확인하는 방법은?

Claude Code는 터미널에서 직접 실행하는 AI 코딩 도구입니다. 사용량 확인 경로는 크게 세 가지로 나뉩니다. 세션 종료 시 자동 출력되는 요약을 읽는 방법, 세션 진행 중 슬래시 명령어로 현재 누적량을 조회하는 방법, 그리고 Anthropic 콘솔과 API로 기간별 상세 내역을 분석하는 방법입니다.

세션 진행 중에 빠르게 확인하려면 /cost 명령어를 사용합니다. 입력하면 현재까지 누적된 입력 토큰 수, 출력 토큰 수, 예상 비용이 즉시 표시됩니다. 작업 중간에 비용이 예상보다 빠르게 증가하고 있다는 판단이 들 때 가장 먼저 확인할 수 있는 방법입니다.

claude --verbose 옵션으로 실행하면 각 API 요청마다 토큰 소비량이 실시간으로 출력됩니다. 어떤 작업이 컨텍스트를 많이 차지하는지 파악할 때 유용합니다. 대용량 파일을 분석하거나 긴 대화를 유지하는 상황에서 소비 패턴을 직접 관찰할 수 있습니다.

세션 종료 시 자동 표시되는 사용량 요약 데이터 읽는 법

Claude Code 세션이 종료되면 터미널에 사용량 요약이 자동으로 출력됩니다. 이 요약에는 네 가지 토큰 분류가 포함됩니다. 각 항목의 의미를 이해하면 비용 구조를 정확히 파악할 수 있습니다.

• 입력 토큰(input tokens): 캐싱 없이 모델에 전달된 텍스트입니다. 대화 이력, 시스템 프롬프트, 첨부 파일 내용이 모두 포함됩니다. 모델의 기본 입력 단가가 적용됩니다.
• 출력 토큰(output tokens): 모델이 생성한 응답입니다. 입력 대비 단가가 높으므로 긴 응답이 반복될수록 비용에 직접 영향을 줍니다.
• 캐시 작성 토큰(cache write tokens): 프롬프트 캐싱을 위해 처음 저장된 토큰입니다. 표준 입력 단가보다 약 25% 높은 비용이 발생하지만, 이후 동일 컨텍스트를 재사용할 때 비용이 크게 절감됩니다.
• 캐시 읽기 토큰(cache read tokens): 이미 저장된 캐시에서 읽어온 토큰입니다. 표준 입력 단가의 약 10% 수준으로 처리됩니다. 이 수치가 높을수록 캐싱 효율이 좋다는 신호입니다.

코드 리뷰나 대규모 파일 분석에서 캐시 읽기 토큰 비율이 높게 나온다면 Claude Code의 프롬프트 캐싱이 효과적으로 작동하고 있는 것입니다. 반대로 캐시 읽기 비율이 낮고 입력 토큰만 계속 높게 유지된다면 세션을 너무 오래 지속하거나 컨텍스트 구성 방식을 점검할 필요가 있습니다.

Anthropic 콘솔에서 날짜별·모델별 상세 내역 조회하는 법

단일 세션을 넘어 날짜별, 모델별 사용 내역을 확인하려면 Anthropic 콘솔을 이용합니다. console.anthropic.com에 로그인한 후 왼쪽 메뉴의 Usage 탭으로 이동합니다.

Usage 탭에서 확인할 수 있는 항목은 다음과 같습니다.

• 날짜 범위별 토큰 소비 추이 차트
• 모델별 사용량 분류 (claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5 등)
• API 키별 사용 내역 (여러 키를 운용하는 경우 유용)
• 캐시 토큰과 일반 토큰의 구분 내역

날짜별 차트에서 특정 날짜에 사용량이 급증한 경우 해당 날짜 항목을 클릭하면 더 세분화된 내역을 확인할 수 있습니다. 온보딩 테스트, 대규모 리팩토링 작업, 또는 자동화 파이프라인이 예상보다 많이 실행됐을 때 원인 날짜를 빠르게 특정할 수 있습니다.

팀 단위로 Claude Code를 도입한 경우, 각 팀원이 별도의 API 키를 사용한다면 키별 사용량을 비교해 비용 배분 근거를 확보할 수 있습니다. 사내 가이드에 API 키 발급 정책과 키별 한도 설정을 명시해 두면 이후 비용 관련 혼선을 줄일 수 있습니다.

토큰 소비가 갑자기 늘었을 때 원인을 진단하는 법

토큰 소비량이 전날 대비 눈에 띄게 늘었다면 다음 순서로 점검합니다.

1. 작업 유형 확인: 대용량 파일 분석, 전체 코드베이스 검색, 긴 문서 처리 등 컨텍스트를 많이 차지하는 작업이 있었는지 먼저 확인합니다.
2. 세션 길이 점검: Claude Code는 대화가 길어질수록 이전 메시지가 컨텍스트에 누적됩니다. 세션을 새로 시작하지 않고 오래 유지하면 동일한 작업이라도 입력 토큰이 계속 증가합니다.
3. 자동화 스크립트 점검: CI/CD 파이프라인이나 반복 실행 스크립트가 Claude Code를 호출하는 경우, 예상보다 많이 트리거됐는지 로그를 확인합니다.
4. 캐시 히트율 확인: 세션 요약에서 캐시 읽기 비율이 낮아졌다면 컨텍스트 변경으로 인해 캐시가 무효화된 상황일 수 있습니다.

--verbose 모드로 실행하면 각 요청의 토큰 소비량이 개별 출력됩니다. 사용량이 갑자기 늘어난 날의 작업 패턴을 재현해 어떤 단계에서 토큰이 집중적으로 소비됐는지 파악할 수 있습니다.

Claude Opus 4.8 모델은 최대 1M 토큰의 컨텍스트 윈도우를 지원합니다. 긴 코드베이스를 통째로 컨텍스트에 올리는 방식은 강력하지만 동시에 입력 토큰이 매우 커집니다. 작업 목적에 맞게 관련 파일만 선택적으로 포함하면 동일한 결과를 얻으면서 비용을 크게 줄일 수 있습니다.

사용량 한도·알림 설정으로 예산 초과를 방지하는 법

Anthropic 콘솔의 Billing 섹션에서 월별 사용 한도(spending limit)를 설정할 수 있습니다. 설정한 한도에 도달하면 API 요청이 거부되므로 예상치 못한 과금을 원천적으로 방지합니다.

한도 외에 알림(notification) 임계값도 설정할 수 있습니다. 특정 비용 수준에 도달했을 때 이메일 알림을 받도록 설정하면 한도 도달 전에 미리 인지하고 사용 방식을 조정할 수 있습니다.

팀 환경에서는 API 키 단위로 한도를 별도 적용하는 방식이 실용적입니다. 개발·스테이징·프로덕션 환경에 각각 별도 키를 발급하고 환경별로 한도를 다르게 설정하면 환경 간 비용 혼용을 방지할 수 있습니다. 스테이징 환경에서 자동화 테스트가 과도하게 실행되더라도 프로덕션 예산에 영향을 주지 않습니다.

작업 단위로 세션을 새로 시작하는 습관도 비용 관리에 효과적입니다. 컨텍스트가 누적된 긴 세션보다 목적에 맞게 새로 시작한 세션이 동일 결과를 더 적은 토큰으로 달성하는 경우가 많습니다. 팀에 Claude Code를 처음 도입할 때 이 원칙을 온보딩 자료에 포함하면 초반 비용 스파이크를 예방할 수 있습니다.

API로 사용량 데이터를 추출해 자동화·팀 공유하는 법

Anthropic API는 각 요청의 응답에 토큰 사용량을 포함합니다. usage 객체에는 네 가지 필드가 있습니다.

• input_tokens: 캐싱 없이 처리된 입력 토큰 수
• output_tokens: 모델이 생성한 출력 토큰 수
• cache_creation_input_tokens: 프롬프트 캐시에 새로 작성된 토큰 수
• cache_read_input_tokens: 기존 캐시에서 읽어온 토큰 수

Python으로 각 요청의 토큰 사용량을 추출하는 예시입니다.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "코드 리뷰를 해줘."}]
)

usage = response.usage
print(f"입력 토큰: {usage.input_tokens}")
print(f"출력 토큰: {usage.output_tokens}")
print(f"캐시 작성: {usage.cache_creation_input_tokens}")
print(f"캐시 읽기: {usage.cache_read_input_tokens}")

이 데이터를 데이터베이스나 스프레드시트에 누적하면 팀 단위 사용량 리포트를 자동화할 수 있습니다. API 키별 일별 토큰 소비량을 집계해 슬랙 채널에 자동 공유하거나, 월별 비용 예측 모델의 입력 데이터로 활용하는 방식이 실무에서 자주 사용됩니다.

스트리밍 응답에서도 스트림 종료 시점에 최종 사용량이 제공됩니다. SDK의 .get_final_message() 메서드를 사용하면 스트리밍 완료 후 usage 객체를 동일한 방식으로 접근할 수 있습니다. 응답이 길거나 에이전트 루프를 실행하는 경우 스트리밍과 함께 사용량을 추적하면 비용이 예상 범위를 벗어나기 전에 조기 차단하는 로직을 구현할 수 있습니다.

Anthropic 콘솔은 Usage 탭 외에도 API를 통한 기간별 집계 데이터 조회를 지원합니다. 이를 활용하면 콘솔 UI에 접근하지 않고도 정기 보고서를 완전히 자동화할 수 있습니다. 여러 프로젝트를 운영하는 팀이라면 프로젝트별로 별도 API 키를 발급하고 키별 데이터를 자동 집계하는 방식이 사내 비용 배분을 투명하게 관리하는 가장 실용적인 접근입니다.

토큰 사용량 파악이 익숙해지면 다음 단계는 Claude 플랫폼 활용 역량 자체를 높이는 것입니다. Claude 관련 공식 자격증인 CCA-F 시험은 프롬프트 엔지니어링, API 활용, MCP 서버 구성 등 실무 역량을 체계적으로 검증합니다. Plinth Prep(plinthprep.com)은 Anthropic과 무관한 독립 학습 사이트로, CCA-F 시험 범위를 주제별로 정리한 연습 문제와 구조화된 학습 경로를 제공합니다. 비용 관리에서 나아가 Claude 플랫폼 전반의 역량을 검증받고 싶다면 체계적인 학습 자료가 독학보다 효율적일 수 있습니다.