클로드 코드 무인 재시도 모드가 일찍 풀린 사용 한도를 알아채게 하는 환경변수 설정법

클로드 코드(Claude Code)를 CI나 야간 작업처럼 사람 없이 무인 재시도 모드(CLAUDE_CODE_RETRY_WATCHDOG=1)로 돌리면, 사용 한도에 걸린 요청은 리셋 시각까지 그대로 기다린다. 10월 20일 나온 2.1.305의 CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS를 설정해 두면 기다리는 동안 한도가 먼저 풀렸는지 확인하고, 풀렸으면 요청을 바로 보낸다.

export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=600000  # 최소 10분 간격으로 확인

값에는 확인 사이의 최소 간격을 밀리초 정수로 넣는다. 60000(1분)부터 10800000(3시간)까지 받고, 비워 두거나 범위를 벗어나면 확인하지 않는다.

조건이 있다.

• claude.ai 구독의 세션 한도나 주간 한도에서만 확인한다. 사용 크레딧(usage credits)을 쓰는 중에는 확인하지 않는다.
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정했으면 확인하지 않는다.
• 2.1.305 이상에서 동작한다.

리셋까지 너무 오래 남았을 때 기다리지 않고 끝내려면 2.1.301의 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS를 같이 설정한다.