Claude CodeはAnthropicのサブスクやAPIキーのほかに、Google CloudのVertex AI経由でも動きます。Vertex AIは2026年に「Agent Platform」へ改称されましたが、Claude Code側の切り替えは今もCLAUDE_CODE_USE_VERTEXです。この記事では2026年11月時点の公式ドキュメントをもとに、API有効化とIAM、settings.jsonに書く環境変数、モデルの固定、globalとリージョンの選び方、クォータの申請、CIでの認証までを手順で示します。最後に、Vertex AI経由を選ぶ案件と見送る案件を線引きします。
まとめ：Claude CodeのVertex AI接続は環境変数3つとモデル固定で決まる
接続に必要な環境変数はCLAUDE_CODE_USE_VERTEX=1、CLOUD_ML_REGION、ANTHROPIC_VERTEX_PROJECT_IDの3つです。GCP側では、Agent Platform APIの有効化、Model GardenでのClaudeの有効化、roles/aiplatform.userの付与を先に済ませます。
見落とされやすいのはモデルの固定です。固定しないと主モデルはOpus 5.5になり、背景処理は非推奨のSonnet 4.5で動きます。チームに配るなら、ANTHROPIC_DEFAULT_*_MODELで版を決めてから展開してください。
リージョンはglobalが基本です。リージョナルエンドポイントで動くのはSonnet 4.6以前のモデルだけなので、国内処理と最新モデルを両方求める案件はVertex AI経由では満たせません。
Vertex AI経由のClaude Codeが通るGoogle管理型の経路と前提条件
設定に入る前に、Claude CodeがGoogle Cloudのどの入口を使い、何が変わるのかをそろえます。
改称後もCLAUDE_CODE_USE_VERTEXで切り替わる接続の仕組み
Claude CodeのAgent Platform設定ページは、題名を「Google Cloud’s Agent Platform, formerly Vertex AI」に改めています。ただしログイン画面の選択肢は今も「Google Vertex AI」で、環境変数や/setup-vertexコマンドの名前も変わっていません。
Google Cloud上のClaudeには、Googleが運営する「Google managed」と、Anthropicが運営する「Anthropic managed」の2つの提供形態があります。Anthropicの提供形態の比較ページによると、前者の送り先はaiplatform.googleapis.com系、後者はclaude.googleapis.comです。CLAUDE_CODE_USE_VERTEXが向かうのは前者です。2形態の選び方はVertex AIでClaudeを使う方法：Model Garden有効化・Anthropic管理型・料金で比べています。
Claude Codeのサブスク版と比べた認証・請求・使えないコマンドの違い
Vertex AI経由にすると、ログインの仕組みと請求先がまるごと入れ替わります。
| 項目 | サブスク（Pro・Max等） | Vertex AI経由 |
|---|---|---|
| 認証 | claude.aiのアカウント | gcloudのADCやサービスアカウント |
| 請求 | Anthropicの月額プラン | Google Cloudのトークン従量課金 |
| 利用上限 | プランごとの使用量上限 | GCPプロジェクトのクォータ |
| /logout | 使える | 使えない |
| Remote Control | 使える | 使えない |
/logoutが使えないことは設定ページに、Remote Controlが無効になることは環境変数リファレンスのANTHROPIC_BASE_URLの説明に書かれています。サブスクの料金と損益分岐はClaude Codeの料金プラン比較で試算しています。
gcloudでAPI有効化からModel Garden申請とIAM付与まで進める手順
GCP側の作業は、プロジェクトごとに1回で済みます。費用と権限を追いやすくするため、Claude Code専用のプロジェクトを作ることを設定ページも勧めています。
Agent Platform APIの有効化と予測権限を付与するgcloudコマンド
必要な権限はaiplatform.endpoints.predictの1つで、モデルの呼び出しとトークン数の計測に使われます。この権限を含む既定のロールがroles/aiplatform.userです。
# 対象プロジェクトを選び、Agent Platform API（旧Vertex AI API）を有効にする
gcloud config set project my-claude-code-prj
gcloud services enable aiplatform.googleapis.com
# 利用者（またはグループ）に Agent Platform User ロールを付ける
gcloud projects add-iam-policy-binding my-claude-code-prj \
--member="group:[email protected]" \
--role="roles/aiplatform.user"
# 手元の端末でApplication Default Credentials（ADC）を作る
gcloud auth application-default login開発者全員に配るなら、aiplatform.endpoints.predictだけを持つカスタムロールを作るほうが、監査で説明しやすくなります。
Model Gardenでモデルを有効化する24〜48時間の待ちと申請の範囲
APIを有効にしただけでは、Claudeは呼べません。Model Gardenで「Claude」を検索し、使うモデルのカードから有効化を申請します。設定ページは承認に24〜48時間かかる場合があるとしており、導入日の前日に申請すると間に合わないことがあります。
申請は、主モデルと背景処理用のモデルの両方が対象です。片方だけだと、起動時のモデル確認で別のモデルへ切り替わります。
envブロックと環境変数でClaude Codeを接続しモデルを固定する設定
GCP側の準備が済んだら、Claude Codeを接続します。方法は対話式のウィザードと、環境変数による手動設定の2つです。
/setup-vertexウィザードと手動設定をCIや配布で使い分ける基準
個人の端末なら、ウィザードが早く済みます。claudeを起動し、ログイン画面で「3rd-party platform」から「Google Vertex AI」を選ぶと、聞かれる項目は認証方法・プロジェクト・リージョンです。ウィザードは呼べるモデルを確かめたうえで、結果を~/.claude/settings.jsonのenvに書き込みます。後から変えるときは/setup-vertexで開き直します。
CIや社内への一括配布は、対話できないため手動設定です。
settings.jsonのenvに書く変数と/statusでの接続確認
手動設定では、シェルでexportする代わりに設定ファイルのenvへまとめておくと、端末ごとの差が出にくくなります。以下は設定ページの変数を1つのファイルにまとめた例です。
{
"env": {
"CLAUDE_CODE_USE_VERTEX": "1",
"CLOUD_ML_REGION": "global",
"ANTHROPIC_VERTEX_PROJECT_ID": "my-claude-code-prj",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
},
"gcpAuthRefresh": "gcloud auth application-default login"
}モデルIDは、AnthropicのGoogle managedのページにあるAgent Platform用のID表から写します。Claude 4.6以降はclaude-sonnet-5-5のようなAPIと同じ形、それより前のモデルはclaude-haiku-4-5@20251001のように日付の前を@にした形です。
起動後に/statusを実行し、「API provider」の行がGoogle Vertex AIかを見ます。この行が出なければ、環境変数がプロセスに届いていません。
ANTHROPIC_VERTEX_PROJECT_IDが他の指定より優先される挙動
設定ページには、GCLOUD_PROJECTやGOOGLE_CLOUD_PROJECT、GOOGLE_APPLICATION_CREDENTIALSが指す認証情報ファイルに別のプロジェクトが入っていても、送り先はANTHROPIC_VERTEX_PROJECT_IDのプロジェクトになると書かれています。
CIのジョブがGOOGLE_CLOUD_PROJECTを本番に向けていても、Claude Codeの請求だけを専用プロジェクトへ寄せられます。逆に、gcloudの既定を変えても送り先は変わりません。
モデル未固定ではOpus 5.5と非推奨のSonnet 4.5で動く落とし穴
固定しない場合の既定値は、設定ページの表で次のとおりです。
| 用途 | 既定のモデル | 備考 |
|---|---|---|
| 主モデル | Opus 5.5 | v2.1.280より前はOpus 5 |
| 小型・高速モデル | Sonnet 4.5 | 非推奨のモデル |
表のIDは、主モデルがclaude-opus-5-5、小型・高速モデルがclaude-sonnet-4-5@20250929です。
セッション名の生成などの背景処理は、通常はHaiku級のモデルが担います。Vertex AIではHaikuが有効でないプロジェクトを考慮して、既定のSonnetが使われます。ANTHROPIC_DEFAULT_SONNET_MODELを書かなければ、sonnetの別名もSonnet 4.5を指したままです。Anthropicのモデル表ではSonnet 4.5は非推奨扱いで、200Kトークンのコンテキストしか持ちません。
もう1つは費用です。主モデルを固定しないとOpusの単価で請求されると、設定ページ自体が警告しています。固定しておけば、新しい版が呼べると分かっても勝手には移らず、更新するかを聞かれます。
globalとリージョン指定の選び方とVERTEX_REGIONで404を避ける設定
CLOUD_ML_REGIONに入れる値で、リクエストの送り先と単価が変わります。
global・マルチリージョン・リージョナルの3種類と10%の単価差
Google managedのページは、エンドポイントを次の3種類に分けています。
| 種類 | CLOUD_ML_REGIONの値 | 処理される場所 | 単価 |
|---|---|---|---|
| global（推奨） | global | 空きのある任意の地域 | 基準 |
| マルチリージョン | us または eu | 米国内またはEU内 | 10%高い |
| リージョナル | us-east5 など | 指定した1地域 | 10%高い |
10%の上乗せはSonnet 4.5以降のモデルに掛かります。プロビジョンドスループットを買う場合はリージョナルが必須です。Claude Codeは値の形を見てホスト名を選び、usやeuならaiplatform.us.rep.googleapis.comのような専用ホストへ送ります。
書き間違いにも注意が要ります。スラッシュ・ドット・空白を含む値は未設定とみなされ、CLOUD_ML_REGIONはus-east5に戻ります。
Sonnet 4.6より新しいモデルがリージョナルで動かない制約と東京の扱い
同じページに「Regional endpoints serve Claude Sonnet 4.6 and earlier models only」とあります。Opus 5.5やSonnet 5.5を使うなら、送り先はglobalかus・euのどれかになります。マルチリージョンは米国とEUしかないため、最新モデルの処理を日本国内に閉じる経路はありません。
Googleのリージョン一覧では、東京（asia-northeast1）がアジア太平洋の表に載っています。ただし、表からはモデルごとの提供有無までは読み取れません。Sonnet 4.6以前を東京で使えるかは、Model Gardenのモデルカードか、次のような1回の呼び出しで確かめます。
# 東京のリージョナルエンドポイントで Sonnet 4.6 が呼べるかを確かめる
# 200 なら提供あり、404 なら東京では未提供（課金は数トークン分）
PROJECT=my-claude-code-prj
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
"https://asia-northeast1-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/asia-northeast1/publishers/anthropic/models/claude-sonnet-4-6:rawPredict" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16}'gcloud auth print-access-tokenは、ADCではなくgcloud CLI自身のログインを使います。403が返るときはIAM、404はモデル未提供か未有効化を疑います。
VERTEX_REGION_CLAUDE_*でモデルごとに送り先を分ける設定例
CLOUD_ML_REGION=globalにしたうえで、globalに対応していないモデルだけを別の地域へ送れます。そのための変数がVERTEX_REGION_CLAUDE_*です。
# 基本は global。global非対応のモデルだけ個別に地域を指定する
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=my-claude-code-prj
# 例：Haiku 4.5 を背景処理に使い、us-east5 へ送る
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
claude環境変数リファレンスによると、変数はモデルの版ごとにあり、VERTEX_REGION_CLAUDE_5_5_OPUSはv2.1.280、VERTEX_REGION_CLAUDE_5_5_SONNETはv2.1.284、VERTEX_REGION_CLAUDE_HAIKU_5_5はv2.1.293で加わりました。未設定や不正な値のときはCLOUD_ML_REGIONの値が使われます。
429とクォータ不足でチームの同時利用を止めないための確認と申請
チームで同時に使い始めると429が出ます。上限を決めるのはAnthropicではなく、Google Cloudのクォータです。
2026年5月26日以降のモデルで系統共有になったクォータの見方
GoogleのClaudeのクォータページでは、2026年5月26日以降に公開されたモデルは、同じ系統（Opus、Sonnetなど）の全バージョンで1つのクォータを共有します。それより前のモデルは、モデルごと・エンドポイントごとです。
global枠のメトリクスはglobal_online_prediction_requests_per_base_modelと、入力・出力別のトークン毎分です。既定値の例では、Opus 4.8のglobalが毎分2,000リクエスト・入力2,000万トークン・出力200万トークンです。系統共有なら新しい版が出ても再申請は要りませんが、globalとマルチリージョンの枠は別に数えられます。
Quotas画面でbase_modelを絞り込んで上限を引き上げる申請手順
クォータページが案内している申請手順は、コンソールからの3段階です。
- Google Cloudコンソールで「Quotas and system limits」を開く
- フィルタで
base_modelに系統名（例：anthropic-claude-opus）を指定する - 該当するglobalまたはマルチリージョンの行を選び、引き上げを申請する
申請前に、429の原因が本当に上限かを切り分けます。Claude Codeの設定ページは、リージョナルを使っている場合に主モデルと小型モデルの両方がその地域で提供されているかを確かめ、可能ならglobalへ切り替えるよう勧めています。
gcpAuthRefreshとWorkload IdentityでCIの認証を保つ構成
ADCのトークンは期限が切れます。端末とCIのそれぞれで、切れたときの動き方を決めておきます。
gcpAuthRefreshで期限切れのときだけ再ログインさせる設定
先の設定例に入れたgcpAuthRefreshは、認証情報が切れたか読めないときに、指定したコマンドを実行してから再試行する設定です。Claude Codeは実行前に今の認証情報でトークンを取れるかを確かめ、まだ有効なら実行しません。この確認が5秒で終わらない場合も実行を見送り、認証エラーで失敗したときにだけ走らせます。
v2.1.261より前は、5秒を超えた確認を期限切れとみなしていました。認証が有効なのに起動のたびにブラウザが開く環境は、更新で直ります。コマンドは3分で打ち切られ、対話入力は渡せません。
Claude Code ActionのVertex接続をOIDC連携で組むワークフロー
GitHub ActionsでClaude Codeを動かす場合は、鍵ファイルを置かずにWorkload Identity連携で認証します。claude-code-actionのクラウド接続ドキュメントの例から、Vertex AIの認証に関わる部分を抜き出すと次の形です（GitHub Appのトークン発行など、他の手順は省いています）。
permissions:
id-token: write # OIDCに必須
steps:
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
- uses: anthropics/claude-code-action@v1
with:
use_vertex: "true"
claude_args: |
--model claude-sonnet-5-5同じドキュメントの例ではモデルがclaude-4-0-sonnet@20250805と書かれていますが、この形はAgent PlatformのID表にありません。ID表の値に置き換えてください。サービスアカウントに付けるロールはroles/aiplatform.userで足ります。プール作成から属性条件までの手順はgoogle-github-actions/authのWorkload Identity連携の設定に、Actionの料金試算はClaude Code GitHub Actionsの料金と導入手順にまとめています。
Vertex AI経由を採用する条件とBedrockやサブスクを選ぶ場面の判断
ここまでの仕様をもとに、Vertex AI経由を選ぶかどうかを言い切ります。
請求と権限をGoogle Cloudに集めたい組織が第一候補にする条件
開発者のアカウントと請求をGoogle Cloudにまとめている組織は、Vertex AI経由を選びます。利用者の追加と削除はIAMのグループ操作で済み、費用の確認先は専用プロジェクトの請求です。管理設定のavailableModelsとenforceAvailableModels（v2.1.287以降）で、社員が使えるモデルを固定できます。
利用状況を部署ごとに見たいなら、Claude CodeのOpenTelemetry設定で計測を足します。Claude CodeからGCPのリソースそのものを操作させたい場合は、接続先の話とは別にGoogle Cloud Developer Pluginの導入手順を参照してください。
国内処理と最新モデルを両立させたい案件でVertex AIを見送る理由
個人情報や契約上の制約で「処理を日本国内に閉じる」が条件の案件では、Vertex AI経由を採用しません。前述のとおり、Sonnet 4.6より新しいモデルはリージョナルで動かず、マルチリージョンは米国とEUだけです。この条件ならAmazon Bedrockのjp.推論プロファイルが候補になり、設定はBedrock Claudeの使い方とClaude Codeの設定で解説しています。
開発者が数人で、GCPの請求に寄せる理由がない場合も見送ります。モデル申請やクォータ管理の手間に見合わないためです。サブスクへの切り替え方はClaude Codeのログイン方法にあります。Claude Codeの社内展開や、Vertex AI上のClaudeを業務システムへ組み込む実装まで任せたい場合は、生成AI開発・AI受託開発の相談窓口で要件の整理から対応しています。
Claude CodeのVertex AI接続で導入前によくある質問
Vertex AI経由でClaude Codeを使い始める段階で出やすい質問に、2026年11月時点の公式ドキュメントで答えます。
「model not found」の404が出たときは何を確認しますか？
Model Gardenでの有効化、CLOUD_ML_REGIONの地域での提供有無、の順に確かめます。globalなら、モデルカードの「Supported features」でglobal対応かどうかも確認が必要です。非対応のモデルはVERTEX_REGION_CLAUDE_*で地域を指定すれば通ります。
Vertex AI経由のClaude Codeの料金はどう決まりますか？
Google Cloudのトークン従量課金で、GCPの請求書に載ります。サブスクの月額は掛かりません。単価を左右するのは、モデルの種類、エンドポイントの種類（マルチリージョンとリージョナルは10%高い）、キャッシュの扱いの3点です。プロンプトキャッシュは自動で有効になり、ENABLE_PROMPT_CACHING_1H=1で1時間保持にすると書き込み単価が上がります。
100万トークンのコンテキストは使えますか？
使えます。Claude Codeの設定ページによると、Fable系、Sonnet 5以降、Opus 4.7以降はv2.1.287から既定で100万トークンです。200Kに抑えたいときはCLAUDE_CODE_DISABLE_1M_CONTEXT=1を設定します。Opus 4.6とSonnet 4.6はモデルIDの末尾に[1m]を付けた場合に限り100万トークンになります。
利用中に管理者がモデルを無効にするとどうなりますか？
版を固定していない階層なら、Claude Codeは同じ階層の古い版、Opusが無ければ既定のSonnetへ切り替え、「Switched to …」と表示します。固定した版で動いているセッションは切り替わらず、リクエストが失敗する挙動です。切り替えを止めて失敗させたいときはCLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1を設定します。
社内のLLMゲートウェイを経由させることはできますか？
ゲートウェイ経由での接続は可能です。ANTHROPIC_VERTEX_BASE_URLにゲートウェイのURLを入れ、ゲートウェイ側がGoogleの認証を持つならCLAUDE_CODE_SKIP_VERTEX_AUTH=1で端末側の認証を省きます。Agent Platformのリクエスト本文は30MBが上限なので、ゲートウェイも同じ上限で設計します。
関連記事
- Vertex AIでClaudeを使う方法：Model Garden有効化・Anthropic管理型・料金：SDKからClaudeを呼ぶ実装と2つの提供形態の比較
- Vertex AIとは？Google CloudのAI開発プラットフォームの機能・料金とSageMaker/Azure MLとの違い：Vertex AI全体の機能と料金
- Bedrock Claudeの使い方：Messages API・InvokeModel・Claude Codeの設定：AWS側でClaude Codeを動かす設定
- Claude Codeの料金プラン比較｜Pro・Max・Team・APIの損益分岐と使用上限・支出上限の設定：サブスクとAPI課金の比べ方
- Claude CodeのOpenTelemetry設定｜利用状況とコストを組織で可視化する実装：組織での利用状況とコストの計測
