Claude Code 비용 추적 도구 비교 및 분석

Claude Code 지출 추적기가 실제로 읽는 데이터

모든 Claude Code 지출 추적기는 세 가지 데이터 소스 중 하나를 읽으며, 어떤 소스를 사용하느냐에 따라 답변할 수 있는 질문이 결정됩니다. 로그 파서는 사용자의 디스크에 있는 세션 기록 파일을 읽습니다. 대시보드는 사용자의 계정이나 조직에 대해 Anthropic이 보관하는 사용 기록을 읽습니다. 메트릭 백엔드는 Claude Code를 켰을 때 발생하는 OpenTelemetry(OTel) 스트림을 읽습니다. 이 세 가지 방식은 모두 정확할 수 있지만, 서로 다른 항목을 집계하기 때문에 결과가 일치하지 않을 수 있습니다.

이 가이드는 토큰에 대해 다시 설명하지 않습니다. Claude Code의 토큰 사용량 계산 방식에서 입력, 출력, 캐시 쓰기 및 캐시 읽기에 대해 다루고 있으며, 해당 내용을 이해하지 못하면 대시보드의 의미를 파악하기 어렵습니다. 여기서 다루는 질문은 더 구체적입니다. 각 도구 형태별로 무엇을 볼 수 있고, 무엇을 절대 볼 수 없는지에 관한 것입니다.

하루에 세 개의 Claude Code 비용 추적기가 등장한 이유

세 개의 서로 다른 Claude Code 비용 추적기가 같은 날 게시되었습니다. 이들은 동일한 도구의 세 가지 버전이 아니며, 바로 그 점이 유용합니다. 하나는 로컬 세션 파일을 파싱하는 방식이었고, 다른 하나는 계정 사용량 화면을 래핑하는 방식이었으며, 마지막 하나는 직접 실행하는 호스팅형 추적 백엔드였습니다.

이 도구들이 동시에 등장한 이유는 에이전트 세션의 비용을 파악하기 어려워졌기 때문입니다. 일반적인 채팅 비용은 화면에 보이는 그대로입니다. 반면 에이전트는 20개의 파일을 읽고, 테스트 스위트를 실행하며, 매 턴마다 전체 대화 내용을 다시 전송하므로 사용자가 직접 입력하지 않은 컨텍스트에 의해 비용이 발생합니다. 구독 모델에서는 정확한 금액이 표시되지 않으며, 어떤 날은 더 빨리 소진되는 사용량 막대만 보일 뿐입니다. 이 세 가지 형태의 도구는 각각 그 정보의 공백을 서로 다른 방식으로 채워줍니다.

형태 1: 로컬 로그 파서로 오늘의 비용 확인하기

Claude Code는 각 대화를 ~/.claude/projects/<project>/<session-id>.jsonl에 JSON Lines(JSONL) 형식으로 저장합니다. 여기서 <project>는 영숫자가 아닌 문자를 -으로 치환한 작업 디렉터리 경로입니다. 해당 파일의 모든 어시스턴트 턴에는 요청에 대한 토큰 수가 포함되어 있습니다. 로그 파서는 이 토큰 수를 합산하여 비용을 산출합니다.

ccusage은 가장 많이 사용되는 도구입니다. 별도의 설치가 필요 없습니다:

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily는 날짜별 합계를 구합니다. --breakdown은 각 행을 모델별로 분리하며, 이를 통해 특정 오후에 사용한 Opus 모델이 일주일 비용의 대부분을 차지한다는 사실을 알 수 있습니다. blocks는 구독이 갱신되는 5시간 단위로 그룹화합니다. session는 대화별 합계를, --instances은 프로젝트별로 그룹화하여 어떤 저장소가 비용을 많이 발생시키는지 파악하게 해줍니다. --since과 --until을 추가하여 범위를 제한하고, npx ccusage@latest daily --help를 실행하여 사용하는 버전의 날짜 형식을 지정하십시오. 2026년 8월 기준으로 이 도구는 Codex 및 OpenCode를 포함한 다른 에이전트 CLI의 로그도 읽을 수 있으며, 이는 여러 도구를 비교할 때 유용합니다.

