SpyBara
Go Premium

google-vertex-ai.md 2026-08-03 20:02 UTC to 2026-08-04 01:59 UTC

9 added, 9 removed.

2026
Tue 4 01:59 Mon 3 20:02 Sun 2 19:00

Google Cloud의 Agent Platform에서 Claude Code 사용하기

Google Cloud의 Agent Platform(이전 Vertex AI)을 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return <div className="cc-cs not-prose"> <div className="cc-cs-card"> <div className="cc-cs-text"> Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

<div className="cc-cs-actions"> <a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

필수 요구사항

Google Cloud의 Agent Platform(이전의 Vertex AI)을 사용하여 Claude Code를 구성하기 전에 다음을 확인하십시오:

자신의 Google Cloud의 Agent Platform 자격증명으로 로그인하려면 아래의 Google Cloud의 Agent Platform으로 로그인을 따르십시오. 팀 전체에 Claude Code를 배포하려면 수동 설정 단계를 사용하고 롤아웃 전에 모델 버전을 고정하십시오.

Agent Platform으로 로그인

Google Cloud 자격증명이 있고 Google Cloud의 Agent Platform을 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. GCP 측 필수 요구사항을 프로젝트당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.

1

GCP 프로젝트에서 Claude 모델 활성화

프로젝트에 대해 Google Cloud의 Agent Platform API 활성화한 다음 Google Cloud의 Agent Platform Model Garden에서 원하는 Claude 모델에 대한 액세스를 요청합니다. 계정에 필요한 권한은 IAM 구성을 참조하십시오.

2

Claude Code를 시작하고 Google Cloud의 Agent Platform 선택

claude를 실행합니다. 로그인 프롬프트에서 3rd-party platform을 선택한 다음 Google Vertex AI를 선택합니다. 이는 로그인 프롬프트가 Google Cloud의 Agent Platform에 대해 여전히 사용하는 레이블입니다.

3

마법사 프롬프트 따르기

Google Cloud에 인증하는 방법을 선택합니다: gcloud의 Application Default Credentials, 서비스 계정 키 파일 또는 환경에 이미 있는 자격증명. 마법사는 프로젝트와 지역을 감지하고, 프로젝트가 호출할 수 있는 Claude 모델을 확인하며, 이를 고정할 수 있게 합니다. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.

로그인한 후 언제든지 /setup-vertex를 실행하여 마법사를 다시 열고 자격증명, 프로젝트, 지역 또는 모델 고정을 변경할 수 있습니다. 모델 고정 단계는 현재 고정된 모델에서 시작됩니다. 마법사는 ~/.claude/settings.json에 쓰거나, CLAUDE_CONFIG_DIR이 설정되어 있을 때 $CLAUDE_CONFIG_DIR/settings.json에 씁니다.

지역 구성

Claude Code는 Google Cloud의 Agent Platform 전역, 다중 지역 및 지역 엔드포인트를 지원합니다. CLOUD_ML_REGION을 global, eu 또는 us와 같은 다중 지역 위치 또는 us-east5와 같은 특정 지역으로 설정합니다. Claude Code는 aiplatform.eu.rep.googleapis.com 및 aiplatform.us.rep.googleapis.com 호스트를 포함한 다중 지역 위치에 대해 각 형식에 맞는 올바른 Google Cloud의 Agent Platform 호스트명을 선택합니다.

수동 설정

Google Cloud의 Agent Platform을 마법사 대신 환경 변수를 통해 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우) 아래 단계를 따르십시오.

1. Agent Platform API 활성화

GCP 프로젝트에서 Google Cloud의 Agent Platform API를 활성화합니다:

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

# Agent Platform API 활성화
gcloud services enable aiplatform.googleapis.com

2. 모델 액세스 요청

Google Cloud의 Agent Platform에서 Claude 모델에 대한 액세스를 요청합니다:

  1. Google Cloud의 Agent Platform Model Garden으로 이동합니다
  2. "Claude" 모델을 검색합니다
  3. 원하는 Claude 모델에 대한 액세스를 요청합니다(예: Claude Sonnet 4.6)
  4. 승인을 기다립니다(24-48시간이 소요될 수 있습니다)

3) GCP 자격증명 구성

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

자세한 내용은 Google Cloud 인증 설명서를 참조하십시오.

Claude Code v2.1.121 이상은 동일한 Application Default Credentials 체인을 통해 X.509 인증서 기반 Workload Identity Federation을 지원합니다. GOOGLE_APPLICATION_CREDENTIALS를 자격증명 구성 파일의 경로로 설정합니다.

고급 자격증명 구성

Claude Code는 gcpAuthRefresh 설정을 통해 GCP에 대한 자동 자격증명 새로 고침을 지원합니다. Claude Code가 GCP 자격증명이 만료되었거나 로드할 수 없음을 감지하면 요청을 다시 시도하기 전에 구성된 명령을 실행하여 새 자격증명을 얻습니다.

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

명령의 출력은 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL을 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 인증 흐름에 적합합니다. 인증이 완료되지 않으면 새로 고침 명령은 3분 후에 시간 초과됩니다. .claude/settings.json과 같은 프로젝트 설정에서 gcpAuthRefresh를 설정하면 워크스페이스 신뢰 프롬프트를 수락한 후에만 명령이 실행됩니다.

4. Claude Code 구성

다음 환경 변수를 설정합니다:

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

# 선택사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위해 Agent Platform 엔드포인트 URL 재정의
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 선택사항: 필요한 경우 prompt caching 비활성화
export DISABLE_PROMPT_CACHING=1

