マルチエージェントClaude Code Vertex AI設定｜Google Cloudで使う
この記事の要点
- Google Cloud の Vertex AI は名前が Agent Platform に変わったが、Claude Code のログイン画面では今も Google Vertex AI と表示される
- 手で設定するなら CLAUDE_CODE_USE_VERTEX=1・CLOUD_ML_REGION・ANTHROPIC_VERTEX_PROJECT_ID の3つが基本
- チームに配るときはモデルの版を固定し、/status で API provider の行を必ず確かめる
会社のクラウドが Google Cloud なら、Claude Code を Vertex AI 経由 で使えます。請求と権限の管理を Google Cloud のプロジェクトにまとめられるのが利点です。
なお Google Cloud の Vertex AI は、いまは Agent Platform という名前に変わっています。ただし Claude Code のログイン画面では、今も「Google Vertex AI」と表示されます。この記事では、検索で探しやすい Vertex AI の名前で書きます。
内容は公式ドキュメント「Claude Code on Google Cloud's Agent Platform」（2026年11月2日確認）にもとづきます。
結論：1人ならウィザード、チームなら6ステップの手動設定
自分1人で試すなら、claude を起動したときのログイン画面で 3rd-party platform → Google Vertex AI を選べば、案内に沿って設定が終わります。 すでにログイン済みなら /login で同じメニューが開きます。
ウィザードでは、認証の方法（gcloud の資格情報・サービスアカウントの鍵のファイル・環境にある資格情報）、プロジェクト、地域を順に聞かれ、使えるモデルを確かめて版を固定するところまで進みます。結果は自分用の設定ファイル（~/.claude/settings.json）の env に保存され、あとから /setup-vertex で開き直せます。
CI やチーム全体に配るときは、次の6ステップで環境変数を使って設定します。
ステップ1：API を有効にする
Google Cloud のプロジェクトで、Agent Platform の API を有効にします。 請求が有効なプロジェクトと、gcloud コマンドが必要です。
gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com公式ドキュメントは、Claude Code 専用のプロジェクトを作ると、費用の把握と権限の管理がしやすい とすすめています。
ステップ2：モデルの利用を申請する
Model Garden で「Claude」を検索し、使いたいモデルの利用を申請します。 承認には24〜48時間かかることがあるので、導入の予定日から逆算して早めに出しておきます。
ステップ3：認証を用意する
Claude Code は Google Cloud の標準の認証の流れを使います。 手元のパソコンなら、次のコマンドで資格情報を用意するのがいちばん手軽です。
gcloud auth application-default loginサービスアカウントの鍵のファイルを使う場合は、GOOGLE_APPLICATION_CREDENTIALS にそのファイルの場所を設定します。資格情報の期限切れに備えたいなら、設定ファイルの gcpAuthRefresh に再ログインのコマンドを書いておくと、期限切れに気づいたときだけ自動で動きます。
注意したいのは、呼び出し先のプロジェクトは ANTHROPIC_VERTEX_PROJECT_ID の値で決まる ことです。ほかの環境変数や鍵のファイルに別のプロジェクトが書かれていても、こちらが使われます。
ステップ4：Claude Code 側の環境変数を設定する
基本は次の3つです。
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID| 変数 | 役割 |
|---|---|
CLAUDE_CODE_USE_VERTEX | 1 で Vertex AI 経由に切り替える |
CLOUD_ML_REGION | global、us や eu のような複数地域、us-east5 のような地域のどれか |
ANTHROPIC_VERTEX_PROJECT_ID | 呼び出し先のプロジェクト |
global に対応していないモデルだけ別の地域にしたいときは、VERTEX_REGION_CLAUDE_HAIKU_4_5 のようにモデルごとの変数で上書きできます。地域の値が地域名の形をしていない（スラッシュや空白を含む等）と未設定として扱われ、CLOUD_ML_REGION が未設定なら us-east5 になります。
プロンプトキャッシュは自動で有効になります。仕組みは プロンプトキャッシュのQ&A で説明しています。
ステップ5：モデルの版を固定する
複数の人に配るときは、モデルの版を必ず固定します。 固定しないと opus や sonnet の呼び名は Claude Code に組み込まれた既定に解決され、それが自分のプロジェクトでまだ使えないことがあります。
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'主に使うモデルを固定しないと Opus の料金で請求される 点にも注意します。起動時には、使う予定のモデルがプロジェクトで呼べるかが確かめられ、固定していないのに既定のモデルが使えないときは、その回だけ前の版や下位のモデルに切り替わってお知らせが出ます。モデルの選び方は Claude Codeのモデル選び を参考にしてください。
ステップ6：/status で確かめる
Claude Code を起動して /status を打ち、API provider の行に Google Vertex AI と出ているかを見ます。 プロジェクト・地域・モデルの行もあわせて確かめます。
provider の行が無いときは、環境変数が Claude Code まで届いていません。claude を起動したシェルで export しているか、設定ファイルの env に書いているかを見直します。設定ファイルの置き場所と効く順番は Claude Codeのsettings.json入門 にまとめています。
権限（IAM）
roles/aiplatform.user のロールを付ければ、必要な権限（aiplatform.endpoints.predict）がそろいます。 もっと絞りたいときは、この権限だけを持つカスタムロールを作ります。
つまずきやすい点
| 症状 | 見直すところ |
|---|---|
| Could not load the default credentials | gcloud auth application-default login を実行するか、GOOGLE_APPLICATION_CREDENTIALS に鍵のファイルを設定 |
| model not found（404） | Model Garden でモデルが有効か、指定した地域で使えるかを確認。global 非対応のモデルはモデルごとの地域の変数で地域を指定 |
| 429 エラー | 地域を指定しているなら主モデルと小さいモデルの両方がその地域で使えるか確認。global に切り替えるのも手 |
| 上限が足りない | Cloud Console で割り当て（クォータ）を確認・引き上げを申請 |
なお Vertex AI 経由では、認証を Google Cloud 側で行うため /logout は使えません。 AWS で使う場合の手順は Claude Code Amazon Bedrock設定、Azure で使う場合は Claude Code Microsoft Foundry設定 で解説しています。
まとめ
- Vertex AI は現在 Agent Platform という名前。Claude Code のログイン画面では Google Vertex AI と表示される
- 手動設定の基本は
CLAUDE_CODE_USE_VERTEX・CLOUD_ML_REGION・ANTHROPIC_VERTEX_PROJECT_IDの3つ - チームに配るときは モデルの版を固定 し、
/statusの API provider の行で確かめる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
