Claude Code 사용량 및 비용 모니터링 방법 (2026)

Claude Code 사용량 및 비용 모니터링 방법 (2026)

Claude Code는 파일 편집, 명령 실행, 코드베이스 검색 및 복잡한 다단계 개발 작업을 수행할 수 있는 Anthropic의 에이전트형 코딩 CLI입니다. 강력한 기능을 제공하지만 그만큼 토큰 집약적이기도 합니다. 단일 복잡한 작업만으로도 여러 도구 호출과 추론 단계를 거치며 수만 개의 토큰을 소비할 수 있습니다.

특히 API 요금제를 사용하거나 팀을 관리하는 경우, 예산 관리를 위해 사용 패턴과 비용을 이해하는 것이 필수적입니다. 이 가이드는 내장 명령어부터 제3자 대시보드에 이르기까지 Claude Code 사용량을 모니터링하는 모든 방법을 다룹니다.

Claude Code 과금 체계 이해하기

Claude Code에는 두 가지 빌링 모델이 있습니다.

요금제	작동 방식	비용
Max 구독	Anthropic Max 플랜에 포함 ($100/월 또는 $200/월)	사용량 제한이 있는 고정 월간 요금
API 기반	Anthropic API key를 통한 토큰당 과금	사용량에 따른 변동 비용

Max 플랜을 사용 중이라면 구독에 포함된 넉넉한 Claude Code 사용 할당량을 제공받습니다. 본인의 API key를 사용하는 경우, 모든 토큰이 청구 금액에 합산됩니다.

Claude Code 토큰 비용 (API 요금제)

Claude Code는 주로 Claude 3.5 Sonnet과 Claude 3.5 Haiku를 사용합니다.

모델	입력 (100만 개당)	출력 (100만 개당)	Claude Code에서의 일반적인 용도
Claude 3.5 Sonnet	$3.00	$15.00	주요 추론, 코드 생성
Claude 3.5 Haiku	$0.80	$4.00	빠른 작업, 파일 읽기
Claude 3 Opus	$15.00	$75.00	복잡한 추론 (활성화된 경우)

일반적인 Claude Code 세션은 다음을 포함합니다:

• 파일 내용 읽기 (입력 토큰)
• 시스템 프롬프트 및 도구 정의 (매 턴마다 발생하는 입력 토큰)
• 모델 추론 및 응답 (출력 토큰)
• 도구 호출 결과 피드백 (입력 토큰)

이는 다단계 작업이 5만~20만 토큰을 쉽게 소비할 수 있음을 의미합니다.

방법 1: 내장 사용량 표시

Claude Code는 터미널에 사용량 정보를 직접 표시합니다. 각 응답 후 출력 하단에서 사용량 요약을 확인하세요.

> claude "refactor the auth module to use middleware pattern"

[Claude Code가 작업을 처리 중...]

───────────────────────────────────────
Cost: $0.24 | Tokens: 42,891 in / 3,204 out | Duration: 34s

`/cost` 명령어 사용하기

대화형 세션 중에 /cost 명령어를 사용하면 누적 사용량을 볼 수 있습니다.

claude

> /cost
Session usage:
  Input tokens:  128,432
  Output tokens:  12,891
  Cache read:     89,204
  Cache write:    31,002
  Total cost:     $0.72
  Duration:       4m 23s

여기에는 캐시된 토큰(더 저렴함)을 포함하여 현재 세션의 실행 합계가 표시됩니다.

세션 종료 시 사용량 확인

Claude Code를 종료하거나 세션이 완료되면 최종 요약이 표시됩니다.

claude -p "add error handling to all API routes"

# 완료 후:
# Total tokens: 89,234 in / 8,921 out
# Estimated cost: $0.42
# Session duration: 1m 47s

방법 2: Anthropic Console 대시보드

Anthropic Console은 API 기반 사용에 대한 상세한 사용 분석을 제공합니다.

1. console.anthropic.com으로 이동합니다.
2. 왼쪽 사이드바에서 Usage를 선택합니다.
3. 다음 기준으로 사용량을 확인합니다:
   • 기간 (일별, 주별, 월별)
   • 모델 (Sonnet, Haiku, Opus)
   • API key

대시보드에는 다음 지표가 표시됩니다:

지표	설명
Total tokens	소비된 총 입력 + 출력 토큰
Total cost	지불된 달러 금액
Requests	API 호출 횟수
Rate limit utilization	Rate limits에 얼마나 근접했는지 여부
Usage by model	모델별 상세 내역