# 선택사항: 기본 5분 대신 1시간 prompt cache TTL 요청
export ENABLE_PROMPT_CACHING_1H=1

# CLOUD_ML_REGION=global일 때, 전역 엔드포인트를 지원하지 않는 모델의 지역 재정의
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

대부분의 모델 버전에는 해당하는 VERTEX_REGION_CLAUDE_* 변수가 있습니다. 전체 목록은 환경 변수 참조를 참조하십시오. Google Cloud의 Agent Platform Model Garden에서 어떤 모델이 전역 엔드포인트를 지원하는지 또는 지역 전용인지 확인하십시오.

Prompt caching은 자동으로 활성화됩니다. 이를 비활성화하려면 DISABLE_PROMPT_CACHING=1을 설정하십시오. 기본 5분 대신 1시간 캐시 TTL을 요청하려면 ENABLE_PROMPT_CACHING_1H=1을 설정하십시오. 1시간 TTL을 사용한 캐시 쓰기는 더 높은 요금으로 청구됩니다. 높은 속도 제한을 위해 Google Cloud 지원팀에 문의하십시오. Google Cloud의 Agent Platform을 사용할 때 /logout 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.

Claude Code는 MCP tool search를 Google Cloud의 Agent Platform에서 기본적으로 비활성화합니다. 따라서 모든 MCP 도구 정의는 미리 로드됩니다. Google Cloud의 Agent Platform은 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에 대해 도구 검색을 지원합니다. 이러한 모델에서 도구 검색을 활성화하려면 ENABLE_TOOL_SEARCH=true를 설정하십시오. Google Cloud의 Agent Platform의 이전 모델은 필요한 베타 헤더를 허용하지 않으며, 이러한 모델에서 도구 검색을 활성화하면 요청이 실패합니다.

5. 모델 버전 고정

이러한 환경 변수를 특정 Google Cloud의 Agent Platform 모델 ID로 설정합니다.

ANTHROPIC_DEFAULT_OPUS_MODEL이 없으면 Google Cloud의 Agent Platform의 opus 별칭이 Opus 4.8로 확인되고, ANTHROPIC_DEFAULT_SONNET_MODEL이 없으면 sonnet 별칭이 Sonnet 4.5로 확인됩니다. 이 예제는 각 별칭을 특정 버전으로 고정합니다:

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'

현재 및 레거시 모델 ID는 모델 개요를 참조하십시오. 환경 변수의 전체 목록은 모델 구성을 참조하십시오.

Claude Code는 고정 변수가 설정되지 않았을 때 이러한 기본 모델을 사용합니다:

모델 유형 기본값
주 모델 claude-opus-4-8
소형/빠른 모델 claude-sonnet-4-5@20250929

백그라운드 작업(예: 세션 제목 생성)은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Google Cloud의 Agent Platform에서 Claude Code는 모든 프로젝트 또는 지역에서 Haiku가 활성화되지 않을 수 있으므로 백그라운드 작업에 기본 Sonnet 모델을 사용합니다. 다음 두 가지 선택이 어떤 모델이 이를 수행하는지 변경합니다:

v2.1.207 이전에는 Google Cloud의 Agent Platform의 주 모델이 기본적으로 Sonnet 4.5였고, opus 별칭이 Opus 4.6으로 확인되었으며, 백그라운드 작업은 항상 주 모델을 사용했습니다.

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

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

시작 모델 확인

Claude Code가 Google Cloud의 Agent Platform으로 구성되어 시작할 때 사용하려는 모델이 프로젝트에서 액세스 가능한지 확인합니다.

현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 프로젝트가 최신 버전을 호출할 수 있으면 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 사용자 설정 파일에 쓰고 Claude Code를 다시 시작합니다. 거절하면 다음 기본 버전 변경까지 기억됩니다.

모델을 고정하지 않았고 현재 기본값을 프로젝트에서 사용할 수 없으면 Claude Code는 현재 세션에 대해 이전 버전으로 폴백하고 알림을 표시합니다. 기본값이 Opus 모델이고 사용 가능한 Opus 버전이 없으면 기본 Sonnet 모델로 폴백합니다. 폴백은 유지되지 않습니다. Model Garden에서 최신 모델을 활성화하거나 버전을 고정하여 선택을 영구적으로 만듭니다.

IAM 구성

필요한 IAM 권한을 할당합니다:

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

더 제한적인 권한의 경우 위의 권한만 포함하는 사용자 정의 역할을 만듭니다.

자세한 내용은 Google Cloud의 Agent Platform IAM 설명서를 참조하십시오.

1M 토큰 context window

Claude Sonnet 5, Opus 4.6 이상 및 Sonnet 4.6은 Google Cloud의 Agent Platform에서 1M 토큰 context window를 지원합니다. Sonnet 5는 항상 1M 윈도우로 실행되며, 선택할 [1m] 변형이 없습니다. 다른 모델의 경우, Claude Code는 1M 모델 변형을 선택할 때 확장된 context window를 자동으로 활성화합니다.

설정 마법사는 모델을 고정할 때 1M context 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 [1m]을 추가합니다. 자세한 내용은 타사 배포를 위한 모델 고정을 참조하십시오.

문제 해결

"기본 자격증명을 로드할 수 없음" 오류가 발생하는 경우:

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

"모델을 찾을 수 없음" 404 오류가 발생하는 경우:

429 오류가 발생하는 경우:

추가 리소스