LLM Gateway

Claude Code와 모델 제공자(Anthropic API, Cloud Provider) 사이에 위치하는 중앙 프록시 레이어. 인증, 사용량 추적, 비용 제어, 감사 로깅, 모델 라우팅을 한 곳에서 관리한다.

해당 개념이 필요한 이유

• 중앙 집중 인증: API 키를 각 개발자에게 배포하는 대신, LLM Gateway에서 일괄 관리
• 사용량 모니터링: 팀/프로젝트별 사용량을 한 곳에서 추적
• 비용 제어: 예산, rate limit을 LLM Gateway 레벨에서 설정
• 감사 로깅: 모든 모델 상호작용을 컴플라이언스용으로 기록
• 모델 라우팅: 코드 변경 없이 Cloud Provider 간 전환 가능

AS-IS

sequenceDiagram
    autonumber
    participant Dev1 as Developer 1
    participant Dev2 as Developer 2
    participant CC as Claude Code
    participant API as 모델 제공자

    Dev1->>CC: 요청 (자체 API Key)
    CC->>API: 직접 호출
    Dev2->>CC: 요청 (자체 API Key)
    CC->>API: 직접 호출

    Note over Dev1,API: 각 개발자가 개별 API Key 관리<br/>사용량 추적 불가, 비용 제어 어려움

TO-BE

sequenceDiagram
    autonumber
    participant Dev1 as Developer 1
    participant Dev2 as Developer 2
    participant CC as Claude Code
    participant GW as LLM Gateway
    participant API as 모델 제공자

    Dev1->>CC: 요청
    CC->>GW: LLM Gateway 경유
    GW->>GW: 인증, 로깅, rate limit 체크
    GW->>API: 인증된 요청 전달
    API-->>GW: 응답
    GW-->>CC: 응답 전달

    Dev2->>CC: 요청
    CC->>GW: LLM Gateway 경유
    GW->>API: 인증된 요청 전달
    API-->>GW: 응답
    GW-->>CC: 응답 전달

    Note over Dev1,API: 중앙에서 인증/비용/감사 일괄 관리

LLM Gateway vs Cloud Provider 역할 차이

LLM Gateway와 Cloud Provider(Bedrock/Vertex AI/Foundry)는 서로 다른 레이어이며 독립적으로 조합할 수 있다.

	LLM Gateway	Cloud Provider (Bedrock/Vertex/Foundry)
핵심 역할	LLM 요청의 트래픽 관리	조직의 인프라 정책 준수
구체적으로	비용 추적, 로깅, rate limit, fallback, 라우팅	기존 IAM/결제/보안 감사 체계 안에서 모델 사용
비유	고속도로 톨게이트 (차량 카운트, 요금 징수)	어떤 나라 도로를 쓸지 선택 (법률/규제 준수)
선택 기준	”LLM 사용을 중앙에서 관리하고 싶은가?"	"기존 클라우드 정책/계정 내에서 써야 하는가?”

Q) “Anthropic API 직접 호출하면 되는 거 아니야? Cloud Provider가 필요한 이유가 뭐야?”

Cloud Provider 없이 Anthropic API 직접 호출도 가능하다. Cloud Provider가 필요한 건 기업 환경의 제약 때문이다:

	Anthropic API 직접	Cloud Provider 경유
설정 난이도	간단 (API Key만 있으면 됨)	복잡 (IAM, VPC 등 설정 필요)
데이터 주권	Anthropic 인프라에서 처리	원하는 리전 선택 가능
기존 결제 체계	별도 Anthropic 결제	AWS/GCP 기존 청구서에 통합
보안 감사	Anthropic 대시보드	CloudTrail, Audit Logs 등 기존 보안 체계 활용
사내 정책	별도 SaaS 승인 필요할 수 있음	이미 승인된 클라우드 계정으로 사용 가능

많은 기업에서 “외부 SaaS에 직접 연결 금지, 승인된 Cloud Provider만 사용” 정책이 있어 Anthropic API 직접 호출이 정책적으로 불가능한 경우 Cloud Provider를 경유한다.

개인 개발자:  Claude Code → Anthropic API (충분함)
기업 환경:    Claude Code → Cloud Provider (보안/정책/비용 요구사항)

조합 가능한 구성:

1) Anthropic 직접              ← 개인/소규모
2) Cloud Provider만            ← 기업, 클라우드 정책 준수
3) LLM Gateway만               ← 비용/로깅 관리 필요
4) LLM Gateway + Cloud Provider ← 둘 다 필요한 기업

LLM Gateway의 독립성: 입구 포맷과 출구 Cloud Provider

LLM Gateway는 Anthropic이나 특정 Cloud Provider와 무관한 독립 소프트웨어이다. LLM Gateway 설정에서 결정하는 것은 두 가지:

• 입구: Claude Code → LLM Gateway에 보내는 API 포맷 (프로토콜)####
• 출구: LLM Gateway → 실제 모델을 호출하는 Cloud Provider (목적지)