사용량 알림 설정

Anthropic Console에서 지출 알림을 구성하세요.

1. Settings > Usage Limits로 이동합니다.
2. 월간 지출 한도(Hard cap)를 설정합니다.
3. 알림 임계값(예: 예산의 80% 도달 시 알림)을 설정합니다.
4. 알림을 받을 이메일 주소를 추가합니다.

구성 예시:
  Monthly limit: $100
  Alert at: $80 (80%)
  Notification emails: dev@company.com, billing@company.com

방법 3: 가시성 로그를 위한 환경 변수

상세한 토큰 로깅을 위해 ANTHROPIC_LOG 환경 변수를 설정하세요.

# 쉘 프로필(.bashrc, .zshrc)에 추가
export ANTHROPIC_LOG=debug

# 또는 단일 세션에 대해 디버그 출력으로 실행
ANTHROPIC_LOG=debug claude "explain this codebase"

이 설정은 요청당 정확한 토큰 수를 포함하여 각 API 호출에 대한 상세 정보를 출력합니다.

방법 4: 사용자 정의 사용량 추적 스크립트

상세한 추적이 필요한 팀의 경우, 모니터링 스크립트로 Claude Code를 래핑할 수 있습니다.

#!/bin/bash
# claude-tracked.sh - Claude Code 사용량을 기록하는 래퍼

LOG_FILE="$HOME/.claude-usage.log"
START_TIME=$(date +%s)

# Claude Code 실행 및 출력 캡처
claude "$@" 2>&1 | tee /tmp/claude-output.txt

END_TIME=$(date +%s)
DURATION=$((END_TIME - START_TIME))

# 출력에서 비용 추출 (필요에 따라 정규식 조정)
COST=$(grep -oP 'Cost: \$[\d.]+' /tmp/claude-output.txt | tail -1 | grep -oP '[\d.]+')
TOKENS=$(grep -oP 'Tokens: [\d,]+ in / [\d,]+ out' /tmp/claude-output.txt | tail -1)

# 사용량 기록
echo "$(date -Iseconds) | Duration: ${DURATION}s | Cost: \$${COST:-unknown} | ${TOKENS:-unknown} | Command: $*" >> "$LOG_FILE"

# 정리
rm -f /tmp/claude-output.txt

실행 가능하게 만들고 별칭(alias)을 설정합니다.

chmod +x ~/claude-tracked.sh
alias claude-t='~/claude-tracked.sh'

이후 사용 로그를 검토합니다.

# 최근 사용량 확인
tail -20 ~/.claude-usage.log

# 이번 달 비용 합산
grep "$(date +%Y-%m)" ~/.claude-usage.log | awk -F'Cost: \\$' '{sum+=$2} END {print "Monthly total: $"sum}'

방법 5: 프로그램 추적을 위한 Claude Code JSON 출력 활용

Claude Code는 사용량 데이터를 프로그래밍 방식으로 파싱하기 쉬운 JSON 출력 모드를 지원합니다.

# 사용량 정보가 포함된 구조화된 출력 얻기
claude -p --output-format json "list all TODO comments in this project" 2>/dev/null | jq '.usage'

Python으로 더 정교한 트래커를 구축할 수 있습니다:

import subprocess
import json
import sqlite3
from datetime import datetime

def run_claude_tracked(prompt, project_dir="."):
    """Claude Code를 실행하고 SQLite 데이터베이스에 사용량을 추적합니다."""

    result = subprocess.run(
        ["claude", "-p", "--output-format", "json", prompt],
        capture_output=True,
        text=True,
        cwd=project_dir
    )

    try:
        output = json.loads(result.stdout)
        usage = output.get("usage", {})

        # 데이터베이스에 저장
        conn = sqlite3.connect("claude_usage.db")
        conn.execute("""
            CREATE TABLE IF NOT EXISTS usage (
                id INTEGER PRIMARY KEY,
                timestamp TEXT,
                prompt TEXT,
                input_tokens INTEGER,
                output_tokens INTEGER,
                cost_usd REAL,
                model TEXT,
                project TEXT
            )
        """)

        conn.execute("""
            INSERT INTO usage (timestamp, prompt, input_tokens, output_tokens, cost_usd, model, project)
            VALUES (?, ?, ?, ?, ?, ?, ?)
        """, (
            datetime.now().isoformat(),
            prompt[:200],
            usage.get("input_tokens", 0),
            usage.get("output_tokens", 0),
            usage.get("cost_usd", 0),
            usage.get("model", "unknown"),
            project_dir
        ))

        conn.commit()
        conn.close()

        return output.get("result", "")
    except json.JSONDecodeError:
        return result.stdout

