ccusage로 Claude Code·Codex 사용량 확인하는 법 (npx 한 줄, 4개월 써보고)

AI 코딩 도구를 매달 구독으로 쓰는데, 내가 실제로 얼마나 굴렸는지 안 보여서 답답하셨다면 이 글이 맞습니다.

저는 Claude Code랑 Codex를 4개월 돌리고, 그걸 ccusage로 처음부터 끝까지 한 번 정산해봤습니다. 토큰 2,025억 개, 정가로 환산하면 13만 2천 달러어치였어요. 그 과정에서 처음 보는 사람은 거의 다 빠지는 함정 몇 개를 직접 밟았습니다. 그래서 "설치하는 법"만이 아니라 "어디서 숫자가 어긋나는지"까지 적어두려고 합니다.

설치는 필요 없습니다. npx 한 줄이면 됩니다.

ccusage가 뭐고, 왜 보나

ccusage는 로컬에 쌓인 Claude Code·Codex 로그를 읽어서, 내가 토큰을 얼마나 썼고 그게 API 정가로 얼마인지 계산해주는 도구입니다. 구독료 영수증이 아니라, "내가 이만큼 굴렸다"는 사용 강도를 보여줍니다.

구독제(정액)로 쓰는 분들한테 특히 쓸모가 있어요. 결제액은 매달 똑같으니까, 정작 내가 그 구독으로 몇 배를 뽑아 쓰는지는 어디에도 안 찍히거든요. 그걸 처음으로 숫자로 보는 도구가 ccusage입니다.

설치 없이 바로 실행하기

터미널에 이 한 줄을 칩니다. Node가 깔려 있으면 별도 설치 없이 그 자리에서 받아 실행됩니다.

npx ccusage

Claude Code 사용량은 이걸로 나옵니다. Codex는 도구가 따로예요.

npx ccusage-codex

처음 실행하면 npx가 패키지를 받겠냐고 한 번 물어봅니다. 엔터 치면 됩니다. 둘 다 로컬 로그만 읽기 때문에, 어디로 내 사용 기록을 올려보내지는 않습니다.

출력을 읽는 법 — monthly / daily / session

ccusage는 같은 데이터를 세 가지 단위로 보여줍니다. 보고 싶은 게 뭐냐에 따라 골라 쓰면 됩니다.

• monthly — 월별 합계. "이번 달에 얼마나 썼나"를 보려면 이걸 봅니다. 곡선이 얼마나 가팔라지는지가 한눈에 들어와요. 저는 2월에 $2,171이던 게 6월엔 $70,948이 돼 있었습니다. 넉 달 만에 33배였어요.
• daily — 날짜별. 어느 날 갑자기 튀었는지를 잡을 때 씁니다. 저는 6월 6일 하루치가 $48,300이었는데, 큰 배치 작업 하나를 통째로 에이전트한테 맡긴 날이었습니다. 이 하루 한 줄이 Claude Code 넉 달 전체($14,478)보다 컸어요. monthly 합계만 봤으면 평평한 곡선에 묻혀 안 보였을 텐데, daily로 떼니까 그제야 튀어나왔습니다.
• session — 세션 단위. 어떤 작업이 무거웠는지 더 잘게 쪼개 볼 때 씁니다.

각 줄에는 토큰 수와 그 토큰을 정가로 환산한 비용이 같이 찍힙니다.

여기서 한 가지 꼭 알아둘 게 있어요. 토큰 수가 곧 작업량은 아닙니다. 제 경우 Claude는 전체 토큰의 96%, Codex는 입력의 96%가 캐시 읽기(cache-read)였습니다. 새로 만들어 보낸 입력은 4%밖에 안 됐어요. "토큰 2,025억"이라는 숫자는 일을 그만큼 했다기보다, 같은 컨텍스트를 그만큼 다시 읽었다에 가깝습니다. 그래서 큰 토큰 숫자에 놀라기 전에, 그 안에서 cache-read 비중을 먼저 보는 게 맞습니다.