이 두 가지는 독립적으로 설정한다. 입구 포맷과 출구 Cloud Provider가 달라도 LLM Gateway가 포맷을 변환해준다.

입구 포맷별 환경변수 설정

# LLM Gateway가 Anthropic Messages 포맷으로 요청을 받겠다
export ANTHROPIC_BASE_URL=https://your-gateway.com
 
# LLM Gateway가 Bedrock 포맷으로 요청을 받겠다
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
 
# LLM Gateway가 Vertex 포맷으로 요청을 받겠다
export ANTHROPIC_VERTEX_BASE_URL='https://your-gateway.com/vertex'
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1

Q) “Bedrock 포맷으로 받으면서 실제로는 Vertex AI Cloud Provider로 전달하는 것도 가능한가?”

가능하다. 다음 설정이 의미하는 바를 한 줄씩 해석하면:

export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
# → "내 LLM Gateway 주소는 이거고, Bedrock 포맷으로 요청을 보낼게"
 
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
# → "AWS 인증은 내가 안 할게, LLM Gateway가 알아서 해"
 
export CLAUDE_CODE_USE_BEDROCK=1
# → "Bedrock 모드 활성화"

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant GW as 내 LLM Gateway<br/>(Anthropic/AWS와 무관)
    participant VX as Vertex AI (GCP)

    CC->>GW: Bedrock 포맷으로 요청<br/>POST /invoke
    Note over GW: 1. Bedrock 포맷 파싱<br/>2. Vertex 포맷으로 변환<br/>3. GCP 인증 처리
    GW->>VX: Vertex 포맷으로 전달<br/>POST :rawPredict
    VX-->>GW: 응답
    Note over GW: Vertex → Bedrock 포맷 변환
    GW-->>CC: Bedrock 포맷으로 응답

    Note over CC,VX: Claude Code는 Bedrock과 통신한다고 "믿음"<br/>실제로는 Vertex AI가 처리

**입구(프로토콜)**과 **출구(Cloud Provider)**는 완전히 독립적이다:

	설정한 것	실제 의미
입구 포맷	Bedrock (/invoke)	Claude Code가 LLM Gateway에 보내는 요청 형식
출구 Cloud Provider	Vertex AI	LLM Gateway가 실제로 모델을 호출하는 곳
인증	SKIP_BEDROCK_AUTH=1	Claude Code는 AWS 키 불필요, LLM Gateway가 GCP 인증 처리

LLM Gateway 요구사항

LLM Gateway가 Claude Code와 동작하려면 다음 API 포맷 중 하나를 지원해야 한다:

API 포맷	Endpoint	필수 전달 항목
Anthropic Messages	/v1/messages, /v1/messages/count_tokens	헤더: anthropic-beta, anthropic-version
Bedrock InvokeModel	/invoke, /invoke-with-response-stream	Body: anthropic_beta, anthropic_version
Vertex rawPredict	:rawPredict, :streamRawPredict	헤더: anthropic-beta, anthropic-version

Base URL과 Endpoint의 차이

• Base URL = 서비스의 루트 주소. 환경변수로 설정하는 것
• Endpoint = 서비스가 제공하는 특정 경로(path). Claude Code가 자동으로 Base URL 뒤에 붙임
• Full URL = Base URL + Endpoint

Full URL = Base URL + Endpoint

예시:
Base URL:  https://bedrock-runtime.us-east-1.amazonaws.com
Endpoint:  /invoke
Full URL:  https://bedrock-runtime.us-east-1.amazonaws.com/invoke

Cloud Provider	Base URL (환경변수로 설정)	Endpoint (Claude Code가 자동 호출)
Anthropic	https://api.anthropic.com	/v1/messages
Bedrock	https://bedrock-runtime.{region}.amazonaws.com	/invoke
Vertex AI	https://{region}-aiplatform.googleapis.com	:rawPredict

Vertex AI의 :rawPredict 표기법은 Google의 gRPC 스타일로, 리소스 경로 뒤에 콜론으로 붙는다:

https://us-east5-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/anthropic/models/claude-sonnet-4-6:rawPredict

Base URL과 Endpoint은 동일하지 않다:

# 이렇게 설정하면:
export ANTHROPIC_BASE_URL=https://my-gateway.com
 
# Claude Code는 내부적으로 이렇게 호출:
# POST https://my-gateway.com/v1/messages   ← /v1/messages는 자동 추가

개발자 관점에서의 설정

LLM Gateway + Cloud Provider가 모두 설정된 환경에서 개발자는 LLM Gateway URL 1개만 알면 된다.

구성 요소	누가 설정	개발자가 알아야 하는 것
Cloud Provider (Bedrock/Vertex)	관리자 (Infra/DevOps)	몰라도 됨
LLM Gateway (LiteLLM 등)	관리자 (Infra/DevOps)	LLM Gateway URL 1개만
Claude Code	개발자	export ANTHROPIC_BASE_URL=https://gateway:4000

