Claude Code 공식문서 리뷰-Deployment[6] : LLM 게이트웨이 구성(LLM gateway configuration)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [LLM 게이트웨이 구성]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/llm-gateway

LLM gateway configuration - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

LLM 게이트웨이 구성

• 용도: Claude Code와 모델 제공업체 사이의 중앙 집중식 프록시 계층
• 장점: API 키 관리, 사용량 추적, 비용 제어, 감사 로깅
• 지원 형식: Anthropic Messages, Bedrock, Vertex API

용어 설명: LLM 게이트웨이
AI 모델 호출을 중앙에서 관리하는 프록시 서비스이다. API 키 관리, 사용량 추적, 비용 제어, 감사 로깅 등을 중앙화할 수 있어 엔터프라이즈 환경에서 유용하다.

 

왜 LLM 게이트웨이가 필요한가?

실제 상황을 생각해보자

팀이 커지면서 이런 문제가 생기기 시작한다:

문제 1: API 키 관리의 혼란
• 개발자마다 각자의 API 키를 쓰고 있음
• 누가 얼마나 쓰는지, 누구 키가 비용을 많이 쓰는지 알 수 없음
• 퇴사자 API 키를 일일이 찾아서 제거해야 함

문제 2: 비용 폭탄
• 한 달에 $1,000 예산이었는데 어느새 $5,000 청구됨
• 어느 팀이, 어떤 프로젝트가 많이 썼는지 추적 불가
• 개발자들이 실수로 무한 루프 돌렸는데 막을 방법이 없음

문제 3: 규정 준수
• 금융/의료 분야에서 "누가 AI에 어떤 질문을 했는지" 로그가 필요함
• 하지만 각자 직접 API 쓰면 중앙에서 추적할 방법이 없음

이럴 때 LLM 게이트웨이가 답이다. 모든 AI 요청을 중앙 게이트웨이를 거치게 하면 위 문제를 한 번에 해결할 수 있다.

 

게이트웨이로 해결되는 것들

기능	실제 효과
중앙 집중식 인증	개발자들은 게이트웨이 토큰만 받으면 됨. 실제 Anthropic API 키는 게이트웨이에만 저장
사용량 추적	"프론트엔드 팀이 이번 달에 50만 토큰 썼네" - 팀/프로젝트별로 누가 얼마나 쓰는지 한눈에
비용 제어	"하루에 $100 이상 쓰면 자동 차단" - 예산 초과 방지
감사 로깅	규정 준수 감사 시 "이 기간에 이런 요청들이 있었다" 증빙 가능
모델 라우팅	AWS Bedrock에서 Google Vertex로 전환해도 개발자 코드 수정 불필요

게이트웨이는 언제 필요한가?

• 팀이 5명 이상: API 키 관리와 비용 추적이 필요해짐
• 규정 준수가 중요한 업계: 금융, 의료, 공공 등
• 여러 AI 제공업체를 쓰거나 전환 계획: Bedrock, Vertex, Anthropic 등
• 비용 예산 관리가 필요: 무제한 지출은 위험

 

게이트웨이 요구사항

LLM 게이트웨이가 Claude Code와 작동하려면 다음 요구사항을 충족해야 한다:

 

API 형식 지원

게이트웨이는 다음 API 형식 중 최소 하나를 노출해야 한다:

API 형식	엔드포인트	필수 전달 항목
Anthropic Messages	/v1/messages, /v1/messages/count_tokens	헤더: anthropic-beta, anthropic-version
Bedrock InvokeModel	/invoke, /invoke-with-response-stream	본문: anthropic_beta, anthropic_version
Vertex rawPredict	:rawPredict, :streamRawPredict, /count-tokens:rawPredict	헤더: anthropic-beta, anthropic-version

중요
헤더를 전달하지 않거나 본문 필드를 보존하지 않으면 기능이 감소하거나 Claude Code 기능을 사용할 수 없을 수 있다.

참고
Bedrock 또는 Vertex와 함께 Anthropic Messages 형식을 사용할 때 환경 변수 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 설정이 필요할 수 있다.

 

구성

모델 선택

기본적으로 Claude Code는 선택한 API 형식에 대한 표준 모델 이름을 사용한다. 게이트웨이에서 커스텀 모델 이름을 구성한 경우, 모델 구성 문서에 문서화된 환경 변수를 사용하여 커스텀 이름과 일치시킨다.

 

LiteLLM 구성

참고
LiteLLM은 서드파티 프록시 서비스이다. Anthropic은 LiteLLM의 보안이나 기능을 보증, 유지 관리 또는 감사하지 않는다. 자체 판단 하에 사용한다.

전제 조건

• Claude Code 최신 버전으로 업데이트
• LiteLLM Proxy Server 배포 및 접근 가능
• 선택한 제공업체를 통한 Claude 모델 접근

인증 방법

정적 API 키

# 환경에서 설정
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# 또는 Claude Code 설정에서
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

이 값은 Authorization 헤더로 전송된다.

 

헬퍼를 통한 동적 API 키

1. API 키 헬퍼 스크립트 생성:

#!/bin/bash
# ~/bin/get-litellm-key.sh

# 예: 볼트에서 키 가져오기
vault kv get -field=api_key secret/litellm/claude-code

# 예: JWT 토큰 생성
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

 

2. Claude Code 설정 구성:

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

 

3. 토큰 갱신 간격 설정:

# 매시간 갱신 (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

참고
이 값은 Authorization 및 X-Api-Key 헤더로 전송된다. apiKeyHelper는 ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY보다 우선순위가 낮다.

 

엔드포인트 구성

통합 엔드포인트 (권장)

LiteLLM의 Anthropic 형식 엔드포인트 사용:

export ANTHROPIC_BASE_URL=https://litellm-server:4000

장점:

• 로드 밸런싱
• 폴백
• 비용 추적 및 최종 사용자 추적의 일관된 지원

 

제공업체별 패스스루 엔드포인트

Claude API through LiteLLM

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic

 

Amazon Bedrock through LiteLLM

export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

 

Google Vertex AI through LiteLLM

export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

 

추가 리소스

리소스	설명
LiteLLM 문서	LiteLLM 공식 문서
Claude Code 설정	Claude Code 설정 옵션
엔터프라이즈 네트워크 구성	기업 네트워크 설정 가이드
서드파티 통합 개요	타사 서비스 연동 가이드

 

요약

항목	내용
용도	중앙 집중식 모델 접근 및 관리
주요 기능	인증 관리, 사용량 추적, 비용 제어, 감사 로깅
지원 API 형식	Anthropic Messages, Bedrock, Vertex
인증	정적 API 키 또는 동적 헬퍼 스크립트