Claude Code, Cline, Cursor를 단일 OpenAI 호환 엔드포인트로 통합하기

Claude Code나 Cline, Cursor 같은 코딩 에이전트를 사용하다 보면 작업 도중에 이용 한도에 도달하는 경우가 있습니다.

5시간 또는 7일 단위의 이용 한도는 리셋 시간까지 기다리는 것 외에는 방법이 없습니다. 게다가 소비량은 요청 토큰 수에 의존하기 때문에, 같은 작업을 해도 '오늘은 왜 이렇게 빨리 다 떨어졌지'라는 느낌을 받기 쉽고 사전에 파악하기 어려운 것이 현실입니다.

본문에서는 구독(Subscription)을 주축으로 유지하면서, 이용 한도가 소진되었을 때만 종량제(Pay-as-you-go) 엔드포인트로 전환하는 구성을 다룹니다. 클라이언트 측 설정은 몇 줄로 간단하며, 기존 워크플로우를 변경하지 않고도 도입할 수 있습니다.

저는 JZS Token (jzstoken.com)이라는 API 엔드포인트를 제공하는 입장에서 이 글을 작성했습니다. 아래에서는 자사 서비스를 예시로 사용한 부분이 있습니다.

다만, 이 글의 주제는 특정 서비스 소개가 아니라 구성 설계입니다. base URL을 변경하면 다른 OpenAI / Anthropic 호환 엔드포인트에서도 동일한 구성을 적용할 수 있습니다. 설정 절차는 독자가 사용하는 임의의 엔드포인트에 맞춰 읽어주시기 바랍니다.

먼저 혼동하기 쉬운 점들을 정리하겠습니다.

즉, Rate Limit에 도달했을 때 다른 엔드포인트로 전환하는 대처는 유효하지만, Context Limit에는 효과가 없습니다. /clear

또는 서브 에이전트(sub-agent), Plan 모드와 같은 절약 기술은 어떤 엔드포인트를 사용하더라도 계속 필요합니다.

본문에서 다루는 것은 위의 표 상단에 있는 제한만 해당합니다.

아이디어는 간단합니다.

• 평소에는 지금까지처럼 구독 인증으로 Claude Code를 구동한다.
• 환경 변수에 전환할 엔드포인트의 base URL과 키를 준비해 둔다.
• 이용 한도에 도달한 세션만 해당 엔드포인트를 향해 재개한다.

핵심은 구독 인증을 깨뜨리지 않는 것입니다. 나중에 설명하겠지만, ANTHROPIC_API_KEY를 셸 프로파일에서 전역적으로 export하면 구독 인증보다 우선하여 인증 오류가 발생합니다. 전환은 셸 단위 또는 세션 단위로 한정할 수 있습니다.

Claude Code는 다른 도구와 달리 base URL에 /api/v1을 붙이지 않습니다. Claude Code 측이 /v1/messages를 자동으로 붙이기 때문에, 붙이면 404 에러가 발생합니다. 이 부분은 처음에 반드시 걸리는 포인트입니다.

export ANTHROPIC_BASE_URL=

# 해서는 안 되는 것: 모든 셸에서 덮어쓰기
~/.zshrc에 export ANTHROPIC_API_KEY=...를 작성하는 것
권장 사항: 전환하고 싶은 세션에서만 유효하게 하기
...

현재 어떤 인증이 유효한지는 `claude /status`로 확인할 수 있습니다.

외부 엔드포인트로 전환하는 동안에는 Status Line의 5시간/7일 창 표시가 비어 있거나 실제와 맞지 않는 값이 됩니다. 이는 구독(subscription) 인증을 전제로 한 값이기 때문입니다. 같은 이유로 세션 비용도 추정치이며, 청구 금액과는 일치하지 않습니다.

종량제(pay-as-you-go) 측으로 전환하는 동안에는 응답의 `usage` (input / output / cache)나 잔액을 표시하는 것이 실제 측정에 가깝습니다.

적합한 경우.

- 사용 할당량에 도달하는 빈도가 높아, 리셋 대기 시간이 실제 작업을 멈추게 하는 경우
- 세션 소비량을 청구서가 아닌 요청 단위로 보고 싶은 경우
- 여러 코딩 에이전트를 동일한 키 체계로 통합하고 싶은 경우

부적합한 경우.

- 월 사용량이 적어 구독 할당량 안에 포함되는 경우 (종량제가 더 비쌉니다)
- 기밀 정보를 외부에 노출할 수 없는 경우 (로컬 LLM이나 셀프호스팅을 고려해 주세요)
- 구독 할당량 내에서 완결시키고 싶은 경우 (이 구성은 할당량을 늘리는 것이 아니라, 할당량이 소진되었을 때의 비상 탈출구입니다).

- 레이트 제한(Rate Limit)과 컨텍스트 제한(Context Limit)은 성질이 다릅니다. 엔드포인트 전환이 적용되는 것은 전자인 경우뿐입니다.
- Claude Code의 base URL에는 `/api/v1`을 붙이지 않습니다. 다른 클라이언트는 붙입니다 -
`ANTHROPIC_API_KEY`
글로벌 export는 구독 인증을 망가뜨립니다. 스코프를 분리하세요 - 병용 구성의 목적은 할당량을 늘리는 것이 아니라 작업이 멈추지 않게 하는 것입니다.

같은 구성을 다른 엔드포인트로 만든 예시나, '여기서 막혔다'는 사례가 있다면 댓글로 알려주세요.