Claude Media
Claude Code Vertex AI IAM設定とチーム展開ガイド
Claude Codeチュートリアル

Claude Code Vertex AI IAM設定とチーム展開ガイド

Claude CodeをGoogle Cloud's Agent Platform(旧Vertex AI)でチーム展開するためのIAM権限・モデルアクセス申請・環境変数設定を手順で確認します。

読了目安 約19分

Vertex AIチーム展開で個人セットアップと何が違うか

Claude CodeをGoogle Cloud's Agent Platform(旧称Vertex AI)経由でチームやCIに展開するときは、/setup-vertexウィザードではなく、管理者がIAM権限・モデルアクセス申請・環境変数を先に整えます。ウィザードは個人がその場でGCP認証情報を選んでサインインする経路で、複数ユーザーの端末やCIに配る設定とは前提が異なります。

このガイドは管理者向けに、APIの有効化からIAMロールの割り当て、モデルバージョンの固定、全員への設定配布までを手順で並べます。

くらべる

ウィザードと手動設定の使い分け

個人の端末

/setup-vertex ウィザード

claudeを起動してログイン画面で3rd-party platformを選ぶと始まります。サインインずみなら/loginで同じメニューを開けます。認証方法・プロジェクト・リージョンを対話で選び、呼び出せるモデルを調べてピン留めまで進み、結果をユーザー設定のenvブロックに保存します。

チーム・CI

手動設定(このガイド)

複数ユーザーに同じ設定を配る、CI/CDでサービスアカウントを使う、IAMロールを管理者側で先に用意する、のいずれかに当てはまる場合の経路です。環境変数と設定ファイルだけで完結するため、対話画面のない環境でも同じ結果になります。

ウィザード側の手順はClaude Code Vertex AIセットアップにまとめています。

ステップ1: APIの有効化とモデルアクセス申請

GCPプロジェクトでGoogle Cloud's Agent Platform APIを有効化し、使いたいClaudeモデルへのアクセスを個別に申請します。

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

API有効化のあとは、Model GardenでClaudeモデルを検索してアクセスを申請します。

  1. Model Gardenを開く
  2. 「Claude」で検索する
  3. 使いたいモデル(Claude Sonnet 4.6など)へのアクセスを申請する
  4. 承認を待つ(24〜48時間程度かかる場合がある)

承認待ちは個人でも同じですが、チーム展開では複数モデルをまとめて事前申請しておくと、あとからユーザーが個別に待たされずに済みます。次のモデル世代へ移すときに備えて、移行先のモデルも早めに申請しておく運用が考えられます。

ステップ2: GCP認証を構成する

Claude Codeは標準的なGoogle Cloud認証を使います。CI環境やサーバーサイドの自動実行では、個人のログインではなくサービスアカウントやWorkload Identity Federationを使う構成が中心になります。

X.509証明書ベースのWorkload Identity Federationにも、Application Default Credentialsの同じ経路で対応しています。GOOGLE_APPLICATION_CREDENTIALSに認証情報の設定ファイルのパスを指定します。

認証情報が期限切れになったときの自動更新には、設定ファイルのgcpAuthRefreshが使えます。期限切れや無効で401が出たときの直し方はGoogle Cloudの認証情報が期限切れのときの対処にまとめています。

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

Claude Codeは更新コマンドを走らせる前に、いまの認証情報でアクセストークンを要求し、本当に期限切れかを調べます。まだ使えるならコマンドは実行されません。この判定が5秒で終わらないときも実行を見送り、リクエストが認証エラーで失敗してから実行します。

コマンドの出力はそのまま画面に表示されますが、対話的な入力は送れません。ブラウザで認証を完了させる形式なら問題なく使え、3分以内に終わらないとタイムアウトします。

複数のターミナルやIDEが同じ認証情報の期限切れに同時に当たると、1つのプロセスだけがコマンドを実行し、残りはその完了を待ちます。60秒待ってもリクエストが保留のままのプロセスは、自分でコマンドを実行します。この待ち合わせを止めたいときはCLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK=1を設定します(v2.1.286以降が必要です)。

プロジェクト設定(.claude/settings.json)にこのキーを書く場合は、hooksと同じワークスペース信頼ルールが適用されます。一度も信頼していないフォルダでの-pセッションでも実行される点が、チームリポジトリに置くときの注意点です。

ステップ3: 環境変数とリージョンの設定

認証を構成したら、Claude Code側の環境変数を設定します。

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

