클로드 코드 한도, 모델 교체와 자격 증명 분리로 이어 쓰는 법

클로드 코드에서 한도에 막혔다고 해서 모든 작업을 API로 넘겨야 하는 것은 아닙니다. 지금 세션이 구독 한도를 쓰는지, API 키로 결제되는지를 /status로 먼저 확인하면 상황이 달라집니다. 한도를 우회하는 것이 아니라, 모델별로 나뉜 제한과 인증 우선순위를 이해해 작업 흐름이 끊기는 구간을 줄이는 방법입니다.

한도는 세 갈래로 따로 계산됩니다

클로드 코드의 사용량 제한은 세 종류로 나뉘며 각각 독립적으로 소진됩니다 ¹.

• 세션 한도: 5시간 주기로 리셋되는 단기 제한입니다.
• 주간 전체 한도: 모든 모델의 사용량을 합산해 주간 단위로 계산합니다.
• 주간 모델별 한도: 최상위 모델에는 별도 주간 제한이 추가됩니다 ¹.

이 구조를 모르면 "한도가 찼다"는 말 하나로 모든 상황을 이해하기 어렵습니다. 실제 사용자 관찰 사례에 따르면 Max 5x 플랜 사용자의 화면에서 세션 한도는 4%, 주간 전체 한도는 69%, 주간 모델(Fable) 한도는 89%로 표시된 경우가 있었습니다 ². 즉, 특정 모델의 한도가 거의 차더라도 전체 주간 한도에는 여유가 남아 있을 수 있습니다.

또한 웹 채팅, 데스크톱 앱, 클로드 코드에서 사용한 양은 모두 같은 한도에 합산됩니다 ². 클로드 채팅을 많이 하면 코드를 작성할 수 있는 잔여량도 함께 줄어듭니다. 반대로 서브에이전트를 여러 개 실행하는 복잡한 작업은 5시간 세션이 리셋되기 전에 주간 한도를 먼저 소진시킬 수 있습니다 ¹.

모델 교체로 이어 갈 수 있는 경우

한도에 걸렸을 때 가장 먼저 확인할 것은 "어떤 한도"에 도달했느냐입니다.

모델별 한도에만 걸렸을 때

최상위 모델(Opus, Sonnet, Fable 등)에만 적용되는 별도 주간 한도에 도달했다면, Claude Code 세션에서 /model 명령으로 다른 계열 모델로 전환해 즉시 작업을 이어갈 수 있습니다 ¹. 앞서 본 사례처럼 주간 모델 한도는 89%지만 주간 전체 한도가 69%인 경우, 아직 여유가 있는 다른 모델로 바꿔 전체 한도 내에서 작업을 계속할 수 있습니다 ².

다만 주의할 점이 있습니다. 모델마다 프롬프트 캐시가 분리되어 있어, 전환 직후 첫 요청은 기존 대화 내용을 캐시 없이 다시 읽게 됩니다. 긴 대화 세션에서는 이 한 번의 처리 비용이 발생할 수 있습니다 ³.

세션 또는 주간 전체 한도에 걸렸을 때

세션 한도와 주간 전체 한도는 모든 모델이 공유합니다. 따라서 이 두 제한에 도달하면 가벼운 모델로 바꿔도 작업이 차단된 상태가 유지됩니다 ¹. 다만 평소보다 가벼운 모델을 사용하면 한도가 소진되는 속도를 늦출 수 있습니다.

'사용 크레딧'은 리셋권이 아닌 종량제 전환입니다

모델 교체로 해결되지 않는 세션·주간 한도 구간에서 작업을 계속하려면 '사용 크레딧' 기능을 사용할 수 있습니다.

이 기능은 이름을 오해하기 쉽지만, 이미 차버린 한도를 초기화해 주는 것이 아닙니다. Anthropic 고객센터 설명에 따르면, 사용 크레딧은 "플랜의 사용 한도에 도달한 뒤 종량제 가격으로 전환해 계속 작업할 수 있게" 해 주는 기능입니다 ³. 즉, 차단되는 대신 표준 API 요금으로 결제 방식이 바뀌는 스위치입니다.

자동 이어 가기 기능 활용하기

크레딧을 쓰지 않고 기다리는 것도 방법입니다. Claude Code v2.1.234 버전부터는 리셋 시각까지 기다렸다가 자동으로 작업을 재개하는 기능이 기본적으로 켜져 있습니다 ³.

• 세션을 열어 두면 하단에 Usage limit reached · continuing automatically at 3:45pm과 같은 메시지가 뜨고, 리셋 시각에 맞춰 멈췄던 작업을 자동으로 이어갑니다.
• 컴퓨터가 30분 이상 잠들었다면 Enter 키를 눌러야 재개됩니다.
• 주간 한도처럼 리셋까지 24시간 이상이 남았거나, 백그라운드에서 실행되는 경우는 자동 재개가 동작하지 않습니다 ³.

