無料相談する

カテゴリー / インストール・ログイン・設定

Claude CodeをVertex AIで使う設定手順と接続できない時の確認点

NO WAVE公開 更新 読了目安 14分

この記事の目次

Claude Code を Vertex AI 経由で使うには、GCP プロジェクトで API を有効化して Model Garden で Claude モデルへのアクセスを申請し、そのうえで claude のログイン画面から 3rd-party platform → Google Vertex AI を選ぶか、CLAUDE_CODE_USE_VERTEX=1・CLOUD_ML_REGION・ANTHROPIC_VERTEX_PROJECT_ID の3つの環境変数を設定します。設定後は Claude Code の中で /status を実行し、API provider の行に Google Vertex AI、GCP project・Default region・Model の行に自分のプロジェクト ID・リージョン・モデルが出ているかを確認します。なお、Claude Code の公式ドキュメントでは Vertex AI は「Google Cloud’s Agent Platform（旧 Vertex AI）」という名前で書かれていますが、ログイン画面の表記は今も「Google Vertex AI」のままです。本記事では Vertex AI と書きます。

Vertex AI 経由はどんな組織に向いているか

公式の導入比較表では、Vertex AI（Agent Platform）経由は「GCP-native deployments」、つまり GCP を基盤にしている組織向けと位置づけられています。表から Vertex AI の列を抜き出すと次のとおりです。

項目 Vertex AI（Agent Platform）経由
課金 GCP を通じた従量課金（PAYG through GCP）
認証 GCP の認証情報
コストの把握 GCP Billing
統制の仕組み IAM ロール、Cloud Audit Logs
Web 版 Claude の利用 含まれない

請求を GCP にまとめたい、権限管理を既存の IAM で行いたい、監査ログを Cloud Audit Logs に寄せたい、という要件があるなら Vertex AI 経由が候補になります。一方で公式は、多くの組織には Claude for Teams または Claude for Enterprise が最適だとも書いています（公式の導入比較ページ）。GCP 側の要件が特にないなら、先にそちらと比べてください。AWS を基盤にしている場合の選択肢は Claude Code を Amazon Bedrock 経由で使う記事で扱っています。

始める前に GCP 側で何を用意するか

公式の Vertex AI 設定ページが挙げる前提条件は5つです。

  • 課金が有効な GCP アカウント
  • Agent Platform API（Vertex AI API）を有効にした GCP プロジェクト
  • 使いたい Claude モデルへのアクセス
  • インストールと設定が済んだ Google Cloud SDK（gcloud）
  • 使うリージョンでのクォータ割り当て

モデルへのアクセス申請は、Model Garden で「Claude」を検索して申請します。公式は承認まで 24〜48 時間かかる場合があると書いているので、導入日程にはこの待ち時間を入れておきます。

利用者の権限は roles/aiplatform.user ロールを付与すれば足ります。このロールには、モデル呼び出しとトークン数の計算に必要な aiplatform.endpoints.predict 権限が含まれます。権限をもっと絞りたい場合は、公式が挙げる必要権限だけを持つカスタムロールを作る方法も案内されています。また公式は、コストの把握とアクセス制御を簡単にするため、Claude Code 専用の GCP プロジェクトを作ることを勧めています。

ログインウィザードで接続するにはどうするか

個人で使い始めるなら、ログインウィザードが手数の少ない導入経路です。GCP 側の準備はプロジェクトごとに1回で済み、Claude Code 側はウィザードが設定します。

  1. ターミナルで claude を起動する
  2. ログイン画面で 3rd-party platform を選び、続けて Google Vertex AI を選ぶ（すでにログイン済みなら /login で同じメニューが開く）
  3. Google Cloud への認証方式を選択する。選択肢は gcloud の Application Default Credentials、サービスアカウントのキーファイル、環境にすでにある認証情報の3つ
  4. プロジェクトとリージョンを入力すると、ウィザードがそのプロジェクトで呼び出せる Claude モデルを確認し、モデルを固定（pin）できる

結果はユーザー設定ファイル ~/.claude/settings.json の env ブロックに保存されます（CLAUDE_CONFIG_DIR を設定している場合はそのディレクトリの settings.json）。自分で環境変数を export する必要はありません。あとから認証情報・プロジェクト・リージョン・固定モデルを変えたいときは、/setup-vertex でウィザードを開き直せます。

