Claude CodeをGoogle Vertex AI経由で使う設定手順

GCPコンソールを開いてみたものの、APIの有効化、IAMロール、Model Gardenの承認……設定項目が多くて「どこから手を付ければいいか」が分からない人は少なくない。実際に試してみると、Claude Code v2.1.98以降に組み込まれた「Sign in with Vertex AI」ウィザードを使えば、環境変数を手で書かずにVertex AI経由で動かせる。事前にGCP側の準備だけ済ませておけば、あとは画面の指示に従うだけで完了する。

この記事でやること

Windows環境でClaude CodeをGoogle Vertex AI経由で使えるようにする設定を、最初から最後まで案内する。

すでにClaude Codeを使っていて、Anthropic直接APIからVertex AIに切り替えたい人、あるいはこれから新しく始める人を想定している。Anthropic直接APIの設定やAmazon Bedrock経由の手順は別記事で扱う。

まずはウィザードだけでOK（全体像）

設定作業は大きく2つのフェーズに分かれる。

GCP側の準備 ── APIの有効化、モデルアクセスの承認、IAMロールの付与
Claude Code側の設定 ── ウィザードで認証・プロジェクト・リージョンを指定

メインルートはClaude Codeに組み込まれた「Sign in with Vertex AI」ウィザード（v2.1.98以降で利用可能）。環境変数を手動で書く方法もあるが、これはCIやスクリプトでの自動化が目的で、通常はウィザードで十分だ。

全体で15〜30分程度で終わる。ただしModel Gardenのアクセス承認は申請から最長48時間かかることがあるので、そこだけ余裕を持って進めたい。

事前に必要なもの

手順に入る前に、以下を用意しておく。

GCPアカウント（請求が有効化済みであること）
GCPプロジェクト（新規でも既存でも可）
gcloud CLI（Windows用インストーラーで導入）
Claude Code v2.1.98以上
Node.js 18以上（npm経由でインストールした場合のみ必要。現在の公式推奨はネイティブインストーラー）

各ツールのバージョンはターミナルで確認できる。

claude --version
node --version
gcloud --version

Claude Codeが古い場合は、公式のインストール方法で再インストールする。WindowsならPowerShellで irm https://claude.ai/install.ps1 | iex を実行するのが推奨されている（npm経由の更新は非推奨）。gcloud CLIが未インストールなら、Google Cloudの公式ページからWindows用インストーラーをダウンロードして実行する。

Step 1: GCP側の準備をする

GCPコンソール（console.cloud.google.com）にログインし、使うプロジェクトを選択する。以降の操作はすべてこのプロジェクトに対して行う。

① Vertex AI APIを有効化する

サイドメニューから「APIとサービス」→「ライブラリ」を開き、Vertex AI API を検索して有効化する。あるいはgcloud CLIから次のコマンドでも有効化できる。

gcloud services enable aiplatform.googleapis.com --project=YOUR_PROJECT_ID

② Model GardenでClaudeモデルのアクセスをリクエストする

Vertex AIの「Model Garden」ページを開き、Claude（例：Claude Sonnet 4.6）を探して「Enable」または「Request Access」をクリックする。利用規約への同意が求められるので内容を確認のうえ同意する。

ここでの承認は即座に通ることもあれば、24〜48時間かかることもある。次のステップに進めないわけではないが、モデルを実際に呼び出す段階でエラーになるので、先に申請だけ済ませておくと安心だ。

③ IAMロールを付与する

Claude Codeを操作するユーザー（またはサービスアカウント）に roles/aiplatform.user を付与する。コンソールなら「IAMと管理」→「IAM」から該当のプリンシパルを選んでロールを追加する。gcloud CLIからなら次の通り。

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID --member="user:YOUR_EMAIL@example.com" --role="roles/aiplatform.user"

GCP側の準備はここまで。

Step 2: ウィザードでClaude Codeを設定する（推奨）

GCP側の準備が済んだら、Claude Code側の設定に移る。ここからはウィザードが案内してくれるので、画面の指示に従って進める。

① ウィザードを起動する

ターミナルで claude と入力してClaude Codeを起動する。初回起動時のログインプロンプト、あるいは既存のセッションで /setup-vertex と入力すると「Sign in with Vertex AI」ウィザードが始まる。

プロバイダーの選択画面で「3rd-party platform」→「Google Vertex AI」を選ぶ。

② 認証方法を選ぶ

ウィザードが認証方法を尋ねてくる。主な選択肢は次の3つ。

Application Default Credentials（ADC） ── gcloud CLIでログイン済みの場合、自動で検出される。一番手軽だ
サービスアカウントキー ── JSONキーファイルを指定する方式
環境変数で設定済みの認証情報 ── すでに認証情報を環境変数で設定している場合に選ぶ

Windowsでgcloud CLIをインストール済みなら、事前に gcloud auth application-default login を実行しておくとADCが使える。

gcloud auth application-default login

ブラウザが開いてGoogleアカウントの認証が求められる。完了するとローカルに認証情報が保存され、ウィザードが自動で読み取る。

③ プロジェクトとリージョンを選ぶ

