Logo
본문으로 이동
고급10분 소요llm-gatewayproxyenterprise

LLM 게이트웨이 솔루션과 함께 Claude Code를 설정하는 방법을 안내합니다. 게이트웨이 요구 사항, 인증 구성, 모델 선택, LiteLLM을 포함한 공급자별 엔드포인트 설정을 다룹니다.

LLM 게이트웨이는 Claude Code와 모델 공급자 사이에 중앙화된 프록시 레이어를 제공합니다. 엔터프라이즈 환경에서 특히 유용한 다음과 같은 기능을 제공합니다.

  • 중앙화된 인증 - API 키 관리를 위한 단일 접점
  • 사용량 추적 - 팀과 프로젝트 전반의 사용량 모니터링
  • 비용 제어 - 예산 및 요청 속도 제한 구현
  • 감사 로깅 - 컴플라이언스를 위한 모든 모델 상호작용 추적
  • 모델 라우팅 - 코드 변경 없이 공급자 간 전환

게이트웨이 요구 사항

LLM 게이트웨이가 Claude Code와 함께 작동하려면 다음 요구 사항을 충족해야 합니다.

API 형식

게이트웨이는 클라이언트에게 다음 API 형식 중 하나 이상을 노출해야 합니다.

1. Anthropic Messages 형식

  • 엔드포인트: /v1/messages, /v1/messages/count_tokens
  • 요청 헤더 전달 필수: anthropic-beta, anthropic-version

2. Bedrock InvokeModel 형식

  • 엔드포인트: /invoke, /invoke-with-response-stream
  • 요청 본문 필드 보존 필수: anthropic_beta, anthropic_version

3. 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 프록시 서버 배포 및 접근 가능
  • 선택한 공급자를 통한 Claude 모델 접근 권한

인증 방법

정적 API 키

고정 API 키를 사용하는 가장 간단한 방법입니다.

# 환경 변수로 설정
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

settings.json을 통한 설정:

{
  "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단계: 토큰 갱신 간격 설정

# 1시간마다 갱신 (3600000ms)
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

통합 엔드포인트는 패스스루 엔드포인트에 비해 다음과 같은 이점을 제공합니다.

  • 로드 밸런싱
  • 폴백(Fallback) 지원
  • 비용 추적 및 최종 사용자 추적 일관성

공급자별 패스스루 엔드포인트 (대안)

Claude API를 LiteLLM을 통해 사용

패스스루 엔드포인트 사용:

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

Amazon Bedrock을 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를 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

엔터프라이즈 사용 사례

멀티 팀 API 키 관리

중앙화된 API 키 관리로 팀별 사용량을 추적하고 비용을 할당할 수 있습니다.

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

#!/bin/bash
# ~/bin/get-team-api-key.sh
# 팀 ID 기반으로 API 키 가져오기
TEAM_ID=$(git config user.team 2>/dev/null || echo "default")
vault kv get -field=api_key "secret/teams/${TEAM_ID}/litellm"

사용량 모니터링 및 비용 제어

LiteLLM 게이트웨이를 통해 다음을 설정할 수 있습니다.

  • 팀별 또는 사용자별 예산 한도
  • 모델별 접근 제어
  • 요청 속도 제한
  • 상세한 사용량 로그

컴플라이언스 및 감사

모든 Claude Code 상호작용을 중앙에서 로깅하여 규정 준수 요구 사항을 충족합니다.

# LiteLLM 서버 설정 예시
litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["slack"]

general_settings:
  master_key: "sk-master-key"
  database_url: "postgresql://..."

문제 해결

연결 문제

게이트웨이 연결에 문제가 있는 경우:

# 게이트웨이 접근 가능 여부 확인
curl -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  ${ANTHROPIC_BASE_URL}/v1/messages \
  -d '{"model":"claude-opus-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

헤더 전달 확인

게이트웨이가 필요한 헤더를 올바르게 전달하는지 확인합니다.

# 요청 헤더 로깅 (게이트웨이 디버그 모드)
export LITELLM_LOG=DEBUG

다음 단계

관련 가이드

서드파티 통합 및 엔터프라이즈 배포고급

Claude Code의 서드파티 서비스 통합 및 엔터프라이즈 배포 옵션을 비교하고 조직 요구사항에 맞는 최적의 구성 방법을 알아봅니다.

Amazon Bedrock 통합고급

Amazon Bedrock을 통해 Claude Code를 설정하는 방법을 알아봅니다. IAM 구성, AWS 자격증명 설정, 모델 버전 고정, 트러블슈팅까지 단계별로 안내합니다.

Google Vertex AI 통합고급

Google Vertex AI를 통해 Claude Code를 설정하는 방법을 알아봅니다. GCP 자격증명 구성, IAM 권한 설정, 모델 버전 고정, 리전 구성까지 단계별로 안내합니다.

LLM 게이트웨이 | Claude Code 가이드 | GodDaeHee | GodDaeHee