muacoTech Note

Claude Codecode.claude.com

Claude Code 사용량과 비용 확인하기/usage, 상태 줄, 캐시로 아끼는 법

Claude Code에서 쓴 토큰과 금액을 확인하고, 화면 아래에 금액을 늘 띄우고, 캐시가 깨지지 않게 써서 비용을 줄여요.

안녕하세요, muaco입니다.

이 글을 읽고 나면 할 수 있는 일

Claude Code를 쓰다 보면 "오늘 얼마나 썼지?" 하는 궁금증이 생겨요. 이 글을 따라 하면 세 가지를 할 수 있어요. 명령 한 줄로 이번 세션에서 쓴 토큰과 금액을 봐요. 화면 맨 아래에 금액과 캐시 적중률을 늘 띄워 둬요. 같은 일을 하면서 돈이 덜 나가도록 캐시를 살리는 습관을 들여요.

토큰부터 짚고 갈게요. 택시 미터기가 달린 거리만큼 요금을 올리듯, AI는 읽고 쓴 글자 조각만큼 요금을 매겨요. 이 글자 조각을 토큰이라고 불러요. Claude Code의 요금도 이 토큰 수로 계산해요.

시작 전에 갖춰야 할 준비물

  • Claude Code 설치와 로그인. 터미널(글자로 명령을 치는 까만 창)에서 claude를 쳤을 때 대화창이 뜨면 준비된 상태예요.
  • 버전 확인. claude --version으로 확인해요. 이 글에서 다루는 캐시 통계는 v2.1.251 이상에서 보여요. 자동 업데이트는 새 버전을 미리 받아 두었다가 다음에 켤 때 적용해요.
  • 내 요금 방식. Pro나 Max 같은 구독인지, API 키(쓴 만큼 돈을 내는 개발자용 열쇠)인지 알아 두세요. 구독자에게는 요금제 안에 사용량이 들어 있어서 세션 금액이 청구와 상관없는 참고 숫자예요. API 사용자에게는 이 숫자가 실제로 나갈 돈에 가까워요.
  • jq. 상태 줄을 직접 만들 때만 필요해요. JSON(이름표 붙은 데이터 묶음)을 읽어 주는 작은 프로그램인데, macOS에는 기본으로 없을 수 있어요. macOS는 brew install jq, Ubuntu 같은 Linux는 sudo apt install jq로 깔아요. jq --version을 쳐서 버전 번호가 찍히면 준비된 상태예요. 아래 예시는 macOS와 Linux의 Bash 기준이에요. Windows는 공식 문서의 PowerShell, Git Bash 예시를 따라 주세요.

따라 하기: 보고, 띄우고, 아끼기

1. 지금 쓴 양 확인하기

따라 하기
  1. 프로젝트 폴더에서 claude를 켜고 질문을 하나 해요. 숫자는 첫 응답이 온 뒤부터 쌓이니, 막 켠 세션에서는 볼 게 없어요.
  2. 입력창에 /usage를 치고 엔터를 눌러요. 맨 위 Session 블록에 Total cost와 Usage by model이 보이면 제대로 된 상태예요.
  3. Usage by model 줄을 읽어요. 모델마다 input(새로 읽은 양), output(써낸 양), cache read(캐시에서 싸게 다시 읽은 양), cache write(캐시에 새로 적은 양)가 나와요. cache read가 다른 값보다 훨씬 크면 캐시가 제 몫을 하고 있어요.
  4. 바로 아래 Prompt cache (main) 줄을 봐요. 91% of input tokens from cache처럼 캐시로 처리한 비율, 캐시를 놓친 횟수(misses), 지금 캐시가 살아 있는지(warm 또는 cold)가 한 줄에 나와요.
  5. 구독자라면 같은 화면의 사용량 막대와 내역도 봐요. d와 w 키로 최근 24시간과 최근 7일을 오갈 수 있어요. 스킬, 서브에이전트, MCP 서버마다 차지한 비중이 퍼센트로 나와서 어디서 많이 쓰는지 짚어 낼 수 있어요.

이 합계는 /clear로 새 세션을 열면 0달러부터 다시 세요(v2.1.211부터 이렇게 바뀌었어요). 금액은 정가로 계산한 추정치예요. 정확한 청구액은 Claude Console의 Usage 페이지에서 확인해요.