ウィザードがGCPプロジェクトIDの入力を求める（一覧から選べる場合もある）。続いてリージョンを指定する。基本的には global を選んでおけば無難だ。リージョンの詳細は次のセクションで説明する。

④ モデルの確認と選択

ウィザードが利用可能なClaudeモデルを一覧表示する。Model Gardenでアクセス承認済みのモデルがここに現れるはずだ。使いたいモデル（例：Claude Sonnet 4.6）を選択する。

⑤ 設定の保存

ウィザードが完了すると、設定内容がClaude Codeのユーザー設定ファイル（settings.jsonのenvブロック）に保存される。ターミナルに設定完了のメッセージが表示されたら成功。

リージョン設定のポイント

ウィザードでリージョンを選ぶ際、いくつか選択肢が出てくる。ざっくり次の区分を押さえておけばいい。

種類	例	特徴
global	`global`	複数リージョンをまたぐ。利用できるモデルの幅が広くなりやすい
multi-region	`us`、`eu`	地域単位の広域指定
regional	`us-east5`、`asia-northeast1`	特定データセンター。レイテンシは低いがモデルが限られる

特別な要件がなければ global を選ぶ。利用可能なモデルの幅が最も広く、リージョンによるモデルの有無でエラーになる心配が少ない。

日本から使う場合、asia-northeast1（東京）も選べるが、利用できるモデルが global より少ないことがある。まずは global で始めて、レイテンシ等の理由で変えたい時に変更すればいい。

手動で環境変数を設定する（CI・スクリプト用途）

CI環境やデプロイスクリプトなど、ウィザードが使えない場面では環境変数を手動で設定する。3つの変数が必要だ。

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=global
ANTHROPIC_VERTEX_PROJECT_ID=YOUR_PROJECT_ID

認証はADCを使う。gcloud auth application-default login で済ませておけば、環境変数に認証情報を直書きしなくても動く。

PowerShellで永続化するなら、Claude Codeの設定ファイル（settings.json）の env ブロックに書くのが確実。

{
  "env": {
    "CLAUDE_CODE_USE_VERTEX": "1",
    "CLOUD_ML_REGION": "global",
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

ただし、これはウィザードの代替手段であり、通常はウィザードが推奨であることに触れておく。

Step 3: 動作確認する

設定が完了したら、Claude Codeを起動して実際にチャットを送ってみる。

claude

起動後に /status を開き、モデルやアカウント情報を確認する。Vertex AI経由の設定が反映されていれば、接続確認としては十分だ。試しに短いメッセージを送ってみる。

> こんにちは。1行で自己紹介してください。

エラーなく回答が返ってくれば、Vertex AI経由でClaude Codeが動いている状態だ。ここまで来れば設定は完了。

うまくいかない時の対処法

設定後にエラーが出た場合、よくある原因を上から順に確認する。

認証エラー

gcloud auth application-default login を実行していない、またはログインの有効期限が切れている可能性がある。再度ログインし直す。

モデル未有効化エラー

Model Gardenでのアクセス承認がまだ完了していない。承認待ちの状態だとモデル呼び出しが失敗する。GCPコンソールのModel Gardenページで承認状況を確認する。

リージョン不一致

選択したリージョンで該当モデルが利用できない。global に変更して試す。ウィザードを再実行するには /setup-vertex を入力する。

権限エラー

roles/aiplatform.user が付与されていない。IAM設定を見直して、自分のアカウント（またはサービスアカウント）にロールが割り当てられているか確認する。

どのケースでも、ウィザードの再実行（/setup-vertex）で設定をやり直せる。

429エラーが頻発する場合

Vertex AI経由で使用している際、429エラー（code:1302）が頻発することがあります。これはレート制限にかかっている可能性があります。

エラー修正の基本的な流れ

設定や動作確認中にエラーが発生した場合、Claude Codeに頼るだけでプログラムのエラー修正はどこまでできるかを参考に、エラーメッセージをそのままClaude Codeに渡してみるのも一つの手です。

設定完了後の確認と次のステップ

設定が永続化されているかを確認しておこう。ターミナルを一度閉じて、再度 claude を起動してみる。前回と同じモデル情報が表示されれば、設定は保存されている。

ここから先の導線をいくつか挙げておく。

次に読む ── Anthropic直接APIとVertex AIの違いを知りたい場合は、API比較の記事を参照
次に試す ── Claude Codeの基本操作に慣れるなら、最初の依頼をしてみよう
権限モードを理解する ── 権限モードを比較して自分に合った設定を選ぶ

GCP側の準備さえ済めば、ウィザード3ステップでVertex AI経由のClaude Codeが使える。一番の待ち時間はModel Gardenの承認待ちなので、そこだけ先に申請しておくとスムーズだ。

まとめ

GCP側でAPIの有効化、Model Gardenのアクセス承認、IAMロールの付与を済ませておけば、あとはウィザードの3ステップ（認証→プロジェクト選択→リージョン選択）でVertex AI経由のClaude Codeが動く。環境変数を手で書く必要もない。Model Gardenの承認は24〜48時間かかることがあるので、そこだけ先に申請しておくとスムーズだ。