가격은 모델 가격표를 기준으로 하며, 이 도구는 세 가지 비용 모드를 지원합니다. --mode auto은 Claude Code가 파일에 기록한 costUSD 값을 사용하며, 값이 없을 경우 토큰 수로 계산합니다. --mode calculate는 항상 토큰 수로 계산하며 기록된 비용은 무시합니다. --mode display은 기록된 비용만 표시하며, 비용 정보가 없는 행에는 $0.00를 출력합니다. 합계가 잘못된 것 같다면 calculate 모드와 display 모드에서 각각 보고서를 실행해 보십시오. 두 결과 사이에 큰 차이가 있다면 대부분의 항목에 기록된 비용이 없다는 뜻이며, 따라서 읽고 있는 모든 수치는 추정치입니다.

동일한 데이터를 프롬프트에 활용할 수도 있습니다. ccusage statusline은 Claude Code 상태 표시줄을 위한 간결한 한 줄을 출력하며, 다른 상태 표시줄 명령과 마찬가지로 ~/.claude/settings.json에 연결됩니다. 설정 블록과 수신 필드에 대한 내용은 Claude Code 상태 표시줄 만들기를 참조하십시오.

로그 파서가 확인할 수 없는 것은 이 머신에서 발생하지 않은 모든 활동입니다. 두 번째 노트북, claude.ai에서의 세션, 팀원의 작업 등은 해당 디스크에 기록됩니다. 또한 cleanupPeriodDays 설정에 따라 기본적으로 30일이 지나면 대화 기록이 삭제되므로, 아카이브하지 않은 지난 분기의 데이터는 확인할 수 없습니다.

구조적인 위험 요소가 하나 더 있습니다. Anthropic의 문서에 따르면 항목 형식은 Claude Code 내부용이며 버전마다 변경될 수 있습니다. 따라서 이 파일을 직접 파싱하는 스크립트는 릴리스마다 중단될 수 있습니다. 이는 이와 유사한 형태의 모든 도구에 해당합니다. 이것이 바로 JSONL을 대상으로 직접 작성한 jq 한 줄짜리 명령어가 생각보다 위험한 이유입니다. 유지 관리되는 파서는 형식이 변경될 때 이를 추적해주지만, 직접 작성한 명령어는 필드 이름이 바뀌는 날 잘못된 수치를 확신에 차서 출력하게 될 것입니다.

마지막으로, 구독 모델에서의 달러 수치에는 주의가 필요합니다. Pro나 Max 요금제는 토큰당 과금되는 방식이 아니므로, 이 수치는 해당 토큰을 API 정가 기준으로 계산했을 때의 비용입니다. 이는 사용량이 얼마나 많은지를 측정하는 지표일 뿐, 실제 청구 금액이 아닙니다. 어떤 요금제를 선택할지 고민 중이라면, 해당 비교는 별도의 과정이 필요합니다: API 과금과 Claude 구독 비교를 참조하십시오.

형태 2: 내장 사용량 화면을 통해 예산을 소모한 모델 확인하기

Claude Code는 자체적인 보고 기능을 제공하지만, 이를 확인하는 사용자는 많지 않습니다. 세션 내에서 /usage을 실행하십시오. 상단의 세션 블록에는 모델별 토큰 사용량과 현재 세션의 비용이 달러 단위로 표시되며, 이는 표준 요금제 기준의 토큰 수를 바탕으로 로컬에서 계산됩니다. 이 수치는 할인이나 프로모션 가격을 반영하지 않으므로 실제 청구서와는 차이가 있을 수 있습니다. 합계는 /clear로 새 대화를 시작할 때 초기화됩니다.

