Claude Code Vertex AIセットアップ — /setup-vertexウィザードの手順

Claude CodeをGoogle CloudのAgent Platform(旧称Vertex AI)経由で使うとき、GCP認証・プロジェクト・リージョン・モデルピン留めを対話でまとめて設定できるのが/setup-vertexウィザードです。ログイン画面の選択肢名は今も「Google Vertex AI」のままですが、裏側で呼んでいるのはGoogle CloudのAgent Platformです。呼び出し条件と、環境変数で手動設定する経路との違いを押さえておくと、個人利用とチーム展開のどちらでも迷いません。

/setup-vertexが使える条件

/setup-vertexはログイン画面とチャット画面のどちらからも呼べますが、条件が異なります。

すでにサインイン済みでチャット画面にいる場合、環境変数CLAUDE_CODE_USE_VERTEX=1を立てていないと/setup-vertexは表示も実行もされません。コマンドメニューの候補一覧にも出ないため、初めて見るとコマンド自体が存在しないと誤解しがちです。条件を満たせばタイプするだけで動きます。

一度サインインした後も、認証情報・プロジェクト・リージョン・モデルピンを変更したくなったら/setup-vertexをいつでも再実行できます。モデルピンの選択画面は、そのとき既にピン留めされているモデルから始まります。

ウィザードを開く前の前提条件

Claude Codeを設定する前に、GCP側で次を満たしておく必要があります。

• 課金が有効なGoogle Cloud Platform(GCP)アカウント
• Google CloudのAgent Platform APIが有効化されたGCPプロジェクト
• 使いたいClaudeモデル(例: Sonnet 4.6)へのアクセス権
• Google Cloud SDK(gcloud)のインストールと設定
• 希望するGCPリージョンでの割り当て(quota)

Agent Platform APIの有効化とモデルアクセスのリクエストは、次のコマンドとModel Gardenの画面操作で行います。

gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com

APIを有効化したら、Google CloudのAgent Platform Model Gardenで「Claude」を検索し、使いたいモデルへのアクセスをリクエストします。承認には24〜48時間かかることがあります。個人が対話的にセットアップするだけならこの後のウィザードにそのまま進めますが、チームに展開する場合は後述のピン留め手順を済ませてからロールアウトします。

IAM側ではroles/aiplatform.userロール(aiplatform.endpoints.predict権限を含む)を割り当てます。より厳しく絞りたい場合は、この権限だけを持つカスタムロールを作成します。コスト管理とアクセス制御を単純にするため、Claude Code専用のGCPプロジェクトを分けておくことも推奨されています。

ウィザードの流れ

/setup-vertex

ウィザードは次の内容を対話で進めます。

1. GCP認証方式の選択: gcloudのApplication Default Credentials、サービスアカウントキーファイル、環境に既にある資格情報のいずれか
2. プロジェクトとリージョンの検出: 選んだ認証方式からプロジェクトIDとリージョンを自動で拾う
3. モデルアクセスの検証: そのGCPプロジェクトが実際に呼び出せるClaudeモデルを確認する
4. モデルのピン留め: 使うモデルを固定する。この画面では1Mトークンのコンテキストウィンドウを有効にする選択肢も同時に出る

完了すると、設定結果はユーザー設定ファイルのenvブロックに書き込まれます。保存先は既定で~/.claude/settings.json、環境変数CLAUDE_CONFIG_DIRを設定している場合はそのディレクトリ配下です。

リージョンはglobal・マルチリージョン・特定リージョンの3種類

Google CloudのAgent Platformは、Claude Codeからみるとエンドポイントの種類が3つに分かれます。CLOUD_ML_REGIONにglobalを指定するか、euやusのようなマルチリージョンを指定するか、us-east5のような特定リージョンを指定するかで、Claude Codeが接続するホスト名が変わります(マルチリージョンではaiplatform.eu.rep.googleapis.comのような専用ホストが使われます)。

Claude Code既定のモデルが、選んだエンドポイントの種類で使えるとは限りません。モデルの対応状況はリージョン・マルチリージョン・グローバルエンドポイントで別々に決まるため、使えない場合はエンドポイントの種類を切り替えるか、対応しているモデルを明示的に指定します。

手動設定(環境変数)との違い

CIやスクリプト化されたロールアウトでは、ウィザードの代わりに環境変数で直接設定する経路も用意されています。

手動設定を選ぶ場合、最低限必要なのはCLAUDE_CODE_USE_VERTEX=1とCLOUD_ML_REGION、ANTHROPIC_VERTEX_PROJECT_IDです。

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