CLOUD_ML_REGIONにはglobal・euやusのようなマルチリージョン・us-east5のような特定リージョンのいずれかを指定できます。マルチリージョンではaiplatform.eu.rep.googleapis.comやaiplatform.us.rep.googleapis.comのホストが選ばれます。

すべてのモデルがすべてのエンドポイント種別に対応しているわけではありません。globalを指定していてグローバルエンドポイント非対応のモデルがある場合は、そのモデルだけ個別にリージョンを指定します。

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

VERTEX_REGION_CLAUDE_*はモデルのバージョンごとに用意されています。たとえばOpus 5.5用のVERTEX_REGION_CLAUDE_5_5_OPUSはv2.1.280、Sonnet 5.5用のVERTEX_REGION_CLAUDE_5_5_SONNETはv2.1.284で追加されました。ピン留めするモデルを新しい世代へ移すときは、対応する変数の有無とあわせて見直します。

リージョンの値にスラッシュ・ドット・空白が含まれるなど、リージョン名やロケーション名の形をしていない場合、Claude Codeはその値を未設定として扱います。VERTEX_REGION_CLAUDE_*はCLOUD_ML_REGIONに、CLOUD_ML_REGIONはus-east5に戻ります。タイプミスしたリージョンがエラーにならず、別のリージョンへ流れる経路になります。

プロジェクトIDは、GCLOUD_PROJECT・GOOGLE_CLOUD_PROJECT・認証情報ファイルに別のIDが入っていても、リクエストの宛先としてはANTHROPIC_VERTEX_PROJECT_IDが使われます。複数のプロジェクトを使い分けるチームは、この変数を明示的に配っておくと宛先がぶれません。

ここまでの環境変数はCLI本体の設定です。VS Code拡張でサードパーティプロバイダーを使う場合は別の設定手順が必要で、VS Code拡張でサードパーティプロバイダーを使う設定で扱っています。

プロンプトキャッシュは自動で有効になります。止めるにはDISABLE_PROMPT_CACHING=1、既定の5分に代えて1時間のTTLを要求するにはENABLE_PROMPT_CACHING_1H=1を設定します。1時間TTLのキャッシュ書き込みは、より高い料率で課金されます。

ステップ4: IAM権限を割り当てる

Claude Codeを実行するアカウント(ユーザーまたはサービスアカウント)にはroles/aiplatform.userロールを割り当てます。このロールにはaiplatform.endpoints.predict(モデル呼び出しとトークンカウントに必要)が含まれます。より限定した権限にしたい場合は、この権限だけを持つカスタムロールを作成します。

ステップ5: チーム展開前にモデルバージョンを固定する

モデルバージョンを固定しないと、sonnetやopusのようなエイリアスはClaude Codeの組み込みデフォルトに解決されます。デフォルトは最新リリースに遅れることがあり、プロジェクトでまだ有効化されていない可能性もあります。

デフォルトが使えない場合、Claude Codeは起動時に古いバージョンや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'

ピン留めを省略したときのデフォルトは、Claude Codeのバージョンによって変わります。古い版のまま残っている端末が混在するチームでは、同じ設定でも端末ごとに別のモデルで動く可能性があります。MCPツール検索も同様で、Agent Platformではv2.1.221より前は既定で無効でした。それ以降はClaude 4.5世代以降のモデルで既定で有効になり、ENABLE_TOOL_SEARCHで挙動を切り替えられます。

あゆみ

ピン留めなしのデフォルトの移り変わり

  1. v2.1.207未満Sonnet 4.5が主モデル

    opusはOpus 4.6に解決され、バックグラウンドタスクは常に主モデルを使います。

  2. v2.1.207〜v2.1.218Opus 4.8が主モデル

    opusもOpus 4.8に解決されます。

  3. v2.1.219〜v2.1.279Opus 5が主モデル

    opusエイリアスと主モデルがOpus 5になります。

  4. v2.1.280以降Opus 5.5が主モデル

    主モデルはclaude-opus-5-5で、sonnetエイリアスはSonnet 4.5に解決されます。小型・高速モデルはclaude-sonnet-4-5@20250929です。

課金面では、v2.1.207以降にアップデートすると、主モデルをピン留めしていないデプロイはOpusレートで課金されます。Sonnet 4.5を主モデルのまま保ちたい場合は、ANTHROPIC_MODELにフルのモデルIDを設定します。