2. 화면 아래에 금액 띄우기

매번 /usage를 치기 번거로우면 상태 줄을 쓰세요. 자동차 계기판처럼 화면 맨 아래 한 줄에 원하는 숫자를 늘 띄워 두는 기능이에요. 상태 줄은 내 컴퓨터에서만 돌아서 토큰을 쓰지 않아요.

따라 하기
  1. 가장 쉬운 길은 말로 시키기예요. /statusline show model name and session cost처럼 cost를 꼭 넣어 적어요. 공식 문서의 예시 문구에는 금액이 빠져 있어요. 적은 대로 Claude Code가 스크립트를 만들고 설정까지 고쳐 줘요. 설정 도중 파일 수정 확인 창이 뜨면 승인하라고 공식 문서도 안내해요. 화면 아래에 금액이 뜨면 3번 묶음으로 넘어가도 돼요. 금액이 안 보이면 문장을 고쳐 다시 시켜요.
  2. 직접 만들려면 아래 내용을 ~/.claude/statusline.sh로 저장해요. ~는 내 홈 폴더를 뜻해요. Claude Code가 세션 정보를 JSON으로 넘겨주면, 이 스크립트가 모델 이름, 이번 세션 추정 금액(cost.total_cost_usd), 캐시 적중 비율(prompt_cache.hit_ratio)을 꺼내 한 줄로 찍어요. 
    #!/bin/bash
input=$(cat)

    MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
