Claude Code 비용 관리

Claude Code 비용 관리

Claude Code 사용량을 추적하고 비용을 관리하는 방법을 다루는 페이지입니다. Anthropic Console에서 콘솔 사용량, 팀 관리 페이지에서 팀 Seat 사용량을 확인할 수 있습니다. 비용 파악·통제를 위해 사용량 확인, 토큰 모니터링, 비용 제한 설정이 모두 필요합니다.

출처: 공식문서

본문

사용량 확인

콘솔 사용량

Anthropic Console의 Usage 탭에서 코드 에이전트 사용량을 봅니다. Date range(날짜 범위) 필터로 시간대를 고르고, Model 필터로 특정 모델을 선택하세요. 사용량은 M tokens(100만 토큰) 기준으로 표시됩니다 — 비용 계산기는 토큰을 달러로 변환해 줍니다. 각 대시보드 아래 코드 에이전트 API 요청 샘플뿐 아니라 부가 요청 사용량을 포함한 월별 집계 요약이 있습니다. Console의 사용량 데이터는 시점에 따라 지연될 수 있습니다. 요금·결제 관련 질문은 지원으로.

조직 소유자 계정은 Console의 Usage 설정에서 팀별 필터링으로 각 팀이 쓴 크레딧을 볼 수 있습니다.

팀 Seat 사용량

팀 플랜을 쓰면 팀 관리 설정의 사용량 정보에서 활성 Seat 수와 월별 Seat당 사용량을 확인할 수 있습니다. 관리자는 청구 정보에서 활성 Seat 수를 늘리거나 줄일 수 있습니다.

  • 각 개발자는 콘솔 사용량을 직접 확인할 수 있습니다.
  • 사용량 요약은 각 개발자의 월간 사용량 합산을 보여줍니다.
  • 청구 가능한 사용량은 모델 제공자가 계산한 토큰 사용량과 일치해야 합니다. 그렇지 않으면 지원팀에 문의하세요.
  • 사용량 보기가 활성화되려면 timestamps 필드가 있는 추가 비용(extra costs) 이벤트(세션 표기, agent 텍스트 콘텐츠 알림 추가 비용)가 필요할 수 있습니다.

관리 설정에서 비용 필드를 활성화해 조직 차원 사용량을 관리자가 볼 수 있게 할 수도 있습니다.

토큰 사용 모니터링

각 대화의 토큰 사용량도 확인할 수 있습니다. model 설정에서 max_tokens_generations 같은 필드를 조정하는 것과 별개로, 세션이 끝나면 통계가 요약됩니다.

입력·출력 토큰

GitHub Actions 나이트리 빌드 설정 없이, 세션 끝에 나타나는 사용량 요약에서 입력(tokens in)·출력(tokens out) 토큰 수를 확인합니다. 세션의 총 토큰 사용량은 입력·출력·캐시·프롬프트 구성 요소의 합계입니다.

비용 제한 (Cost Limits)

관리 설정에서 Cost Limits(비용 한도)를 관리 설정으로 구성하면, 조직·팀·유저 단위로 특정 기간(주간·월간) 최대 비용 한도를 지정할 수 있습니다. 비용 한도에 도달하면 해당 스코프의 사용이 일시 중지되며, 개발자는 데스크톱·CLI에서 진행 중 상태를 볼 수 있습니다. 비용 한도 구성은 청구·관리 담당자에게 요청할 수 있습니다.

비용 한도 예시 (관리 설정)

정책에 명시적으로 지정한 스코프(예: 특정 조직)만 해당 스코프에 대해 설정할 수 있다는 점을 유의하세요. 예를 들어 조직 전체가 아닌 유저 스코프로 구성할 수 있습니다.

{
  "limits": {
    "cost": {
      "monthly": 200,
      "maxMonthly": 100,
      "maxUtilization": 0.75
    }
  }
}

monthly는 월간 비용 한도(달러)입니다. maxMonthly는 유저가 요청할 수 있는 월간 한도의 상한입니다. maxUtilization은 한도에 도달하기 전 막을 수 있는 활용 비율(0~1)입니다.

  • monthly: 200 = 해당 스코프의 월간 비용 한도가 $200
  • maxMonthly: 100 = 유저가 월간 한도를 최대 $100까지 요청 가능
  • maxUtilization: 0.75 = 한도에 도달하기 전까지 비용의 75%에서 사용 중단

비용 한도가 도달하면 스코프가 일시 중지되고, 유저·관리자에게 알림이 갑니다.

비용을 아끼는 모범 사례

  • 프롬프트 캐싱: 반복되는 큰 컨텍스트(시스템 프롬프트, 도구 정의, 자주 읽는 파일)는 프롬프트 캐싱으로 입력 토큰 비용을 크게 줄입니다.
  • 최대 토큰 제한: model 설정에서 출력 토큰 상한을 필요한 만큼만 설정하세요.
  • 깨끗한 세션: 오래된 대화의 불필요한 컨텍스트는 토큰 비용을 늘립니다. /clear로 세션을 리셋하고 /compact로 컨텍스트를 요약·압축하세요.
  • 작업 분리: 너무 큰 단일 세션 대신 작은 작업 단위로 나누면 컨텍스트 재사용을 줄입니다.

더 알아보기