1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Google Vertex AI에서 Claude Code 사용하기
6
7> Google Vertex AI를 통해 Claude Code를 구성하는 방법을 알아봅니다. 설정, IAM 구성 및 문제 해결을 포함합니다.
8
9export const ContactSalesCard = ({surface}) => {
10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;
11 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">
12 <line x1="5" y1="12" x2="19" y2="12" />
13 <polyline points="12 5 19 12 12 19" />
14 </svg>;
15 const STYLES = `
16.cc-cs {
17 --cs-slate: #141413;
18 --cs-clay: #d97757;
19 --cs-clay-deep: #c6613f;
20 --cs-gray-000: #ffffff;
21 --cs-gray-700: #3d3d3a;
22 --cs-border-default: rgba(31, 30, 29, 0.15);
23 font-family: inherit;
24}
25.dark .cc-cs {
26 --cs-slate: #f0eee6;
27 --cs-gray-000: #262624;
28 --cs-gray-700: #bfbdb4;
29 --cs-border-default: rgba(240, 238, 230, 0.14);
30}
31.cc-cs-card {
32 display: flex; align-items: center; justify-content: space-between;
33 gap: 16px; padding: 14px 16px; margin: 0;
34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);
35 border-radius: 8px; flex-wrap: wrap;
36}
37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }
38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }
39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
40.cc-cs-btn-clay {
41 display: inline-flex; align-items: center; gap: 8px;
42 background: var(--cs-clay-deep); color: #fff; border: none;
43 border-radius: 8px; padding: 8px 14px;
44 font-size: 13px; font-weight: 500;
45 transition: background-color 0.15s; white-space: nowrap;
46}
47.cc-cs-btn-clay:hover { background: var(--cs-clay); }
48.cc-cs-btn-ghost {
49 display: inline-flex; align-items: center; gap: 8px;
50 background: transparent; color: var(--cs-gray-700);
51 border: 0.5px solid var(--cs-border-default);
52 border-radius: 8px; padding: 8px 14px;
53 font-size: 13px; font-weight: 500;
54}
55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }
56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }
57@media (max-width: 720px) {
58 .cc-cs-actions { width: 100%; }
59}
60`;
61 return <div className="cc-cs not-prose">
62 <style>{STYLES}</style>
63 <div className="cc-cs-card">
64 <div className="cc-cs-text">
65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.
66 </div>
67 <div className="cc-cs-actions">
68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">
69 View plans
70 </a>
71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">
72 Contact sales {iconArrowRight()}
73 </a>
74 </div>
75 </div>
76 </div>;
77};
78
79export const Experiment = ({flag, treatment, children}) => {
80 const VID_KEY = 'exp_vid';
81 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);
82 const fnv1a = s => {
83 let h = 0x811c9dc5;
84 for (let i = 0; i < s.length; i++) {
85 h ^= s.charCodeAt(i);
86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
87 }
88 return h >>> 0;
89 };
90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';
91 const [decision] = useState(() => {
92 const params = new URLSearchParams(location.search);
93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];
94 const force = params.get('gb-force');
95 if (force) {
96 for (const p of force.split(',')) {
97 const [k, v] = p.split(':');
98 if (k === flag) return {
99 variant: v || 'treatment',
100 track: false
101 };
102 }
103 }
104 if (navigator.globalPrivacyControl) {
105 return {
106 variant: 'control',
107 track: false
108 };
109 }
110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);
111 if (prefsMatch) {
112 try {
113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {
114 return {
115 variant: 'control',
116 track: false
117 };
118 }
119 } catch {
120 return {
121 variant: 'control',
122 track: false
123 };
124 }
125 } else {
126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];
127 if (!country || CONSENT_COUNTRIES.has(country)) {
128 return {
129 variant: 'control',
130 track: false
131 };
132 }
133 }
134 let vid;
135 try {
136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);
137 if (ajsMatch) {
138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');
139 } else {
140 vid = localStorage.getItem(VID_KEY);
141 if (!vid) {
142 vid = crypto.randomUUID();
143 }
144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;
145 }
146 try {
147 localStorage.setItem(VID_KEY, vid);
148 } catch {}
149 } catch {
150 return {
151 variant: 'control',
152 track: false
153 };
154 }
155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);
156 return {
157 variant,
158 track: true,
159 vid
160 };
161 });
162 useEffect(() => {
163 if (!decision.track) return;
164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {
165 method: 'POST',
166 headers: {
167 'Content-Type': 'application/json',
168 'x-service-name': 'claude_code_docs'
169 },
170 body: JSON.stringify({
171 events: [{
172 event_type: 'GrowthbookExperimentEvent',
173 event_data: {
174 device_id: decision.vid,
175 anonymous_id: decision.vid,
176 timestamp: new Date().toISOString(),
177 experiment_id: flag,
178 variation_id: decision.variant === 'treatment' ? 1 : 0,
179 environment: 'production'
180 }
181 }]
182 }),
183 keepalive: true
184 }).catch(() => {});
185 }, []);
186 return decision.variant === 'treatment' ? treatment : children;
187};
188
189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="vertex" />} />
190
191## 필수 요구사항
192
193Vertex AI를 사용하여 Claude Code를 구성하기 전에 다음을 확인하십시오:
194
195* 청구가 활성화된 Google Cloud Platform(GCP) 계정
196* Vertex AI API가 활성화된 GCP 프로젝트
197* 원하는 Claude 모델에 대한 액세스(예: Claude Sonnet 4.6)
198* Google Cloud SDK(`gcloud`) 설치 및 구성
199* 원하는 GCP 지역에 할당된 할당량
200
201자신의 Vertex AI 자격증명으로 로그인하려면 아래의 [Vertex AI로 로그인](#sign-in-with-vertex-ai)을 따르십시오. 팀 전체에 Claude Code를 배포하려면 [수동 설정](#set-up-manually) 단계를 사용하고 롤아웃 전에 [모델 버전을 고정](#5-pin-model-versions)하십시오.
202
203## Vertex AI로 로그인
204
205Google Cloud 자격증명이 있고 Vertex AI를 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. GCP 측 필수 요구사항을 프로젝트당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.
206
207<Note>
208 Vertex AI 설정 마법사는 Claude Code v2.1.98 이상이 필요합니다. `claude --version`을 실행하여 확인하십시오.
209</Note>
210
211<Steps>
212 <Step title="GCP 프로젝트에서 Claude 모델 활성화">
213 프로젝트에 대해 [Vertex AI API를 활성화](#1-enable-vertex-ai-api)한 다음 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 원하는 Claude 모델에 대한 액세스를 요청합니다. 계정에 필요한 권한은 [IAM 구성](#iam-configuration)을 참조하십시오.
214 </Step>
215
216 <Step title="Claude Code를 시작하고 Vertex AI 선택">
217 `claude`를 실행합니다. 로그인 프롬프트에서 **3rd-party platform**을 선택한 다음 **Google Vertex AI**를 선택합니다.
218 </Step>
219
220 <Step title="마법사 프롬프트 따르기">
221 Google Cloud에 인증하는 방법을 선택합니다: `gcloud`의 Application Default Credentials, 서비스 계정 키 파일 또는 환경에 이미 있는 자격증명. 마법사는 프로젝트와 지역을 감지하고, 프로젝트가 호출할 수 있는 Claude 모델을 확인하며, 이를 고정할 수 있게 합니다. 결과를 [사용자 설정 파일](/ko/settings)의 `env` 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.
222 </Step>
223</Steps>
224
225로그인한 후 언제든지 `/setup-vertex`를 실행하여 마법사를 다시 열고 자격증명, 프로젝트, 지역 또는 모델 고정을 변경할 수 있습니다.
226
227## 지역 구성
228
229Claude Code는 Vertex AI [전역](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai), 다중 지역 및 지역 엔드포인트를 지원합니다. `CLOUD_ML_REGION`을 `global`, `eu` 또는 `us`와 같은 다중 지역 위치 또는 `us-east5`와 같은 특정 지역으로 설정합니다. Claude Code는 `aiplatform.eu.rep.googleapis.com` 및 `aiplatform.us.rep.googleapis.com` 호스트를 포함한 다중 지역 위치에 대해 각 형식에 맞는 올바른 Vertex AI 호스트명을 선택합니다.
230
231<Note>
232 Vertex AI는 모든 엔드포인트 유형에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 모델 가용성은 [특정 지역](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), 다중 지역 위치 및 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)에 따라 다릅니다. 지원되는 위치로 전환하거나 지원되는 모델을 지정해야 할 수 있습니다.
233</Note>
234
235## 수동 설정
236
237마법사 대신 환경 변수를 통해 Vertex AI를 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우) 아래 단계를 따르십시오.
238
239### 1. Vertex AI API 활성화
240
241GCP 프로젝트에서 Vertex AI API를 활성화합니다:
242
243```bash theme={null}
244# 프로젝트 ID 설정
245gcloud config set project YOUR-PROJECT-ID
246
247# Vertex AI API 활성화
248gcloud services enable aiplatform.googleapis.com
249```
250
251### 2. 모델 액세스 요청
252
253Vertex AI에서 Claude 모델에 대한 액세스를 요청합니다:
254
2551. [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)으로 이동합니다
2562. "Claude" 모델을 검색합니다
2573. 원하는 Claude 모델에 대한 액세스를 요청합니다(예: Claude Sonnet 4.6)
2584. 승인을 기다립니다(24-48시간이 소요될 수 있습니다)
259
260### 3. GCP 자격증명 구성
261
262Claude Code는 표준 Google Cloud 인증을 사용합니다.
263
264자세한 내용은 [Google Cloud 인증 설명서](https://cloud.google.com/docs/authentication)를 참조하십시오.
265
266Claude Code v2.1.121 이상은 동일한 Application Default Credentials 체인을 통해 [X.509 인증서 기반 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)을 지원합니다. `GOOGLE_APPLICATION_CREDENTIALS`를 자격증명 구성 파일의 경로로 설정합니다.
267
268<Note>
269 인증할 때 Claude Code는 `ANTHROPIC_VERTEX_PROJECT_ID` 환경 변수에서 프로젝트 ID를 자동으로 사용합니다. 이를 재정의하려면 다음 환경 변수 중 하나를 설정하십시오: `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS`.
270</Note>
271
272### 4. Claude Code 구성
273
274다음 환경 변수를 설정합니다:
275
276```bash theme={null}
277# Vertex AI 통합 활성화
278export CLAUDE_CODE_USE_VERTEX=1
279export CLOUD_ML_REGION=global
280export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
281
282# 선택사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위해 Vertex 엔드포인트 URL 재정의
283# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com
284
285# 선택사항: 필요한 경우 prompt caching 비활성화
286export DISABLE_PROMPT_CACHING=1
287
288# 선택사항: 기본 5분 대신 1시간 prompt cache TTL 요청
289export ENABLE_PROMPT_CACHING_1H=1
290
291# CLOUD_ML_REGION=global일 때, 전역 엔드포인트를 지원하지 않는 모델의 지역 재정의
292export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
293export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
294```
295
296대부분의 모델 버전에는 해당하는 `VERTEX_REGION_CLAUDE_*` 변수가 있습니다. 전체 목록은 [환경 변수 참조](/ko/env-vars)를 참조하십시오. [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 어떤 모델이 전역 엔드포인트를 지원하는지 또는 지역 전용인지 확인하십시오.
297
298[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)은 자동으로 활성화됩니다. 이를 비활성화하려면 `DISABLE_PROMPT_CACHING=1`을 설정하십시오. 기본 5분 대신 1시간 캐시 TTL을 요청하려면 `ENABLE_PROMPT_CACHING_1H=1`을 설정하십시오. 1시간 TTL을 사용한 캐시 쓰기는 더 높은 요금으로 청구됩니다. 높은 속도 제한을 위해 Google Cloud 지원팀에 문의하십시오. Vertex AI를 사용할 때 `/login` 및 `/logout` 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 비활성화됩니다.
299
300[MCP tool search](/ko/mcp#scale-with-mcp-tool-search)는 엔드포인트가 필요한 베타 헤더를 허용하지 않으므로 Vertex AI에서 기본적으로 비활성화됩니다. 모든 MCP 도구 정의는 대신 미리 로드됩니다. 옵트인하려면 `ENABLE_TOOL_SEARCH=true`를 설정하십시오.
301
302### 5. 모델 버전 고정
303
304<Warning>
305 여러 사용자에게 배포할 때 특정 모델 버전을 고정합니다. 고정하지 않으면 `sonnet` 및 `opus`와 같은 모델 별칭이 최신 버전으로 확인되며, Anthropic이 업데이트를 출시할 때 Vertex AI 프로젝트에서 아직 활성화되지 않았을 수 있습니다. Claude Code는 최신 버전을 사용할 수 없을 때 시작 시 [이전 버전으로 폴백](#startup-model-checks)하지만, 고정하면 사용자가 새 모델로 이동하는 시기를 제어할 수 있습니다.
306</Warning>
307
308이러한 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다.
309
310`ANTHROPIC_DEFAULT_OPUS_MODEL`이 없으면 Vertex의 `opus` 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.7 ID로 설정합니다:
311
312```bash theme={null}
313export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
314export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
315export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
316```
317
318현재 및 레거시 모델 ID는 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 참조하십시오. 환경 변수의 전체 목록은 [모델 구성](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.
319
320Claude Code는 고정 변수가 설정되지 않았을 때 이러한 기본 모델을 사용합니다:
321
322| 모델 유형 | 기본값 |
323| :------- | :--------------------------- |
324| 주 모델 | `claude-sonnet-4-5@20250929` |
325| 소형/빠른 모델 | `claude-haiku-4-5@20251001` |
326
327모델을 추가로 사용자 정의하려면:
328
329```bash theme={null}
330export ANTHROPIC_MODEL='claude-opus-4-7'
331export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
332```
333
334## 시작 모델 확인
335
336Claude Code가 Vertex AI로 구성되어 시작할 때 사용하려는 모델이 프로젝트에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.98 이상이 필요합니다.
337
338현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 프로젝트가 최신 버전을 호출할 수 있으면 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 [사용자 설정 파일](/ko/settings)에 쓰고 Claude Code를 다시 시작합니다. 거절하면 다음 기본 버전 변경까지 기억됩니다.
339
340모델을 고정하지 않았고 현재 기본값을 프로젝트에서 사용할 수 없으면 Claude Code는 현재 세션에 대해 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 최신 모델을 활성화하거나 [버전을 고정](#5-pin-model-versions)하여 선택을 영구적으로 만듭니다.
341
342## IAM 구성
343
344필요한 IAM 권한을 할당합니다:
345
346`roles/aiplatform.user` 역할에는 필요한 권한이 포함됩니다:
347
348* `aiplatform.endpoints.predict` - 모델 호출 및 토큰 계산에 필요
349
350더 제한적인 권한의 경우 위의 권한만 포함하는 사용자 정의 역할을 만듭니다.
351
352자세한 내용은 [Vertex IAM 설명서](https://cloud.google.com/vertex-ai/docs/general/access-control)를 참조하십시오.
353
354<Note>
355 비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code용 전용 GCP 프로젝트를 만듭니다.
356</Note>
357
358## 1M 토큰 context window
359
360Claude Opus 4.7, Opus 4.6 및 Sonnet 4.6은 Vertex AI에서 [1M 토큰 context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)를 지원합니다. Claude Code는 1M 모델 변형을 선택할 때 확장된 context window를 자동으로 활성화합니다.
361
362[설정 마법사](#sign-in-with-vertex-ai)는 모델을 고정할 때 1M context 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 `[1m]`을 추가합니다. 자세한 내용은 [타사 배포를 위한 모델 고정](/ko/model-config#pin-models-for-third-party-deployments)을 참조하십시오.
363
364## 문제 해결
365
366할당량 문제가 발생하는 경우:
367
368* [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)을 통해 현재 할당량을 확인하거나 할당량 증가를 요청합니다
369
370"모델을 찾을 수 없음" 404 오류가 발생하는 경우:
371
372* [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)에서 모델이 활성화되어 있는지 확인합니다
373* 지정된 위치에서 모델을 사용할 수 있는지 확인합니다. 일부 모델은 특정 지역이 아닌 `global` 또는 `eu` 및 `us`와 같은 다중 지역 위치에서만 제공됩니다
374* `CLOUD_ML_REGION=global`을 사용하는 경우 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)의 "지원되는 기능" 아래에서 모델이 전역 엔드포인트를 지원하는지 확인합니다. 전역 엔드포인트를 지원하지 않는 모델의 경우:
375 * `ANTHROPIC_MODEL` 또는 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 통해 지원되는 모델을 지정하거나,
376 * `VERTEX_REGION_<MODEL_NAME>` 환경 변수를 사용하여 지역 또는 다중 지역 위치를 설정합니다
377
378429 오류가 발생하는 경우:
379
380* 지역 엔드포인트의 경우 주 모델과 소형/빠른 모델이 선택한 지역에서 지원되는지 확인합니다
381* `CLOUD_ML_REGION=global`로 전환하여 더 나은 가용성을 고려합니다
382
383## 추가 리소스
384
385* [Vertex AI 설명서](https://cloud.google.com/vertex-ai/docs)
386* [Vertex AI 가격](https://cloud.google.com/vertex-ai/pricing)
387* [Vertex AI 할당량 및 제한](https://cloud.google.com/vertex-ai/docs/quotas)
