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

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

Claude CodeをGoogle CloudのAgent Platform(Vertex AI)経由で使うための/setup-vertexウィザードを、起動条件・認証方式・リージョン設定・モデルピン留めまで手順で確認します。

読了目安 約15分

/setup-vertexは、Claude CodeをGoogle CloudのAgent Platform(旧称Vertex AI)経由で使うための設定ウィザードです。GCP認証・プロジェクト・リージョン・モデルピン留めを、対話でまとめて設定できます。ログイン画面の選択肢名は今も「Google Vertex AI」のままですが、裏側で呼んでいるのはGoogle CloudのAgent Platformです。

つまずきの大半は、ウィザードの外にあります。コマンドメニューに出ない、プロジェクトIDの優先順位、ピン留めしないときの既定モデル、の3点です。この記事ではその3点を軸に、手順を並べます。

/setup-vertexの入り口は2つある

/setup-vertexはログイン画面とチャット画面のどちらからも開けます。

くらべる

ウィザードの入り口

初回向け

ログイン画面から

claudeを起動し、ログインプロンプトで「3rd-party platform」→「Google Vertex AI」を選びます。すでにサインイン済みなら/loginで同じメニューが開きます。

再設定向け

チャット画面から

サインイン後は、いつでも/setup-vertexでウィザードを開き直せます。認証情報・プロジェクト・リージョン・モデルピンを変えたいときに使います。

注意したいのは、コマンドメニューの候補です。CLAUDE_CODE_USE_VERTEX=1が立つまで、/setup-vertexはメニューから隠れています。隠れているだけで、全文をタイプすれば実行できます。メニューに出ないからコマンドが無い、と判断しないでください。

シェルのプロファイルが古いCLAUDE_CODE_USE_VERTEXをexportしていて、自分では消せないことがあります。その場合は、設定ファイルのenvブロックに"CLAUDE_CODE_USE_VERTEX": ""と書きます。空文字はプロバイダー選択では未設定として扱われ、子プロセスには空文字のまま引き継がれます。

ウィザードを開く前に済ませるGCP側の準備

Claude Codeを設定する前に、GCP側で次を満たしておきます。

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

APIの有効化は次の2行です。

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

そのあとModel Gardenで「Claude」を検索し、使うモデルへのアクセスをリクエストします。承認には24〜48時間かかることがあります。待ち時間があるので、ウィザードを開くのは承認が下りてからです。

IAMではroles/aiplatform.userを割り当てます。このロールに含まれるaiplatform.endpoints.predictが、モデル呼び出しとトークン数のカウントに必要な権限です。絞りたい場合は、この権限だけを持つカスタムロールを作ります。コストとアクセスの管理を単純にするため、Claude Code専用のGCPプロジェクトを分ける方法もあります。チーム単位の権限設計はVertex AIのIAM設定とチーム展開で扱っています。

ウィザードの流れ

手順

/setup-vertexが聞くこと

  1. 1

    GCPの認証方式を選ぶ

    gcloudのApplication Default Credentials、サービスアカウントのキーファイル、環境にすでにある資格情報のいずれかです。

  2. 2

    プロジェクトとリージョンを入力する

    プロジェクトとリージョンはウィザードが尋ねます。リージョンの種類は次節のとおり3通りです。

  3. 3

    使えるClaudeモデルを検証する

    そのプロジェクトが実際に呼び出せるモデルを確認します。

  4. 4

    モデルを固定し、1Mコンテキストを選ぶ

    使うモデルをピン留めします。この画面には1Mトークンのコンテキストウィンドウを有効にする選択肢も出ます。再実行したときは、現在ピン留め中のモデルから始まります。

結果はユーザー設定ファイルのenvブロックに書き込まれるので、環境変数を自分でexportする必要はありません。保存先は~/.claude/settings.jsonで、CLAUDE_CONFIG_DIRを設定している場合は$CLAUDE_CONFIG_DIR/settings.jsonです。

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

CLOUD_ML_REGIONに何を入れるかで、接続先のホスト名が変わります。

  • global: グローバルエンドポイント
  • euやusのようなマルチリージョン: aiplatform.eu.rep.googleapis.com、aiplatform.us.rep.googleapis.comといった専用ホスト
  • us-east5のような特定リージョン: そのリージョンのホスト

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

