Google Cloud の Agent Platform 上の Claude Code

Google Cloud の Agent Platform（旧 Vertex AI）を通じた Claude Code の設定方法について学びます。セットアップ、IAM 設定、トラブルシューティングを含みます。

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

View plans Contact sales

前提条件

Claude Code を Google Cloud の Agent Platform（旧 Vertex AI）で設定する前に、以下を確認してください。

• 請求が有効になっている Google Cloud Platform（GCP）アカウント
• Google Cloud の Agent Platform API が有効になっている GCP プロジェクト
• 目的の Claude モデルへのアクセス（例：Claude Sonnet 4.6）
• Google Cloud SDK（gcloud）がインストールされ、設定されていること
• 目的の GCP リージョンに割り当てられたクォータ

Google Cloud の Agent Platform 認証情報でサインインするには、以下のAgent Platform でサインインに従ってください。チーム全体に Claude Code をデプロイするには、手動セットアップの手順を使用し、ロールアウト前にモデルバージョンをピン留めしてください。

Agent Platform でサインイン

Google Cloud 認証情報を持っていて、Google Cloud の Agent Platform を通じて Claude Code の使用を開始したい場合、ログインウィザードがそれをガイドします。GCP 側の前提条件はプロジェクトごとに 1 回完了します。ウィザードが Claude Code 側を処理します。

1. GCP プロジェクトで Claude モデルを有効にする

プロジェクトのGoogle Cloud の Agent Platform API を有効にして、Google Cloud の Agent Platform Model Gardenで必要な Claude モデルへのアクセスをリクエストしてください。アカウントに必要な権限については、IAM 設定を参照してください。

2. Claude Code を起動して Google Cloud の Agent Platform を選択する

claude を実行します。ログインプロンプトで、3rd-party platform、次に Google Vertex AI を選択します。これはログインプロンプトが Google Cloud の Agent Platform に対して使用しているラベルです。既にサインインしている場合は、/login を実行して同じメニューを開きます。

3. ウィザードプロンプトに従う

Google Cloud への認証方法を選択します。gcloud からの Application Default Credentials、サービスアカウントキーファイル、または環境内に既にある認証情報です。ウィザードはプロジェクトとリージョンを検出し、プロジェクトが呼び出せる Claude モデルを確認し、それらをピン留めできます。結果はユーザー設定ファイルの env ブロックに保存されるため、環境変数を自分でエクスポートする必要はありません。

サインイン後、いつでも /setup-vertex を実行してウィザードを再度開き、認証情報、プロジェクト、リージョン、またはモデルピンを変更できます。モデルピンステップは、現在ピン留めされているモデルから開始します。ウィザードは ~/.claude/settings.json に書き込むか、CLAUDE_CONFIG_DIRが設定されている場合は $CLAUDE_CONFIG_DIR/settings.json に書き込みます。

リージョン設定

Claude Code は Google Cloud の Agent Platform のグローバル、マルチリージョン、および地域別エンドポイントをサポートしています。CLOUD_ML_REGION を global、eu または us などのマルチリージョンロケーション、または us-east5 などの特定のリージョンに設定します。Claude Code は各フォームの正しい Google Cloud の Agent Platform ホスト名を選択します。これには、マルチリージョンロケーション用の aiplatform.eu.rep.googleapis.com および aiplatform.us.rep.googleapis.com ホストが含まれます。

[!NOTE]

Google Cloud の Agent Platform は、すべてのエンドポイントタイプで Claude Code デフォルトモデルをサポートしていない場合があります。モデルの可用性は、特定のリージョン、マルチリージョンロケーション、およびグローバルエンドポイントによって異なります。サポートされているロケーションに切り替えるか、サポートされているモデルを指定する必要がある場合があります。

手動でセットアップする

ウィザードの代わりに環境変数を通じて Google Cloud の Agent Platform を設定するには、例えば CI またはスクリプト化されたエンタープライズロールアウトで、以下の手順に従ってください。

Agent Platform API を有効にする

GCP プロジェクトで Google Cloud の Agent Platform API を有効にします。YOUR-PROJECT-ID を GCP プロジェクト ID に置き換えてください。以下の設定手順でも同じように置き換えます。

