Claude Code Max 구독 사용하기

Claude Code Max 구독 사용하기

Claude Code Max 구독 트래픽을 LiteLLM AI Gateway를 통해 라우팅하는 방법을 알려드릴게요. Max 구독을 쓰면서도 사용량 추적과 예산 관리, 안전 제어까지 모두 LiteLLM에서 처리할 수 있어요.

출처: 문서

본문

직접 API 대신 Claude Code Max를 쓰는 이유

  • 비용 절감 — Claude Code Max 구독은 토큰 단위 API 요금보다 Claude Code 파워 유저에게 더 저렴해요

LiteLLM으로 라우팅하는 이유

  • 비용 귀속(Cost attribution) — 사용자, 팀, 키 단위로 지출을 추적할 수 있어요

  • 예산 및 속도 제한 — 지출 상한과 요청 제한을 설정할 수 있어요

  • 가드레일(Guardrails) — 모든 요청에 콘텐츠 필터링과 안전 제어를 적용할 수 있어요

빠른 시작 영상

Claude Code를 LiteLLM Gateway로 설정하는 전체 과정을 처음부터 끝까지 설명하는 영상을 시청해 보세요.

사전 요구 사항

  • Claude Code 설치

  • Claude Max 구독

  • LiteLLM Gateway 실행

1단계: LiteLLM Proxy 구성하기

핵심 설정인 forward_client_headers_to_llm_api: true가 들어간 config.yaml을 만들게요.

config.yaml

model_list:  - model_name: anthropic-claude    litellm_params:      model: anthropic/claude-sonnet-5  - model_name: claude-sonnet-5    litellm_params:      model: anthropic/claude-sonnet-5  - model_name: claude-opus-5    litellm_params:      model: anthropic/claude-opus-5general_settings:  master_key: os.environ/LITELLM_MASTER_KEY  forward_client_headers_to_llm_api: true  # Required: forwards OAuth token to Anthropic

forward_client_headers_to_llm_api는 왜 필요한 걸까요?

이 설정은 사용자의 OAuth 토큰(Authorization 헤더에 담긴)을 LiteLLM을 통해 Anthropic API로 전달해 주는 역할을 해요. 덕분에 LiteLLM이 추적과 제어를 담당하면서도, 각 사용자가 자신의 Max 구독으로 인증을 처리할 수 있어요.

2단계: LiteLLM Proxy 시작하기

LiteLLM Proxy를 시작해 볼게요.

litellm --config /path/to/config.yaml# RUNNING on http://0.0.0.0:4000

전체 과정(Walkthrough)

1부: LiteLLM에서 가상 키(Virtual Key) 만들기

LiteLLM Dashboard로 이동해서 Claude Code용 가상 키를 새로 만들어 볼게요.

1.1 가상 키 페이지 열기

LiteLLM Dashboard의 Virtual Keys 섹션으로 이동해요.

1.2 "Create New Key" 클릭하기

1.3 키 세부 정보 구성하기

키 이름(예: claude-code-test)을 입력하고, 접근을 허용할 모델을 선택해요.

1.4 모델 선택하기

이 키로 접근할 수 있게 할 Anthropic 모델을 선택해요(예: anthropic-claude, claude-4.5-haiku).

1.5 모델 선택 확인하기

1.6 키 생성하기

"Create Key"를 클릭해서 가상 키를 생성해요. 생성된 키 값(예: «redacted:sk-…»)을 복사해 두세요.

2부: Claude Code Max 플랜에 로그인하기(클라이언트 측)

Claude Code 환경 변수를 설정하고 Max 구독으로 인증해 볼게요.

2.1 환경 변수 설정하기

가상 키와 함께 LiteLLM Gateway를 사용하도록 Claude Code를 구성해요.

Claude Code 환경 변수 구성

export ANTHROPIC_BASE_URL=http://localhost:4000export ANTHROPIC_MODEL="anthropic-claude"export ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: *** «redacted:sk-…»"

환경 변수 설명

| 변수 | 설명 | | ANTHROPIC_BASE_URL | Claude Code가 LiteLLM Gateway 엔드포인트를 가리키게 해요 | | ANTHROPIC_MODEL | LiteLLM config.yaml에 구성된 모델 이름이에요 | | ANTHROPIC_CUSTOM_HEADERS | LiteLLM 인증용 x-litellm-api-key 헤더예요 |

2.2 Claude Code 실행하기

Claude Code를 시작해요.

Claude Code 실행

claude

2.3 로그인 방법 선택하기

"Claude account with subscription"(Pro, Max, Team 또는 Enterprise)을 선택해요.

2.4 브라우저에서 승인하기

Claude Code가 브라우저를 열어 인증을 진행해요. "Authorize"를 클릭해서 Claude Max 계정을 연결해요.

2.5 로그인 성공

인증이 끝나면 로그인 성공 확인 화면이 나와요.

2.6 설정 완료

Enter를 눌러 보안 안내를 지나고 설정을 완료해요.

