Claude Code を Google Cloud の Agent Platform で動かす

Claude Code は Anthropic の API だけでなく、Google Cloud の Agent Platform（旧 Vertex AI）経由でも動かせます。GCP に課金と権限が集約されている組織では、こちらのほうが導入しやすいことがあります。この記事では公式ドキュメントに基づき、ログインウィザードでの接続、環境変数による手動設定、モデルの固定、IAM とリージョン、つまずきやすい点を順に整理します。

前提条件

設定を始める前に、次が揃っている必要があります。

課金が有効な Google Cloud Platform（GCP）アカウント
Agent Platform API を有効にした GCP プロジェクト
使いたい Claude モデルへのアクセス権（例: Claude Sonnet 4.6）
インストール・設定済みの Google Cloud SDK（gcloud）
使いたい GCP リージョンに割り当てられたクォータ

個人で自分の GCP 資格情報を使って入るだけならログインウィザードで完結します。チームへ配布する場合は、後述の手動設定とモデルの固定まで済ませてから配ってください。

ログインウィザードで接続する

GCP 側の前提を一度満たしておけば、Claude Code 側はウィザードが面倒を見ます。手順は3段階です。

まず GCP プロジェクトで Agent Platform API を有効にし、Model Garden で使いたい Claude モデルへのアクセスを申請します。承認には24〜48時間かかることがあります。

次に claude を起動し、ログインプロンプトで 3rd-party platform を選び、続けて Google Vertex AI を選びます。ログイン画面のラベルは現在も Vertex AI のままです。すでにサインイン済みなら /login で同じメニューを開けます。

最後に認証方法を選びます。gcloud のアプリケーションデフォルト認証情報、サービスアカウントのキーファイル、すでに環境にある資格情報のいずれかです。ウィザードはプロジェクトとリージョンを検出し、そのプロジェクトから呼べる Claude モデルを確認して固定まで行います。結果はユーザー設定ファイルの env ブロックに保存されるので、自分で環境変数を書き出す必要はありません。

設定を変えたくなったら、いつでも /setup-vertex で同じウィザードを開けます。書き込み先は ~/.claude/settings.json、CLAUDE_CONFIG_DIR を設定している場合は $CLAUDE_CONFIG_DIR/settings.json です。

環境変数で手動設定する

CI やスクリプト化された組織展開のように、ウィザードを使えない場面では環境変数で設定します。まず API を有効にします。

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

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

認証は Google Cloud の標準的な仕組みをそのまま使います。X.509 証明書を用いた Workload Identity 連携も、同じアプリケーションデフォルト認証情報の経路でサポートされます。その場合は GOOGLE_APPLICATION_CREDENTIALS に資格情報設定ファイルのパスを指定します。

プロジェクト ID の解決順には注意が必要です。Claude Code は ANTHROPIC_VERTEX_PROJECT_ID をリクエストのプロジェクト ID として使いますが、GCLOUD_PROJECT と GOOGLE_CLOUD_PROJECT、および GOOGLE_APPLICATION_CREDENTIALS が指す資格情報ファイルのほうが優先されます。いずれも無ければ gcloud の設定かアタッチされたサービスアカウントから解決されます。

Claude Code 側の設定は次のとおりです。

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

# 任意: エンドポイント URL を上書きする（独自エンドポイントやゲートウェイ向け）
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 任意: プロンプトキャッシュを無効にする
# export DISABLE_PROMPT_CACHING=1

# CLOUD_ML_REGION=global のとき、global 非対応のモデルだけリージョンを上書きする
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5

CLOUD_ML_REGION には global、eu や us のようなマルチリージョン、us-east5 のような個別リージョンを指定できます。Claude Code はそれぞれに対応するホスト名を自動的に選びます。

プロンプトキャッシュは自動的に有効です。止めたい場合は DISABLE_PROMPT_CACHING=1、既定の5分ではなく1時間の TTL を要求したい場合は ENABLE_PROMPT_CACHING_1H=1 を設定します。1時間 TTL のキャッシュ書き込みは料金が高くなる点に注意してください。なお Agent Platform 利用時は認証を Google Cloud 側が持つため、/logout コマンドは使えません。

