Google Cloud에서 Claude 설정하기(Google 관리형)

회사가 Google Cloud's Agent Platform을 통해 Claude를 구매하면, Claude Code, Claude Desktop, 그리고 직접 빌드한 애플리케이션은 모두 사용자의 Google Cloud 프로젝트를 통해 Claude에 연결됩니다. Google Cloud 자격 증명으로 로그인하므로 Anthropic API 키가 필요하지 않으며, 사용량은 Google Cloud에서 청구합니다.

설정은 네 단계로 이루어집니다. 먼저 누군가 프로젝트를 한 번 준비하고, 그런 다음 각자 자신의 계정에 접근 권한을 부여합니다. 다음으로 터미널에서 Claude에 요청 하나를 보내고 응답을 받습니다. 그 후 사용하는 앱이 해당 프로젝트를 가리키도록 설정합니다. 직접 작성한 코드에서만 Claude를 호출한다면 응답을 받는 단계에서 멈춰도 됩니다. Claude Code의 경우, Claude가 답변하고 /status에 프로젝트 ID가 표시되면 완료된 것입니다.

Google Cloud는 Claude를 두 가지 서비스로 판매하며, 설정 방식이 서로 다릅니다. 따라서 가장 먼저 할 일은 어떤 서비스를 사용하는지 확인하는 것입니다.

사용 중인 서비스 확인하기

두 서비스는 Claude를 누가 운영하는지에 따라 다릅니다. Claude Models on Google Cloud(Google 관리형)에서는 Google이 Google Cloud's Agent Platform(이전 명칭 Vertex AI)의 일부로 Claude 모델을 운영합니다. Agent Platform은 이 단계들이 적용되는 Google Cloud의 영역으로, 이 API를 켜고, 그 역할 중 하나를 부여받으며, 사용량은 Agent Platform 사용량으로 청구됩니다. Anthropic 관리형 서비스에서는 Anthropic이 Claude API를 운영합니다.

어떤 서비스를 사용하고 있는지 확인하려면 이미 가지고 있는 것을 살펴보세요. 아래 표는 무엇을 확인해야 하는지 보여줍니다.

Model Garden은 각 모델이 고유한 카드로 표시되는 Google Cloud 콘솔의 영역입니다.

요청 URL도 세 번째 단서입니다. Google 관리형에서는 URL이 Agent Platform 호스트를 가리키며, URL 경로에 .../publishers/anthropic/models/{model}이 포함됩니다. 두 서비스 개요에서 호스트 목록을 확인할 수 있습니다.

Anthropic 관리형을 사용 중이라면, 대신 Google Cloud에서 Claude 설정하기(Anthropic 관리형)를 따르세요. API 키로 api.anthropic.com을 호출하는 경우에는 두 서비스 중 어느 것도 사용하지 않는 것입니다.

필요한 것과 비용

시작하기 전에 다음을 준비하세요:

• 결제가 활성화된 Google Cloud 프로젝트와 해당 프로젝트 ID
• 사용할 리전에서 사용할 Claude 모델에 대한 할당량. Google의 Anthropic Claude 모델 할당량 문서에 기본 할당량이 나와 있으며, 프로젝트의 할당량을 확인하거나 늘리도록 요청하는 방법도 안내합니다.
• Google Cloud의 명령줄 도구인 gcloud CLI
• 테스트 요청을 보내기 위한 curl과 Bash 셸
• 사용할 경우, 버전 2.1.293 이상의 Claude Code. 업데이트하려면 claude update를 실행하세요.

아래 명령에서 YOUR-PROJECT-ID 또는 PROJECT_ID가 표시되는 곳은 모두 자신의 프로젝트 ID로 바꾸세요.

gcloud CLI를 방금 설치했다면 gcloud auth login 또는 gcloud init으로 로그인하세요. 이는 gcloud CLI 자체의 로그인이며, 테스트 요청에서 사용됩니다. Claude Code가 사용하는 Application Default Credentials는 별도의 로그인으로, "자신에게 접근 권한 부여하기"에서 다룹니다.

Google Cloud는 사용량을 Agent Platform 사용량으로 청구합니다. 여기에는 Claude Code나 Claude Desktop에서 보내는 요청도 포함됩니다. 가격을 확인하려면 이 서비스 문서 페이지의 청구 섹션부터 시작하세요.

