メインコンテンツへスキップ

​
前提条件

Vertex AIでClaude Codeを設定する前に、以下を確認してください：
  • 請求が有効になっているGoogle Cloud Platform（GCP）アカウント
  • Vertex AI APIが有効になっているGCPプロジェクト
  • 目的のClaudeモデルへのアクセス（例：Claude Sonnet 4.5）
  • Google Cloud SDK（gcloud）がインストールおよび設定されていること
  • 目的のGCPリージョンに割り当てられたクォータ

​
リージョン設定

Claude CodeはVertex AI グローバルとリージョナルエンドポイントの両方で使用できます。
Vertex AIは、すべてのリージョンでClaude Codeのデフォルトモデルをサポートしていない場合があります。サポートされているリージョンまたはモデルに切り替える必要がある場合があります。
Vertex AIは、グローバルエンドポイントでClaude Codeのデフォルトモデルをサポートしていない場合があります。リージョナルエンドポイントまたはサポートされているモデルに切り替える必要がある場合があります。

​
セットアップ

​
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.5）へのアクセスをリクエストします
  4. 承認を待ちます（24～48時間かかる場合があります）

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

Claude Codeは標準的なGoogle Cloud認証を使用します。 詳細については、Google Cloud認証ドキュメントを参照してください。
認証時に、Claude CodeはANTHROPIC_VERTEX_PROJECT_ID環境変数からプロジェクトIDを自動的に使用します。これをオーバーライドするには、GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT、またはGOOGLE_APPLICATION_CREDENTIALSのいずれかの環境変数を設定します。

​
4. Claude Codeを設定する

以下の環境変数を設定します： 
# Vertex AI統合を有効にする
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

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

# CLOUD_ML_REGION=globalの場合、サポートされていないモデルのリージョンをオーバーライドする
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# オプション：他の特定のモデルのリージョンをオーバーライドする
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
プロンプトキャッシングは、cache_controlエフェメラルフラグを指定すると自動的にサポートされます。これを無効にするには、DISABLE_PROMPT_CACHING=1を設定します。レート制限を高くするには、Google Cloudサポートに連絡してください。
Vertex AIを使用する場合、Google Cloud認証情報を通じて認証が処理されるため、/loginおよび/logoutコマンドは無効になります。

​
5. モデル設定

Claude CodeはVertex AIに対して以下のデフォルトモデルを使用します：
モデルタイプデフォルト値
プライマリモデルclaude-sonnet-4-5@20250929
小型/高速モデルclaude-haiku-4-5@20251001
Vertex AIユーザーの場合、Claude CodeはHaiku 3.5からHaiku 4.5に自動的にアップグレードされません。新しいHaikuモデルに手動で切り替えるには、ANTHROPIC_DEFAULT_HAIKU_MODEL環境変数をフルモデル名に設定します（例：claude-haiku-4-5@20251001）。
モデルをカスタマイズするには： 
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
IAM設定

必要なIAMパーミッションを割り当てます： roles/aiplatform.userロールには必要なパーミッションが含まれています：
  • aiplatform.endpoints.predict - モデル呼び出しとトークンカウントに必要
より制限的なパーミッションの場合は、上記のパーミッションのみを持つカスタムロールを作成します。 詳細については、Vertex IAMドキュメントを参照してください。
コスト追跡とアクセス制御を簡素化するために、Claude Code用の専用GCPプロジェクトを作成することをお勧めします。

​
1Mトークンコンテキストウィンドウ

Claude Sonnet 4およびSonnet 4.5は、Vertex AIで1Mトークンコンテキストウィンドウをサポートしています。
1Mトークンコンテキストウィンドウは現在ベータ版です。拡張コンテキストウィンドウを使用するには、Vertex AIリクエストにcontext-1m-2025-08-07ベータヘッダーを含めます。

​
トラブルシューティング

クォータの問題が発生した場合：
  • Cloud Consoleを通じて現在のクォータを確認するか、クォータ増加をリクエストします
「モデルが見つかりません」404エラーが発生した場合：
  • Model Gardenでモデルが有効になっていることを確認します
  • 指定されたリージョンへのアクセス権があることを確認します
  • CLOUD_ML_REGION=globalを使用している場合、Model Gardenの「サポートされている機能」でモデルがグローバルエンドポイントをサポートしていることを確認します。グローバルエンドポイントをサポートしていないモデルの場合は、以下のいずれかを実行します：
    • ANTHROPIC_MODELまたはANTHROPIC_SMALL_FAST_MODELを通じてサポートされているモデルを指定するか、
    • VERTEX_REGION_<MODEL_NAME>環境変数を使用してリージョナルエンドポイントを設定します
429エラーが発生した場合：
  • リージョナルエンドポイントの場合、プライマリモデルと小型/高速モデルが選択されたリージョンでサポートされていることを確認します
  • より良い可用性のためにCLOUD_ML_REGION=globalへの切り替えを検討します

​
追加リソース