Pro, Max, Team 또는 Enterprise 플랜을 사용하는 경우, 동일한 화면에서 플랜 한도 사용량을 확인할 수 있으며, 최근 사용량을 기술, 서브 에이전트, 플러그인, 개별 MCP 서버별로 전체 대비 백분율로 분류하여 보여줍니다. 긴 컨텍스트나 캐시 미스 등 최근 사용량의 10% 이상을 차지하는 동작은 별도로 표시됩니다. d 또는 w를 눌러 최근 24시간과 최근 7일간의 데이터를 전환할 수 있습니다. 이 수치는 해당 기기의 로컬 세션 기록을 기반으로 계산된 근사치이므로, 다른 기기에서의 사용량은 포함되지 않습니다.

개발자가 1명을 초과하면 수치는 계정 단위로 집계됩니다. API 조직은 Console 사용량 페이지를 통해 멤버별 비용과 수락된 코드 라인 수를 확인할 수 있는 Claude Code 대시보드를 이용할 수 있으며, 관리자 키를 사용하여 동일한 일일 사용자별 지표를 반환하는 Claude Code Analytics API를 사용할 수 있습니다. Team 및 Enterprise 플랜은 관리자 콘솔에서 CSV 내보내기를 지원하는 일일 업데이트 비용 보고서를 제공하며, Enterprise 플랜은 추가로 분석 API를 제공합니다. 어떤 보고서를 보게 될지는 각 개발자의 로그인 방식에 따라 달라지므로, 혼합된 조직의 경우 두 보고서를 확인하여 직접 합산해야 합니다.

예산을 책정할 때, 2026년 8월 기준 Anthropic의 비용 문서에 게시된 수치는 개발자 1인당 활성 일수 기준 평균 약 13달러, 월간 150달러에서 250달러 수준이며, 사용자의 90%는 활성 일수당 30달러 미만을 사용합니다. 이는 엔터프라이즈 배포 환경의 벤치마크일 뿐 귀하의 팀에 대한 예측치로 간주해서는 안 됩니다. 파일럿 그룹을 운영하여 직접 측정한 뒤 추정치를 산출하십시오.

대시보드에서 확인할 수 없는 정보는 일 단위나 개인 단위보다 세부적인 내용입니다. 대시보드는 화요일에 Opus가 가장 많이 사용되었다는 사실은 알려주지만, 어떤 프롬프트, 어떤 저장소, 혹은 어떤 CI 작업이 원인인지는 알려주지 않습니다. 또한 조직 보고서는 일 단위로 업데이트되므로 지연 시간이 발생합니다. 따라서 이는 당장 오늘 오후에 폭주하는 에이전트를 적발하기 위한 도구가 아니라 사후 검토 도구에 가깝습니다. 에이전트 폭주를 막으려면 보고서가 아닌 제한 설정이 필요하며, 이에 관한 내용은 VPS에서 에이전트 비용 제한하기에서 다룹니다.

형태 3: 자체 OpenTelemetry 스택으로 프롬프트 회귀 지점 파악하기

Claude Code는 환경 변수 하나만 설정하면 OpenTelemetry 메트릭과 이벤트를 출력합니다. 이는 사용자별 토큰 및 비용 데이터를 실시간에 가깝게 직접 제어하는 시스템으로 전송할 수 있는 유일한 방법입니다. 메트릭에는 USD 단위의 claude_code.cost.usage, 토큰 단위의 claude_code.token.usage, claude_code.session.count 및 claude_code.active_time.total이 포함됩니다.

토큰 메트릭은 속성 정보 때문에 특히 유용합니다. 각 데이터 포인트는 input, output, cacheRead 또는 cacheCreation 중 하나인 type를 포함하며, 추가로 main, subagent 또는 auxiliary 중 하나인 model와 query_source를 포함합니다. 또한 agent.name, skill.name, mcp_server.name 및 mcp_tool.name도 함께 전송됩니다. 이 정보는 일반적인 대시보드로는 확인할 수 없는 질문에 답을 줍니다. 예를 들어 전체 비용 중 사용자의 직접적인 요청이 아닌 서브 에이전트가 차지하는 비중, 특정 MCP 서버가 입력 토큰을 두 배로 늘렸는지 여부, CLAUDE.md 수정 후 캐시 읽기 효율이 급감했는지 등을 파악할 수 있습니다. 캐시 동작 방식은 보통 예상치 못한 문제가 발생하는 지점이므로, 프롬프트 캐싱이 비용 효율적인 경우를 참조하여 무엇을 확인해야 하는지 파악하십시오.