프로젝트 준비하기(한 번만)

프로젝트에서 누군가 Claude를 호출하려면 먼저 프로젝트에서 Agent Platform API가 켜져 있고 Claude 모델이 활성화되어 있어야 합니다. 이 단계들은 Google Cloud 프로젝트당 한 번, 보통 관리자가 수행합니다. 이미 누군가 해당 프로젝트에서 이 작업을 완료했다면 "자신에게 접근 권한 부여하기"로 넘어가세요.

1. Agent Platform API를 켭니다. gcloud가 해당 프로젝트를 가리키도록 설정한 다음, aiplatform.googleapis.com 서비스를 활성화합니다.

   bash

   gcloud config set project YOUR-PROJECT-ID
   gcloud services enable \
     aiplatform.googleapis.com

   Google의 Claude 모델 시작 전 단계에서 이 단계와 결제 확인 방법을 다룹니다.

2. Model Garden에서 사용할 Claude 모델을 활성화합니다. Google은 Claude 모델 카드 목록을 제공합니다. 각 모델의 카드를 열고 Enable을 클릭하세요. Claude Code의 경우 claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-sonnet-5를 활성화하세요. Claude Code를 연결할 때 앞의 세 모델을 고정(pin)합니다. Claude Sonnet 5는 고정하지 마세요. 이렇게 고정해 두면, 다른 모드를 설정하지 않는 한 이 서비스에서 대화형 세션이 시작되는 모드인 자동 모드에서 작업을 검사하는 기본 모델이 됩니다. 고정하지 않으면 Claude Code는 이 서비스에서 지원 중단된 기본 Claude Sonnet 모델을 사용합니다.

Enable을 클릭하는 사람은 Identity and Access Management(IAM)에서 Consumer Procurement Entitlement Manager 역할을 가지고 있어야 합니다. 해당 ID는 roles/consumerprocurement.entitlementManager입니다.

자신에게 접근 권한 부여하기

프로젝트는 준비되었지만, 자신의 계정에는 여전히 Claude를 호출할 권한과 Claude Code가 사용할 수 있는 로그인이 필요합니다. 각자 자신의 계정에 대해 다음 단계를 수행합니다.

1. gcloud가 해당 프로젝트를 가리키도록 설정합니다.

   bash

   gcloud config set project YOUR-PROJECT-ID

2. Claude를 호출할 수 있는 역할을 받습니다. 요청을 보내는 계정에는 aiplatform.endpoints.predict 권한이 포함된 IAM 역할, 예를 들어 Agent Platform User(roles/aiplatform.user)가 필요합니다. 다음 명령은 해당 역할을 부여합니다:

   bash

   gcloud projects add-iam-policy-binding \
     PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/aiplatform.user

   PRINCIPAL을 user: 뒤에 이메일 주소를 붙인 형태로 바꾸세요. 예를 들어 user:you@example.com입니다. Google의 접근 권한 부여 페이지에서 PRINCIPAL이 취할 수 있는 다른 형식을 확인할 수 있습니다. 프로젝트의 IAM 정책을 변경할 권한이 없다면 관리자에게 대신 명령을 실행해 달라고 요청하세요.

3. Application Default Credentials로 로그인합니다. 이는 Claude Code가 Claude를 호출할 때 사용하는 Google Cloud 자격 증명입니다.

   bash

   gcloud auth application-default login

Claude에 테스트 요청 보내기

앱을 연결하기 전에 Claude에 요청을 하나 보내세요. 응답을 받으면 프로젝트와 접근 권한이 모두 정상 작동한다는 것을 알 수 있습니다. 이 요청은 직접 빌드한 애플리케이션과 마찬가지로 Agent Platform API를 직접 호출합니다.

1. gcloud CLI가 어떤 계정으로 로그인되어 있는지 확인합니다. 이 요청은 Application Default Credentials가 아니라 gcloud CLI 자체의 로그인에서 토큰을 가져옵니다.

   bash

   gcloud auth list

   "자신에게 접근 권한 부여하기"에서 역할을 받은 계정이 활성 계정이어야 합니다. 그렇지 않다면 gcloud auth login을 실행하세요.