CLOUD_ML_REGIONごとの挙動と、非対応モデルだけを別変数で上書きする手順はClaude CodeでVertex AIのリージョンを設定するに書いています。

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

CIやスクリプト化したロールアウトでは、ウィザードを使わず環境変数で直接設定します。

項目/setup-vertexウィザード環境変数での手動設定
向く場面/setup-vertexウィザード個人が対話的にセットアップ環境変数での手動設定CI・スクリプト化された企業ロールアウト
GCP認証/setup-vertexウィザード対話プロンプトで選択環境変数での手動設定ADC・サービスアカウントキー・Workload Identity Federationを自分で用意
プロジェクトID/setup-vertexウィザードウィザードが尋ねる環境変数での手動設定ANTHROPIC_VERTEX_PROJECT_IDを明示設定
モデルのアクセス確認/setup-vertexウィザードウィザードが検証環境変数での手動設定Model Gardenで自分で確認
保存先/setup-vertexウィザード設定ファイルのenvブロック環境変数での手動設定シェルのexport、またはenvブロックに自分で記載

最低限必要なのは次の3つです。

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

プロジェクトIDはANTHROPIC_VERTEX_PROJECT_IDが勝つ

GCLOUD_PROJECTやGOOGLE_CLOUD_PROJECTに別のプロジェクトが入っていても、宛先は変わりません。GOOGLE_APPLICATION_CREDENTIALSが指す資格情報ファイルに別のプロジェクトが入っていても同じです。Agent PlatformへのリクエストはANTHROPIC_VERTEX_PROJECT_IDのプロジェクトに送られます。手動設定ではANTHROPIC_VERTEX_PROJECT_IDを明示するのが手順で、前節の最低限の3変数にも含まれています。

認証の更新を自動化するgcpAuthRefresh

GCPの認証が切れたとき、再ログインを自動で走らせる設定があります。設定ファイルに次のように書きます。

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

Claude Codeは、資格情報が期限切れか読み込めないと判断したときだけ、このコマンドを実行してからリクエストを再試行します。実行前に現在の資格情報でアクセストークンを取り、まだ使えるなら何もしません。

この確認が5秒以内に終わらない場合も、コマンドは走らず、リクエストが資格情報エラーで失敗したあとに初めて実行されます。v2.1.261より前は、確認のタイムアウトが「期限切れ」として扱われ、資格情報が有効でも起動時にブラウザが開くことがありました。

コマンドの出力は表示されますが、対話入力は送れません。ブラウザで認証を完了するタイプのコマンドに向いています。3分以内に認証が済まないとタイムアウトします。プロジェクト設定(.claude/settings.json)に書いた場合は、フォルダを信頼する前に走るフックと同じ扱いで実行されます。

そのほかの認証経路

X.509証明書ベースのWorkload Identity Federationにも対応しています。GOOGLE_APPLICATION_CREDENTIALSに認証設定ファイルのパスを指定すると、ADCと同じ経路で認証されます。カスタムエンドポイントやゲートウェイを経由する場合は、ANTHROPIC_VERTEX_BASE_URLで接続先のURLを上書きできます。

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

複数人に配るなら、ピン留めしておくと更新でモデルが変わりません。理由は、ピン留めしないときの既定値にあります。

設定何に解決されるか
opusエイリアス(ANTHROPIC_DEFAULT_OPUS_MODELなし)何に解決されるかOpus 5.5
sonnetエイリアス(ANTHROPIC_DEFAULT_SONNET_MODELなし)何に解決されるかSonnet 4.5
主モデルの既定何に解決されるかclaude-opus-5-5
小型・高速モデルの既定何に解決されるかclaude-sonnet-4-5@20250929

この既定はv2.1.280以降のものです。v2.1.280より前は主モデルの既定がOpus 5で、v2.1.207からv2.1.218まではOpus 4.8、v2.1.207より前はSonnet 4.5でした。opusエイリアスも同じで、v2.1.219〜v2.1.279はOpus 5、v2.1.207〜v2.1.218はOpus 4.8、v2.1.207より前はOpus 4.6でした。つまり、ピン留めしていないチームは、Claude Codeを更新するたびに別のモデルを使い始めた可能性があります。