3부: LiteLLM과 함께 Claude Code 사용하기

이제 Claude Code를 평소처럼 사용하면 되고, 모든 요청이 LiteLLM에서 추적돼요.

3.1 Claude Code에서 요청 보내기

Claude Code를 사용하기 시작하면 요청이 LiteLLM Gateway를 통해 흘러가요.

3.2 LiteLLM Dashboard에서 로그 확인하기

LiteLLM Dashboard의 Logs 페이지로 이동해 모든 Claude Code 요청을 확인할 수 있어요.

3.3 요청 세부 정보 확인하기

요청을 클릭하면 토큰, 비용, 소요 시간, 사용된 모델 등 상세 정보를 볼 수 있어요.

로그에는 다음과 같은 내용이 표시돼요:

  • Key Name: claude-code-test(생성한 가상 키)

  • Model: anthropic/claude-sonnet-4-20250514

  • Tokens: 65012 (프롬프트 64679 + 완성 333)

  • Cost: $0.249754

  • Status: Success

동작 원리

LiteLLM Gateway는 두 가지 유형의 인증을 처리해요:

  • x-litellm-api-key: LiteLLM으로 요청을 인증해요(사용량 추적, 예산, 속도 제한)

  • OAuth 토큰(Authorization 헤더): Claude Max 인증을 위해 Anthropic API로 전달돼요

헤더 흐름

| 헤더 | 용도 | 처리 주체 | | x-litellm-api-key | LiteLLM Gateway 인증, 예산 추적, 속도 제한 | LiteLLM | | Authorization: Bearer {oauth... | Claude Max 구독 인증 | Anthropic API |

완전한 요청 흐름 예시

Claude Code가 LiteLLM을 통해 호출할 때의 전형적인 요청 모습을 보여드릴게요.

Claude Code에서 LiteLLM으로의 요청 예시

curl -X POST "http://localhost:4000/v1/messages" \  -H "x-litellm-api-key: *** «redacted:sk-…»" \  -H "Authorization: Bearer oauth_...plan" \  -H "Content-Type: application/json" \  -d '{    "model": "anthropic-claude",    "max_tokens": 1024,    "messages": [{"role": "user", "content": "Hello, Claude!"}]  }'

그러면 LiteLLM은 다음 작업을 수행해요:

  • Gateway 접근을 위해 x-litellm-api-key를 검증해요

  • 사용량 추적을 위해 요청을 기록해요

  • (forward_client_headers_to_llm_api: true 때문에) OAuth Authorization 헤더와 함께 요청을 Anthropic으로 전달해요

고급 구성

모델별 헤더 전달

더 세밀한 제어가 필요하다면 특정 모델에 대해서만 헤더 전달을 활성화할 수 있어요.

config.yaml - 모델별 헤더 전달

model_list:  - model_name: anthropic-claude    litellm_params:      model: anthropic/claude-sonnet-5  - model_name: claude-opus-5    litellm_params:      model: anthropic/claude-opus-5general_settings:  master_key: os.environ/LITELLM_MASTER_KEYlitellm_settings:  model_group_settings:    forward_client_headers_to_llm_api:      - anthropic-claude      - claude-opus-5

예산 제어

Max 구독을 사용하면서 사용자별 예산을 설정해 볼게요.

config.yaml - 예산 추적용 데이터베이스와 함께

model_list:  - model_name: anthropic-claude    litellm_params:      model: anthropic/claude-sonnet-5general_settings:  master_key: os.environ/LITELLM_MASTER_KEY  forward_client_headers_to_llm_api: true  database_url: "postgresql://..."

그리고 예산이 설정된 가상 키를 만들게요.

예산이 있는 가상 키 생성

curl -X POST "http://localhost:4000/key/generate" \  -H "Authorization: Bearer $LITEL..._KEY" \  -H "Content-Type: application/json" \  -d '{    "key_alias": "developer-1",    "max_budget": 100.00,    "budget_duration": "monthly"  }'

문제 해결

OAuth 토큰이 전달되지 않는 경우

증상(Symptom): Anthropic API에서 인증 오류 발생

해결 방법: config에서 forward_client_headers_to_llm_api: true가 설정됐는지 확인해요.

config.yaml - 헤더 전달 활성화

general_settings:  forward_client_headers_to_llm_api: true

LiteLLM 인증 실패

증상: LiteLLM Gateway에서 401 오류 발생

해결 방법: ANTHROPIC_CUSTOM_HEADERS에 x-litellm-api-key 헤더가 올바르게 설정됐는지 확인해요.

키 정보 확인

curl -X GET "http://localhost:4000/key/info" \  -H "Authorization: Bearer ***"

모델을 찾을 수 없는 경우

증상: 모델을 찾을 수 없다는 오류

해결 방법: ANTHROPIC_MODEL이 config의 모델 이름과 일치하는지 확인해요.

사용 가능한 모델 목록

curl "http://localhost:4000/v1/models" \  -H "Authorization: Bearer ***"

더 알아보기 (Learn more)