​
모델 구성

기본적으로 Claude Code는 claude-opus-4-20250514를 사용합니다. 다음 환경 변수를 사용하여 이를 재정의할 수 있습니다:

# Anthropic API
ANTHROPIC_MODEL='claude-opus-4-20250514'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku-20241022'

# Amazon Bedrock (모델 ID 사용)
ANTHROPIC_MODEL='us.anthropic.claude-opus-4-20250514-v1:0'
ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'

# Amazon Bedrock (추론 프로필 ARN 사용)
ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'
ANTHROPIC_SMALL_FAST_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-small-model-id'

# Google Vertex AI
ANTHROPIC_MODEL='claude-3-7-sonnet@20250219'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

전역 구성을 사용하여 이러한 변수를 설정할 수도 있습니다:

# Anthropic API 구성
claude config set --global env '{"ANTHROPIC_MODEL": "claude-opus-4-20250514"}'

# Bedrock 구성 (모델 ID 사용)
claude config set --global env '{"CLAUDE_CODE_USE_BEDROCK": "true", "ANTHROPIC_MODEL": "us.anthropic.claude-opus-4-20250514-v1:0"}'

# Bedrock 구성 (추론 프로필 ARN 사용)
claude config set --global env '{"CLAUDE_CODE_USE_BEDROCK": "true", "ANTHROPIC_MODEL": "arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id"}'

# Vertex AI 구성
claude config set --global env '{"CLAUDE_CODE_USE_VERTEX": "true", "ANTHROPIC_MODEL": "claude-3-7-sonnet@20250219"}'

다양한 제공업체에서 사용 가능한 모든 모델에 대해서는 모델 이름 참조를 참조하세요.

​
타사 API와 함께 사용

Claude Code는 어떤 API 제공업체를 사용하든 Claude Sonnet 3.7과 Claude Haiku 3.5 모델 모두에 대한 액세스가 필요합니다.

​
Amazon Bedrock에 연결

CLAUDE_CODE_USE_BEDROCK=1

프롬프트 캐싱을 활성화하지 않은 경우 다음도 설정하세요:

DISABLE_PROMPT_CACHING=1

비용 절감 및 더 높은 속도 제한을 위한 프롬프트 캐싱에 대해서는 Amazon Bedrock에 문의하세요.

표준 AWS SDK 자격 증명(예: ~/.aws/credentials 또는 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY와 같은 관련 환경 변수)이 필요합니다. AWS 자격 증명을 설정하려면 다음을 실행하세요:

aws configure

프록시를 통해 Claude Code에 액세스하려면 ANTHROPIC_BEDROCK_BASE_URL 환경 변수를 사용할 수 있습니다:

ANTHROPIC_BEDROCK_BASE_URL='https://your-proxy-url'

프록시가 자체 AWS 자격 증명을 유지하는 경우 CLAUDE_CODE_SKIP_BEDROCK_AUTH 환경 변수를 사용하여 Claude Code의 AWS 자격 증명 요구 사항을 제거할 수 있습니다.

CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

사용자는 AWS 계정에서 Claude Sonnet 3.7 및 Claude Haiku 3.5 모델 모두에 액세스할 수 있어야 합니다. 모델 액세스 역할이 있는 경우 이러한 모델이 아직 사용 가능하지 않다면 액세스를 요청해야 할 수 있습니다. 추론 프로필은 교차 리전 기능을 필요로 하기 때문에 각 리전에서 Bedrock에 대한 액세스가 필요합니다.

​
Google Vertex AI에 연결

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

프롬프트 캐싱을 활성화하지 않은 경우 다음도 설정하세요:

DISABLE_PROMPT_CACHING=1

Vertex AI의 Claude Code는 현재 us-east5 리전만 지원합니다. 프로젝트에 이 특정 리전에 할당된 할당량이 있는지 확인하세요.

사용자는 Vertex AI 프로젝트에서 Claude Sonnet 3.7 및 Claude Haiku 3.5 모델 모두에 액세스할 수 있어야 합니다.

google-auth-library를 통해 구성된 표준 GCP 자격 증명이 필요합니다. GCP 자격 증명을 설정하려면 다음을 실행하세요:

gcloud auth application-default login

프록시를 통해 Claude Code에 액세스하려면 ANTHROPIC_VERTEX_BASE_URL 환경 변수를 사용할 수 있습니다:

ANTHROPIC_VERTEX_BASE_URL='https://your-proxy-url'

프록시가 자체 GCP 자격 증명을 유지하는 경우 CLAUDE_CODE_SKIP_VERTEX_AUTH 환경 변수를 사용하여 Claude Code의 GCP 자격 증명 요구 사항을 제거할 수 있습니다.

CLAUDE_CODE_SKIP_VERTEX_AUTH=1

최상의 경험을 위해 Google에 연락하여 높은 속도 제한을 요청하세요.

​
프록시를 통해 연결

Claude Code를 LLM 프록시와 함께 사용할 때 다음 환경 변수와 구성을 사용하여 인증 동작을 제어할 수 있습니다. 이러한 설정은 Bedrock 및 Vertex 관련 설정과 함께 사용할 수 있습니다.

​
설정

Claude Code는 Bedrock 및 Vertex와 함께 사용하도록 구성하기 위해 환경 변수로 제어되는 여러 설정을 지원합니다. 전체 참조는 환경 변수를 참조하세요.

환경 변수 대신 파일을 통해 구성하려면 Claude Code 설정 파일의 env 객체에 이러한 설정을 추가할 수 있습니다.

또한 apiKeyHelper 설정을 구성하여 API 키를 가져오는 사용자 정의 셸 스크립트를 설정할 수 있습니다(시작 시 한 번 호출되며 각 세션 기간 동안 또는 CLAUDE_CODE_API_KEY_HELPER_TTL_MS가 경과할 때까지 캐시됨).

​
LiteLLM

LiteLLM은 타사 프록시 서비스입니다. Anthropic은 LiteLLM의 보안이나 기능을 보증, 유지 또는 감사하지 않습니다. 이 가이드는 정보 제공 목적으로만 제공되며 오래된 정보가 될 수 있습니다. 자유 재량으로 사용하세요.

이 섹션에서는 Claude Code를 LiteLLM Proxy Server와 구성하는 방법을 보여줍니다. LiteLLM Proxy Server는 사용량 및 지출 추적, 중앙 집중식 인증, 사용자별 예산 책정 등을 제공하는 타사 LLM 프록시입니다.

​
1단계: 사전 요구 사항

  • 최신 버전으로 업데이트된 Claude Code
  • 실행 중이며 Claude Code에서 네트워크로 접근 가능한 LiteLLM Proxy Server
  • LiteLLM 프록시 키

​
2단계: 프록시 인증 설정

다음 인증 방법 중 하나를 선택하세요:

옵션 A: 정적 프록시 키 환경 변수로 프록시 키를 설정하세요:

ANTHROPIC_AUTH_TOKEN=your-proxy-key

옵션 B: 동적 프록시 키 조직에서 순환 키 또는 동적 인증을 사용하는 경우:

  1. ANTHROPIC_AUTH_TOKEN 환경 변수를 설정하지 마세요
  2. 인증 토큰을 제공하는 키 헬퍼 스크립트를 작성하세요
  3. Claude Code 설정의 apiKeyHelper 구성에 스크립트를 등록하세요
  4. 자동 새로 고침을 활성화하기 위해 토큰 수명을 설정하세요: 
    CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
    이를 apiKeyHelper가 반환하는 토큰의 수명(밀리초)으로 설정하세요.

​
3단계: 배포 구성

LiteLLM을 통해 사용하려는 Claude 배포를 선택하세요:

  • Anthropic API: Anthropic의 API에 직접 연결
  • Bedrock: Claude 모델이 있는 Amazon Bedrock
  • Vertex AI: Claude 모델이 있는 Google Cloud Vertex AI
옵션 A: LiteLLM을 통한 Anthropic API
  1. LiteLLM 엔드포인트 구성: 
    ANTHROPIC_BASE_URL=https://litellm-url:4000/anthropic
옵션 B: LiteLLM을 통한 Bedrock
  1. Bedrock 설정 구성: 
    ANTHROPIC_BEDROCK_BASE_URL=https://litellm-url:4000/bedrock
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
CLAUDE_CODE_USE_BEDROCK=1
옵션 C: LiteLLM을 통한 Vertex AI

권장: 프록시 지정 자격 증명

  1. Vertex 설정 구성: 
    ANTHROPIC_VERTEX_BASE_URL=https://litellm-url:4000/vertex_ai/v1
CLAUDE_CODE_SKIP_VERTEX_AUTH=1
CLAUDE_CODE_USE_VERTEX=1

대안: 클라이언트 지정 자격 증명

로컬 GCP 자격 증명을 사용하려면:

  1. 로컬에서 GCP로 인증:

    gcloud auth application-default login

  2. Vertex 설정 구성:

    ANTHROPIC_VERTEX_BASE_URL=https://litellm-url:4000/vertex_ai/v1
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=your-gcp-region

  3. LiteLLM 헤더 구성 업데이트:

    LiteLLM 구성에서 general_settings.litellm_key_header_name이 Proxy-Authorization으로 설정되어 있는지 확인하세요. 통과 GCP 토큰은 Authorization 헤더에 위치하기 때문입니다.

​
4단계. 모델 선택

기본적으로 모델은 모델 구성에 지정된 것을 사용합니다.

LiteLLM에서 사용자 정의 모델 이름을 구성한 경우 앞서 언급한 환경 변수를 해당 사용자 정의 이름으로 설정하세요.

자세한 정보는 LiteLLM 문서를 참조하세요.