料金にも響きます。Opusはtokenあたりの単価がSonnetより高く、主モデルを固定していない構成は、v2.1.207以降に更新した時点からOpus単価で課金されます。Sonnet 4.5を主モデルのままにしたいときは、ANTHROPIC_MODELにモデルIDの全体を指定します。

ANTHROPIC_DEFAULT_SONNET_MODELで既定を操作し、ANTHROPIC_DEFAULT_OPUS_MODELを設定していない構成では、そのSonnetが既定のまま残ります。

ピン留めの例です。

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'

バックグラウンドタスクにはSonnetが使われる

セッションタイトルの生成のようなバックグラウンドタスクは、通常Haikuクラスの小型モデルが担います。Agent PlatformではHaikuがすべてのプロジェクト・リージョンで有効とは限らないため、既定では組み込みのSonnetが代わりに使われます。

担当モデルが変わるのは、次の2つの選択をしたときです。

  • --model、ANTHROPIC_MODEL、model設定で主モデルを選ぶと、バックグラウンドタスクもそのモデルを使います。ANTHROPIC_DEFAULT_MODELで起動したセッションも同じです。ANTHROPIC_DEFAULT_OPUS_MODELだけを設定してANTHROPIC_DEFAULT_SONNET_MODELを設定しない構成も、この「選択」に含まれます。自前のOpusを指定したプロジェクトで、組み込みのSonnetが無効かもしれないためです。
  • Haikuを使うなら、プロジェクトで有効なモデルIDをANTHROPIC_DEFAULT_HAIKU_MODELに設定します。

起動時のモデル確認と、自動で切り替わる条件

Agent Platform設定で起動すると、Claude Codeは使う予定のモデルがプロジェクトで呼べるかを確認します。ピン留めの有無で動きが分かれます。

くらべる

起動時のモデル確認

固定した版が優先

ピン留めあり

ピンした版が現行の既定より古く、プロジェクトが新しい版を呼べるときは、ピンを更新するか尋ねます。承諾すると設定ファイルに新しいモデルIDを書き、Claude Codeを再起動します。断ると、次に既定が変わるまでその選択が覚えられます。

フォールバックあり

ピン留めなし

現行の既定がプロジェクトで使えなければ、そのセッションだけ古い版に切り替え、通知を出します。まず同じ系統の古い版を試し、既定がOpusでどのOpusも使えないときは、既定のSonnetに落ちます。この切り替えは保存されません。

--model、ANTHROPIC_MODEL、model設定でSonnetまたはOpusの特定の版を指定して起動すると、その版が対応するエイリアスのピンとして扱われます。opusのようなエイリアスや、Claude Codeが認識しないモデルIDはピンになりません。

使えないと判定されたモデルは、このマシンに最長1日記憶され、その間の起動はAgent Platformに再確認せずに飛ばされます。現行の既定モデルについては、前回の確認から10分たつと起動時に再確認するので、管理者が有効化し直せば戻ります。記憶を止めたいときはCLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1を設定します。この2つの環境変数はv2.1.285以降が対象です。

セッション中にモデルが無効になった場合

管理者がModel Gardenでモデルを無効にするなどしてアクセスを失うと、リクエストを失敗させ続けずに別のモデルへ切り替わります。このときSwitched to <fallback> because <model> is not availableと表示されます。切り替わるのは、ピン留めしていない系統だけです。自分で選んだ特定の版のセッションはモデルを保ち、フォールバックのチェーンも無ければリクエストは失敗します。オートモードでは、Agent Platformでオートモードが対応するモデルにだけ切り替わり、該当がなければリクエストは失敗します。

失敗させたいときはCLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1を設定します。自分で設定したフォールバックのチェーンは、このフラグがあっても切り替えを続けるので、全リクエストを失敗させるならチェーンも外します。

1Mコンテキストとツール検索