ANTHROPIC_DEFAULT_SONNET_MODELだけを設定してANTHROPIC_DEFAULT_OPUS_MODELを設定していないデプロイでは、指定したSonnetが既定のまま維持されます。

バックグラウンドタスクのモデル

セッションタイトル生成などのバックグラウンドタスクは、通常Haikuクラスのモデルが担います。Google Cloud's Agent Platformではプロジェクトによって未有効化の場合があるため、既定ではSonnetモデルが代わりに使われます。

次の選択をしたときは、バックグラウンドタスクもそのモデルに移ります。

  • --model・ANTHROPIC_MODEL・model設定で主モデルを選んだとき
  • ANTHROPIC_DEFAULT_MODELで起動時のモデルを指定したとき
  • ANTHROPIC_DEFAULT_OPUS_MODELだけを設定したとき(組み込みのSonnetがプロジェクトで有効とは限らないため)

Haikuを使いたい場合はANTHROPIC_DEFAULT_HAIKU_MODELに、プロジェクトで有効なモデルIDを指定します。

起動時のモデルチェックと切り替え

Claude Codeは起動時に、使おうとしているモデルがプロジェクトで呼び出せるかを調べます。

  • 古いピンが残っている: 現行のデフォルトより古いバージョンをピン留めしていて、プロジェクトが新しい版を呼び出せるなら、更新を促すプロンプトが出ます。承認するとユーザー設定に新しいモデルIDが書かれてClaude Codeが再起動し、断ると次にデフォルトが変わるまで覚えています
  • デフォルトが使えない: ピン留めがなければ、そのセッションに限って古いバージョンへ切り替え、通知を出します。Opusが既定でどのバージョンも使えない場合はSonnetに移ります
  • --modelで版を指定した: 指定した版がそのセッションのピンとして扱われ、置き換え対象のデフォルトの可用性チェックは省かれます

opusのようなエイリアスと、Claude Codeが認識しないモデルIDは、ピンとして扱われません。

モデルを呼び出せないと分かったとき、その拒否はこのマシンに最大1日記憶され、その間の起動では問い合わせなしで飛ばされます。現行デフォルトの拒否だけは、前回のチェックから10分経つと起動時に再確認されるので、管理者が有効化し直したモデルが戻ってきます。記憶を止めるにはCLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1を設定します(v2.1.285以降が必要です)。

セッションの途中でModel Gardenからモデルが無効化された場合も、リクエストを失敗させ続けるのではなく別のモデルへ切り替え、Switched to <fallback> because <model> is not availableと表示します。切り替わるのはピン留めしていない階層だけで、版を指定したセッションはモデルが変わらずリクエストが失敗します。

失敗させたいときはCLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1を設定します(v2.1.285以降が必要です)。フォールバックチェーンを設定している場合は、チェーンが優先されるため、そちらも外す必要があります。

1Mトークンのコンテキストウィンドウ

Claude Sonnet 5、Opus 4.6以降、Sonnet 4.6は、Google Cloud's Agent Platformで1Mトークンのコンテキストウィンドウに対応します。Sonnet 5は常に1Mで動き、選ぶ[1m]バリアントはありません。

ほかのモデルは、1Mのバリアントを選ぶと自動で有効になります。手動でピン留めしたモデルで使うには、モデルIDの末尾に[1m]を付けます。

ステップ6: 設定を検証する

Claude Codeを起動して/statusを実行します。API providerの行がGoogle Vertex AIになり、GCP project・Default region・Modelの行にプロジェクトID・リージョン・解決されたモデルが出れば設定が通っています。

provider行が出ない場合は、環境変数がプロセスに届いていません。claudeを起動したシェルでexportされているか、設定ファイルのenvブロックに書かれているかを見直します。なお、このプロバイダーではログイン情報がGoogle Cloud側にあるため、/logoutコマンドは使えません。

全員に同じ設定を強制する

環境変数をメールやwikiで配るだけでは、端末ごとに設定がずれていきます。管理者向けのmanaged-settings.jsonにまとめると、ユーザー側の設定では上書きできません。配置先は次のとおりです。

OSパス
macOSパス/Library/Application Support/ClaudeCode/managed-settings.json
Linux・WSLパス/etc/claude-code/managed-settings.json
WindowsパスC:\Program Files\ClaudeCode\managed-settings.json

Google Cloud's Agent Platform経由のセッションは、claude.aiのサーバー管理設定を受け取りません。許可リストなどの配布は、MDMかこの設定ファイルで行います。

