본문으로 건너뛰기

클로드 코드 토큰 사용량 확인, 상태 요약 비용과 구독 한도 읽는 법

클로드 코드 토큰 사용량은 대화창에 /usage를 입력하면 확인돼요. 구독자는 플랜 한도를, API 사용자는 세션의 추정 비용을 보세요. 상태 요약에 비용이 많이 든다는 글을 보셨다면, 백그라운드 에이전트를 얼마나 쓰는지도 함께 살펴보면 됩니다.

따로 일을 맡긴 에이전트의 작업을 짧게 보여주는 것이 클로드 코드(Claude Code)의 상태 요약이에요. 이 표시를 만드는 데도 모델을 호출합니다. 공개 분석에서 비용 비중이 16.4%로 나왔는데, 개발팀 설명은 약 2%였어요. 두 숫자의 차이부터 내 사용량을 읽는 방법까지 짚어볼게요.

/usage에서 한도와
비용을 나눠 봐요

구독자는 플랜 사용량 표시부터 보면 돼요. 프로(Pro), 맥스(Max) 요금제에서는 구독에 포함된 사용량을 얼마나 썼는지 보여줍니다. 세션의 달러 추정치를 보고 그만큼 추가 결제됐다고 읽으면 안 맞아요.

API는 프로그램에서 모델을 호출하고 사용량에 따라 비용을 내는 방식입니다. API 사용자라면 /usage의 Session에서 현재 세션의 토큰과 추정 비용을 확인할 수 있어요. 실제 청구액은 클로드 콘솔의 사용량과 대조하면 됩니다.

클로드 코드 /usage 실제 화면의 Session과 구독 한도 위치, 비용과 한도 사용률 및 초기화 시각은 가림

출처: 클로드 코드 /usage 실제 화면, 2026-10-30 캡처. 비용과 한도 사용률, 초기화 시각은 가렸어요.

공식 비용 문서는 세션 비용을 토큰 수와 요율로 계산한 추정치라고 설명합니다. 조직에서 별도 요율을 설정했다면 그 가격을 반영해요. 상태 요약의 추정 비용이 줄어도 고정 월 구독료가 같은 비율로 줄어드는 것은 아닙니다.

상태 요약 비용은
에이전트 작업량에 따라 달라요

플레머릭스 AI(Flamerix AI)는 한 주의 요청 기록에서 상태 요약이 전체 추정 비용 중 16.4%를 차지했다고 공개했습니다. 전체 요청 중 비중은 19.7%였어요. 비용을 나눈 값과 요청 횟수를 나눈 값이라 서로 다릅니다.

반면 클로드 코드 개발팀 작성자의 답변은 사용량 데이터를 보내는 사용자 전체에서 API 정가 기준 약 2%, 터미널에서는 약 6%였다고 설명합니다. 작업 중인 백그라운드 에이전트에 요약 호출이 생기며, 쉬고 있는 에이전트에는 생기지 않는다고 했어요.

내 비용에 가까운 쪽을 가늠하려면 실행 방식을 보세요.

  • 긴 작업을 여러 에이전트에 맡긴다면: 백그라운드 작업 중심인 16.4% 사례와 조건이 더 비슷해요. 긴 대화 기록을 반복해서 보내는지, 캐시를 놓치는 요청이 있는지 확인할 대상입니다.
  • 주 대화 위주로 짧게 쓴다면: 16.4%를 내 절감률로 잡을 근거가 약합니다. 약 2%도 전체 사용자 평균이므로 내 계정의 비율로 확정할 수는 없어요.
  • 터미널에서 비교한다면: 개발팀이 제시한 터미널 수치인 약 6%도 참고할 만합니다. 전체 평균 약 2%보다 실행 환경이 가까운 비교 대상입니다.

숫자 하나를 고르는 것보다 내 기록에서 같은 비율을 구하는 편이 정확해요. 계산할 때는 같은 기간의 상태 요약 추정 비용을 전체 요청의 추정 비용으로 나눕니다. 이때 요청 기록이 빠지면 비율도 달라집니다.

캐시 읽기와 쓰기를
나누면 토큰 비용이 보여요

토큰은 모델이 글을 처리할 때 나누는 단위입니다. 입력은 모델에 보내는 글, 출력은 모델이 만들어낸 글이에요. 캐시는 앞서 보낸 내용을 저장했다가 다시 쓰는 기능입니다.

공식 모니터링 문서의 type은 토큰을 처리한 방식을 뜻해요. 아래 네 항목으로 나눕니다.

  • input: 캐시에서 읽거나 캐시에 쓰는 부분을 뺀 일반 입력입니다.
  • output: 모델이 새로 만든 답변입니다.
  • cacheRead: 저장해둔 내용을 다시 읽은 토큰입니다. 캐시 읽기로 보면 돼요.
  • cacheCreation: 나중에 다시 쓰도록 저장한 토큰입니다. 캐시 쓰기에 해당합니다.
