--- title: "Claude CodeをVertex AIで使う設定：環境変数・IAM・リージョンとクォータ申請" url: "https://www.issoh.co.jp/tech/details/19449/" published: 2026-11-07 updated: 2026-11-07 categories: ["AI"] publisher: "株式会社一創" --- # Claude CodeをVertex AIで使う設定：環境変数・IAM・リージョンとクォータ申請 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設定ページ](https://code.claude.com/docs/en/google-vertex-ai)は、題名を「Google Cloud’s Agent Platform, formerly Vertex AI」に改めています。ただしログイン画面の選択肢は今も「Google Vertex AI」で、環境変数や`/setup-vertex`コマンドの名前も変わっていません。 Google Cloud上のClaudeには、Googleが運営する「Google managed」と、Anthropicが運営する「Anthropic managed」の2つの提供形態があります。Anthropicの[提供形態の比較ページ](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/overview)によると、前者の送り先は`aiplatform.googleapis.com`系、後者は`claude.googleapis.com`です。`CLAUDE_CODE_USE_VERTEX`が向かうのは前者です。2形態の選び方は[Vertex AIでClaudeを使う方法：Model Garden有効化・Anthropic管理型・料金](https://www.issoh.co.jp/tech/details/18420/)で比べています。 ### Claude Codeのサブスク版と比べた認証・請求・使えないコマンドの違い Vertex AI経由にすると、ログインの仕組みと請求先がまるごと入れ替わります。 | 項目 | サブスク（Pro・Max等） | Vertex AI経由 | | -------------- | --------------- | --------------------- | | 認証 | claude.aiのアカウント | gcloudのADCやサービスアカウント | | 請求 | Anthropicの月額プラン | Google Cloudのトークン従量課金 | | 利用上限 | プランごとの使用量上限 | GCPプロジェクトのクォータ | | /logout | 使える | 使えない | | Remote Control | 使える | 使えない | `/logout`が使えないことは設定ページに、Remote Controlが無効になることは[環境変数リファレンス](https://code.claude.com/docs/en/env-vars)の`ANTHROPIC_BASE_URL`の説明に書かれています。サブスクの料金と損益分岐は[Claude Codeの料金プラン比較](https://www.issoh.co.jp/tech/details/17988/)で試算しています。 ## 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:dev-team@example.co.jp" \ --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のページ](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/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の[リージョン一覧](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/locations)では、東京（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のクォータページ](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude/quotas)では、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段階です。 1. Google Cloudコンソールで「Quotas and system limits」を開く 2. フィルタで`base_model`に系統名（例：`anthropic-claude-opus`）を指定する 3. 該当する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のクラウド接続ドキュメント](https://github.com/anthropics/claude-code-action/blob/main/docs/cloud-providers.md)の例から、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連携の設定](https://www.issoh.co.jp/tech/details/16953/)に、Actionの料金試算は[Claude Code GitHub Actionsの料金と導入手順](https://www.issoh.co.jp/tech/details/7094/)にまとめています。 ## Vertex AI経由を採用する条件とBedrockやサブスクを選ぶ場面の判断 ここまでの仕様をもとに、Vertex AI経由を選ぶかどうかを言い切ります。 ### 請求と権限をGoogle Cloudに集めたい組織が第一候補にする条件 開発者のアカウントと請求をGoogle Cloudにまとめている組織は、Vertex AI経由を選びます。利用者の追加と削除はIAMのグループ操作で済み、費用の確認先は専用プロジェクトの請求です。管理設定の`availableModels`と`enforceAvailableModels`（v2.1.287以降）で、社員が使えるモデルを固定できます。 利用状況を部署ごとに見たいなら、[Claude CodeのOpenTelemetry設定](https://www.issoh.co.jp/tech/details/17005/)で計測を足します。Claude CodeからGCPのリソースそのものを操作させたい場合は、接続先の話とは別に[Google Cloud Developer Pluginの導入手順](https://www.issoh.co.jp/tech/details/18296/)を参照してください。 ### 国内処理と最新モデルを両立させたい案件でVertex AIを見送る理由 個人情報や契約上の制約で「処理を日本国内に閉じる」が条件の案件では、Vertex AI経由を採用しません。前述のとおり、Sonnet 4.6より新しいモデルはリージョナルで動かず、マルチリージョンは米国とEUだけです。この条件ならAmazon Bedrockの`jp.`推論プロファイルが候補になり、設定は[Bedrock Claudeの使い方とClaude Codeの設定](https://www.issoh.co.jp/tech/details/17865/)で解説しています。 開発者が数人で、GCPの請求に寄せる理由がない場合も見送ります。モデル申請やクォータ管理の手間に見合わないためです。サブスクへの切り替え方は[Claude Codeのログイン方法](https://www.issoh.co.jp/tech/details/18748/)にあります。Claude Codeの社内展開や、Vertex AI上のClaudeを業務システムへ組み込む実装まで任せたい場合は、[生成AI開発・AI受託開発の相談窓口](https://www.issoh.co.jp/service/ai/development/)で要件の整理から対応しています。 ## 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管理型・料金](https://www.issoh.co.jp/tech/details/18420/)：SDKからClaudeを呼ぶ実装と2つの提供形態の比較 - [Vertex AIとは？Google CloudのAI開発プラットフォームの機能・料金とSageMaker/Azure MLとの違い](https://www.issoh.co.jp/tech/details/15546/)：Vertex AI全体の機能と料金 - [Bedrock Claudeの使い方：Messages API・InvokeModel・Claude Codeの設定](https://www.issoh.co.jp/tech/details/17865/)：AWS側でClaude Codeを動かす設定 - [Claude Codeの料金プラン比較｜Pro・Max・Team・APIの損益分岐と使用上限・支出上限の設定](https://www.issoh.co.jp/tech/details/17988/)：サブスクとAPI課金の比べ方 - [Claude CodeのOpenTelemetry設定｜利用状況とコストを組織で可視化する実装](https://www.issoh.co.jp/tech/details/17005/)：組織での利用状況とコストの計測 --- 出典: [Claude CodeをVertex AIで使う設定：環境変数・IAM・リージョンとクォータ申請]()（株式会社一創）