2. 요청을 보냅니다. 먼저 YOUR-PROJECT-ID를 바꾸세요. Google Cloud는 이 요청도 다른 요청과 동일하게 청구합니다.

   bash

   curl https://aiplatform.googleapis.com/v1/projects/YOUR-PROJECT-ID/locations/global/publishers/anthropic/models/claude-opus-5-5:rawPredict \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "anthropic_version": "2026-10-21",
       "messages": [{"role": "user", "content": "Hey Claude!"}],
       "max_tokens": 100
     }'

   이 요청은 global 리전을 사용합니다. 데이터 레지던시가 필요하다면 호스트와 경로가 모두 달라집니다. 문서에서는 us 멀티 리전에서의 동일한 요청을 보여줍니다.

3. 응답을 확인합니다. 응답은 JSON이며, Claude의 답변은 type이 text인 content 항목에 들어 있습니다. 실제 응답은 이 축약된 예시와 다른 단어와 더 많은 필드를 포함합니다:

   json

   {
     "type": "message",
     "role": "assistant",
     "content": [{"type": "text", "text": "Hello! Nice to meet you."}],
     "stop_reason": "end_turn"
   }

오류도 JSON으로 반환되며, 다음 중 하나의 코드가 표시됩니다:

이 코드들은 Google의 API 오류 목록에 나와 있습니다. 응답을 받은 후에도 앱이 Claude에 연결되지 않는다면, 먼저 해당 앱의 로그인과 설정을 확인하세요.

Claude Code 또는 Claude Desktop 연결하기

프로젝트 준비, 접근 권한 설정, Claude의 응답 확인이 모두 끝났다면 사용하는 앱이 해당 프로젝트를 가리키도록 설정하세요. 두 앱 모두 프로젝트 ID와 리전이라는 동일한 두 가지 값을 요구합니다. 아래 단계에서는 global 리전을 사용합니다.

데이터 레지던시가 필요하다면 us 또는 eu 멀티 리전을 사용하세요. 사용 가능한 용량이 있는 리전으로 요청을 보내는 global보다 비용이 10% 더 높습니다. 리전 엔드포인트는 Claude Sonnet 4.6 및 이전 모델만 제공합니다. 문서에서는 글로벌, 멀티 리전, 리전 엔드포인트를 비교합니다.

Claude Code

로그인 마법사가 Claude Code 측 설정을 처리합니다.

1. Claude Code를 시작합니다.

   bash

   claude

2. Agent Platform을 선택합니다. 로그인 프롬프트에서 3rd-party platform을 선택한 다음 Google Vertex AI를 선택하세요. 이는 로그인 프롬프트가 Google Cloud's Agent Platform에 대해 여전히 사용하는 라벨입니다. 이미 로그인되어 있다면 /login을 실행하면 동일한 메뉴가 열립니다.

3. 마법사의 안내를 따릅니다. Google Cloud에 인증하는 방법을 물으면, "자신에게 접근 권한 부여하기"에서 설정한 gcloud의 Application Default Credentials를 선택하세요. 그런 다음 프로젝트 ID와 global 리전을 입력합니다. 마법사는 프로젝트에서 호출할 수 있는 Claude 모델을 확인하고 고정할 수 있게 해줍니다. 세 모델 모두 고정하세요: claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5. 마법사가 모델의 다른 버전에서 시작한다면 고정하기 전에 변경하세요. Haiku 모델을 고정하면 Claude Code는 백그라운드 작업에 이를 사용합니다. 마법사는 결과를 사용자 설정 파일에 저장하므로 직접 환경 변수를 내보낼 필요가 없습니다.

4. Claude Code에 메시지를 보냅니다. 답변이 오면 Claude Code가 Google Cloud를 통해 Claude에 연결된 것입니다.

원하는 프로젝트를 사용하고 있는지 확인하세요. /status를 실행하세요. API provider 줄에 Google Vertex AI가 표시됩니다. GCP project, Default region, Model 줄에는 프로젝트 ID, 리전, 확인된 모델이 표시됩니다. 이 프로젝트 ID를 "프로젝트 준비하기(한 번만)"에서 사용한 프로젝트와 비교하세요.