실전 함정 — 기본값으로 돌리면 조용히 빠지는 것들

여기가 이 글의 진짜 이유입니다. 명령어 자체는 위 두 줄이 전부인데, 그냥 돌리면 숫자가 틀어집니다. 제가 실제로 밟은 순서대로 적습니다.

1) --offline은 최신 모델을 0원으로 빠뜨립니다

빨리 돌리려고 --offline(캐시된 가격표)을 줬더니 Claude 비용이 $4,144로 나왔어요. 인터넷이 붙은 상태에서 라이브 가격으로 다시 돌리니까 $14,478. 세 배 넘게 차이가 났습니다.

원인을 뜯어보니, opus-4-8이나 fable-5 같은 최신 모델 가격이 오프라인 캐시에 아예 없어서 조용히 0원으로 처리되고 있었습니다. 에러도 안 나고요. 그냥 그 줄만 비용 0으로 빠져버립니다.

그러니까 정확한 비용을 보려면 라이브 가격으로 돌려야 합니다. --offline은 인터넷이 없을 때나 대충 빠르게 볼 때만 쓰세요.

2) 아카이브된 세션은 기본 집계에서 통째로 빠집니다

이게 제일 의외였어요. ccusage-codex는 기본적으로 ~/.codex/sessions만 읽습니다. 그런데 저는 따로 보관해둔 세션이 61개 있었고, 거기에만 토큰 37.7억, 정가로 $2천어치가 들어 있었습니다.

기본값으로 돌렸을 땐 이게 합계에 안 잡혔어요. CODEX_HOME 환경변수를 그 보관 폴더로 바꿔서 한 번 더 돌리고 나서야 합산됐습니다.

CODEX_HOME=/내/아카이브/경로 npx ccusage-codex

따로 백업해둔 세션이 있다면, 한 번에 다 보이지 않는다는 걸 염두에 두세요. 폴더별로 돌려서 더해야 합니다.

3) 13만 달러는 결제액이 아닙니다

마지막은 숫자를 읽는 관점입니다. ccusage가 매기는 비용은 그 토큰을 API 단건으로 썼을 때의 정가(LiteLLM 기준)를 환산한 값이지, 제가 실제로 낸 돈이 아니에요. 통장에서 빠져나간 건 매달 구독료뿐이었습니다.

무제한 뷔페에서 먹은 접시를 단품 가격으로 일일이 더한 영수증 같은 겁니다. 그 금액을 낸 건 아니지만, "이만큼 먹었다"는 양 자체는 정확하거든요. 그러니 13만이라는 숫자에 겁먹을 게 아니라, 구독료 대비 몇 배를 뽑았나로 읽으면 됩니다.

정리하면, 이 순서로 돌리세요

처음 보는 분이라면 이렇게 시작하면 됩니다.

npx ccusage           # Claude Code, 월별부터
npx ccusage-codex     # Codex

그다음, 숫자를 믿기 전에 세 가지를 확인합니다. 라이브 가격으로 돌렸는지(아니면 최신 모델이 0원으로 빠집니다), 아카이브 세션까지 합쳤는지, 그리고 비용 숫자를 결제액이 아니라 사용 강도로 읽고 있는지.

저도 이 세 개를 다 잘못 본 채로 한참 들여다봤습니다. 솔직히 처음 13만이 찍혔을 땐 손이 멈췄거든요.

그 하루에 $48,300이 어떻게 나왔는지, 4개월 곡선이 어쩌다 33배가 됐는지는 따로 정리해뒀습니다. 숫자에 놀랐다가 다시 읽은 이야기가 궁금하시면 여기로요.

https://datacook.tistory.com/148

ccusage로 4개월 AI 사용량을 정산했더니 13만 달러였습니다 — 근데 제가 낸 돈은 아닙니다

 

(기준: 2026-06-16, ccusage 20.0.14, API 정가 환산. 모델·가격표는 바뀌니까 돌릴 땐 본인 환경에서 다시 확인하세요.)