이와 관련하여 자주 언급되는 내용 중 바로잡을 점이 하나 있습니다. Langfuse는 훌륭한 자체 호스팅 트레이싱 백엔드이며, VPS에서 실행하는 방법은 에이전트 트레이싱을 위한 Langfuse 자체 호스팅에서 다룹니다. Langfuse의 OTLP 엔드포인트는 트레이스 데이터만 수신합니다. Claude Code는 스팬(span)이 아닌 메트릭과 로그 이벤트를 내보내므로, OTEL_EXPORTER_OTLP_ENDPOINT을 Langfuse로 설정하면 프로젝트 데이터가 비어 있게 되며 유의미한 오류 메시지도 출력되지 않습니다. Langfuse는 직접 API를 사용하여 에이전트를 구축할 때 적합한 도구입니다. 이 경우 개발자가 직접 코드에서 프롬프트, 모델, 비용을 포함한 각 스팬을 생성하기 때문입니다. Claude Code CLI의 경우에는 메트릭 저장소가 적합합니다.

자체 VPS에서 Claude Code 비용 추적 설정하기

메트릭을 수신할 수집기(collector)와 이를 저장할 Prometheus, 이 두 가지 서비스면 충분합니다. OTLP 포트를 외부에 개방하면 누구나 데이터를 쓸 수 있으므로 두 서비스 모두 공용 인터넷에서 격리해야 합니다. /opt/ccmetrics/compose.yaml를 작성하십시오:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1는 WireGuard 터널 내부의 서버 주소이므로, 수집기는 귀하의 머신에서만 접근할 수 있고 외부에서는 접근할 수 없습니다. Docker가 게시한 포트는 ufw에 의해 필터링되지 않으므로 포트 앞의 주소 설정이 실질적인 보안 역할을 합니다. Docker 게시 포트가 ufw를 우회하는 이유를 참조하십시오. 터널 자체를 설정하는 방법은 자체 VPS에서 WireGuard VPN 구축하기를 확인하십시오.

/opt/ccmetrics/collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml. Prometheus는 Compose 네트워크를 통해 서비스 이름으로 수집기에 접근하므로, 8889 포트는 호스트에 게시되지 않습니다:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

수집기 로그는 Everything is ready. Begin running and processing data.로 끝나야 합니다. 설정 오류로 로그가 멈춘다면 YAML 구문 분석에 실패한 것이며, 컨테이너는 재시작을 반복하게 됩니다.

이제 Claude Code를 해당 수집기로 연결하십시오. Claude Code를 실행하는 각 머신의 ~/.claude/settings.json에 다음을 추가하십시오:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

세션을 시작하고 프롬프트를 하나 보낸 뒤, 내보내기 간격(여기서는 10초, 기본값은 60초)만큼 기다린 후 Prometheus에 수집된 데이터를 확인하십시오:

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

claude_code_으로 시작하는 여러 이름을 확인할 수 있어야 합니다. 익스포터는 점(dot)을 밑줄(underscore)로 바꾸고 단위를 추가하므로, 정확한 문자열은 수집기 버전에 따라 다를 수 있습니다. 결과가 비어 있다면 데이터가 도착하지 않은 것입니다. http/protobuf은 4318 포트를 사용하고 grpc는 4317 포트를 사용하므로, 프로토콜과 포트가 일치하는지 확인하십시오. 불일치할 경우 조용히 실패합니다. claude --debug을 실행하면 디버그 로그에 OTel 내보내기 오류가 보고됩니다.