# プロジェクト ID を設定
gcloud config set project YOUR-PROJECT-ID

# Agent Platform API を有効にする
gcloud services enable aiplatform.googleapis.com

モデルアクセスをリクエストする

Google Cloud の Agent Platform で Claude モデルへのアクセスをリクエストします。

1. Google Cloud の Agent Platform Model Gardenに移動します
2. 「Claude」モデルを検索します
3. 目的の Claude モデルへのアクセスをリクエストします（例：Claude Sonnet 4.6）
4. 承認を待ちます（24 ～ 48 時間かかる場合があります）

GCP 認証情報を設定する

Claude Code は標準的な Google Cloud 認証を使用します。

詳細については、Google Cloud 認証ドキュメントを参照してください。

Claude Code は、同じ Application Default Credentials チェーンを通じて X.509 証明書ベースのワークロード ID フェデレーションをサポートしています。GOOGLE_APPLICATION_CREDENTIALS を認証情報設定ファイルのパスに設定します。

[!NOTE]

Claude Code は Google Cloud の Agent Platform リクエストを ANTHROPIC_VERTEX_PROJECT_ID のプロジェクトにアドレス指定します。GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT、または GOOGLE_APPLICATION_CREDENTIALS で参照される認証情報ファイルが異なるプロジェクトを持つ場合でも同じです。

高度な認証情報設定

Claude Code は gcpAuthRefresh 設定を通じて GCP の自動認証情報更新をサポートしています。これを Claude Code の 設定ファイル（例：~/.claude/settings.json）に追加します。Claude Code が GCP 認証情報の有効期限が切れているか読み込めないことを検出すると、リクエストを再試行する前に新しい認証情報を取得するために設定されたコマンドを実行します。

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

コマンドを実行する前に、Claude Code は現在の認証情報でアクセストークンをリクエストして、実際に有効期限が切れていることを確認し、まだ機能している場合はコマンドをスキップします。

チェックが 5 秒以内に完了しない場合、Claude Code もコマンドをスキップし、リクエストが認証情報エラーで失敗した後にのみ実行します。v2.1.261 より前は、タイムアウトしたチェックは有効期限が切れた認証情報としてカウントされたため、認証情報がまだ有効であってもコマンドがスタートアップ時にブラウザを開く可能性がありました。

Claude Code はコマンドの出力を表示しますが、コマンドに対話的な入力を送信することはできません。これは、CLI が URL を表示し、ブラウザで認証を完了するブラウザベースの認証フローに適しています。認証が完了しない場合、更新コマンドは 3 分後にタイムアウトします。.claude/settings.json などのプロジェクト設定で gcpAuthRefresh を設定した場合、Claude Code は設定ファイルの ワークスペース信頼ルールと同じルールの下でそれを実行します。これには、信頼したことのないフォルダ内の -p セッションが含まれます。

Claude Code を設定する

次の環境変数を設定します。

# Agent Platform 統合を有効にする
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# オプション：カスタムエンドポイントまたはゲートウェイ用に Agent Platform エンドポイント URL をオーバーライドする
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# CLOUD_ML_REGION=global の場合、グローバルエンドポイントをサポートしていないモデルのリージョンをオーバーライドする
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

ほとんどのモデルバージョンには、対応する VERTEX_REGION_CLAUDE_* 変数があります。完全なリストについては、環境変数リファレンスを参照してください。どのモデルがグローバルエンドポイントをサポートしているか、または地域別のみをサポートしているかを確認するには、Google Cloud の Agent Platform Model Gardenを確認してください。

リージョン値がリージョンまたはロケーション名のような形状でない場合、Claude Code はそれを未設定として扱います。例えば、Claude Code はスラッシュ、ドット、またはスペースを含む値を未設定として扱います。Claude Code は各変数に対して異なるソースにフォールバックします。

• VERTEX_REGION_CLAUDE_*：Claude Code は CLOUD_ML_REGION にフォールバックします。
• CLOUD_ML_REGION：Claude Code は us-east5 にフォールバックします。