1Mトークンのコンテキストウィンドウは、Sonnet 5、Opus 4.6以降、Sonnet 4.6が対象です。Sonnet 5は常に1Mで動き、選ぶ[1m]版はありません。その他のモデルは、1M版を選ぶとClaude Codeが自動で拡張コンテキストを有効にします。手動でピン留めしたモデルでは、モデルIDの末尾に[1m]を付けます。変数に[1m]を付けずに1Mを使うときは、/model opus[1m](Sonnetなら/model sonnet[1m])を実行すると、変数で指定したモデルに[1m]が付きます。[1m]は変数ごとに読まれ、付いていない変数は同じモデルでも200Kで動きます。詳しい比較はBedrock/Vertexで1Mコンテキストを有効化する方法にあります。

MCPのツール検索は、モデルの世代で既定が決まります。Opus 4.5、Sonnet 4.5、Haiku 4.5とそれ以降は既定で有効です。Claude 3.xを含む古いモデルでは、Agent Platform側がツール検索に必要なbetaヘッダーを拒否します。そのためMCPツール定義を最初から読み込み、ENABLE_TOOL_SEARCH=trueでも上書きされません。全モデルで止めるにはENABLE_TOOL_SEARCH=falseを設定します。v2.1.221より前は、ENABLE_TOOL_SEARCH=trueを設定しない限り、Agent Platform上のすべてのモデルでツール検索が無効でした。

プロンプトキャッシュは自動で有効です。止めるにはDISABLE_PROMPT_CACHING=1、TTLを5分の既定から1時間にするにはENABLE_PROMPT_CACHING_1H=1を設定します。1時間TTLのキャッシュ書き込みは、単価が高くなります。TTLは会話本体とそれ以外で分けられます。CLAUDE_CODE_PROMPT_CACHE_TTLとCLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTLがv2.1.242以降で使えます。入る値は5mか1hだけで、ENABLE_PROMPT_CACHING_1Hより優先されます。FORCE_PROMPT_CACHING_5Mを設定すると、これらより優先して5分になります。

つまずいたときの切り分け

まず/statusを実行します。API providerの行にGoogle Vertex AI、GCP projectとDefault regionの行にプロジェクトIDとリージョン、Modelの行に解決済みのモデルが出ます。プロバイダーの行が出ないなら、環境変数がプロセスに届いていません。claudeを起動したシェルでexportされているか、設定ファイルのenvブロックに書かれているかを確認します。

代表的なエラーと、最初に見る場所です。

症状最初に見る場所
「Could not load the default credentials」最初に見る場所gcloud auth application-default loginでADCを設定し直すか、GOOGLE_APPLICATION_CREDENTIALSにサービスアカウントキーのパスを設定する
「model not found」の404最初に見る場所Model Gardenでそのモデルが有効かを見る。次に、指定した場所でそのモデルが提供されているかを見る。globalなら「Supported features」でグローバル対応を確かめる
429最初に見る場所リージョナルエンドポイントなら、主モデルと小型モデルの両方がそのリージョンで使えるかを見る。CLOUD_ML_REGION=globalへの切り替えも選択肢

404の原因には、モデルが特定のリージョンになく、globalやマルチリージョンにだけある場合も含まれます。globalで非対応のモデルは、ANTHROPIC_MODELかANTHROPIC_DEFAULT_HAIKU_MODELで対応モデルを指定します。あるいはVERTEX_REGION_<モデル名>で場所を上書きして回避します。この上書きに入れる値がリージョン名らしくないと(スラッシュ・ドット・スペースを含むと)未設定扱いになります。VERTEX_REGION_CLAUDE_*はCLOUD_ML_REGIONに、CLOUD_ML_REGION自体はus-east5に戻ります。

429や割り当ての問題は、Cloud Consoleで現在のquotaを確認し、必要なら引き上げを申請します。レート制限の引き上げはGoogle Cloudのサポートに連絡します。

なお、Agent Platformを使っているときは認証がGoogle Cloudの資格情報で扱われるため、/logoutコマンドは使えません。

まとめ

既定モデルと課金単価は、更新のたびに動いてきました。配布する設定では、主モデルとopus・sonnetの両方をピン留めしておくと、更新で使うモデルが変わりません。Bedrock側の同種のウィザードはClaude Code Bedrockセットアップで、サードパーティプロバイダー経由での機能制約はClaude Codeコードレビューで確認できます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →