​
전제 조건

Vertex AI로 Claude Code를 구성하기 전에 다음 사항을 확인하세요:

  • 청구가 활성화된 Google Cloud Platform (GCP) 계정
  • Vertex AI API가 활성화된 GCP 프로젝트
  • 원하는 Claude 모델에 대한 액세스 권한 (예: Claude Sonnet 4)
  • Google Cloud SDK (gcloud)가 설치되고 구성됨
  • 원하는 GCP 지역에 할당된 할당량

​
지역 구성

Claude Code는 Vertex AI 전역 및 지역 엔드포인트 모두에서 사용할 수 있습니다.

Vertex AI는 모든 지역에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 지원되는 지역 또는 모델로 전환해야 할 수 있습니다.

Vertex AI는 전역 엔드포인트에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 지역 엔드포인트 또는 지원되는 모델로 전환해야 할 수 있습니다.

​
설정

​
1. Vertex AI API 활성화

GCP 프로젝트에서 Vertex AI API를 활성화하세요:

# 프로젝트 ID 설정
gcloud config set project YOUR-PROJECT-ID

# Vertex AI API 활성화
gcloud services enable aiplatform.googleapis.com

​
2. 모델 액세스 요청

Vertex AI에서 Claude 모델에 대한 액세스를 요청하세요:

  1. Vertex AI Model Garden으로 이동
  2. “Claude” 모델 검색
  3. 원하는 Claude 모델에 대한 액세스 요청 (예: Claude Sonnet 4)
  4. 승인 대기 (24-48시간 소요될 수 있음)

​
3. GCP 자격 증명 구성

Claude Code는 표준 Google Cloud 인증을 사용합니다.

자세한 정보는 Google Cloud 인증 문서를 참조하세요.

인증 시 Claude Code는 ANTHROPIC_VERTEX_PROJECT_ID 환경 변수의 프로젝트 ID를 자동으로 사용합니다. 이를 재정의하려면 다음 환경 변수 중 하나를 설정하세요: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, 또는 GOOGLE_APPLICATION_CREDENTIALS.

​
4. Claude Code 구성

다음 환경 변수를 설정하세요:

# Vertex AI 통합 활성화
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 선택사항: 필요한 경우 프롬프트 캐싱 비활성화
export DISABLE_PROMPT_CACHING=1

# CLOUD_ML_REGION=global일 때, 지원되지 않는 모델에 대한 지역 재정의
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# 선택사항: 다른 특정 모델에 대한 지역 재정의
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1

프롬프트 캐싱은 cache_control 임시 플래그를 지정할 때 자동으로 지원됩니다. 비활성화하려면 DISABLE_PROMPT_CACHING=1을 설정하세요. 높은 속도 제한을 위해서는 Google Cloud 지원팀에 문의하세요.

Vertex AI를 사용할 때는 Google Cloud 자격 증명을 통해 인증이 처리되므로 /login 및 /logout 명령이 비활성화됩니다.

​
5. 모델 구성

Claude Code는 Vertex AI에 대해 다음 기본 모델을 사용합니다:

모델 유형기본값
기본 모델claude-sonnet-4@20250514
소형/고속 모델claude-3-5-haiku@20241022

모델을 사용자 정의하려면:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
IAM 구성

필요한 IAM 권한을 할당하세요:

roles/aiplatform.user 역할에는 필요한 권한이 포함됩니다:

  • aiplatform.endpoints.predict - 모델 호출에 필요
  • aiplatform.endpoints.computeTokens - 토큰 계산에 필요

더 제한적인 권한의 경우, 위의 권한만으로 사용자 정의 역할을 생성하세요.

자세한 내용은 Vertex IAM 문서를 참조하세요.

비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code 전용 GCP 프로젝트를 생성하는 것을 권장합니다.

​
1M 토큰 컨텍스트 윈도우

Claude Sonnet 4는 Vertex AI에서 1M 토큰 컨텍스트 윈도우를 지원합니다.

1M 토큰 컨텍스트 윈도우는 현재 베타 버전입니다. 확장된 컨텍스트 윈도우를 사용하려면 Vertex AI 요청에 context-1m-2025-08-07 베타 헤더를 포함하세요.

​
문제 해결

할당량 문제가 발생하는 경우:

  • Cloud Console을 통해 현재 할당량을 확인하거나 할당량 증가를 요청하세요

“model not found” 404 오류가 발생하는 경우:

  • Model Garden에서 모델이 활성화되어 있는지 확인하세요
  • 지정된 지역에 대한 액세스 권한이 있는지 확인하세요
  • CLOUD_ML_REGION=global을 사용하는 경우, Model Garden의 “지원되는 기능” 아래에서 모델이 전역 엔드포인트를 지원하는지 확인하세요. 전역 엔드포인트를 지원하지 않는 모델의 경우 다음 중 하나를 수행하세요:
    • ANTHROPIC_MODEL 또는 ANTHROPIC_SMALL_FAST_MODEL을 통해 지원되는 모델을 지정하거나,
    • VERTEX_REGION_<MODEL_NAME> 환경 변수를 사용하여 지역 엔드포인트를 설정하세요

429 오류가 발생하는 경우:

  • 지역 엔드포인트의 경우, 선택한 지역에서 기본 모델과 소형/고속 모델이 지원되는지 확인하세요
  • 더 나은 가용성을 위해 CLOUD_ML_REGION=global로 전환하는 것을 고려하세요

​
추가 리소스