메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

LLM gateway는 Claude Code와 모델 공급자 간의 중앙 집중식 프록시 계층을 제공하며, 종종 다음을 제공합니다:
  • 중앙 집중식 인증 - API 키 관리를 위한 단일 지점
  • 사용량 추적 - 팀 및 프로젝트 전체의 사용량 모니터링
  • 비용 제어 - 예산 및 속도 제한 구현
  • 감사 로깅 - 규정 준수를 위한 모든 모델 상호작용 추적
  • 모델 라우팅 - 코드 변경 없이 공급자 간 전환

Gateway 요구사항

LLM gateway가 Claude Code와 함께 작동하려면 다음 요구사항을 충족해야 합니다: API 형식 Gateway는 클라이언트에 다음 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 기능을 사용할 수 없을 수 있습니다.
Claude Code는 API 형식을 기반으로 활성화할 기능을 결정합니다. Bedrock 또는 Vertex와 함께 Anthropic Messages 형식을 사용할 때 환경 변수 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정해야 할 수 있습니다.
요청 헤더 Claude Code는 모든 API 요청에 다음 헤더를 포함합니다:
헤더설명
X-Claude-Code-Session-Id현재 Claude Code 세션의 고유 식별자입니다. 프록시는 이를 사용하여 요청 본문을 구문 분석하지 않고 단일 세션의 모든 API 요청을 집계할 수 있습니다.
X-Claude-Code-Agent-Id요청을 발급한 서브에이전트 또는 팀원의 식별자입니다. 프록시는 이를 사용하여 요청 본문을 구문 분석하지 않고 세션 내 개별 병렬 서브에이전트에 API 비용을 할당할 수 있습니다. 프로세스 내 서브에이전트 또는 팀원이 발급한 요청에만 표시됩니다.
X-Claude-Code-Parent-Agent-Id요청을 하는 에이전트를 생성한 에이전트의 식별자입니다. 프록시에서 중첩된 에이전트 전체에 API 비용을 할당하려면 X-Claude-Code-Agent-Id와 함께 이를 사용합니다. 요청하는 에이전트가 다른 에이전트에 의해 생성된 경우에만 표시됩니다.
두 에이전트 ID 헤더는 지속적인 사용자 또는 디바이스 ID가 아닌 생성당 임시 식별자입니다. Claude Code는 또한 클라이언트 버전과 대화에서 파생된 지문을 포함하는 짧은 속성 블록을 시스템 프롬프트 앞에 추가합니다. Anthropic API는 처리 전에 이 블록을 제거하므로 자사 프롬프트 캐싱에 영향을 주지 않습니다. Gateway가 전체 요청 본문을 기반으로 키가 지정된 자체 프롬프트 캐시를 구현하는 경우 CLAUDE_CODE_ATTRIBUTION_HEADER=0을 설정하여 이를 생략합니다.

구성

모델 선택

기본적으로 Claude Code는 선택한 API 형식에 대해 표준 모델 이름을 사용합니다. ANTHROPIC_BASE_URL이 Anthropic Messages 형식을 노출하는 게이트웨이를 가리킬 때, Claude Code는 시작 시 게이트웨이의 /v1/models 엔드포인트를 쿼리하고 반환된 모델을 /model 선택기에 추가할 수 있습니다. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 설정하여 이를 활성화합니다. 발견은 기본적으로 꺼져 있으므로 공유 API 키로 지원되는 게이트웨이가 키가 액세스할 수 있는 모든 모델을 모든 사용자에게 노출하지 않습니다. 발견된 각 항목은 “From gateway”로 레이블이 지정되며, 응답에서 제공될 때 display_name 필드를 사용합니다. 이는 Claude Code v2.1.129 이상이 필요합니다. 발견은 Anthropic Messages 형식에만 적용됩니다. Bedrock 또는 Vertex 통과 엔드포인트에서는 실행되지 않으며, ANTHROPIC_BASE_URL이 설정되지 않았거나 api.anthropic.com을 가리킬 때도 실행되지 않습니다. 발견 요청은 추론 요청과 동일한 방식으로 인증됩니다. 인증 토큰이 설정되지 않았을 때 ANTHROPIC_AUTH_TOKEN을 베어러 토큰으로 또는 ANTHROPIC_API_KEYx-api-key 헤더로 보내며, ANTHROPIC_CUSTOM_HEADERS의 모든 헤더와 함께 보냅니다. ID가 claude 또는 anthropic으로 시작하는 모델만 선택기에 추가됩니다. 결과는 ~/.claude/cache/gateway-models.json에 캐시되며 각 시작 시 새로고침됩니다. 요청이 실패하거나 게이트웨이가 /v1/models을 구현하지 않으면, 선택기는 이전 시작의 캐시된 목록 또는 기본 제공 모델 목록으로 폴백됩니다. 게이트웨이가 발견 필터와 일치하지 않는 모델 이름을 사용하는 경우, 모델 구성에 문서화된 환경 변수를 사용하여 수동으로 추가합니다.

LiteLLM 구성

LiteLLM PyPI 버전 1.82.7 및 1.82.8은 자격 증명 탈취 악성코드로 손상되었습니다. 이 버전들을 설치하지 마십시오. 이미 설치한 경우:
  • 패키지 제거
  • 영향을 받은 시스템의 모든 자격 증명 회전
  • BerriAI/litellm#24518의 복구 단계 따르기
LiteLLM은 제3자 프록시 서비스입니다. Anthropic은 LiteLLM의 보안 또는 기능을 보증, 유지 관리 또는 감사하지 않습니다. 이 가이드는 정보 제공 목적으로 제공되며 오래될 수 있습니다. 자신의 판단에 따라 사용하십시오.

필수 조건

  • 최신 버전으로 업데이트된 Claude Code
  • 배포되고 액세스 가능한 LiteLLM Proxy Server
  • 선택한 공급자를 통한 Claude 모델 액세스

기본 LiteLLM 설정

Claude Code 구성:

인증 방법

정적 API 키
고정 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"}'
  1. 헬퍼를 사용하도록 Claude Code 설정을 구성합니다:
{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}
  1. 토큰 새로고침 간격을 설정합니다:
# 1시간마다 새로고침 (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
이 값은 AuthorizationX-Api-Key 헤더로 전송됩니다. apiKeyHelperANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY보다 우선순위가 낮습니다.

통합 엔드포인트 (권장)

LiteLLM의 Anthropic 형식 엔드포인트 사용:
export ANTHROPIC_BASE_URL=https://litellm-server:4000
통합 엔드포인트의 통과 엔드포인트 대비 이점:
  • 로드 밸런싱
  • 폴백
  • 비용 추적 및 최종 사용자 추적에 대한 일관된 지원

공급자별 통과 엔드포인트 (대안)

LiteLLM을 통한 Claude API
통과 엔드포인트 사용:
export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
LiteLLM을 통한 Amazon Bedrock
통과 엔드포인트 사용:
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
LiteLLM을 통한 Google Vertex AI
통과 엔드포인트 사용:
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
AWS를 통한 Claude Platform 게이트웨이
Claude Platform on AWS 엔드포인트로 전달하는 게이트웨이로 라우팅:
export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
더 자세한 정보는 LiteLLM 문서를 참조하십시오.

추가 리소스