Claude Code on Google Cloud's Agent Platform

Claude Code를 Google Cloud's Agent Platform(이전 Vertex AI)을 통해 사용하도록 구성하는 가이드예요. 설정·IAM 구성·트러블슈팅을 다룬다. 자신의 Google Cloud 자격 증명으로 로그인하거나, 팀 배포라면 수동 설정과 모델 버전 고정을 따라가면 돼요.

출처: 공식문서

본문

전제조건

결제가 활성화된 GCP(Google Cloud Platform) 계정
Google Cloud's Agent Platform API가 활성화된 GCP 프로젝트
원하는 Claude 모델(예: Claude Sonnet 4.6) 접근 권한
Google Cloud SDK(gcloud) 설치·구성
원하는 GCP 지역에 할당된 쿼터

Agent Platform으로 로그인

Google Cloud 자격 증명이 있고 시작하고 싶다면 로그인 마법사가 안내해요. GCP 쪽 전제조건은 프로젝트당 한 번, 마법사가 Claude Code 쪽을 처리해요.

GCP 프로젝트에서 Claude 모델 활성화 — Agent Platform API를 활성화하고, Model Garden에서 원하는 Claude 모델 접근을 요청.
Claude Code 실행 후 Agent Platform 선택 — claude 실행 후 로그인 프롬프트에서 3rd-party platform → Google Vertex AI(로그인 프롬프트는 여전히 이 라벨 사용). 이미 로그인돼 있으면 /login으로 같은 메뉴.
마법사 프롬프트 따라가기 — Google Cloud 인증 방식 선택(Application Default Credentials, 서비스 계정 키 파일, 환경의 기존 자격 증명). 프로젝트·지역을 물어보고, 프로젝트가 호출 가능한 Claude 모델을 검증하고 고정하게 해요. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경변수를 직접 export할 필요 없어요.

로그인 후엔 /setup-vertex로 언제든 자격 증명·프로젝트·지역·모델 고정을 바꿀 수 있어요. 마법사는 ~/.claude/settings.json(또는 CLAUDE_CONFIG_DIR 설정 시 $CLAUDE_CONFIG_DIR/settings.json)에 써요.

지역 구성

Claude Code는 Google Cloud's Agent Platform의 global, 멀티지역, 리전 엔드포인트를 지원해요. CLOUD_ML_REGION에 global, eu·us 같은 멀티지역, 또는 us-east5 같은 특정 지역을 설정하세요. Claude Code는 각 형태에 맞는 호스트명을 선택해요(멀티지역엔 aiplatform.eu.rep.googleapis.com, aiplatform.us.rep.googleapis.com). 모델 가용성이 엔드포인트 형태별로 다를 수 있으니 지원되는 위치·모델을 확인해야 해요.

수동 설정

1. Agent Platform API 활성화

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. 모델 접근 요청 — Model Garden에서 "Claude" 모델 검색 후 원하는 모델 접근 요청(승인에 24-48시간 걸릴 수 있음).

3. GCP 자격 증명 구성 — Claude Code는 표준 Google Cloud 인증을 사용해요. X.509 인증서 기반 Workload Identity Federation도 Application Default Credentials chain을 통해 지원돼요. GOOGLE_APPLICATION_CREDENTIALS에 자격 증명 구성 파일 경로를 설정하세요. Claude Code는 GCLOUD_PROJECT·GOOGLE_CLOUD_PROJECT·자격 증명 파일이 다른 프로젝트를 가져도 요청을 ANTHROPIC_VERTEX_PROJECT_ID의 프로젝트로 보내요.

고급 자격 증명 구성: Claude Code는 gcpAuthRefresh 설정으로 GCP 자격 증명 자동 갱신을 지원해요(설정 파일 예: ~/.claude/settings.json). 자격 증명이 만료됐거나 로드 불가면 구성된 명령을 실행해 새 자격 증명을 얻고 요청을 재시도해요.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

명령 실행 전에 현재 자격 증명으로 access token을 요청해 실제 만료 여부를 확인하고, 아직 동작하면 건너뛰어요(5초 내에 검사가 안 끝나도 건너뛰고 요청이 자격 증명 오류로 실패한 뒤에만 실행). 갱신 명령은 3분 후 타임아웃돼요.

4. Claude Code 구성

# Enable Agent Platform integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Override the Agent Platform endpoint URL for custom endpoints or gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