{
  "env": {
    "CLAUDE_CODE_USE_VERTEX": "1",
    "CLOUD_ML_REGION": "global",
    "ANTHROPIC_VERTEX_PROJECT_ID": "YOUR-PROJECT-ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8"
  },
  "allowedProviders": ["vertex"],
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],
  "enforceAvailableModels": true
}
まとめ

この設定ファイルが効く3つの制御

  • allowedProviders

    Claudeに到達できるサービスを絞ります。"vertex"だけを並べると、Anthropic APIなど別のプロバイダーを選んだセッションは起動時・ログイン時・次のAPI呼び出し時に拒否されます。v2.1.285以降が必要で、未設定なら任意のプロバイダーを使えます。

  • availableModels と enforceAvailableModels

    選べるモデルを絞り、enforceAvailableModelsでDefaultの解決先も許可リストの中に収めます。Agent Platformの起動時チェックも許可リストのモデルだけを対象にしますが、この動作にはv2.1.287以降が必要です。エントリはAgent Platformに送るモデルIDで書きます。

  • gcpAuthRefresh

    優先度が最も高い設定元の値だけが読まれ、低い設定元の値は無視されます。更新コマンドを管理側で固定したいときは、managed-settings.jsonに置きます。

allowedProvidersの中身に認識できない名前があると、その項目は捨てられて残りの許可リストは有効なままです。空のリスト、または全項目が認識できない場合は、すべてのプロバイダーが拒否されてClaude Codeが起動しません。

つまずきやすいポイント

Could not load the default credentials

Application Default Credentialsが設定されていません。gcloud auth application-default loginを実行するか、GOOGLE_APPLICATION_CREDENTIALSにサービスアカウントキーのパスを設定します。

クォータ関連のエラー

Cloud Consoleで現在のクォータを確かめるか、増枠をリクエストします。レート制限の引き上げは、Google Cloudのサポートに依頼します。

model not foundの404エラー

次の順で見ていきます。

  1. Model GardenでそのモデルがEnabledになっているか
  2. 指定したロケーションでそのモデルが提供されているか。globalやマルチリージョン(eu・us)だけで提供され、特定リージョンでは使えないモデルがあります
  3. globalを指定している場合、対象モデルがグローバルエンドポイントに対応しているか。Model Gardenの「Supported features」で調べます

対応していなければ、ANTHROPIC_MODELやANTHROPIC_DEFAULT_HAIKU_MODELで対応済みのモデルを指定するか、VERTEX_REGION_<モデル名>でモデルごとのリージョンを設定します。

429エラー

リージョン固定のエンドポイントでは、主モデルと小型・高速モデルの両方がそのリージョンで提供されているかが問題になります。可用性を優先するならCLOUD_ML_REGION=globalへの切り替えが選択肢です。

まとめ

チーム展開では、IAMのroles/aiplatform.userとモデルのピン留めを管理者が決め、設定の配布と制限はmanaged-settings.jsonで一本化するのが土台になります。ピンを省いた端末は、Claude Codeのバージョンによって別のモデルで動き、課金レートも変わります。

Amazon Bedrock・Microsoft Foundryなど他のクラウド経由の構成を比べる場合は、Claude Code Microsoft Foundry設定ガイドも参考になります。

よくある質問

社内のゲートウェイやプロキシを経由させられますか

ANTHROPIC_VERTEX_BASE_URLでAgent Platformのエンドポイントを差し替えられます。ゲートウェイ側でGoogleの認証を済ませる構成なら、CLAUDE_CODE_SKIP_VERTEX_AUTHでClaude Code側のGoogle認証を省きます。allowedProvidersと併用するときは、"customEndpoint"が管理者設定のenvブロックで固定した値にだけ許可される点に注意します。

サービスアカウントキーとWorkload Identity Federationはどう選びますか

Claude Code側はどちらもApplication Default Credentialsの経路で読むため、設定の書き方はGOOGLE_APPLICATION_CREDENTIALSで共通です。違いはGoogle Cloud側の運用で、キーファイルを配布するかどうかが判断の軸になります。

モデルアクセスの申請はチームの全員が個別に行う必要がありますか

いいえ。申請はModel Gardenでプロジェクトに対して行います。管理者が必要なモデルを事前にまとめて申請しておけば、ユーザーが個別に待たされずに済みます。

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

関連する記事

Claude Code をもっと見る →