입력과 출력 옆의 캐시를 읽기와 쓰기로 나눈 분류 도식

도식 출처: 지피터스 제작, 2026-10-30.

같은 대화 기록을 다시 보냈어도 일반 입력과 캐시 읽기는 비용이 달라요. 캐시 쓰기에도 비용이 붙습니다. 전체 입력량에 일반 입력 요금만 곱하면, 캐시를 사용한 요청의 비용을 잘못 계산하게 됩니다.

공식 문서의 type은 일반 입력과 출력, 캐시 읽기 cacheRead와 캐시 쓰기 cacheCreation을 따로 집계해요

출처: 클로드 코드 공식 모니터링 문서, 2026-10-30 캡처.

/usage에 Prompt cache (main)이 보이면 주 대화에서 캐시를 얼마나 활용했는지 나타냅니다. 공식 문서상 이 표시는 버전 2.1.251 이상에서 지원하며, 따로 맡긴 에이전트의 통계는 포함하지 않아요. 이 숫자만으로 상태 요약의 캐시 사용률을 알기는 어렵습니다.

요청 출처를 나누면
상태 요약 비용을 찾아요

query_source는 어떤 기능이 요청을 보냈는지 적은 항목입니다. 토큰 합계에서는 주 대화인 main, 따로 일을 맡긴 에이전트인 subagent, 그 밖의 보조 기능인 auxiliary로 나눕니다. auxiliary를 전부 상태 요약 비용으로 더하면 범위가 너무 넓어요.

공식 문서의 query_source는 주 대화 main, 별도 에이전트 subagent, 보조 기능 auxiliary로 요청 출처를 나눠요

출처: 클로드 코드 공식 모니터링 문서, 2026-10-30 캡처.

상태 요약만 찾으려면 개별 요청 기록이 필요합니다. 클로드 코드는 오픈텔레메트리(OpenTelemetry)라는 계측 표준으로 사용량을 내보내요. 설정된 수집 도구에서 claude_code.api_request라는 요청 이벤트를 찾아보면 됩니다.

플레머릭스 AI는 이 이벤트의 query_source가 agent_summary인 요청을 모았다고 설명합니다. 요청마다 붙은 cost_usd는 달러 추정 비용이에요. 해당 요청들의 비용 합계를 전체 요청 비용 합계와 비교한 것이 앞서 나온 비율입니다.

이미 사용량을 수집하는 팀이라면 담당자에게 같은 기간의 전체 요청과 agent_summary 요청의 비용을 나눠달라고 하면 돼요. 수집 설정이 없다면 /usage만으로 이 비율을 계산하기는 어렵습니다. 토큰 합계의 auxiliary와 개별 요청의 agent_summary를 구분해야 비용을 덜 헷갈려요.

버전과 캐시 누락을
확인한 뒤 절감 효과를 봐요

개발팀 작성자는 버전 2.1.311 이상에 캐시 개선을 넣었다고 설명했습니다. 상태 요약이 캐시를 쓰지 못하는 비싼 경우를 고친 내용입니다. 같은 작업이어도 수정 전후의 비용이 달라질 수 있어요.

버전은 터미널에서 claude --version으로 확인하면 됩니다. 개선 전 기록과 개선 뒤 기록을 섞어서 비교하면 업데이트 효과를 다른 설정의 효과로 오해할 수 있어요. 버전을 맞춘 뒤 캐시 읽기와 쓰기, 추정 비용을 함께 대조하면 됩니다.

원문에 소개된 차단 스크립트는 자바스크립트 실행 도구인 번(Bun)의 사전 로딩 기능으로 요약 타이머를 멈춥니다. 작성자는 업데이트로 다시 호출이 생길 수 있고, 에이전트 상태 표시도 갱신되지 않는다고 설명해요. 이 글에서는 실행을 검증하지 않아 설치 명령은 싣지 않았습니다.

지금은 /usage에서 내 구독 한도나 세션 비용을 확인하세요. 상태 요약 비용까지 비교하고 싶다면, 다음 작업을 시작하기 전에 개별 요청 수집 여부부터 담당자에게 확인해보세요.

글쓴이 강지인. AI 커뮤니티 지피터스(GPTers)에서 1인 마케팅을 맡고 있고, 매일 AX와 AI 뉴스, 에이전트에 관한 글을 씁니다.


확인일 2026-10-30
사용량과 캐시 통계: 클로드 코드 공식 비용 문서
토큰 종류와 요청 출처: 클로드 코드 공식 모니터링 문서
상태 요약 측정: 플레머릭스 AI 분석

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

함께 읽어보세요

AI 소식 전체 보기