대부분 모델 버전은 해당 VERTEX_REGION_CLAUDE_* 변수가 있어요. 지역 값이 지역/위치 이름 형태가 아니면(슬래시·점·공백 포함) 미설정으로 처리해요. 폴백: VERTEX_REGION_CLAUDE_* → CLOUD_ML_REGION, CLOUD_ML_REGION → us-east5.

프롬프트 캐싱은 자동 활성화. 끄려면 DISABLE_PROMPT_CACHING=1, 1시간 TTL은 ENABLE_PROMPT_CACHING_1H=1(높은 요율로 청구). 요금 한도 상향은 Google Cloud 지원에 문의. Agent Platform 사용 시 /logout은 사용 불가(Google Cloud 자격 증명으로 인증).

MCP 도구 로딩 방식: Claude Opus 4.5·Sonnet 4.5·Haiku 4.5 이상은 tool search 기본 활성화, 모든 Claude 3.x 포함 이전 모델은 Agent Platform 서빙 스택이 필요 beta 헤더를 거부하므로 MCP 정의를 upfront 로드해요(ENABLE_TOOL_SEARCH=true로도 오버라이드 안 됨). ENABLE_TOOL_SEARCH=false로 모든 모델에서 tool search를 끌 수 있어요.

5. 모델 버전 고정

여러 사용자에게 배포할 땐 특정 모델 버전을 고정해야 해요. 고정하지 않으면 sonnet·opus 별칭이 Agent Platform용 내장 기본값으로 해석돼 최신 릴리스보다 늦을 수 있어요. 예:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

고정하지 않았을 때 기본: Primary model = claude-opus-5, Small/fast model = claude-sonnet-4-5@20250929. 백그라운드 작업은 보통 Haiku급 모델을 쓰는데, Agent Platform에선 Haiku가 모든 프로젝트/지역에 활성화돼 있지 않을 수 있어 기본 Sonnet 모델을 써요. 설정하지 않고 v2.1.207 이상으로 업데이트하면 Opus 요율로 청구될 수 있으니 primary 모델 고정이 중요해요.

6. 구성 확인 — Claude Code 실행 후 /status로 확인. API provider 줄에 Google Vertex AI가, GCP project·Default region·Model 줄에 프로젝트 ID·지역·해석된 모델이 나와요. provider 줄이 없으면 환경변수가 프로세스에 닿지 않는 거예요.

시작 시 모델 검사

Claude Code가 Agent Platform 구성으로 시작하면 사용할 모델이 프로젝트에서 접근 가능한지 검증해요. 고정 버전이 현재 기본보다 오래되고 프로젝트가 새 버전을 호출할 수 있으면 고정 업데이트를 제안해요. 고정하지 않았고 기본이 없으면 이번 세션에 한해 폴백(기본의 이전 버전 먼저, Opus 기본이면 Sonnet 폴백)하고 알림을 보여줘요.

IAM 구성

roles/aiplatform.user 역할을 할당하세요(필수 권한 포함: aiplatform.endpoints.predict — 모델 호출·토큰 카운팅). 더 제한하려면 위 권한만 담은 커스텀 역할을 만들고, 비용 추적·접근 제어를 위해 Claude Code 전용 GCP 프로젝트를 만드는 걸 권장해요.

1M 토큰 컨텍스트 창

Claude Sonnet 5, Opus 4.6+, Sonnet 4.6은 Agent Platform에서 1M 토큰 컨텍스트 창을 지원해요. Sonnet 5는 항상 1M 창으로 실행(선택할 [1m] 변형 없음). 수동 고정 모델엔 모델 ID에 [1m]을 붙이면 돼요.

트러블슈팅

"Could not load the default credentials": gcloud auth application-default login 실행, GOOGLE_APPLICATION_CREDENTIALS에 서비스 계정 키 파일 경로 설정.
쿼터 문제: Cloud Console에서 쿼터 확인·증액 요청.
"model not found" 404: Model Garden에서 모델 활성화 확인, 지정한 위치에서 모델 사용 가능 확인(일부 모델은 global·멀티지역만), CLOUD_ML_REGION=global이면 global 엔드포인트 지원 여부 확인 — 안 되면 ANTHROPIC_MODEL/ANTHROPIC_DEFAULT_HAIKU_MODEL로 지원 모델 지정하거나 VERTEX_REGION_<MODEL_NAME>으로 지역 설정.
429 오류: 리전이면 primary/small-fast 모델이 선택 지역에서 지원되는지, CLOUD_ML_REGION=global로 전환 고려.

더 알아보기

Google Cloud's Agent Platform documentation
Google Cloud's Agent Platform pricing
Google Cloud's Agent Platform quotas and limits
Model configuration: 모델 고정·기본값