클로드 코드 사용량 한도에 걸렸을 때

클로드 코드를 쓰다가 작업 흐름이 끊길까 걱정되는 분께 맞는 기록입니다. 특히 글 작성, 코드 수정, 배치 작업처럼 한 세션에서 끝날 듯했던 일이 예상보다 길어질 때 사용량은 더 신경 쓰이게 됩니다.

한도 관리는 한 번 설정하고 끝나는 일이 아닙니다. 계정으로 쓰는 방식, 세션에 쌓인 맥락, 자동화 작업 수가 맞물리므로 작업 중에도 상태를 확인해야 합니다. 화면에 뜨는 메시지와 문서 설명 사이에는 놓치기 쉬운 지점도 있습니다.

먼저 결론부터

• 구독 계정으로 클로드 코드를 쓸 때는 주 단위 한도에 걸릴 수 있으며, 한도 메시지에 해제 시각이 함께 표시됩니다.
• 실제로 확인한 한도 문구는 주간 한도와 오후 3시 초기화 시각을 동시에 알려 줬습니다.
• API 문서의 RPM, ITPM, OTPM, 월 지출 상한은 구독 요금제의 주간 한도와 별도 체계입니다.
• 세션에서는 아래 명령으로 누적 토큰·비용과 현재 컨텍스트 창 사용량을 확인할 수 있습니다.

/usage
/cost
/context

• 배치 작업은 모델을 고정해야 기본값에 따라 무거운 모델이 선택되는 낭비를 줄일 수 있습니다.

--model sonnet

• 여러 에이전트를 병렬로 돌리는 자동화는 한도 소모 속도까지 작업 계획에 넣어야 합니다.

한도 문구를 실제로 확인했다

기록을 남깁니다.

9월 18일 오전 10시 56분, 글을 모두 쓰고 커밋하기 직전에 세션이 죽었으며 마지막 줄에 아래 문구가 표시되어, 구독 계정으로 돌리던 작업에도 주 단위 한도가 있고 해제 시각이 메시지 안에 함께 나온다는 점을 실제로 확인했습니다.

문구는 아래와 같습니다.

You've hit your weekly limit · resets 3pm

이 메시지는 기다려야 할 시점을 알려 줍니다. 우리 사례에서는 오후 3시에 다시 쓸 수 있었습니다. 사용량 숫자만 확인하다가 세션이 끊기면 당황하기 쉬운데, 한도에 도달한 뒤에는 이 문구의 초기화 시각을 먼저 확인하면 됩니다.

계정 방식마다 한도가 다릅니다

여기서 갈립니다.

API 문서가 설명하는 한도는 분당 요청 수인 RPM, 입력 토큰 수인 ITPM, 출력 토큰 수인 OTPM, 월 지출 상한으로 구성되며, 구독 요금제에서 클로드 코드를 돌릴 때 마주치는 주간 한도와는 다른 기준으로 움직입니다.

계정 방식을 확인하세요.

API 키로 호출 중이라면 API 문서의 제한 항목을 봐야 합니다. 구독 계정으로 클로드 코드를 실행 중이라면 화면의 한도 메시지와 초기화 시각이 직접적인 기준입니다. 두 체계를 섞어 보면 현재 왜 멈췄는지 판단하기 어렵습니다.

세션 안에서 확인하는 숫자

세션 상태는 명령으로 볼 수 있습니다.

/usage
/cost
/context

첫 두 명령은 누적 토큰과 비용을 보여 줍니다. 세 번째 명령은 현재 컨텍스트 창을 얼마나 쓰고 있는지 그림으로 보여 줍니다. 작업이 길어질수록 컨텍스트 상태를 함께 보는 편이 좋습니다.

반복해서 넣는 내용은 프롬프트 캐싱으로 입력 토큰을 줄일 수 있습니다. 필요 없는 MCP 도구를 띄우지 않는 것도 문서가 권하는 방법입니다. 컨텍스트 창에 남겨 둘 정보와 도구를 작업 단위로 고르면 세션 부담을 줄일 수 있습니다.

모델을 고정하면 낭비를 막는다

원인을 찾았습니다.

우리는 배치에서 모델을 지정하지 않아 기본값에 따라 무거운 모델이 쓰이고 있었고, 모델을 고정한 뒤에는 작업 성격에 맞지 않는 선택으로 사용량이 커지는 낭비가 사라졌습니다.

고정값을 넣었습니다.

--model sonnet

쓸 수 있는 값에는 아래 별칭이 있습니다.

sonnet
opus
haiku
opusplan
opus[1m]

opusplan은 계획할 때 무거운 모델을 쓰고 실행할 때 가벼운 모델을 씁니다. 별칭 뒤에 [1m]을 붙이면 확장 컨텍스트를 씁니다. 세션 안에서는 다음처럼 모델을 바꿀 수 있습니다.

/model sonnet

모델 선택 우선순위는 세션 명령, 실행 플래그, 환경변수, 설정 파일 순입니다. 스킬과 서브에이전트는 별도 컨텍스트를 쓰므로 본 세션의 컨텍스트 부담도 줄어듭니다.

병렬 작업 수가 한도를 앞당긴다

자동화는 편리합니다.

우리는 하루 12편을 여섯 체인으로 병렬 처리하며, 한도에 걸린 날도 이 방식으로 작업하던 날이었습니다. 여러 에이전트가 동시에 일을 시작하면 각 작업의 사용량이 함께 쌓이므로, 단일 세션을 쓸 때와 같은 속도로 한도가 줄어들지 않습니다.

작업량을 나눠 보세요. 급하지 않은 체인은 초기화 시각 뒤로 보내고, 당장 필요한 체인에는 모델 고정과 컨텍스트 점검을 먼저 적용하는 편이 안전합니다.

마무리

다음 작업 전에 계정 방식부터 적어 두고, 배치 실행 명령에는 사용할 모델을 명시해 두는 편이 좋습니다. 자동화 체인이 많다면 한 번에 돌릴 체인 수와 멈춰도 되는 작업을 나누면, 한도에 걸린 뒤 작업 순서를 다시 정하는 시간을 줄일 수 있습니다.

이번에 직접 확인한 한도 문구는 API 문서에 적힌 제한 체계와 대상이 다르기 때문에 그 문서에서 찾기 어렵습니다. API 문서는 요청과 토큰, 지출 제한을 설명하고, 구독 계정의 실제 세션 화면은 주간 한도와 초기화 시각을 알려 줍니다. 둘을 따로 기록해 두면 다음 중단 상황에서 훨씬 빨리 판단할 수 있습니다.