사용 크레딧을 켜면 구독료와 별도로 요금이 청구됩니다. Claude Code는 매 요청마다 대화 전체를 전송하므로, 긴 대화일수록 토큰 비용이 커질 수 있습니다. 예상치 못한 지출을 막기 위해 월 지출 한도(spend limits)를 미리 설정해 두는 것이 권장됩니다 ³.

7단계 인증 우선순위가 과금 경로를 결정합니다

구독과 API 키를 함께 쓰는 환경에서는 과금 경로가 의도치 않게 API로 설정되는 경우가 많습니다. 클로드 코드는 자동으로 경로를 전환하지 않으며, 설정된 자격 증명 중 우선순위가 가장 높은 하나를 선택합니다.

2026년 10월 10일 기준 인증 문서에 정리된 우선순위는 다음과 같습니다 ⁴.

ANTHROPIC_API_KEY(3단계)가 환경 변수에 남아 있고, /login을 통해 구독(7단계)에 로그인해 있다면 요청은 API 키로 처리됩니다.

• 대화형 모드: Claude Code가 API 키를 사용할지 한 번 물어보며, 승인하면 그 선택이 기억됩니다 ⁴.
• 비대화형 모드(claude -p, CI 등): 확인 과정 없이 항상 API 키를 사용합니다 ⁴.

노트북에서 대화할 때는 구독을 쓰는데, 백그라운드 자동화 스크립트는 API 요금이 나가 비용이 발생하는 이유가 여기에 있습니다. 현재 세션이 어떤 자격 증명을 쓰는지 확인하려면 Claude Code에서 /status를 입력하면 됩니다. 로그인 정보와 API 키가 모두 있을 경우, 현재 사용하지 않는 쪽은 '사용 안 함'으로 표시됩니다 ⁴.

스크립트도 구독 한도로 실행하기: setup-token

자동화 작업도 API 비용 없이 구독 한도 안에서 처리하고 싶다면 claude setup-token을 사용할 수 있습니다. 이 명령어는 구독 인증용 OAuth 토큰을 생성해 주며, 생성된 토큰은 화면에 표시만 되고 저장되지 않습니다.

# 1. 토큰 발급 후 복사
claude setup-token

# 2. 환경 변수에 저장하고, 기존 API 키는 삭제하여 우선순위 충돌 방지
export CLAUDE_CODE_OAUTH_TOKEN="복사한_토큰"
unset ANTHROPIC_API_KEY

# 3. 구독 한도로 실행 확인
claude -p "테스트 실패 원인을 요약해 줘"

여기서 unset ANTHROPIC_API_KEY가 중요합니다. CLAUDE_CODE_OAUTH_TOKEN(5단계)보다 ANTHROPIC_API_KEY(3단계)의 우선순위가 높으므로, API 키가 남아 있으면 여전히 API 요금이 청구되기 때문입니다 ⁴.

프록시를 통한 모델 분리 구성

한도 관리와는 별개로, 작업 유형에 따라 모델을 나누어 배정하고 싶다면 LiteLLM 같은 프록시를 활용할 수 있습니다. Claude Code의 ANTHROPIC_BASE_URL을 프록시 서버 주소로 설정하고, ANTHROPIC_AUTH_TOKEN에 발급받은 가상 키를 넣으면 요청이 프록시를 거치게 됩니다 ⁵⁶.

이 방식을 사용하면 고가 모델(Opus 등)은 원본 API로 그대로 통과시키고, 저가 모델(Haiku 등) 경로는 DeepSeek 같은 대체 모델로 매핑하는 구성이 가능합니다 ⁷⁵. 이를 통해 클로드 코드 내부의 서브에이전트 기능은 유지하면서, 비용이 드는 메인 대화만 상위 모델을 쓰는 식으로 운영할 수 있습니다 ⁷. 다만 프록시를 사용하는 경우 ANTHROPIC_AUTH_TOKEN이 우선순위 2단계이므로, 구독이 아닌 게이트웨이 운영자에게 요금이 청구된다는 점을 명확히 해야 합니다 ⁴.

결론: /status로 현재 경로 확인부터 시작합니다

클로드 코드에서 한도 관리는 단순한 사용량 조절이 아니라, 어떤 자격 증명으로 요청이 나가는지 통제하는 문제입니다. 모델별 한도에는 막혔다면 /model로 다른 모델 전환이 가능합니다. 세션이나 주간 전체 한도라면 크레딧으로 종량제 전환을 하거나 자동 재개를 기다려야 합니다.

가장 먼저 할 일은 /status를 열어 현재 인증 방식이 구독인지 API 키인지 확인하는 것입니다. 의도와 달리 API로 청구되고 있다면 셸 환경 변수, .env 파일, settings.json 등에서 키가 주입되고 있는지 추적해 보세요.