なお、Vertex AI 経由では認証を Google Cloud の認証情報で行うため、/logout コマンドは使えません。

環境変数で手動設定するにはどうするか

CI やスクリプトで全社に配る場合は、公式もウィザードではなく環境変数での設定を案内しています。まず API を有効化します。

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

認証には標準の Google Cloud 認証が使われます。X.509 証明書ベースの Workload Identity Federation を使う場合は、GOOGLE_APPLICATION_CREDENTIALS に認証情報の設定ファイルのパスを入れます。

次に Claude Code 側の環境変数を設定します。公式の例は次のとおりです。

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

ここで押さえておきたいのが、リクエストの送り先プロジェクトは ANTHROPIC_VERTEX_PROJECT_ID が優先される点です。GCLOUD_PROJECT や GOOGLE_CLOUD_PROJECT、GOOGLE_APPLICATION_CREDENTIALS が指す認証ファイルに別のプロジェクトが入っていても、Claude Code は ANTHROPIC_VERTEX_PROJECT_ID のプロジェクトへ送ります。課金先を取り違えないよう、まずこの値を確認してください。社内のゲートウェイを経由させたいときは、任意で ANTHROPIC_VERTEX_BASE_URL によりエンドポイント URL を上書きできます。

認証の有効期限が切れるたびに手でログインし直すのが面倒なら、gcpAuthRefresh 設定が使えます。認証情報の期限切れや読み込み失敗を検知すると、指定したコマンドを実行して新しい認証情報を取得し、リクエストをやり直します。

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

このコマンドは、認証が3分以内に終わらないとタイムアウトします。設定ファイルの書き方全般は settings.json の解説を参照してください。

CLOUD_ML_REGION は global・マルチリージョン・個別リージョンのどれにするか

CLOUD_ML_REGION には3つの形を指定できます。

指定の形 値の例
グローバルエンドポイント global
マルチリージョン eu、us
個別リージョン us-east5 など

注意点は、Claude Code の既定モデルがすべてのエンドポイント種別で使えるとは限らないことです。モデルの提供状況は個別リージョン・マルチリージョン・グローバルで異なり、モデルによっては global やマルチリージョンでしか提供されていません。global を指定していて、特定のモデルだけがグローバルエンドポイントに対応していない場合は、そのモデル用の VERTEX_REGION_CLAUDE_* 変数でリージョンを個別に上書きします。公式の例では次のように書きます。

export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

もう1つ気づきにくいのが値の書式です。スラッシュ・ドット・空白を含む値など、リージョン名の形でない値は未設定として扱われ、VERTEX_REGION_CLAUDE_* は CLOUD_ML_REGION に、CLOUD_ML_REGION は us-east5 にフォールバックします。どのリージョンでどのモデルが使えるかは Model Garden で確認できます。

チームで使う前にモデルを固定すべきなのはなぜか

複数の利用者に配る場合、公式はモデルのバージョンを固定するよう警告しています。固定しないと、sonnet や opus といったエイリアスは Claude Code に組み込まれた Vertex AI 用の既定値に解決されます。この既定値は最新リリースより遅れることがあり、自分のプロジェクトでまだ有効化されていない可能性もあります。

固定しない場合の既定値は、2026年10月19日に公式ページと照合した時点で次のとおりです。

モデルの種類 既定値
主モデル claude-opus-5-5
small/fast モデル claude-sonnet-4-5@20250929

費用に直結するのは主モデルが Opus である点です。公式は、Opus は Sonnet よりトークン単価が高く、主モデルを固定しなければ Opus の単価で課金されると明記しています。Sonnet 4.5 を主モデルにしたいなら、ANTHROPIC_MODEL にそのモデルのフル ID を設定します。セッション名の生成などのバックグラウンド処理は通常 Haiku 系のモデルが担いますが、Vertex AI では Haiku がすべてのプロジェクトやリージョンで有効とは限らないため、既定の Sonnet モデルが使われます。ただし --model・ANTHROPIC_MODEL・model 設定で主モデルを選んだ場合は、バックグラウンド処理もそのモデルを使います。Haiku に任せたいなら、ANTHROPIC_DEFAULT_HAIKU_MODEL にプロジェクトで使えるモデル ID を設定します。