Cloud Provider 연결, 인증, 라우팅은 LLM Gateway가 대신 처리한다.

LiteLLM: 오픈소스 LLM Gateway

LiteLLM은 100+ LLM Cloud Provider의 API를 하나의 통합 인터페이스로 추상화하는 오픈소스 LLM Gateway이다. Cloud Provider마다 API 포맷, 인증 방식, 모델명이 전부 다른 문제를 해결한다.

AS-IS (LiteLLM 없이)

sequenceDiagram
    autonumber
    participant Dev1 as Developer A
    participant Dev2 as Developer B
    participant Ant as Anthropic API
    participant BR as AWS Bedrock
    participant VX as Vertex AI

    Dev1->>Ant: API Key A로 호출 (Anthropic 포맷)
    Dev1->>BR: AWS Credentials로 호출 (Bedrock 포맷)
    Dev2->>VX: GCP Credentials로 호출 (Vertex 포맷)
    Dev2->>Ant: API Key B로 호출 (Anthropic 포맷)

    Note over Dev1,VX: 문제점:<br/>1. 각 개발자가 각 Cloud Provider 키를 개별 관리<br/>2. Cloud Provider별 API 포맷이 다름<br/>3. 전체 사용량/비용 추적 불가<br/>4. Cloud Provider 장애 시 수동 전환 필요

TO-BE (LiteLLM 사용)

sequenceDiagram
    autonumber
    participant Dev1 as Developer A
    participant Dev2 as Developer B
    participant Lite as LiteLLM (LLM Gateway)
    participant Ant as Anthropic API
    participant BR as AWS Bedrock

    Dev1->>Lite: 통합 포맷으로 요청 (1개 키)
    Dev2->>Lite: 통합 포맷으로 요청 (1개 키)
    Lite->>Lite: 인증, 로깅, rate limit
    Lite->>Ant: 라우팅 (Anthropic 포맷으로 변환)
    Ant-->>Lite: 응답

    Note over Lite,Ant: Anthropic 장애 발생!
    Lite->>BR: 자동 fallback (Bedrock 포맷으로 변환)
    BR-->>Lite: 응답
    Lite-->>Dev1: 응답 (개발자는 전환을 모름)

    Note over Dev1,BR: 해결:<br/>1. 개발자는 1개 LLM Gateway 키만 관리<br/>2. 통합 API 포맷<br/>3. 중앙 사용량/비용 추적<br/>4. 자동 load balancing + fallback

LiteLLM 기본 설정 (통합 Endpoint, 권장)

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

인증은 정적 API 키 또는 동적 헬퍼 스크립트로 설정:

# 정적 키
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key
 
# 동적 키 (Claude Code settings 파일)
# { "apiKeyHelper": "~/bin/get-litellm-key.sh" }

Fallback 비용 구조

Q) “Fallback을 위해 Bedrock, Anthropic 모두 설정하려면 각각 별도 비용이 드는 거지?”

맞다. 각 Cloud Provider/Anthropic 연결은 별도 계정 + 별도 비용이다. LiteLLM 자체는 무료 오픈소스이지만, 연결하는 각 모델 제공자는 모두 유료이다.

항목	비용 발생 여부	설명
Anthropic API 계정	사용한 만큼 과금	API Key 발급 필요
AWS Bedrock 계정	사용한 만큼 과금	AWS 계정 + Bedrock 활성화 필요
GCP Vertex AI 계정	사용한 만큼 과금	GCP 계정 + Vertex 활성화 필요
LiteLLM 서버	서버 운영 비용	오픈소스지만 서버 인프라 필요

"LiteLLM으로 fallback 설정하자!" 의 실제 의미:

  Anthropic 계정 유지비   ← 돈
+ AWS Bedrock 계정 유지비  ← 돈
+ LiteLLM 서버 운영비      ← 돈
─────────────────────────
= 안정성 확보              ← 대가

“설정하면 좋으니 하자”가 아니라 **“N개 Cloud Provider 비용을 지불하고 안정성을 사는 것”**이다. 실제 과금은 사용한 쪽에만 발생하지만, 계정은 모두 유지해야 한다.

Fallback 설정은 개발자가 아닌 LiteLLM 서버 관리자가 담당한다:

# LiteLLM 서버 config (관리자가 설정)
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: sk-ant-xxx              # ← Anthropic 계정 필요 (돈)
  - model_name: claude-sonnet
    litellm_params:
      model: bedrock/claude-sonnet-4-6  # ← AWS 계정 필요 (돈)
      aws_access_key_id: xxx
      aws_secret_access_key: xxx

참고 문서

• Claude Code LLM Gateway Configuration
• LiteLLM Documentation
• Claude Code Settings
• Enterprise Network Configuration