머신이 한 대뿐이고 서버가 없다면 위의 모든 과정을 건너뛰어도 됩니다. OTEL_METRICS_EXPORTER=prometheus를 설정하면 Claude Code가 http://localhost:9464/metrics에서 직접 스크랩 엔드포인트를 노출합니다. prometheus만 익스포터로 나열된 경우, Claude Code는 메트릭 이름에서 USD, tokens, s 단위를 생략하여 스크랩 결과가 유효한 Prometheus 텍스트 형식을 유지하도록 합니다.

이 구성에는 개인정보 보호와 관련된 결정 사항이 하나 있습니다. 기본적으로는 카운트 정보만 머신을 떠나며, 프롬프트 텍스트나 도구 출력은 포함되지 않습니다. OTEL_LOG_USER_PROMPTS=1 및 OTEL_LOG_TOOL_CONTENT=1을 설정하면 이 정보들이 포함되므로, 메트릭 서버에 소스 코드나 컨텍스트에 포함된 기타 정보가 저장될 수 있습니다. 해당 설정을 활성화할 때는 신중해야 하며, 먼저 에이전트 컨텍스트에서 비밀 정보 제외하기를 읽어보시기 바랍니다.

스크립트 및 CI 실행 비용 추적

비대화형 실행은 화면을 지켜보는 사람이 없기 때문에 예상치 못한 비용을 발생시킵니다. claude -p는 --output-format json을 사용하여 해당 실행의 비용을 결과 페이로드에 포함해 보고합니다:

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

이 페이로드에는 total_cost_usd와 모델별 상세 내역이 포함되어 있으므로, CI 작업은 대시보드 없이도 자체적인 비용을 기록할 수 있습니다. 값을 파일에 추가하거나 앞서 언급한 수집기로 메트릭을 전송하십시오. 이는 가장 저렴하고 유용한 비용 추적 방법이며, 실행당 jq 호출 한 번의 비용만 발생합니다.

실패 유형과 확인 방법

보고서가 비어 있습니다. npx ccusage@latest daily이 행을 출력하지 않는다면 Claude Code가 기록하는 위치를 읽지 못하는 것입니다. CLAUDE_CONFIG_DIR은 해당 위치를 변경하므로, 파서에 이를 알려주어야 합니다. 행은 존재하지만 약 한 달 전부터 기록이 없다면 이는 cleanupPeriodDays이 설계대로 작동하는 것입니다. 기본적으로 대화 기록은 30일 후에 삭제됩니다.

두 대의 기기에서 보고하는 총계가 다릅니다. 이는 버그가 아니며 예상된 동작입니다. /usage와 모든 로그 파서는 로컬 세션 기록만 읽기 때문에, 다른 기기나 claude.ai에서 사용한 기록은 양쪽 모두에 나타나지 않습니다.

로컬 총계가 청구서와 일치하지 않습니다. 로컬 수치는 표준 정가 기준의 토큰 수를 바탕으로 계산됩니다. 프로모션 가격이나 계약된 할인율은 반영되지 않으며, 구독 중인 경우 토큰은 개별적으로 청구되지 않습니다. API 청구에 대한 공식적인 기준은 Console 사용량 페이지입니다.

동일한 작업을 수행했음에도 비용이 증가했습니다. 다른 무엇보다 먼저 캐시 열을 확인하십시오. 긴 세션은 매 턴마다 전체 기록을 다시 전송합니다. 캐시가 활성화된 상태에서는 캐시 요금이 적용되지만, 캐시가 만료되면 전체 입력 요금이 적용되므로 긴 휴식 후에는 전체 대화 내용을 다시 처리하게 됩니다. 이는 출력 토큰 수에 비해 입력 토큰 수가 크게 나타나는 현상으로 이어지며, 입력 및 출력 토큰 가격 책정에서 두 수치가 독립적으로 변하는 이유를 설명합니다.