エイリアスごとに固定するには、公式の例のように次の変数を設定します。

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'

Claude Code は起動時に、使う予定のモデルがプロジェクトで呼び出せるかを確認します。モデルを固定しておらず既定モデルが使えない場合は、そのセッションに限って代替モデルに切り替え、通知を出します。この切り替えは保存されないので、恒久的に変えるなら Model Garden で新しいモデルを有効にするか、バージョンを固定します。管理設定で enforceAvailableModels を有効にすると、この起動時のモデル確認は availableModels の許可リストにあるモデルだけを対象にします（Claude Code v2.1.287 以降）。

既定モデルは版によって変わってきました。公式によると、Claude Code v2.1.280 より前は Vertex AI での主モデルの既定が Opus 5 でした。展開の直前に、公式の Vertex AI 設定ページで既定値を確認してから固定する値を決めてください。モデルごとの違いは Claude Code のモデルの違いで整理しています。

接続できないときはどこから確認するか

最初に見るのは /status です。正しく設定されていれば、API provider の行に Google Vertex AI が表示され、GCP project・Default region・Model の行にプロジェクト ID、リージョン、実際に使われるモデルが出ます。

API provider の行が出ない場合は、環境変数が Claude Code のプロセスまで届いていません。claude を起動したシェルで export されているかを確認するか、設定ファイルの env ブロックに書きます。

「Could not load the default credentials」と出る場合は、認証情報を読み込めていません。公式の対処は、次のコマンドで ADC を設定するか、GOOGLE_APPLICATION_CREDENTIALS にサービスアカウントのキーファイルのパスを設定することです。

gcloud auth application-default login

「model not found」の 404 が出る場合は、次の順に確認します。

  1. Model Garden でそのモデルが Enabled になっているか
  2. 指定したリージョンでそのモデルが提供されているか（global や eu・us でしか提供されないモデルがある）
  3. CLOUD_ML_REGION=global の場合、そのモデルがグローバルエンドポイントに対応しているか。対応していなければ、ANTHROPIC_MODEL か ANTHROPIC_DEFAULT_HAIKU_MODEL で対応モデルを指定するか、VERTEX_REGION_CLAUDE_* でリージョンを指定する

429 が出る場合は、個別リージョンを使っているなら、主モデルと small/fast モデルの両方がそのリージョンで提供されているかを確認します。公式は、可用性を上げる手段として CLOUD_ML_REGION=global への切り替えも挙げています。

クォータの問題は Cloud Console で確認し、必要なら引き上げを申請します。レート上限の引き上げは Google Cloud サポートへ連絡します。Vertex AI に限らないエラー全般は Claude Code のエラー対処法にまとめています。

Vertex AI 経由では使えない機能は何か

Vertex AI 経由では、Claude のサブスクリプションが前提の機能は使えません。それに加えて、公式の機能一覧で「Not available」とされているのは次の機能です。

  • fast mode
  • Advisor
  • Channels
  • 分析ダッシュボード
  • サーバー管理設定（server-managed settings）
  • /design-sync と /import コマンド

一部だけ使える機能もあります。Web 検索は Opus 4・Sonnet 4・Haiku 4.5 以降のモデルで使え、auto mode は Sonnet 5 以降・Opus 4.7 以降・Haiku 5.5・Fable モデルに限られます。Zero Data Retention の扱いは Google Cloud との契約次第です。スケジュール実行には /schedule の代わりに /loop を、クラウド上での実行には GitHub Actions か GitLab CI/CD を使うよう公式は案内しています。

データの扱いについては、Vertex AI 経由ではエラー報告・テレメトリ・バグ報告が既定でオフです。/feedback で作ったレポートも Anthropic には送られず、~/.claude/feedback-bundles/ 以下にローカル保存されます。権限設計を含むセキュリティの論点全体は エンタープライズ向けセキュリティガイドで扱っています。

CI で使う場合、GitHub Actions では use_vertex: "true" を指定し、Workload Identity Federation と roles/aiplatform.user だけを持つ専用サービスアカウントで認証する構成が公式の手順です。ワークフローの組み方は Claude Code GitHub Actions の解説を参照してください。

CONTINUE THE SESSION

関連記事