Vertex AI 経由で Claude Code を使う｜GCP 認証と設定方法
「Claude Code を会社の GCP 環境から使いたい」「Anthropic に直接 API 契約しなくても Claude Code は使えるの?」という問いに答えるのが本記事です。Claude Code は Anthropic 直 API 以外に、Google Cloud Vertex AI と AWS Bedrock をバックエンドとして選択できます。Vertex AI 経由にすると、GCP の請求アカウントへの統合、IAM による細かいアクセス制御、VPC Service Controls によるネットワーク境界保護が可能になります。
本記事は Anthropic 公式ドキュメント — Google Vertex AI 上の Claude Code を基に、GCP プロジェクトの準備から認証設定・環境変数・モデルのピン留めまでを一通り整理します。
Claude Code を Vertex AI 経由で動かすには、CLAUDE_CODE_USE_VERTEX=1 を設定して /setup-vertex ウィザードを実行するのが最短手順です。Claude Code v2.1.98 以降で利用でき、GCP の Application Default Credentials またはサービスアカウントキーで認証します。Anthropic API キーは不要で、課金は GCP の請求アカウントにまとまります。
IAM では roles/aiplatform.user ロールを付与するだけで Claude Code の実行に必要な権限が揃います。エンタープライズ向けには専用 GCP プロジェクトを作成して、コスト追跡とアクセス制御を分離する構成が公式推奨です。
複数人へのデプロイ時はモデルバージョンのピン留めが重要で、エイリアス(sonnet など)を使うと Vertex AI でそのバージョンが未有効なときに起動エラーになります。ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6' のように明示指定することで、チーム全体のモデルバージョンを制御できます。
目次 (11)
Vertex AI 経由で Claude Code を使うメリット
Anthropic に別途契約せず、Google Cloud のクレジットや既存の GCP 請求アカウントで Claude Code を動かせる点が最大のメリットです。
| 項目 | Vertex AI 経由 | Anthropic 直 API |
|---|---|---|
| 課金先 | GCP 請求アカウント | Anthropic クレジット |
| 認証方式 | gcloud / サービスアカウント | Anthropic API キー |
| SSO / IAM 連携 | GCP IAM で一元管理 | Anthropic Console のみ |
| VPC 境界保護 | VPC Service Controls 対応 | 非対応 |
| 最新モデル提供速度 | 数週間遅れる場合あり | リリース当日 |
| クォータ管理 | Cloud Console で増減申請 | Anthropic 側で個別対応 |
GCP にすでに組織アカウントを持つ企業では、Claude Code のコスト集計・アクセス制御・監査ログをすべて GCP 側で完結できます。機密データを扱う金融・医療系では、VPC Service Controls の境界内で Claude Code を動かせることが採用の理由になるケースもあります。
前提条件｜GCP プロジェクトと API の準備
Claude Code を Vertex AI で動かすには、以下を事前に揃えておきます。
- 請求が有効な GCP アカウント
- Vertex AI API が有効な GCP プロジェクト
- Vertex AI Model Garden で Claude モデルへのアクセス申請済み
- Google Cloud SDK(
gcloud)のインストールと初期設定 - 使用するリージョンへのクォータ割り当て
GCP 側の事前設定手順
- GCP プロジェクトを作成または選択し、デフォルトプロジェクトに設定する
gcloud config set project YOUR-PROJECT-ID
- Vertex AI API を有効化する
gcloud services enable aiplatform.googleapis.com
- Vertex AI Model Garden で「Claude」を検索し、利用したいモデル(Claude Sonnet 4.6 など)の「Enable」をクリックしてアクセスをリクエストする。承認には 24〜48 時間かかる場合があります。
ウィザードを使った最短セットアップ(推奨)
Claude Code v2.1.98 以降では、/setup-vertex コマンドで対話型ウィザードが起動します。環境変数を手書きせずに設定が完了するため、個人・チームを問わずウィザード経由が推奨です。
- Claude Code のバージョンを確認する
claude --version
# v2.1.98 以上が必要
claudeを実行し、ログインプロンプトを開く- 「3rd-party platform」 → 「Google Vertex AI」 の順に選択する
- Google Cloud への認証方法を選ぶ
gcloud auth application-default loginで取得した Application Default Credentials- サービスアカウントキーファイル
- 環境にすでにある認証情報
- ウィザードがプロジェクトとリージョンを自動検出し、有効化済みの Claude モデルを確認してピン留めする
- 設定結果はユーザー設定ファイルの
envブロックに自動保存される
セットアップ後に認証情報・プロジェクト・リージョン・モデルを変更したいときは、いつでも /setup-vertex を再実行できます。
環境変数による手動設定
CI/CD やチームへの一括デプロイには、環境変数で直接設定する手動方式が適しています。
# Vertex AI 統合を有効化
export CLAUDE_CODE_USE_VERTEX=1
# グローバルエンドポイントを使用(ほとんどのケースで推奨)
export CLOUD_ML_REGION=global
# GCP プロジェクト ID
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
CLOUD_ML_REGION には global(グローバルエンドポイント)、eu / us(マルチリージョン)、us-east5 などの特定リージョンを設定できます。グローバルエンドポイントはすべてのモデルが対応しているわけではないため、Vertex AI Model Garden で事前に確認してください。
モデルごとにリージョンを上書きしたい場合は専用の環境変数を使います。
# グローバルエンドポイント非対応モデルのリージョン個別指定
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
認証情報の自動更新設定
認証情報が期限切れになったときに自動で再取得するには、設定ファイルの gcpAuthRefresh を使います。
{
"gcpAuthRefresh": "gcloud auth application-default login",
"env": {
"ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
}
}
指定したコマンドは Claude Code が認証エラーを検出したタイミングで実行され、3 分でタイムアウトします。ブラウザで URL を開いて認証を完了するフローに対応しています。設定はプロジェクト設定ファイル(.claude/settings.json)に記述することもでき、ワークスペース信頼を受け入れた後にのみ実行されます。
IAM 権限の設定
Claude Code に必要な GCP 権限は roles/aiplatform.user ロールです。このロールに含まれる主要な権限は以下の 1 つです。
aiplatform.endpoints.predict— モデル呼び出しとトークンカウントに必要
最小権限を付与したい場合は、aiplatform.endpoints.predict のみを持つカスタムロールを作成できます。ロールの付与は次のコマンドで行います。
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
--member="user:YOUR_EMAIL@example.com" \
--role="roles/aiplatform.user"
詳細なアクセス制御方針は Vertex IAM ドキュメント を参照してください。コスト追跡とアクセス制御を簡素化するために、Claude Code 専用の GCP プロジェクトを作成することが公式で推奨されています。
モデルバージョンのピン留め
複数のユーザーに Claude Code を配布する場合、モデルバージョンを明示的にピン留めすることが重要です。ピン留めなしでは sonnet / opus などのエイリアスが最新バージョンに解決されますが、Vertex AI プロジェクトでそのバージョンが未有効の場合は起動エラーになります。
# 特定のモデルバージョンにピン留め
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
モデルの現在および過去のバージョン ID は Anthropic モデル概要 で確認できます。
ピン留めしていないモデルが利用できない場合、Claude Code は自動的に前のバージョンにフォールバックして通知を表示します。フォールバックは一時的なため、恒久対応には Model Garden でのモデル有効化かピン留め設定が必要です。
100 万トークンコンテキストウィンドウを使う場合は、モデル ID に [1m] を追加します。Claude Opus 4.6 以降・Sonnet 4.6 が Vertex AI での 1M コンテキストに対応しています。ウィザードのピン留めオプションでも選択可能です。
リージョン設定とグローバルエンドポイント
Vertex AI は特定リージョン・マルチリージョン・グローバルの三層でエンドポイントを提供します。
CLOUD_ML_REGION 設定値 |
エンドポイント種別 | 主な特徴 |
|---|---|---|
global |
グローバル | 最も広い可用性。一部モデルは非対応 |
eu / us |
マルチリージョン | 地理的なデータレジデンシー要件に対応 |
us-east5 など |
地域別 | 特定リージョンのみ。モデル可用性は限定的 |
日本からの利用では global または us-east5 が最初の選択肢になります。東京リージョン(asia-northeast1)は Claude モデルが直接提供されていない期間があるため、Vertex AI のパートナーモデル提供リージョン一覧 を都度確認してください。
CLOUD_ML_REGION=global でグローバルエンドポイントをサポートしていないモデルを使う場合、モデルごとのリージョン上書き変数(VERTEX_REGION_CLAUDE_*)を設定することで動作させられます。
トラブルシューティング
よく発生するエラーと対処法を整理します。
「デフォルト認証情報を読み込めません」エラー
gcloud auth application-default loginを実行して Application Default Credentials を更新するGOOGLE_APPLICATION_CREDENTIALSをサービスアカウントキーファイルのパスに設定する
404「モデルが見つかりません」エラー
- Model Garden でモデルが有効になっているか確認する
- 指定したリージョンでそのモデルが利用可能か確認する
CLOUD_ML_REGION=global使用時は、グローバルエンドポイント非対応のモデルにはVERTEX_REGION_<MODEL_NAME>で個別リージョンを指定する
429 レートリミットエラー
- プライマリモデルと Haiku の両方が選択したリージョンでサポートされているか確認する
- 地域別エンドポイントから
CLOUD_ML_REGION=globalへの切り替えを検討する - Cloud Console のクォータ管理 からクォータ増加をリクエストする
クォータの問題
プロジェクト作成直後はリージョンごとのクォータが低く設定されています。Cloud Console のクォータページ から増加申請が可能です。
まとめ
Vertex AI 経由で Claude Code を使うには、GCP プロジェクトで Vertex AI API を有効化して Model Garden でモデルへのアクセスをリクエストした後、/setup-vertex ウィザードまたは環境変数 CLAUDE_CODE_USE_VERTEX=1 で連携を有効にします。
GCP のコスト管理・IAM・セキュリティ境界をそのまま Claude Code に適用できるため、すでに Google Cloud 上に開発インフラを持つ企業に適した構成です。複数人への配布時はモデルバージョンのピン留めを忘れずに行いましょう。最新の設定情報は Anthropic 公式ドキュメント で随時更新されています。