プロンプトキャッシュは自動的に有効になります。これを無効にするには、DISABLE_PROMPT_CACHING=1 を設定します。デフォルトの 5 分ではなく 1 時間のキャッシュ TTL をリクエストするには、ENABLE_PROMPT_CACHING_1H=1 を設定します。1 時間の TTL でのキャッシュ書き込みはより高いレートで課金されます。メインの会話と Claude Code が外部で行うリクエストに異なる TTL を設定するには、TTL を自分で選択してください。

レート制限を高くするには、Google Cloud サポートに連絡してください。Google Cloud の Agent Platform を使用する場合、認証が Google Cloud 認証情報を通じて処理されるため、/logout コマンドは利用できません。

Claude Code は MCP tool searchと事前ロードをモデル生成によって決定します。

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5、およびそれ以降：Claude Code はデフォルトでツール検索を有効にします。
• 以前のモデル：Claude Code は MCP ツール定義を事前にロードします。これは、これらのモデルの Agent Platform サービングスタックが必要なベータヘッダーを拒否するためです。ENABLE_TOOL_SEARCH=true を設定してもこれを上書きしません。

すべてのモデルでツール検索を無効にするには、ENABLE_TOOL_SEARCH=false を設定します。v2.1.221 より前は、Claude Code は ENABLE_TOOL_SEARCH=true を設定しない限り、Google Cloud の Agent Platform 上のすべてのモデルでツール検索を無効にしていました。

モデルバージョンをピン留めする

[!WARNING]

複数のユーザーにデプロイする場合は、特定のモデルバージョンをピン留めしてください。ピン留めなしでは、sonnet および opus などのモデルエイリアスは Claude Code の Google Cloud の Agent Platform 用の組み込みデフォルトに解決され、最新リリースより遅れる可能性があり、プロジェクトでまだ有効になっていない可能性があります。Claude Code は、デフォルトが利用できない場合、スタートアップ時に前のバージョンまたは下位層のモデルにフォールバックしますが、ピン留めすることで、ユーザーが新しいモデルに移行するタイミングを制御できます。

これらの環境変数を特定の Google Cloud の Agent Platform モデル ID に設定します。

ANTHROPIC_DEFAULT_OPUS_MODEL がない場合、Google Cloud の Agent Platform 上の opus エイリアスは Opus 5.5 に解決され、ANTHROPIC_DEFAULT_SONNET_MODEL がない場合、sonnet エイリアスは Sonnet 4.5 に解決されます。この例では、各エイリアスを特定のバージョンにピン留めします。

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'

現在および従来のモデル ID については、モデル概要を参照してください。環境変数の完全なリストについては、モデル設定を参照してください。

Claude Code は、ピン留め変数が設定されていない場合、これらのデフォルトモデルを使用します。

v2.1.280 より前は、Google Cloud の Agent Platform 上のプライマリモデルは Opus 5 にデフォルト設定され、opus エイリアスは v2.1.219 から Opus 5 に解決されました。

セッションタイトル生成などのバックグラウンドタスクは、小型/高速モデル（通常は Haiku クラスモデル）を使用します。Google Cloud の Agent Platform では、Haiku がすべてのプロジェクトまたはリージョンで有効になっていない可能性があるため、Claude Code はバックグラウンドタスクにデフォルトの Sonnet モデルを使用します。2 つの選択がどのモデルがバックグラウンドタスクを実行するかを変更します。

• --model、ANTHROPIC_MODEL、または model 設定でプライマリモデルを選択すると、バックグラウンドタスクはそのモデルを使用します。ANTHROPIC_DEFAULT_MODELで設定したモデルで Claude Code がセッションを開始する場合、バックグラウンドタスクもそのモデルを使用します。ANTHROPIC_DEFAULT_SONNET_MODEL なしで ANTHROPIC_DEFAULT_OPUS_MODEL を設定することも、組み込み Sonnet モデルがプロジェクトで有効になっていない可能性があるため、選択としてカウントされます。
• バックグラウンドタスクに Haiku を使用するには、ANTHROPIC_DEFAULT_HAIKU_MODEL をプロジェクトで利用可能なモデル ID に設定します。

[!WARNING]