서브 에이전트를 사용한 날의 수치가 비정상적으로 보입니다. 각 서브 에이전트는 고유한 컨텍스트 윈도우를 실행하므로, 토큰 사용량은 실행된 에이전트의 수와 각 에이전트의 지속 시간에 비례하여 증가합니다. OTel 데이터만이 claude_code.token.usage의 query_source 속성을 통해 이를 구분할 수 있습니다. 일반적인 로그 파서는 총계만 보여줄 뿐 상세 내용은 알 수 없게 만듭니다.

FAQ

ccusage가 Max 플랜의 실제 청구 금액을 보여주나요?

아니요. 구독 모델에서는 토큰 단위로 요금이 청구되지 않으므로, 로그 파서는 토큰을 표준 API 정가 기준으로 계산하여 동일한 작업을 API로 수행했을 때의 비용을 보여줍니다. 이는 해당 일자의 작업 부하를 상대적으로 측정하거나 프로젝트 및 모델 간의 비용을 비교하는 데 유용합니다. 실제 청구 금액은 Console의 사용량 페이지에서 API 요금을, 플랜 결제 페이지에서 구독 요금을 확인하십시오.

Claude Code는 이 도구들이 읽는 세션 파일을 어디에 저장하나요?

~/.claude/projects/<project>/<session-id>.jsonl에 저장됩니다. 여기서 <project>은 작업 디렉터리 경로이며, 영문자와 숫자가 아닌 문자는 -로 치환됩니다. 각 줄은 메시지, 도구 사용 또는 메타데이터 항목 하나를 나타내는 JSON 객체입니다. CLAUDE_CONFIG_DIR로 전체 디렉터리를 이동할 수 있으며, settings.json 내의 cleanupPeriodDays 설정으로 30일 보관 주기를 제어합니다. Anthropic은 해당 항목 형식을 내부용으로 간주하며 버전 간에 변경될 수 있다고 명시하므로, 직접 스크립트를 작성하기보다 유지 관리되는 도구를 사용하여 파싱하십시오.

Claude Code 원격 분석 데이터를 Langfuse로 보낼 수 있나요?

직접 보낼 수는 없습니다. Langfuse OTLP 엔드포인트는 트레이스를 수신하지만, Claude Code는 스팬(span)이 아닌 메트릭과 로그 이벤트를 내보내므로 데이터가 전달될 곳이 없습니다. Claude Code 메트릭은 OpenTelemetry 수집기로 보내 Prometheus에 저장하십시오. Langfuse는 API를 사용하여 직접 구축한 에이전트에 사용하십시오. 직접 작성한 코드에서 프롬프트, 모델, 비용 정보가 포함된 스팬을 내보낼 수 있습니다.

로컬에서 계산한 수치가 Console 사용량 페이지와 다른 이유는 무엇인가요?

계산 방식이 다르기 때문입니다. /usage과 로그 파서는 사용자가 작업 중인 기기의 세션 파일에서 토큰 수를 합산한 뒤 표준 정가를 적용합니다. 반면 Console은 할인 적용 후 모든 기기와 모든 키를 통틀어 조직에 실제로 청구된 금액을 보고합니다. 따라서 수치가 일치하지 않는 것은 정상입니다. 차이가 매우 크다면 다른 기기, CI 러너 또는 다른 팀원이 동일한 계정으로 요금을 발생시키고 있을 가능성이 높습니다.

CI에서 claude -p 실행 비용을 어떻게 추적하나요?

--output-format json 옵션을 사용하여 실행한 뒤 결과에서 total_cost_usd 값을 읽으십시오. 예를 들어 claude -p "..." --output-format json | jq '.total_cost_usd'를 사용할 수 있습니다. 동일한 페이로드에 모델별 상세 내역과 세션 ID가 포함되어 있습니다. 작업별로 해당 값을 기록하면 별도의 에이전트, 대시보드 또는 추가 서비스 없이도 파이프라인별 비용을 파악할 수 있습니다.