設定できたら claude を起動して /status を実行します。API provider の行が Google Vertex AI になり、プロジェクト ID・リージョン・解決されたモデルが表示されれば成功です。プロバイダ行が出ないときは、環境変数がプロセスに届いていません。claude を起動したシェルで export されているか、設定ファイルの env ブロックに入れてあるかを確認します。

モデルを固定する

複数人へ配る場合は、モデルのバージョンを固定してください。固定しないと sonnet や opus といったエイリアスが Claude Code 側の既定値に解決され、その既定値がプロジェクトでまだ有効になっていない可能性があります。

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-opus-5、小型・高速モデルは claude-sonnet-4-5@20250929 が使われます。

ここには費用面の落とし穴があります。Opus はトークン単価が Sonnet より高いため、主モデルを固定していない環境は Opus の料金で課金されます。Sonnet 4.5 を主モデルのまま使いたいなら ANTHROPIC_MODEL にそのフルモデル ID を設定してください。

もう一点、背景処理（セッションタイトルの生成など）のモデル選択も Agent Platform では挙動が変わります。通常は Haiku 系が使われますが、Haiku がすべてのプロジェクト・リージョンで有効とは限らないため、既定の Sonnet モデルが使われます。背景処理に Haiku を使いたい場合は、プロジェクトで利用可能なモデル ID を ANTHROPIC_DEFAULT_HAIKU_MODEL に設定します。

起動時にはモデルの到達性が確認されます。固定したバージョンが既定より古く、かつ新しい版が呼べる場合は更新を促されます。固定していない状態で既定が使えない場合は、その回だけ古い版へフォールバックし、通知が出ます（このフォールバックは保存されません）。恒久的に決めたいなら Model Garden で有効化するか、バージョンを固定します。

IAM とリージョン

必要な IAM 権限は roles/aiplatform.user ロールに含まれます。実際に要るのは次の1つです。

aiplatform.endpoints.predict — モデルの呼び出しとトークン数の計測に必要

より絞りたい場合は、この権限だけを持つカスタムロールを作ります。コストの追跡とアクセス制御を単純にするため、Claude Code 専用の GCP プロジェクトを作ることが公式に推奨されています。

リージョンについては、モデルの提供状況が個別リージョン・マルチリージョン・global エンドポイントで異なります。既定のモデルがどのエンドポイント種別でも使えるとは限らないので、Model Garden の「Supported features」で対応状況を確認してください。

1M トークンのコンテキストウィンドウは Claude Sonnet 5、Opus 4.6 以降、Sonnet 4.6 が Agent Platform 上で対応します。Sonnet 5 は常に 1M で動作し、[1m] の指定は不要です。それ以外のモデルでは、手動で固定する場合にモデル ID の末尾へ [1m] を付けます。

トラブルシューティング

公式ドキュメントに挙がっている典型的な失敗と対処です。

「Could not load the default credentials」 — gcloud auth application-default login でアプリケーションデフォルト認証情報を設定するか、GOOGLE_APPLICATION_CREDENTIALS にサービスアカウントのキーファイルのパスを設定します。

「model not found」で 404 — Model Garden でそのモデルが有効になっているかを確認します。さらに、指定した場所で提供されているかも確認が必要です。global や eu / us のマルチリージョンでのみ提供され、個別リージョンには無いモデルがあります。CLOUD_ML_REGION=global を使っているなら、対応モデルへ切り替えるか VERTEX_REGION_<MODEL_NAME> でそのモデルだけリージョンを指定します。

429 エラー — 個別リージョンのエンドポイントを使っている場合、主モデルと小型・高速モデルの両方がそのリージョンで提供されているかを確認します。可用性を優先するなら CLOUD_ML_REGION=global への切り替えも選択肢です。

クォータ不足 — Cloud Console から現在のクォータを確認し、必要なら引き上げを申請します。

資格情報の期限切れが頻繁に起きる環境では、設定ファイルの gcpAuthRefresh に更新コマンドを書いておくと、期限切れを検出したときに自動で実行されます。ブラウザで完結する認証フローと相性が良い仕組みで、3分でタイムアウトします。

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

本記事は Claude Code 公式ドキュメント「Claude Code on Google Cloud's Agent Platform」を元にした非公式の日本語解説です。最新の仕様は公式ドキュメントを確認してください。