Claude Opus 모델은 Sonnet 모델보다 토큰당 가격이 더 높습니다. 세 모델을 모두 고정해도 Claude Code의 기본 모델은 여전히 Opus이므로, /model로 모델을 전환하기 전까지는 Opus 요금으로 청구됩니다. 나중에 모델 고정, 프로젝트, 리전, 자격 증명을 변경하려면 /setup-vertex를 실행하여 마법사를 다시 열 수 있습니다.

CI나 스크립트화된 배포처럼 마법사 없이 Claude Code를 설정하려면, claude를 시작하는 셸에서 다음 환경 변수를 설정하세요:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-5-5'

이후 /status에 API provider 줄이 표시되지 않는다면, 환경 변수가 프로세스에 전달되지 않은 것입니다. 수동 설정 단계에서 팀을 위한 모델 버전 고정 방법을 포함해 나머지 내용을 다룹니다.

Claude Desktop

Claude Desktop도 동일한 프로젝트를 통해 Claude 모델을 사용할 수 있으며, Claude Cowork 세션도 이 앱에서 실행됩니다. 보통 IT 관리자가 모든 기기에 배포하므로, 사용 중인 기기에 이미 배포되어 있는지 확인해 보세요. 한 기기에서 직접 시도해 보려면 동일한 값을 수동으로 입력하세요.

1. 앱 내 구성 창을 엽니다. Help → Troubleshooting → Enable Developer Mode로 이동한 다음 Developer → Configure Third-Party Inference…를 선택하세요.

2. 제공자를 선택합니다. Connection 섹션에서 Inference provider를 Vertex AI로 설정하세요.

3. Vertex AI 자격 증명 카드를 작성합니다. GCP project ID에 프로젝트 ID를, GCP region에 리전을 입력하세요. 리전은 global로 설정할 수 있습니다. 그런 다음 자격 증명 출처를 정확히 하나만 제공하세요. GCP credentials file path는 gcloud auth application-default login이 생성하는 파일을 받아들입니다. Google은 해당 파일이 저장되는 위치를 안내합니다.

4. 모델을 추가합니다. Models 아래에서, 활성화한 모델의 퍼블리셔 모델 ID(예: claude-opus-5-5)를 사용해 Model list 항목을 하나 이상 추가하세요.

5. 설정을 적용합니다. Apply Changes를 클릭하세요. 앱은 이 기기에만 설정을 저장하고 해당 설정으로 다시 시작됩니다. 그런 다음 메시지를 보내 Claude가 응답하는지 확인하세요.

Google Cloud's Agent Platform으로 Claude Desktop을 3P에 배포하기에서는 다른 로그인 방법과 모든 기기에 설정을 배포하는 방법을 다룹니다.

작동하지 않는 경우

다음과 같은 오류로 인해 Claude Code가 Claude에 연결되지 못할 수 있습니다. 표에서 해당 오류를 찾아 해결 방법을 적용하세요.

특정 위치에는 모델이 없을 수 있습니다. 일부 모델은 특정 리전이 아니라 global 또는 eu, us와 같은 멀티 리전 위치에서만 제공됩니다. 리전을 변경하는 경우 해당 위치에서 사용하는 모델을 사용할 수 있는지 확인하세요.

이 해결 방법들은 Google Cloud's Agent Platform에서 Claude Code 문제 해결에서 가져온 것이며, 더 자세한 내용도 다룹니다. Claude Desktop의 경우 자체 Troubleshoot 섹션부터 확인하세요.

다음 단계

프로젝트 ID와 리전을 쉽게 찾을 수 있는 곳에 보관하세요. Claude Code, Claude Desktop, SDK 클라이언트 모두 이 값들을 요구합니다.

• Claude Code를 배우려면, Claude Code 101을 수강한 다음 Claude Code in action을 수강하세요.
• Claude Cowork를 배우려면, Introduction to Claude Cowork를 수강하세요.
• 직접 작성한 코드에서 Claude를 호출하려면, Google 관리형 문서 페이지를 참조하세요. SDK를 설치하고 AnthropicVertex 클라이언트로 요청을 보내는 방법을 보여줍니다.

서비스 자체에 대해 더 알아보려면, 문서에서 다음 각 항목에 대한 섹션을 확인하세요:

• 글로벌, 멀티 리전, 리전 엔드포인트
• 속도 제한
• 모니터링 및 로깅
• 청구