HIT=$(echo "$input" | jq -r '((.prompt_cache.hit_ratio // 0) * 100) | floor')
    

    COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))
    

    echo "[$MODEL] $COST_FMT | cache ${HIT}% | ${MINS}m ${SECS}s"

  3. 실행 권한을 줘요. chmod +x ~/.claude/statusline.sh를 한 번 치면 돼요. 이 단계를 빼먹으면 상태 줄이 빈칸으로 남아요.
  4. 가짜 데이터로 먼저 돌려 봐요. echo '{"model":{"display_name":"Opus"},"cost":{"total_cost_usd":0.55,"total_duration_ms":45000}}' | ~/.claude/statusline.sh를 쳤을 때 [Opus] $0.55 | cache 0% | 0m 45s처럼 한 줄이 찍히면 스크립트는 정상이에요.
  5. ~/.claude/settings.json에 아래 내용을 넣고 저장해요. 파일에 이미 다른 설정이 있으면 바깥 중괄호 안에 "statusLine" 항목만 더해요. 저장하면 Claude Code가 설정을 알아서 다시 읽어요. 화면 아래에 모델 이름과 금액이 뜨면 성공이에요. 
    {
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

캐시 비율을 담은 prompt_cache 값은 v2.1.251 이상에서, 그것도 첫 응답이 온 뒤에야 들어와요. 그 전에는 cache 0%로 보여요.

3. 캐시를 살려 비용 줄이기

캐시가 왜 돈을 아껴 주는지 먼저 볼게요. Claude Code는 요청할 때마다 기본 지시문, CLAUDE.md, 지금까지의 대화를 통째로 다시 보내요. 앞부분이 지난번과 글자 하나까지 같으면 캐시에서 꺼내 읽는데, 이때 요금은 보통 입력 요금의 약 10% 수준이에요. 앞부분이 조금이라도 바뀌면 그 뒤를 전부 새로 읽어요.

따라 하기
  1. 모델과 effort(생각을 얼마나 깊게 할지 정하는 단계)는 세션 처음에 정해요. 모델마다 캐시가 따로고 대부분의 모델은 effort 단계마다도 캐시가 따로예요. 그래서 중간에 /model로 모델을 바꾸거나 effort를 바꾸면 다음 요청이 대화 전체를 새로 읽어요. 캐시가 살아 있을 때 바꾸려 하면 Claude Code가 한 번 되물어요. 그 질문이 뜨면 정말 지금 바꿔야 하는지 따져 봐요.
  2. 전혀 다른 일로 넘어갈 때는 /clear로 새로 시작해요. 필요 없는 옛 대화를 요청마다 싣고 다니지 않게 돼요. 나중에 돌아올 세션이면 먼저 /rename으로 이름을 붙이고 돌아올 때 /resume으로 불러와요.
  3. 대화를 요약해서 줄이는 /compact는 일이 한 매듭 지어진 때 직접 실행해요. 작업 한가운데서 자동 압축이 끼어들면 그 순간에 비용이 몰려요. 엉뚱한 길로 갔다면 /rewind로 되돌아가는 편이 싸요. 이미 캐시된 앞부분으로 돌아가기 때문이에요.
  4. 캐시가 얼마나 사는지 알아 둬요. 시간제 물품 보관함처럼, 정해진 시간 안에 돌아오면 맡긴 짐을 그대로 찾고 시간이 지나면 비워져요. 이 시간을 TTL이라고 불러요. 구독 요금제 사용량 안에서 쓰면 메인 대화는 1시간이지만 서브에이전트 같은 나머지 요청은 5분이에요. 사용량 크레딧, API 키, Bedrock 같은 클라우드 제공자로 쓰면 기본 5분이에요. 이 시간보다 오래 쉬고 돌아오면 첫 요청이 전체를 다시 읽어요.
  5. API 키 사용자라면 ~/.claude/settings.json에 "promptCacheTtl": "1h"를 넣어 1시간 캐시를 쓸 수 있어요(v2.1.242 이상). 대신 캐시에 적는 요금이 더 비싸요. 쉬지 않고 이어서 일하는 사람에게는 오히려 손해고 자주 자리를 비웠다 돌아오는 사람에게 맞아요.

잘 지키고 있는지는 /usage의 Prompt cache (main) 줄로 확인해요. 비율이 높고 misses가 늘지 않으면 잘 되고 있어요. v2.1.260 이상에서는 놓친 이유도 likely cause: tool definitions changed처럼 짚어 줘요.

여기서 다들 한 번 막혀요

  • jq: command not found가 떠요. jq가 깔려 있지 않은 상태예요. 준비물의 명령으로 설치하고 jq --version으로 확인한 뒤 4번 단계를 다시 돌려요.
  • 상태 줄이 아예 안 떠요. 실행 권한부터 확인해요. chmod +x ~/.claude/statusline.sh를 다시 쳐도 돼요. 4번 단계처럼 스크립트를 직접 돌려서 한 줄이 찍히는지도 봐요. 폴더를 믿을지 묻는 창을 수락하지 않았다면 상태 줄은 빈칸으로 남아요. Claude Code를 다시 켜고 그 창을 수락해요. 이유를 모르겠으면 claude --debug로 켜 보세요. Windows의 Git Bash에서는 경로에 역슬래시 대신 슬래시(/)를 써요.
  • 값이 비어 있거나 --로 나와요. 첫 응답이 오기 전에는 값이 비어(null) 있어요. 스크립트의 // 0이 이럴 때 0을 대신 넣어 줘요. 대화를 여러 번 주고받아도 그대로면 Claude Code를 다시 켜요.
  • 잠깐 쉬고 왔더니 느리고 비싸졌어요. 캐시가 식은 경우예요. /usage의 Prompt cache (main) 줄 끝이 cold인지 봐요. 자리를 비운 사이에도 /loop 같은 예약 작업은 정해진 간격마다 대화 전체를 보내며 돌아요. 쓰지 않는 예약 작업은 멈춰 두세요.
  • /usage 금액과 청구서가 달라요. 화면의 금액은 정가로 계산한 추정치예요. 회사가 계약 단가로 쓰고 있다면 관리자가 modelPricing을 관리형 설정으로 넣어 줘야 맞아요. 그렇게 넣으면 Total cost 줄에 at your organization's configured rates가 붙어요.

여기서 더 나아가려면

/context로 무엇이 자리를 차지하는지 봐요. 안 쓰는 MCP 서버는 /mcp에서 꺼 두세요. 대부분의 코딩 일은 Sonnet으로 충분하고 Opus는 복잡한 설계처럼 깊이 따져야 하는 일에 아껴 쓰면 돼요. 팀 전체 사용량을 실시간으로 모으고 싶다면 OpenTelemetry 내보내기를 알아보세요.

여기까지예요.

출처

#Claude Code#비용#사용량#토큰#프롬프트 캐싱#상태 줄#usage

같은 분류의 글