Google Vertex AI 上の Claude Code

Google 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) => ; 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

export const Experiment = ({flag, treatment, children}) => { const VID_KEY = 'exp_vid'; 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']); const fnv1a = s => { let h = 0x811c9dc5; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24); } return h >>> 0; }; const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment'; const [decision] = useState(() => { const params = new URLSearchParams(location.search); const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')]; const force = params.get('gb-force'); if (force) { for (const p of force.split(',')) { const [k, v] = p.split(':'); if (k === flag) return { variant: v || 'treatment', track: false }; } } if (navigator.globalPrivacyControl) { return { variant: 'control', track: false }; } const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/); if (prefsMatch) { try { if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) { return { variant: 'control', track: false }; } } catch { return { variant: 'control', track: false }; } } else { const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1]; if (!country || CONSENT_COUNTRIES.has(country)) { return { variant: 'control', track: false }; } } let vid; try { const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/); if (ajsMatch) { vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, ''); } else { vid = localStorage.getItem(VID_KEY); if (!vid) { vid = crypto.randomUUID(); } document.cookie = ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000; } try { localStorage.setItem(VID_KEY, vid); } catch {} } catch { return { variant: 'control', track: false }; } const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid); return { variant, track: true, vid }; }); useEffect(() => { if (!decision.track) return; fetch('https://api.anthropic.com/api/event_logging/v2/batch', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-service-name': 'claude_code_docs' }, body: JSON.stringify({ events: [{ event_type: 'GrowthbookExperimentEvent', event_data: { device_id: decision.vid, anonymous_id: decision.vid, timestamp: new Date().toISOString(), experiment_id: flag, variation_id: decision.variant === 'treatment' ? 1 : 0, environment: 'production' } }] }), keepalive: true }).catch(() => {}); }, []); return decision.variant === 'treatment' ? treatment : children; };

<Experiment flag="docs-contact-sales-cta" treatment={} />

前提条件

Claude Code を Vertex AI で設定する前に、以下を確認してください。

• 請求が有効になっている Google Cloud Platform（GCP）アカウント
• Vertex AI API が有効になっている GCP プロジェクト
• 目的の Claude モデルへのアクセス（例：Claude Sonnet 4.6）
• Google Cloud SDK（gcloud）がインストールされ、設定されていること
• 目的の GCP リージョンに割り当てられたクォータ

Vertex AI 認証情報で サインインするには、以下のVertex AI でサインインに従ってください。チーム全体に Claude Code をデプロイするには、手動セットアップの手順を使用し、ロールアウト前にモデルバージョンをピン留めしてください。

Vertex AI でサインイン

Google Cloud 認証情報を持っていて、Vertex AI を通じて Claude Code の使用を開始したい場合、ログインウィザードがそれをガイドします。GCP 側の前提条件はプロジェクトごとに 1 回完了します。ウィザードが Claude Code 側を処理します。

サインイン後、いつでも /setup-vertex を実行してウィザードを再度開き、認証情報、プロジェクト、リージョン、またはモデルピンを変更できます。

リージョン設定

Claude Code は Vertex AI のグローバル、マルチリージョン、および地域別エンドポイントをサポートしています。CLOUD_ML_REGION を global、eu または us などのマルチリージョンロケーション、または us-east5 などの特定のリージョンに設定します。Claude Code は各フォームの正しい Vertex AI ホスト名を選択します。これには、マルチリージョンロケーション用の aiplatform.eu.rep.googleapis.com および aiplatform.us.rep.googleapis.com ホストが含まれます。

手動でセットアップする

ウィザードの代わりに環境変数を通じて Vertex AI を設定するには、例えば CI またはスクリプト化されたエンタープライズロールアウトで、以下の手順に従ってください。

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.6）
4. 承認を待ちます（24 ～ 48 時間かかる場合があります）

3. GCP 認証情報を設定する

Claude Code は標準的な Google Cloud 認証を使用します。

詳細については、Google Cloud 認証ドキュメントを参照してください。

Claude Code v2.1.121 以降は、同じ Application Default Credentials チェーンを通じて X.509 証明書ベースのワークロード ID フェデレーションをサポートしています。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 を設定する

次の環境変数を設定します。

# Vertex AI 統合を有効にする
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# オプション：カスタムエンドポイントまたはゲートウェイ用に Vertex エンドポイント URL をオーバーライドする
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# オプション：必要に応じてプロンプトキャッシングを無効にする
export DISABLE_PROMPT_CACHING=1

# オプション：デフォルトの 5 分ではなく 1 時間のプロンプトキャッシュ 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_* 変数があります。完全なリストについては、環境変数リファレンスを参照してください。どのモデルがグローバルエンドポイントをサポートしているか、または地域別のみをサポートしているかを確認するには、Vertex Model Gardenを確認してください。

prompt cachingは自動的に有効になります。これを無効にするには、DISABLE_PROMPT_CACHING=1 を設定します。デフォルトの 5 分ではなく 1 時間のキャッシュ TTL をリクエストするには、ENABLE_PROMPT_CACHING_1H=1 を設定します。1 時間の TTL でのキャッシュ書き込みはより高いレートで課金されます。レート制限を高くするには、Google Cloud サポートに連絡してください。Vertex AI を使用する場合、Google Cloud 認証情報を通じて認証が処理されるため、/login および /logout コマンドは無効になります。

MCP tool searchは、エンドポイントが必要なベータヘッダーを受け入れないため、Vertex AI ではデフォルトで無効になっています。すべての MCP ツール定義は代わりに事前にロードされます。オプトインするには、ENABLE_TOOL_SEARCH=true を設定します。

5. モデルバージョンをピン留めする

これらの環境変数を特定の Vertex AI モデル ID に設定します。

ANTHROPIC_DEFAULT_OPUS_MODEL がない場合、Vertex 上の opus エイリアスは Opus 4.6 に解決されます。最新モデルを使用するには、Opus 4.7 ID に設定します。

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

現在および従来のモデル ID については、モデル概要を参照してください。環境変数の完全なリストについては、モデル設定を参照してください。

Claude Code は、ピン留め変数が設定されていない場合、これらのデフォルトモデルを使用します。

モデルをさらにカスタマイズするには、以下を実行します。

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

起動時のモデルチェック

Claude Code が Vertex AI で設定されて起動すると、使用するモデルがプロジェクトでアクセス可能であることを確認します。このチェックには Claude Code v2.1.98 以降が必要です。

Claude Code デフォルトより古いモデルバージョンをピン留めしていて、プロジェクトが新しいバージョンを呼び出せる場合、Claude Code はピンを更新するよう促します。受け入れると、新しいモデル ID がユーザー設定ファイルに書き込まれ、Claude Code が再起動されます。拒否すると、次のデフォルトバージョン変更まで記憶されます。

モデルをピン留めしていなくて、現在のデフォルトがプロジェクトで利用できない場合、Claude Code は現在のセッション用に前のバージョンにフォールバックし、通知を表示します。フォールバックは永続化されません。Model Gardenで新しいモデルを有効にするか、バージョンをピン留めして選択を永続化してください。

IAM 設定

必要な IAM 権限を割り当てます。

roles/aiplatform.user ロールには、必要な権限が含まれています。

• aiplatform.endpoints.predict - モデル呼び出しとトークンカウントに必要

より制限的な権限については、上記の権限のみを持つカスタムロールを作成してください。

詳細については、Vertex IAM ドキュメントを参照してください。

100 万トークンコンテキストウィンドウ

Claude Opus 4.7、Opus 4.6、および Sonnet 4.6 は、Vertex AI で100 万トークンコンテキストウィンドウをサポートしています。Claude Code は、100 万トークンモデルバリアントを選択すると、拡張コンテキストウィンドウを自動的に有効にします。

セットアップウィザードは、モデルをピン留めするときに 100 万トークンコンテキストオプションを提供します。手動でピン留めされたモデルの代わりに有効にするには、モデル ID に [1m] を追加します。詳細については、サードパーティデプロイメント用のモデルをピン留めするを参照してください。

トラブルシューティング

「デフォルト認証情報を読み込めません」エラーが発生した場合：

• gcloud auth application-default login を実行して Application Default Credentials をセットアップしてください
• GOOGLE_APPLICATION_CREDENTIALS をサービスアカウントキーファイルパスに設定してください
• すべてのオプションについては、GCP 認証情報の設定を参照してください

クォータの問題が発生した場合：

• Cloud Consoleを通じて現在のクォータを確認するか、クォータ増加をリクエストしてください

「モデルが見つかりません」404 エラーが発生した場合：

• Model Gardenでモデルが有効になっていることを確認してください
• 指定したロケーションでモデルが利用可能であることを確認してください。一部のモデルは global またはマルチリージョンロケーション（eu および us など）でのみ提供され、特定のリージョンでは提供されていません
• CLOUD_ML_REGION=global を使用している場合、Model Gardenの「サポートされている機能」でモデルがグローバルエンドポイントをサポートしていることを確認してください。グローバルエンドポイントをサポートしていないモデルの場合は、以下のいずれかを実行してください：
  • ANTHROPIC_MODEL または ANTHROPIC_DEFAULT_HAIKU_MODEL を通じてサポートされているモデルを指定するか、
  • VERTEX_REGION_<MODEL_NAME> 環境変数を使用してリージョンまたはマルチリージョンロケーションを設定してください

429 エラーが発生した場合：

• 地域別エンドポイントの場合、プライマリモデルと小型/高速モデルが選択したリージョンでサポートされていることを確認してください
• より良い可用性のために CLOUD_ML_REGION=global に切り替えることを検討してください

追加リソース

• Vertex AI ドキュメント
• Vertex AI 価格
• Vertex AI クォータと制限