# 사용 예시
response = run_claude_tracked(
    "add input validation to the user registration endpoint",
    "/path/to/project"
)

사용량 데이터베이스 쿼리 예시:

-- 일일 비용 요약
SELECT date(timestamp) as day, SUM(cost_usd) as total_cost,
       SUM(input_tokens) as total_input, SUM(output_tokens) as total_output
FROM usage
GROUP BY date(timestamp)
ORDER BY day DESC;

-- 프로젝트별 비용
SELECT project, SUM(cost_usd) as total_cost, COUNT(*) as requests
FROM usage
GROUP BY project
ORDER BY total_cost DESC;

-- 가장 비싼 단일 요청
SELECT timestamp, prompt, cost_usd, input_tokens, output_tokens
FROM usage
ORDER BY cost_usd DESC
LIMIT 10;

방법 6: Max 플랜 사용량 모니터링

Anthropic Max 플랜을 사용하는 경우, Claude Code 사용량은 구독 허용량의 일부입니다. 모니터링 방법은 다음과 같습니다.

1. claude.ai/settings를 방문합니다.
2. 구독 섹션에서 사용량을 확인합니다.
3. Claude Code 사용량 미터를 확인합니다.

Max 플랜 한도는 매달 초기화됩니다. 다음 사항을 유의하세요.

Max 플랜	월간 가격	Claude Code 허용량
Max (standard)	$100/월	높은 사용량 한도
Max (scaled)	$200/월	매우 높은 사용량 한도

한도에 도달하면 Claude Code가 더 작은 모델로 스로틀링(throttling)되거나 응답 길이가 제한될 수 있습니다. 중요한 개발 기간에 중단되지 않도록 월 중순에 사용량을 확인하십시오.

비용 최적화 팁

전략	절감 효과	방법
일회성 작업에 -p (print mode) 사용	10-30%	대화형 세션 오버헤드 로딩 방지
프롬프트 구체화	20-40%	불필요한 대화 및 재시도 감소
--max-turns 플래그 사용	최대 50%	에이전트 루프의 폭주 제한
특정 파일로 범위 제한	15-25%	Claude가 검색하게 두는 대신 @file 참조 사용
단순 작업에 Haiku 사용	70-80%	claude --model haiku "simple question"
캐시 친화적인 대화	20-30%	매번 새로 시작하는 대신 세션 재개

# 비용 폭주 방지를 위한 턴 제한
claude --max-turns 5 "add tests for the payment module"

# 빠른 질문을 위해 Haiku 사용
claude --model haiku "what does the handleAuth function do?"

# 캐시된 컨텍스트를 활용하기 위해 이전 세션 재개
claude --resume

팀 사용량 모니터링

팀의 경우 개발자별 API key를 설정하고 개별적으로 모니터링하세요.

# Anthropic Console에서 개발자별 키 생성
# 각 개발자의 환경에 설정:
export ANTHROPIC_API_KEY=sk-ant-developer-specific-key

# Anthropic Console > API Keys > Usage에서 키별 사용량 확인

키별 지출 한도 설정을 고려해 보세요.

개발자	월간 한도	알림 임계값
시니어 엔지니어	$200	$160
주니어 엔지니어	$100	$80
QA/테스트	$50	$40
CI/CD 자동화	$300	$240

마치며

Claude Code 사용량 모니터링은 어디를 확인해야 할지만 알면 간단합니다. 내장된 /cost 명령어와 세션 요약으로 가벼운 모니터링이 가능하며, 본격적인 추적을 위해서는 Anthropic Console 대시보드와 지출 알림, 맞춤형 로깅 솔루션을 결합하면 됩니다. 핵심은 비용이 문제가 된 후가 아니라, 문제가 되기 전에 모니터링을 설정하는 것입니다.

AI 기반 애플리케이션을 구축 중이고 이미지, 비디오, 아바타 등 다양한 AI 서비스 전반의 비용을 모니터링하고 싶다면, Hypereal AI를 무료로 사용해 보세요 (35 크레딧 제공, 신용카드 불필요). 당사의 대시보드는 요청당 투명한 비용 추적을 제공하여 지출 현황을 항상 명확하게 파악할 수 있게 해줍니다.