멈추지 않는 AI 개발 환경: Claude Code 주간 한도에도 안 끊기는 프록시 구축기

멈추지 않는 AI 개발 환경: Claude Code 주간 한도에도 안 끊기는 프록시 구축기

새벽 세 시, 자율 에이전트에게 밤새 작업을 맡겨두고 잠들었는데 아침에 열어보니 파이프라인이 429 에러로 멈춰 있던 적이 있으신가요. 화면엔 "한도 초과"라는 문구뿐이고, 다음 세션 창이 열릴 때까지 손 놓고 기다리는 수밖에 없습니다. Claude 유료 구독은 5시간 단위로 도는 세션 한도 위에 별도의 주간 한도가 얹혀 있고, 이 사용량은 웹·데스크톱·모바일·Claude Code를 가리지 않고 하나의 총량으로 합산됩니다 (출처: Anthropic 공식 고객센터 문서). 그래서 "멈추지 않는 AI 개발 환경"을 목표로 로컬 프록시를 직접 포크해서 손봤습니다.

문제: 세션 한도와 주간 한도, 이중으로 막힌다

Claude 유료 플랜은 5시간마다 돌아가는 세션 한도와, 그 위에 별도로 존재하는 주간 한도라는 두 겹의 벽을 갖고 있습니다. 이 두 한도는 웹, 데스크톱 앱, 모바일, Claude Code까지 한 계정의 사용량을 전부 하나의 풀로 묶어 계산합니다 (출처: support.anthropic.com). 낮에 Claude Code로 코딩을 많이 했다면 저녁에 웹에서 던진 질문 하나로도 한도가 훌쩍 넘어갈 수 있다는 뜻입니다. 진짜 문제는 한도에 걸리는 순간입니다. 세션이 그대로 멈추고, 리셋 시간까지 사람이 옆에서 지켜보는 수밖에 없습니다. 밤새 자율로 돌리려던 작업일수록 타격이 큽니다.

해법 구조: 여러 구독을 하나의 프록시 뒤로 묶는다

teamclaude는 Claude Code와 Anthropic API 사이에 로컬 리버스 프록시(요청을 그대로 전달하며 트래픽을 관리하는 서버)를 하나 세우는 방식입니다. Claude Code는 API 서버에 직접 붙는 대신 이 프록시를 거치고, 프록시가 정당하게 보유한 여러 구독 계정 중 하나를 골라 요청을 대신 넘깁니다. 설정에서 ANTHROPIC_BASE_URL(커스텀 엔드포인트를 지정하는 환경변수) 하나만 프록시 주소로 바꾸면 되는데, 이는 Anthropic 공식 문서가 안내하는 정식 경로입니다 (출처: docs.anthropic.com/en/docs/claude-code). 계정 선택은 단순 순번 돌리기가 아니라 "use-or-lose"입니다. 임계값 아래 계정 중 주간 쿼터가 가장 빨리 리셋되는, 즉 안 쓰면 곧 버려질 여유분부터 먼저 씁니다. 이 판단은 API 응답에 실려오는 anthropic-ratelimit 계열 헤더만으로 이뤄지는데, 잔여 한도를 헤더로 알리고 초과 시 429와 retry-after를 반환하는 것 자체가 Anthropic 공식 스펙입니다 (출처: docs.anthropic.com/en/api/rate-limits). 의존 패키지 없이 Node.js 내장 모듈만으로 짰습니다.

장애 내성 엔지니어링: 포크가 더한 것

원본 프로젝트 위에 제가 얹은 건 크게 네 갈래입니다. 최상위 모델인 Fable, Mythos는 별도의 주간 한도로 관리되는데, 이 창을 모델별로 정확히 인식해 라우팅하도록 손봤습니다. 최상위 모델이 실재하며 구독제에서 별도 주간 한도를 받는다는 사실은 Anthropic 뉴스에서도 확인됩니다 (출처: anthropic.com/news). 모델 폴백 체인도 넣어 함대 전체가 한 모델의 쿼터를 소진하면 다른 모델로 조용히 내려서라도 응답을 이어가되, 판단이 중요한 인터랙티브 세션은 Opus 아래로 내리지 않도록 일부러 막았습니다. 품질을 슬쩍 낮추기보다 잠깐 멈추고 재시도하는 편이 낫다고 봤습니다. 종료 신호를 받으면 5초 안에 프로세스를 정리하는 유한 종료도 넣어 배포 도중 프록시가 오래 물려 있지 않게 했고, 스트림 시작 전 네트워크가 끊기면 연결을 끊는 대신 다른 계정으로 바로 넘겨 응답이 갑자기 멈추는 상황을 줄였습니다.

설치했다고 끝이 아니다

포크를 처음 배포했을 때 겪은 일입니다. 코드는 최신인데 프록시가 자꾸 죽어 있었습니다. 원인은 설치 방식이었습니다. 전역 설치를 심볼릭 링크(원본 파일을 가리키기만 하는 바로가기) 방식으로 하면 링크가 사용자 문서 폴더 아래를 가리키는데, macOS는 TCC(문서·사진 폴더를 앱이 함부로 못 읽게 막는 보안 장치)로 이 폴더를 보호합니다. launchd 같은 백그라운드 실행 관리자는 화면 없이 부팅 초기에 뜨기 때문에 동의 창을 띄울 수 없고, 프록시가 그 경로를 못 읽어 죽었다 살아났다를 반복했습니다. 해결은 파일을 실제로 복사하는 tarball 설치로 바꾸고 재시작하는 것이었습니다. 재시작은 걱정할 게 없습니다. 쿼터 상태가 파일에 저장돼 있다가 재시작 시 복원되고, 짧은 시간 안에 계정 전체의 잔여 한도가 다시 측정됩니다. 이 사고 이후 배포 절차에 재기동 확인을 못박고, 회귀 방지 테스트를 165개까지 늘렸습니다. 배포는 설치가 아니라 재기동까지입니다.

멈추지 않는 AI 개발 환경, 지금부터

결국 하고 싶었던 건 하나였습니다. 한도가 찼다고, 네트워크가 잠깐 끊겼다고 밤새 돌리던 작업이 멈추지 않는 환경입니다. 여러 구독을 정당하게 풀링하고, 쿼터 헤더를 읽어 계정을 옮기고, 모델이 막히면 폴백하고, 스트림이 끊기기 전에 계정을 바꾸는 장치 하나하나가 결국 멈추지 않는 AI 개발 환경을 만들기 위한 것입니다. QJC는 이런 자동화와 AI 전환 작업을 실제로 설계하고 구축합니다. 지금 qjc.app에서 멈추지 않는 AI 개발 환경을 확인해보세요.