Claude 구독 한도 확인법 — 5시간·주간 사용률을 숫자로 보는 공식 필드가 있습니다

Claude 구독 한도 확인법을 찾아본 적 있다면 아마 답을 못 얻으셨을 겁니다. 전에 구독의 '20배'가 무엇의 20배인지를 파봤을 때도 공식 문서 어디에도 한도의 절대값이 없었습니다. 그런데 다른 문서를 읽다가 5시간 한도와 주간 한도를 몇 퍼센트 썼는지 그대로 내주는 필드를 찾았습니다. 절대값은 여전히 없습니다. 하지만 퍼센트는 있습니다.

📌 30초 요약

• 사용률은 볼 수 있습니다 — 5시간 창과 주간 창 각각 0~100 퍼센트와 초기화 시각이 공식 필드로 나옵니다.
• 절대값은 여전히 없습니다 — "몇 번" "몇 토큰"인지는 안 알려줍니다. 퍼센트뿐입니다.
• 조용히 안 나오는 경우가 있습니다 — 구독자만, 세션의 첫 응답 이후에만, 그리고 두 창이 각각 따로 빠질 수 있습니다.
• 화면의 비용은 추정치입니다. 문서가 직접 "실제 청구와 다를 수 있다"고 적어놨고, 새 세션을 시작하면 0으로 돌아갑니다.
• 컨텍스트 퍼센트를 직접 계산해보니 4.25 · 7.75 · 8.35 세 값이 나왔습니다. 어느 필드를 쓰느냐에 따라 1.8배까지 차이가 납니다.
• 200k 경고는 고정 임계값이라, 100만 컨텍스트 모델에서는 20% 지점에서 켜집니다.

전에 못 찾았던 것 — 일부가 나왔습니다

상태줄(status line)은 화면 맨 아래에 원하는 걸 띄우는 기능입니다. 여기에 세션 데이터가 JSON으로 들어오는데, 그 안에 구독 한도 사용률이 들어 있습니다.

// 공식 문서에 실린 샘플 그대로
"rate_limits": {
  "five_hour": {
    "used_percentage": 23.5,
    "resets_at": 1738425600
  },
  "seven_day": {
    "used_percentage": 41.2,
    "resets_at": 1738857600
  }
}

resets_at은 유닉스 초라 사람이 읽으려면 변환해야 합니다. 위 값을 변환하면 각각 2월 1일 16:00 UTC, 2월 6일 16:00 UTC가 나옵니다. 즉 언제 초기화되는지까지 알 수 있습니다.

알 수 있는 것	필드	비고
5시간 창을 몇 퍼센트 썼나	rate_limits.five_hour.used_percentage	0~100
주간 창을 몇 퍼센트 썼나	rate_limits.seven_day.used_percentage	0~100
언제 초기화되나	resets_at	유닉스 초
한도의 절대값	해당 필드 없음	여전히 못 찾음

그러니까 "내가 한도의 23.5%를 썼다"는 알 수 있지만, "그 100%가 몇 번인지"는 여전히 모릅니다. 절반쯤 해소된 셈입니다. 그래도 실용적으로는 큰 차이입니다 — 퍼센트만 봐도 지금 아껴야 할 때인지는 판단할 수 있으니까요.

⚠️ 조용히 안 나오는 경우 — 문서에 적혀 있습니다

이 필드는 구독자에게만, 그리고 세션의 첫 응답이 온 뒤에만 나타납니다. 게다가 5시간 창과 주간 창이 각각 독립적으로 빠질 수 있습니다. 문서도 이걸 알고 있어서 없을 때를 우아하게 처리하라며 // empty를 붙인 예제를 줍니다. 스크립트를 짤 때 이 처리를 빼먹으면 값이 없는 날 상태줄이 이상하게 보입니다.

화면의 비용은 추정치이고, 새 세션을 열면 0으로 돌아갑니다

비용도 같은 JSON에 들어옵니다. 그런데 그 설명이 솔직합니다.

"Estimated session cost in USD, computed client-side. May differ from your actual bill. Resets to $0 when /clear starts a new session"

USD 기준 세션 비용 추정치이며 클라이언트에서 계산됩니다. 실제 청구서와 다를 수 있습니다. 새 세션을 시작하면 0달러로 초기화됩니다 — 공식 문서

세 가지가 한 문장에 다 들어 있습니다. ①추정치다 ②내 컴퓨터가 계산한 값이다 ③실제 청구와 다를 수 있다. 그리고 뒤에 붙은 한 줄이 실무에서 제일 중요합니다 — 대화를 새로 시작하면 0으로 리셋됩니다.