Opus モデルは Sonnet モデルよりトークンあたりの価格が高いため、プライマリモデルをピン留めしない場合は Opus レートで課金されます。Sonnet 4.5 をプライマリモデルとして使用するには、ANTHROPIC_MODEL をその完全なモデル ID に設定します。ANTHROPIC_DEFAULT_SONNET_MODEL でデフォルトを制御し、ANTHROPIC_DEFAULT_OPUS_MODEL を設定しないデプロイは、制御された Sonnet モデルをデフォルトとして保ちます。

モデルをさらにカスタマイズするには、以下を実行します。

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

設定を確認する

Claude Code を起動して /status を実行し、セットアップを確認します。API provider 行は Google Vertex AI を表示し、GCP project、Default region、および Model 行はプロジェクト ID、リージョン、および解決されたモデルを表示します。プロバイダー行が見つからない場合、環境変数がプロセスに到達していません。claude を起動したシェルでエクスポートされているか、設定ファイルの env ブロックで設定されていることを確認してください。

起動時のモデルチェック

Claude Code が Google Cloud の Agent Platform で設定されて起動すると、使用するモデルがプロジェクトでアクセス可能であることを確認します。

Claude Code デフォルトより古いモデルバージョンをピン留めしていて、プロジェクトが新しいバージョンを呼び出せる場合、Claude Code はピンを更新するよう促します。受け入れると、新しいモデル ID がユーザー設定ファイルに書き込まれ、Claude Code が再起動されます。拒否すると、次のデフォルトバージョン変更まで記憶されます。

モデルをピン留めしていなくて、現在のデフォルトがプロジェクトで利用できない場合、Claude Code は現在のセッション用にフォールバックし、通知を表示します。デフォルトモデルの以前のバージョンを最初に試し、デフォルトが Opus モデルで Opus バージョンが利用できない場合は、デフォルト Sonnet モデルにフォールバックします。フォールバックは永続化されません。Model Gardenで新しいモデルを有効にするか、バージョンをピン留めして選択を永続化してください。

特定の Sonnet または Opus バージョンでセッションを開始する場合（例えば --model、ANTHROPIC_MODEL、またはmodel 設定を使用）、そのバージョンは一致する sonnet または opus エイリアスのセッションのピン留めされたデフォルトとして機能します。Claude Code は、設定したモデルが置き換える組み込みデフォルトの可用性チェックをスキップし、設定したモデルで起動します。フォールバック通知はありません。

opus などのモデルエイリアスはピンとして機能せず、Claude Code が認識しないモデル ID も同様です。

これらのチェックがプロジェクトが呼び出せないモデルを見つけた場合、Claude Code はこのマシン上でその拒否を最大 1 日間記憶し、その間の起動時に記憶されたモデルをスキップして Agent Platform に再度問い合わせません。Claude Code は、現在のデフォルトモデルの記憶された拒否を、最後のチェック以降 10 分が経過した後に起動時に再度チェックするため、管理者が再度有効にしたデフォルトが戻ります。メモリをオフにするには、CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1を設定してください。

組織がモデル許可リストを強制している場合

管理設定で enforceAvailableModels を設定すると、起動時のモデルチェックは availableModels リストで許可されたモデルのみを使用します。これには Claude Code v2.1.287 以降が必要です。enforceAvailableModels のないリストは、これらのチェックを制限しません。

チェックでは各エントリを Agent Platform に送信するモデル ID と比較するため、リストはそれらの ID で記述してください。次の例では Opus 4.8 と Sonnet 4.5 を許可します。

{
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],
  "enforceAvailableModels": true
}

エイリアス、バージョンプレフィックス、modelOverrides エントリについては、サードパーティデプロイ向けにモデルをピン留めするを参照してください。

セッション中にモデルが無効化された場合

プロジェクトがセッションで実行しているモデルへのアクセスを失った場合（例えば、管理者が Model Gardenで無効化した場合）、Claude Code は各リクエストが失敗する代わりにセッションを別のモデルに切り替え、Switched to <fallback> because <model> is not available を表示します。起動時フォールバックと同じモデルを試します。同じティアの以前のバージョンを最初に試し、Opus セッションで Opus バージョンが利用できない場合は、デフォルト Sonnet モデルを試します。

