muaco Tech 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

같은 분류의 글