습관적으로 대화를 자주 갈아엎는 사람은 화면에서 세 자리 숫자를 볼 일이 없습니다. 매번 몇 센트짜리 작은 수만 보이니까요. 그런데 청구서는 그 수들을 전부 합친 값입니다. "화면에 얼마 안 나오던데"가 실제 지출과 어긋나는 지점이 바로 여기입니다. 사용량 화면의 숫자가 왜 전부가 아닌지는 결제 첫 달에 볼 것에서 따로 다뤘습니다.

컨텍스트 퍼센트를 직접 계산해봤더니 답이 세 개였습니다

컨텍스트 사용률도 같은 JSON에 들어옵니다. 그런데 계산에 쓸 수 있는 필드가 여러 개라, 어느 걸 쓰느냐에 따라 답이 달라집니다. 공식 문서에 실린 샘플 JSON을 그대로 놓고 세 가지 방식으로 계산해봤습니다.

# 문서의 샘플 값
input_tokens                 = 8500
cache_creation_input_tokens  = 5000
cache_read_input_tokens      = 2000
output_tokens                = 1200
context_window_size          = 200000

# 세 가지로 계산한 결과
input_tokens 만                     8500 / 200000 = 4.25%   # 흔한 실수
입력 + 캐시생성 + 캐시읽기         15500 / 200000 = 7.75%   # 공식 필드와 일치
거기에 출력까지 더하면             16700 / 200000 = 8.35%   # 문서가 하지 말라는 방식

공식 필드가 내주는 값은 7.75%입니다. 그런데 input_tokens라는 이름만 보고 그것만 쓰면 4.25%가 나옵니다. 실제의 1.8분의 1입니다. 컨텍스트가 절반쯤 찼는데 화면에는 4분의 1로 뜨는 상황이 벌어집니다.

계산 방식	토큰	퍼센트	판정
입력 토큰만	8,500	4.25%	과소 표시
입력 + 캐시 생성 + 캐시 읽기	15,500	7.75%	공식 값과 일치
출력까지 포함	16,700	8.35%	문서가 말리는 방식

계산하면서 하나 더 눈에 띈 게 있습니다. 이 샘플에서 15,500토큰 중 7,000이 캐시입니다. 45.2%죠. 컨텍스트를 채우고 있는 것의 절반 가까이가 내가 방금 친 말이 아니라 재사용되는 덩어리라는 뜻입니다. 첫 프롬프트를 치기도 전에 이미 무엇이 실려 있는지는 컨텍스트에 뭐가 차 있는지에서 다뤘습니다.

200k 경고는 컨텍스트 크기와 무관한 고정 임계값입니다

같은 JSON에 20만 토큰을 넘었는지 알려주는 항목이 따로 있습니다. 그런데 문서가 실제 컨텍스트 크기와 상관없는 고정 임계값이라고 못박아 뒀습니다. 확장 컨텍스트 모델이라면 이게 무슨 뜻이 되는지 계산해봤습니다.

컨텍스트 크기	경고가 켜지는 지점	의미
200,000	100.0%	거의 다 찼을 때 켜짐
500,000	40.0%	아직 절반도 안 썼는데 켜짐
1,000,000	20.0%	5분의 1에서 켜짐

확장 컨텍스트를 쓰면서 이 항목으로 "이제 정리할 때"를 판단하면, 아직 80%가 남았는데 경고를 보게 됩니다. 반대로 문제도 아닙니다 — 200k 모델에서는 100%가 되어서야 켜지니 미리 알려주는 역할을 못 합니다. 어느 쪽이든 이 항목 하나로 판단하면 안 됩니다. 퍼센트 필드를 같이 보세요.

그래서 이렇게 붙였습니다

위 내용을 반영한 상태줄 스크립트입니다. 없을 수 있는 값은 전부 기본값 처리했고, 컨텍스트 퍼센트는 공식 필드를 그대로 씁니다(직접 계산하다 4.25% 함정에 빠지지 않으려고요).

#!/bin/bash
# jq 가 필요합니다
input=$(cat)

PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

# 없을 수 있는 값 - empty 로 받아 빈 문자열 처리
H5=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

LINE="ctx ${PCT}% | \$${COST}"
[ -n "$H5" ] && LINE="$LINE | 5h ${H5%%.*}%"
[ -n "$WK" ] && LINE="$LINE | wk ${WK%%.*}%"

echo "$LINE"
# 출력 예: ctx 8% | $0.01234 | 5h 23% | wk 41%

✅ 안심해도 되는 것 하나

문서가 명시해 뒀습니다 — 상태줄은 로컬에서 돌고 API 토큰을 쓰지 않습니다. 비용을 보려고 붙인 기능이 비용을 늘리면 곤란한데, 그건 아니라는 뜻입니다. 다만 스크립트가 느리면 문제가 됩니다 — 갱신은 300밀리초로 묶여 처리되고, 실행 중에 새 갱신이 오면 돌던 스크립트가 취소됩니다. 네트워크를 타는 명령을 넣으면 상태줄이 영영 안 갱신될 수 있습니다.