CLOUD_ML_REGION=globalを指定した場合、グローバルエンドポイントに対応していない特定のモデルだけはVERTEX_REGION_CLAUDE_*という個別の環境変数でリージョンを上書きできます。値がリージョン名やロケーション名らしい形(スラッシュ・ドット・スペースを含まない)でなければ未設定として扱われ、VERTEX_REGION_CLAUDE_*はCLOUD_ML_REGIONへ、CLOUD_ML_REGION自体はus-east5へフォールバックします。

高度な認証が必要な組織向けには、X.509証明書ベースのWorkload Identity Federationにも対応しています。GOOGLE_APPLICATION_CREDENTIALSに証明書設定ファイルのパスを指定する形で、Application Default Credentialsのチェーンと同じ経路で認証します。

モデルを固定する(ピン留め)

チーム展開ではモデルのピン留めが実質必須です。ピン留めしないとsonnet・opusのエイリアスは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'

バックグラウンドタスク(セッションタイトル生成など)は通常Haikuクラスのモデルが担いますが、Google CloudのAgent PlatformではHaikuがすべてのプロジェクト・リージョンで有効とは限らないため、既定でSonnetモデルが代わりに使われます。ANTHROPIC_DEFAULT_OPUS_MODELだけを設定してANTHROPIC_DEFAULT_SONNET_MODELを設定しない構成も「選択」扱いになり、組み込みのSonnetがそのプロジェクトで無効な場合に影響します。バックグラウンドタスクにHaikuを使いたい場合はANTHROPIC_DEFAULT_HAIKU_MODELを明示的に設定します。

つまずきやすいポイント

/statusを実行すると、APIプロバイダーの行に「Google Vertex AI」、GCPプロジェクト・リージョン・解決済みモデルが表示されます。このプロバイダー行が出ない場合は、環境変数がプロセスに届いていないサインです。claudeを起動したシェルで実際にexportされているか、設定ファイルのenvブロックに書かれているかを確認します。トラブル発生時はまずこの/statusの出力を確認し、想定と違う値が出ている箇所から順に疑うと切り分けが早くなります。

代表的なエラーと最初に見る場所は次のとおりです。症状ごとに切り分けの起点が異なるため、エラーメッセージをそのまま検索する前にこの表で当たりをつけると遠回りを避けられます。

まとめ

/setup-vertexは、Google CloudのAgent Platform導入で最も摩擦の大きいGCP認証・プロジェクト検出・モデル検証を対話でまとめて片づけるコマンドです。チャット画面から呼ぶにはCLAUDE_CODE_USE_VERTEX=1が必要で、個人利用ならウィザード、CIやチーム一括展開なら環境変数による手動設定が向きます。リージョンはglobal・マルチリージョン・特定リージョンの3種類があり、選んだ種類によって使えるモデルが変わる点だけは事前に確認しておくと展開後のトラブルを避けられます。Bedrock側の同種のウィザードはClaude Code Bedrockセットアップで、コードレビューなどサードパーティプロバイダー経由での機能制約はClaude Codeコードレビューで確認できます。

よくある質問

/setup-vertexがコマンド一覧に出てきません

CLAUDE_CODE_USE_VERTEX=1が設定されていないチャット画面では表示されません。表示されなくてもタイプすれば条件を満たしていれば実行されます。初回セットアップならログイン画面の「3rd-party platform」→「Google Vertex AI」から同じウィザードに入れます。

ログイン画面の表記が「Google Vertex AI」なのはなぜですか

Google CloudのAgent Platformは以前Vertex AIという名称でした。ログイン画面の選択肢名はまだ旧称のままですが、実体は同じサービスです。ドキュメント上の呼び方も両方が併存しています。

プロジェクトIDが自動で拾われません

Claude CodeはANTHROPIC_VERTEX_PROJECT_IDをプロジェクトIDとして使いますが、GCLOUD_PROJECT・GOOGLE_CLOUD_PROJECT環境変数やGOOGLE_APPLICATION_CREDENTIALSで指定した資格情報ファイルの内容がこれより優先されます。いずれも未設定の場合はgcloudの設定またはアタッチされたサービスアカウントから解決されます。優先順位を意識せずに変数を並べると意図しないプロジェクトに接続することがあります。

モデルをピン留めしないとどうなりますか

sonnet・opusのエイリアスはClaude Code組み込みの既定モデルに解決されます。起動時にそのモデルがプロジェクトで使えなければ、古いバージョンやSonnetへ自動フォールバックします。チーム展開でモデル切り替えのタイミングを揃えたい場合は、ピン留めして明示的にコントロールしてください。