切り替えは、ピン留めしていないティアにのみ適用されます。これは起動時フォールバックと同じ条件です。選択した特定のバージョンでのセッションはそのモデルを保持し、フォールバックモデルチェーンがない場合、リクエストは失敗します。auto モードでは、Claude Code は Agent Platform で auto モードがサポートするモデルにのみ切り替えます。それらのモデルも利用できない場合、リクエストは失敗します。

設定したフォールバックモデルチェーンはティア切り替えを置き換えます。これらの拒否時に Claude Code は設定したフォールバックに切り替えます。拒否されたリクエストが切り替わらずに失敗するようにするには、CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1を設定してください。設定したフォールバックチェーンはこれらの拒否時に切り替わります。すべての拒否されたリクエストが失敗するようにしたい場合は、チェーンも削除してください。

IAM 設定

roles/aiplatform.user ロールを割り当てます。このロールには必要な権限が含まれています。

• aiplatform.endpoints.predict - モデル呼び出しとトークンカウントに必要

より制限的な権限については、上記の権限のみを持つカスタムロールを作成してください。

詳細については、Google Cloud の Agent Platform IAM ドキュメントを参照してください。

[!NOTE]

Claude Code 用に専用の GCP プロジェクトを作成して、コスト追跡とアクセス制御を簡素化してください。

100 万トークンコンテキストウィンドウ

Fable モデル、Sonnet 5 以降、および Opus 4.7 以降は、Google Cloud の Agent Platform でデフォルトで100 万トークンコンテキストウィンドウで実行され、[1m] サフィックスは不要です。代わりに 200K ウィンドウを維持するには、CLAUDE_CODE_DISABLE_1M_CONTEXT=1 を設定します。

Opus 4.6 と Sonnet 4.6 は、[1m] バリアントを選択すると 100 万ウィンドウを使用できます。セットアップウィザードは、モデルをピン留めするときに 100 万トークンコンテキストオプションを提供します。代わりに手動でピン留めしたモデルで有効にするには、モデル ID に [1m] を追加します。ピン留めを変更せずに 100 万ウィンドウを使用する方法を含む詳細については、サードパーティデプロイ用のモデルをピン留めするを参照してください。

v2.1.287 より前は、Fable モデルと Opus 4.7 以降は Google Cloud の Agent Platform でデフォルトで 200K ウィンドウで実行され、[1m] サフィックスによって 100 万ウィンドウを使用していました。

トラブルシューティング

「デフォルト認証情報を読み込めません」エラーが発生した場合：

• gcloud auth application-default login を実行して Application Default Credentials をセットアップしてください
• GOOGLE_APPLICATION_CREDENTIALS をサービスアカウントキーファイルパスに設定してください
• すべてのオプションについては、GCP 認証情報の設定を参照してください

クォータの問題が発生した場合：

• Cloud Consoleを通じて現在のクォータを確認するか、クォータ増加をリクエストしてください

「モデルが見つかりません」404 エラーが発生した場合：

• Model Gardenでモデルが有効になっていることを確認してください
• 指定したロケーションでモデルが利用可能であることを確認してください。一部のモデルは global またはマルチリージョンロケーション（eu および us など）でのみ提供され、特定のリージョンでは提供されていません
• CLOUD_ML_REGION=global を使用している場合、Model Gardenの「サポートされている機能」でモデルがグローバルエンドポイントをサポートしていることを確認してください。グローバルエンドポイントをサポートしていないモデルの場合は、以下のいずれかを実行してください：
  • ANTHROPIC_MODEL または ANTHROPIC_DEFAULT_HAIKU_MODEL を通じてサポートされているモデルを指定するか、
  • 環境変数リファレンスに記載されているモデルの VERTEX_REGION_CLAUDE_* 変数を使用して、リージョンまたはマルチリージョンロケーションを設定してください

429 エラーが発生した場合：

• 地域別エンドポイントの場合、プライマリモデルと小型/高速モデルが選択したリージョンでサポートされていることを確認してください
• より良い可用性のために CLOUD_ML_REGION=global に切り替えることを検討してください

追加リソース

• Google Cloud の Agent Platform ドキュメント
• Google Cloud の Agent Platform 価格
• Google Cloud の Agent Platform クォータと制限