前提条件

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 側を処理します。

サインイン後、いつでも /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 ホストが含まれます。

手動でセットアップする

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

1. 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

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

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

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

3) GCP 認証情報を設定する

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

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

Claude Code は、同じ Application Default Credentials チェーンを通じて X.509 証明書ベースのワークロード ID フェデレーションをサポートしています。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 セッションが含まれます。

4. 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 にフォールバックします。

prompt cachingは自動的に有効になります。これを無効にするには、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 3.x モデルを含む以前のモデル：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 上のすべてのモデルでツール検索を無効にしていました。

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

これらの環境変数を特定の 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 は、ピン留め変数が設定されていない場合、これらのデフォルトモデルを使用します。

セッションタイトル生成などのバックグラウンドタスクは、小型/高速モデル（通常は 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 に設定します。

v2.1.280 より前は、Google Cloud の Agent Platform 上のプライマリモデルは Opus 5 にデフォルト設定され、opus エイリアスは v2.1.219 から Opus 5 に解決されました。v2.1.207 ～ v2.1.218 では、Google Cloud の Agent Platform 上のプライマリモデルは Opus 4.8 にデフォルト設定され、opus エイリアスは Opus 4.8 に解決されました。v2.1.207 より前は、プライマリモデルは Sonnet 4.5 にデフォルト設定され、opus エイリアスは Opus 4.6 に解決され、バックグラウンドタスクは常にプライマリモデルを使用していました。

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

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

6. 設定を確認する

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 も同様です。

IAM 設定

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

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

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

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

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

Claude Sonnet 5、Opus 4.6 以降、および Sonnet 4.6 は、Google Cloud の Agent Platform で100 万トークンコンテキストウィンドウをサポートしています。Sonnet 5 は常に 100 万ウィンドウで実行され、選択する [1m] バリアントはありません。その他のモデルについては、Claude Code は 100 万トークンモデルバリアントを選択すると、拡張コンテキストウィンドウを自動的に有効にします。

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

トラブルシューティング

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

• 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_<MODEL_NAME> 環境変数を使用してリージョンまたはマルチリージョンロケーションを設定してください

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

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

追加リソース

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