🗺️ AI 지출 전체 지도

상태줄은 새는 곳을 보이게 만드는 단계의 도구입니다. 무료로 시작해서 결제하고 상한을 걸기까지, 순서대로 묶어 둔 지도가 있습니다.

AI 지출 완전 정복 — 7단계 지도 보기 →

자주 묻는 것

Q. 그래서 한도가 정확히 몇 번인지는 알 수 있나요?

아니요. 퍼센트와 초기화 시각만 나옵니다. 100%가 몇 회인지, 몇 토큰인지는 이 필드에 없습니다. '20배'가 무엇의 20배인지를 팠을 때 못 찾은 그 숫자는 여전히 못 찾은 상태입니다. 다만 비율은 이제 볼 수 있습니다.

Q. 화면의 비용을 그대로 믿어도 되나요?

추세 파악용으로만. 문서가 직접 "추정치이고 실제 청구와 다를 수 있다"고 적었습니다. 그리고 새 세션마다 0으로 리셋되니 하루 총액이 아닙니다. 실제 금액은 결제 대시보드에서 보세요.

Q. 한국어로 쓰면 한도가 더 빨리 차나요?

한도를 토큰으로 세는 구조라면 그렇습니다. 같은 대화라도 한국어 쪽이 토큰을 더 씁니다. 다만 흔히 말하는 3~5배는 아니었습니다 — 직접 재보니 1.44배였습니다.

Q. 스크립트를 직접 못 짜겠는데요?

문서에 따르면 원하는 걸 자연어로 말하면 스크립트를 만들어 설정까지 넣어주는 명령이 있습니다. "5시간 한도랑 비용 보여줘" 같은 식이죠. 위 코드를 직접 붙여 넣어도 되고요.

🧠 같은 JSON의 effort 값에도 함정이 있습니다

위에서 훑은 세션 데이터에는 추론 강도(effort)도 함께 들어옵니다. 상태줄에 띄워두면 지금 몇으로 도는지 바로 보이는데, 그 이름을 그대로 믿으면 안 됩니다 — 공식 문서가 눈금이 모델별로 따로 매겨져 있어 같은 레벨 이름이 모델 간에 같은 값을 뜻하지 않는다고 적어놨습니다. 즉 모델을 갈아타면 화면의 글자는 그대로인데 실제 추론량은 달라져 있습니다. 게다가 조직 상한이 걸려 있으면 자동화로 돌릴 때는 경고 없이 낮은 값으로 실행됩니다. 자세한 건 effort 레벨이 조용히 내려가는 경우 넷에 있습니다.

✨ 정리하면

사용률은 볼 수 있게 됐습니다. 5시간 창과 주간 창의 퍼센트, 그리고 초기화 시각까지. 한도의 절대값은 여전히 안 나오지만, 퍼센트만으로도 지금 아껴야 하는지는 판단됩니다.

대신 화면의 숫자 셋은 각각 다른 방식으로 어긋납니다. 비용은 추정치이고 새 세션에 0으로 돌아가고, 컨텍스트 퍼센트는 어느 필드를 쓰느냐로 1.8배가 갈리고, 200k 경고는 컨텍스트가 클수록 일찍 켜집니다. 숫자를 띄우는 것보다 그 숫자가 무엇을 세는지 아는 게 먼저입니다.

📎 출처와 주의

• 1차 확인 — 필드 이름·설명·샘플 JSON·제약 조건은 모두 공식 상태줄 문서에서 직접 확인했습니다(2026년 8월 15일 기준). 인용한 영문 문장도 원문 그대로입니다.
• 직접 계산 — 4.25 · 7.75 · 8.35 퍼센트, 캐시 비중 45.2 퍼센트, 200k 임계값이 켜지는 지점(100/40/20 퍼센트)은 문서에 실린 샘플 값을 제가 계산기에 넣어 얻은 값입니다.
• 주의 — 샘플은 샘플입니다. 위 퍼센트들은 문서의 예시 숫자로 구조를 보여준 것이지 여러분 세션의 실제 값이 아닙니다. 비율 관계(특히 1.8배 차이)는 어느 세션에서도 성립하지만, 구체적인 값은 직접 확인하세요.
• 못 확인한 것 — 한도 100%가 몇 회·몇 토큰인지는 이 문서에서 찾지 못했습니다. "없다"가 아니라 이 경로에서 못 찾았다는 뜻입니다.
• 필드 구성과 정책은 버전에 따라 바뀝니다. 스크립트가 갑자기 빈 값을 내면 필드 이름부터 다시 확인하세요.