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

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

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

読了目安 約12分

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

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

このガイドは管理者向けに、APIの有効化からIAMロールの割り当て、チーム全体でのモデルバージョン固定までを一次ソースの手順どおりに並べます。

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

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

​bash 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を使う構成が中心になります。

Claude CodeはX.509証明書ベースのWorkload Identity Federationにも対応しており、GOOGLE_APPLICATION_CREDENTIALSに認証情報の設定ファイルパスを指定します。認証情報が期限切れになったときの自動更新には、設定ファイルのgcpAuthRefreshが使えます。

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

gcpAuthRefreshはブラウザ認証フローのようにコマンドの出力をそのまま表示しますが、対話的な入力は送れません。認証が3分以内に完了しないとタイムアウトします。プロジェクト設定(.claude/settings.json)にこのキーを書く場合、hooksと同じワークスペース信頼ルールが適用され、一度も信頼していないフォルダでの-pセッションでも実行されます。

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

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

​bash 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のような特定リージョンのいずれかを指定できます。すべてのモデルがすべてのエンドポイント種別に対応しているわけではなく、モデルごとに対応状況が異なります。globalを指定していてもグローバルエンドポイント非対応のモデルがある場合は、そのモデルだけ個別のリージョンを指定します。

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

ANTHROPIC_VERTEX_PROJECT_IDよりGCLOUD_PROJECT・GOOGLE_CLOUD_PROJECT・認証情報ファイルに紐づくプロジェクトIDのほうが優先されるので、複数のプロジェクトを使い分けるチームは優先順位を意識しておく必要があります。ここまでの環境変数はCLI本体の設定で、VS Code拡張でサードパーティプロバイダーを使う場合は別の設定手順が必要です。詳しくはVS Code拡張でサードパーティプロバイダーを使う設定を参照してください。

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

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

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

モデルバージョンを固定しないと、sonnetやopusのようなエイリアスはClaude Codeの組み込みデフォルトに解決されます。デフォルトは最新リリースに遅れることがあり、しかもプロジェクトでまだ有効化されていない可能性もあります。デフォルトが使えない場合、Claude Codeはより古いバージョンやSonnetへ自動でフォールバックしますが、この挙動は永続化されません。チーム展開では明示的にピン留めして、いつユーザーを新しいモデルへ移行させるかを管理側で決めます。

​bash 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' ​

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

ピン留めを省略した場合のデフォルト解決先とバージョン差も、チーム展開では確認しておく必要があります。opusはOpus 5に、sonnetはSonnet 4.5に解決され、Primaryはclaude-opus-5、Small/fastはclaude-sonnet-4-5@20250929です。ただしv2.1.207〜v2.1.218ではPrimaryがOpus 4.8になりopusもOpus 4.8に解決されます。v2.1.207未満ではPrimaryがSonnet 4.5、opusはOpus 4.6に解決され、バックグラウンドタスクは常にPrimaryのモデルを使います。加えて起動時にはモデルチェックが働き、現行の既定より古いバージョンをピン留めしていると更新を促すプロンプトが表示されます。opusのようなエイリアスはピン留めとしては機能しない点にも注意してください。

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

/setup-vertexウィザードとの使い分け

個人が自分の端末でサインインするだけなら、Claude Code Vertex AIセットアップの/setup-vertexウィザードのほうが手早く終わります。ウィザードはGCPプロジェクトとリージョンを検出し、呼び出せるモデルを確認したうえでピン留めまで対話で完結させ、結果をユーザー設定ファイルに書き込みます。

このガイドで扱った手順が向くのは、①複数ユーザーに同じ設定を配りたい ②CI/CDでサービスアカウントを使う ③IAMロールをあらかじめ管理者側で用意しておきたい、のいずれかに当てはまる場合です。個人利用から始めて後でチーム展開に切り替えることもでき、その場合はウィザードが書き込んだ設定を土台に、IAM権限とモデルピンだけをこのガイドの手順で管理者向けに整理し直せます。

つまずきやすいポイント

「Could not load the default credentials」エラーが出る場合、Application Default Credentialsが設定されていません。gcloud auth application-default loginを実行するか、GOOGLE_APPLICATION_CREDENTIALSにサービスアカウントキーのパスを設定します。

クォータ関連のエラーが出る場合、Cloud Consoleで現在のクォータを確認するか、増枠をリクエストします。

「model not found」の404エラーが出る場合、Model GardenでそのモデルがEnabledになっているか、指定したロケーションでそのモデルが提供されているかを確認します。globalロケーションを指定している場合は、対象モデルがグローバルエンドポイントに対応しているかをModel Gardenの「Supported features」で確認してください。対応していなければ、モデルごとのリージョン変数を個別に設定するか、対応済みの別モデルを指定します。

429エラーが出る場合、リージョン固定のエンドポイントではそのリージョンでのモデル提供状況を確認し、可用性を優先するならCLOUD_ML_REGION=globalへの切り替えを検討します。

まとめ

チーム展開のIAM設定は、①Agent Platform APIの有効化とModel Gardenでのモデルアクセス申請 ②サービスアカウントまたはWorkload Identity Federationによる認証 ③roles/aiplatform.userの割り当て ④モデルバージョンの固定、の4点に集約されます。個人のその場サインインは/setup-vertexウィザードに任せ、複数ユーザーやCIへの配布はこのガイドの環境変数とIAM権限で管理する、という役割分担で考えると迷いません。Amazon Bedrock・Microsoft Foundryなど他のクラウド経由でClaude Codeを使う選択肢を比較検討している場合は、Claude Code Microsoft Foundry設定ガイドも合わせて確認してください。

よくある質問

roles/aiplatform.userより狭い権限にできますか

できます。このロールに含まれるaiplatform.endpoints.predict権限だけを持つカスタムロールを作成すれば、モデル呼び出しとトークンカウントに必要な範囲に絞れます。

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

いいえ。申請はGCPプロジェクト単位です。プロジェクト管理者が事前に必要なモデルへのアクセスをまとめて申請しておけば、そのプロジェクトを使うユーザー全員が申請済みのモデルを呼び出せます。

Workload Identity Federationとサービスアカウントキー、どちらを使うべきですか

公式ドキュメントはどちらも認証方法として提示するのみで、優先順位は明記していません。長期間有効なキーファイルを配布したくないCI環境ではWorkload Identity Federationが選ばれやすく、簡易に済ませたいローカル検証ではサービスアカウントキーやApplication Default Credentialsで十分なケースが多くなります。

gcpAuthRefreshはどんな場面で必要ですか

GCP認証情報が期限切れ、または読み込めない状態をClaude Codeが検知したときに、設定したコマンドを実行して新しい認証情報を取得する仕組みです。ブラウザで認証を完了させる運用のチームで、認証切れのたびに手動対応するのを避けたい場合に設定します。

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

関連する記事

Claude Code をもっと見る →