클로드 코드 한도 — 초과 메시지와 초기화 시간
클로드 코드의 한도는 네 가지이고, 막혔을 때 뜨는 메시지에 초기화 시각이 같이 찍힙니다. session limit(5시간)과 weekly limit(7일)은 모든 모델이 같이 쓰는 한도라 모델을 바꿔도 안 풀리고, Opus limit·Sonnet limit은 그 모델 계열에만 걸리는 한도라 /model로 다른 계열로 옮기면 계속 작업할 수 있습니다. 아래에서 메시지별 대처와, 한도에 걸리기 전에 미리 알아채는 방법을 정리합니다. (Claude Code 2.1.204, 2026년 9월 18일 기준)
1. 한도 메시지 네 가지 — 뭐가 다른가
공식 오류 문서에 실린 메시지는 이렇습니다.
You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm| 메시지 | 무엇에 걸린 건가 | 모델을 바꾸면 풀리나 |
|---|---|---|
session limit |
5시간 롤링 창 | ❌ 모든 모델이 같이 쓰는 창입니다 |
weekly limit |
7일 창 | ❌ 마찬가지입니다 |
Opus limit |
Opus 계열 요청만 | ✅ /model로 다른 계열로 |
Sonnet limit |
Sonnet 계열 요청만 | ✅ 같은 방식입니다 |
2. 두 한도는 동시에 쌓인다
여기서 많이들 당합니다. 사용량은 세션 한도와 주간 한도에 동시에 기록됩니다. 그래서 큰 작업을 한 번 몰아치면 5시간 창이 초기화되기도 전에 주간 한도가 먼저 바닥날 수 있습니다. 공식 문서도 큰 작업을 한꺼번에 펼치는 경우를 예로 들고 있습니다.
다 쓰기 전에 클로드 코드가 미리 알려 주기도 합니다. 이런 줄이 뜨면 절반 이상 쓴 것입니다.
You've used 85% of your session limit · resets 3:45pm지금 얼마나 썼는지를 숫자로 확인하는 방법은 클로드 코드 사용량 확인에 따로 정리해 두었습니다. 이 글은 한도에 걸렸을 때와 걸리기 전에 집중합니다.
3. 초기화까지 기다릴 때 — 자동으로 이어하기
가장 확실한 대처는 메시지에 찍힌 초기화 시각까지 기다리는 것입니다. 그런데 요즘 버전은 기다렸다가 알아서 이어서 합니다. claude.ai 구독으로 로그인한 대화형 세션이면, 세션을 열어 둔 채 아래 줄이 바닥에 뜹니다.
Usage limit reached · continuing automatically at 3:45pm · esc to cancel빈 입력창에서 Esc를 누르면 기다리기를 취소합니다. 이 기능은 v2.1.234 이상에서만 있습니다. 그 아래 버전이면 이 줄이 안 뜨는 게 정상이니, 안 보인다면 claude --version부터 확인하세요.
/config 설정은 따로 노는 설정이라, 끄려면 양쪽을 각각 꺼야 합니다.
4. 걸리기 전에 알아채기 — 상태줄에 한도 띄우기
한도 메시지는 이미 막힌 다음에 뜹니다. 작업 흐름이 끊기는 게 싫으면 상태줄(status line)에 남은 한도를 상시 표시해 두는 게 낫습니다. 클로드 코드는 상태줄 스크립트에 JSON을 표준입력으로 넘겨주는데, 그 안에 한도 값이 들어 있습니다.
| 필드 | 뜻 |
|---|---|
rate_limits.five_hour.used_percentage |
5시간 롤링 한도를 몇 % 썼는지 (0~100) |
rate_limits.seven_day.used_percentage |
주간(7일) 한도를 몇 % 썼는지 (0~100) |
rate_limits.*.resets_at |
그 창이 초기화되는 시각 (유닉스 epoch 초) |
context_window.used_percentage |
지금 대화가 컨텍스트 창을 몇 % 차지했는지 |
rate_limits는 claude.ai 구독(Pro·Max)으로 로그인한 경우, 그것도 세션의 첫 응답이 온 뒤에야 들어옵니다. API 키로 쓰면 아예 없습니다. five_hour와 seven_day도 각각 따로 없을 수 있고, 초기화 시각이 지난 창은 클로드 코드가 아예 빼 버립니다. 그러니 스크립트는 값이 없어도 안 죽게 짜야 합니다.
윈도우에서도 그냥 도는 파이썬 상태줄
공식 문서 예제는 jq를 쓰는 셸 버전이 먼저 나오는데, 윈도우에는 jq가 기본으로 없습니다. 파이썬은 JSON 파싱이 기본 내장이라 어느 OS에서든 그대로 돕니다. 아래를 ~/.claude/statusline.py로 저장합니다.
#!/usr/bin/env python3
import json, sys, time
data = json.load(sys.stdin)
model = data['model']['display_name']
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)
bar = '#' * (pct * 10 // 100) + '.' * (10 - pct * 10 // 100)
parts = [f"[{model}] {bar} {pct}%"]
rate = data.get('rate_limits', {}) # 구독 계정에서만 들어온다
five = rate.get('five_hour', {}).get('used_percentage')
week = rate.get('seven_day', {}).get('used_percentage')
if five is not None:
parts.append(f"5h {five:.0f}%")
if week is not None:
resets = rate['seven_day'].get('resets_at')
when = time.strftime('%m/%d %H:%M', time.localtime(resets)) if resets else ''
parts.append(f"7d {week:.0f}% (reset {when})")
print(' | '.join(parts))그리고 ~/.claude/settings.json에 상태줄을 등록합니다.
{
"statusLine": {
"type": "command",
"command": "python ~/.claude/statusline.py",
"padding": 2
}
}실제로 돌려 본 출력입니다. 구독 계정에서 오는 모양의 JSON을 표준입력으로 넣으면 이렇게 나옵니다.
[Opus] ###....... 37% | 5h 24% | 7d 41% (reset 09/19 01:46)rate_limits가 없는 입력(API 키 사용자)을 넣으면 한도 부분만 조용히 빠집니다. 오류로 죽지 않습니다.
[Sonnet] .......... 8%스크립트를 손으로 짜기 싫으면 세션에서 /statusline 모델 이름이랑 5시간·주간 한도 퍼센트를 보여줘처럼 말로 시켜도 됩니다. 클로드 코드가 ~/.claude/에 스크립트를 만들고 설정까지 고쳐 줍니다.
회사에서 클로드 앱 게이트웨이를 통해 쓰는 경우라면 rate_limits.spend_limit이 하나 더 옵니다. 같은 두 필드를 갖되 한도를 넘기면 퍼센트가 100을 넘을 수 있고, v2.1.251 이상에서만 들어옵니다.
5. 한도가 계속 모자랄 때
/usage-credits— Pro·Max에서는 사용량 크레딧을 켜서 한도 위로 더 쓸 수 있습니다. Team·Enterprise에서는 이 명령이 관리자에게 요청하는 창구가 됩니다. (claude.ai 구독으로 로그인한 상태에서만 뜹니다)- 플랜 올리기 — 기본 한도 자체를 올리는 방법입니다. 플랜별 차이는 클로드 코드 요금제에 정리해 두었습니다.
- 쓰는 양 줄이기 — 지시문을
CLAUDE.md에 몰아넣으면 세션마다 통째로 올라갑니다. 필요할 때만 읽히는 스킬로 빼면 한 세션이 먹는 양이 줄어듭니다. 만드는 법은 claude skills 사용법에 있습니다.
6. 컨텍스트 경고는 한도가 아니다
가장 자주 헷갈리는 지점입니다. "컨텍스트가 거의 찼다"는 경고나 자동 압축(auto-compact) 안내는 요금제 한도와 아무 상관이 없습니다. 대화가 길어져 모델이 한 번에 받을 수 있는 입력 크기에 가까워졌다는 뜻일 뿐입니다. 이걸 한도 소진으로 오해해 하염없이 기다리는 경우가 많은데, /compact 한 번이면 되는 일입니다.
무엇이 컨텍스트를 잡아먹는지는 /context로 색 격자를 보면 바로 드러납니다. MCP 서버 정의나 메모리 파일이 부풀어 있으면 여기서 보입니다. 정리 방법은 셋입니다.
/clear— 관련 없는 작업으로 넘어갈 때 아예 새로 시작합니다. 나중에 찾을 것 같으면/rename으로 이름을 붙여 두고/resume으로 돌아옵니다./compact— 지금까지의 대화를 요약해 자리를 비웁니다./compact 코드 예제와 API 사용법 위주로처럼 무엇을 남길지 지시할 수 있습니다./mcp— 안 쓰는 MCP 서버를 끕니다. 서버 정의는 컨텍스트를 상시 차지합니다.
자주 묻는 질문 (FAQ)
Q. 한도가 언제 초기화되나요?
고정된 시각이 아니라 메시지에 찍힌 시각입니다. 5시간 창은 롤링이라 쓰기 시작한 시점을 기준으로 돌고, 주간 창은 7일 단위입니다. 정확한 시각은 한도 메시지나 /usage 화면에 나오고, 상태줄에 띄워 두면 resets_at으로 늘 보입니다.
Q. 모델을 바꿨는데도 계속 막힙니다.
메시지를 다시 보세요. session limit이나 weekly limit이면 모든 모델이 공유하는 한도라 모델을 바꿔도 안 풀립니다. 모델 전환으로 풀리는 건 Opus limit·Sonnet limit뿐입니다.
Q. 상태줄에 5h·7d가 안 뜹니다.
세 가지를 확인합니다. ① claude.ai 구독(Pro·Max)으로 로그인했는지 — API 키 인증이면 이 필드가 아예 없습니다. ② 세션의 첫 응답이 온 뒤인지 — 그 전에는 값이 안 들어옵니다. ③ 초기화 시각이 지난 창은 클로드 코드가 빼 버리므로, 값 없음을 견디게 짰는지.
Q. 아무것도 안 하고 있어도 한도가 닳나요?
조금 닳습니다. claude --resume용 대화 요약 같은 백그라운드 작업이 있고, 상태 확인 요청도 오갑니다. 공식 문서는 이런 백그라운드 소비를 세션당 보통 0.04달러 미만으로 봅니다.
Q. 다른 AI CLI도 한도가 이런 식인가요?
창의 길이와 이름이 다릅니다. codex 사용량 확인은 5시간 한도를, gemini cli 사용량 확인은 무료 한도를 따로 정리해 두었습니다.
마무리
정리하면 이렇습니다. 메시지 이름부터 보세요. session·weekly면 기다리는 것 말고 답이 없고, Opus·Sonnet이면 /model 한 번으로 계속 갑니다. 그리고 막히고 나서 대처하는 것보다 상태줄에 rate_limits를 띄워 두는 편이 훨씬 낫습니다 — 85% 경고가 뜨기 전에 흐름을 스스로 조절할 수 있으니까요.
한도 관련 동작은 버전을 많이 탑니다. 자동 이어하기는 v2.1.234, 게이트웨이 지출 한도 필드는 v2.1.251부터입니다. 내 화면이 이 글과 다르면 claude --version을 먼저 확인해 보세요.
📚 참고 출처 (2026년 9월 18일 확인 · Claude Code 2.1.204 기준)
· Claude Code — 오류 레퍼런스(Usage limits)
· Claude Code — 상태줄(status line)
· Claude Code — 비용 관리
· Claude Code — 명령어 레퍼런스
COMMENTS