Google で Claude Code を使う方法｜Vertex AI 設定とモデルピン

Google で Claude Code を使う 2 経路の整理

Google で Claude Code を使う方法は、用途別に大きく 2 経路に分かれます。第一に個人開発者が claude.ai と同じ Google アカウントで OAuth ログインし、Pro または Max プランのサブスクリプション枠で Claude Code CLI を動かす経路、第二に企業や Google Cloud ユーザーが Vertex AI Model Garden 経由で CLI を起動し、GCP の課金と IAM に統合する経路です。前者は claude を実行して「Anthropic Console」を選ぶだけで完結し、後者は CLAUDE_CODE_USE_VERTEX=1 を有効にしたうえで Vertex AI へリクエストをルーティングします。

本記事は Vertex AI 経由のセットアップを主軸に解説します。Anthropic 直契約と比べたメリットは、(1) Google Cloud の請求アカウントに一本化できる、(2) roles/aiplatform.user で IAM 管理ができる、(3) VPC Service Controls で境界保護が効く、(4) Cloud Logging に監査ログが残る、(5) 既存の Google Cloud SSO とコンプライアンス統制をそのまま適用できる、の 5 点です出典。一方、最新モデルは Anthropic 直 API が先行公開されるケースが多く、Vertex AI 上で有効化されるまで数日のラグが出る場合がある点には注意します。

なお、個人 Pro/Max ログインの「Google アカウント認証」と、Vertex AI 経由の「Google Cloud 認証」は別物です。前者は claude.ai の OAuth、後者は Application Default Credentials(gcloud auth)で、認証情報の保存先も課金経路も異なります。会社の Workspace アカウントで claude.ai にログインしても、自動的に Vertex AI 経由になるわけではないので、業務利用なら明示的に Vertex AI を選択する必要があります。

Vertex AI で Claude Code を使う前提条件

Vertex AI セットアップに着手する前に、以下の 5 点を満たしているか確認します。請求設定とクォータ確保はとくに見落としやすく、後から「モデルが見つかりません 404」エラーの原因になります。

1. 請求が有効化された Google Cloud Platform アカウントを保有していること。
2. 利用予定の GCP プロジェクトで Vertex AI API(aiplatform.googleapis.com)が有効化済みであること。
3. Vertex AI Model Garden で目的の Claude モデル(例: Claude Sonnet 4.6、Opus 4.7)へのアクセスがリクエスト済みかつ承認済みであること。
4. ローカル開発環境に Google Cloud SDK(gcloud CLI)がインストールされ、gcloud auth application-default login が完了していること。
5. 目的の GCP リージョン(例: us-east5、europe-west1、または global エンドポイント)に Claude モデル用のクォータが割り当てられていること。

加えて、Claude Code 本体は v2.1.98 以降を推奨します。claude --version で確認し、古ければ npm i -g @anthropic-ai/claude-code または公式インストーラで最新化します。v2.1.98 未満では後述の /setup-vertex ウィザードと起動時モデルチェックが利用できず、環境変数の手動設定だけで対応する必要が出てきます出典。

モデルアクセスのリクエストは Model Garden の Claude 詳細ページから「リクエスト」ボタンで送信できます。Anthropic 側のレビューに 24〜48 時間かかるケースがあるため、検証スケジュールに合わせて早めに申請しておきます。

/setup-vertex ウィザードでサインインする 3 ステップ

Claude Code v2.1.98 以降には、Vertex AI 接続の初期設定を対話的に進める /setup-vertex ウィザードが同梱されています。gcloud の Application Default Credentials を読み取ってプロジェクトとリージョンを自動検出し、利用可能な Claude モデルを一覧表示してピン留めまで完了します。所要時間は GCP 側の前提が整っていれば 3〜5 分です。

1. GCP プロジェクトで Vertex AI API を有効化し、Model Garden で目的の Claude モデルへのアクセスをリクエストする。承認後にプロジェクトから該当モデルが呼び出せる状態にしておく。
2. ターミナルで claude を実行し、初回ログインプロンプトで 3rd-party platform を選び、続けて Google Vertex AI を選択する。すでにログイン済みの場合は /setup-vertex を直接実行する。
3. ウィザードの案内に従い、gcloud の Application Default Credentials、サービスアカウントキーファイル、または環境変数のいずれで認証するかを選ぶ。プロジェクト ID とリージョンが自動検出され、呼び出し可能なモデル一覧から使うものをピン留めする。

ウィザードの結果はユーザー設定ファイル(~/.claude/settings.json 等)の env ブロックに書き込まれるため、CLAUDE_CODE_USE_VERTEX や CLOUD_ML_REGION を手動で export する必要はありません。サインイン後にプロジェクトやリージョンを変更したくなったら、いつでも /setup-vertex を再実行して上書きできます出典。

なお、CI 環境やコンテナのように対話入力ができない場面では、次節の手動セットアップで環境変数を明示的に設定する経路を選びます。エンタープライズロールアウトでは「ウィザードは個別開発者向け」「CI/イメージは手動セットアップ」と使い分けるのが定石です。

手動セットアップ｜環境変数 4 種類の設定

CI パイプラインや Docker イメージなど、ウィザードを起動できない環境では、4 種類の環境変数で Vertex AI を有効化します。エクスポートする値は以下のとおりです。

# Vertex AI 経由を有効化
export CLAUDE_CODE_USE_VERTEX=1

# リージョン: global / us / eu / 特定リージョン(us-east5 等)
export CLOUD_ML_REGION=global

# プロジェクト ID(GCLOUD_PROJECT より優先される)
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# サービスアカウント認証を使う場合のみ
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

CLOUD_ML_REGION には グローバルエンドポイント(global)、マルチリージョン(us または eu)、特定リージョン(us-east5 等) の 3 形式が指定できます。Claude Code は値の形式から自動でホスト名を選び、マルチリージョンの場合は aiplatform.eu.rep.googleapis.com または aiplatform.us.rep.googleapis.com にリクエストを送ります。可用性は global がもっとも安定するため、最初の選択肢として推奨されます出典。

プロジェクト ID の解決は (1) ANTHROPIC_VERTEX_PROJECT_ID、(2) GCLOUD_PROJECT / GOOGLE_CLOUD_PROJECT、(3) GOOGLE_APPLICATION_CREDENTIALS の認証情報ファイル、(4) gcloud 設定、(5) アタッチされたサービスアカウント の優先順で行われます。複数プロジェクトを切り替える運用では、ANTHROPIC_VERTEX_PROJECT_ID を明示してミスを防ぎます。

プロンプトキャッシュは Vertex AI でもデフォルトで有効です。無効化したい場合は DISABLE_PROMPT_CACHING=1、デフォルトの 5 分 TTL を 1 時間に延長したい場合は ENABLE_PROMPT_CACHING_1H=1 を設定します。1 時間 TTL は書き込みコストが高めの料金体系になるため、長時間の対話継続が必要なエージェントタスクだけに絞るのが現実的です。

モデルピン留めとリージョン選択の実務

複数ユーザーへロールアウトする際は、モデルバージョンのピン留めが必須になります。ピンを設定しないと sonnet や opus エイリアスは「Anthropic が公開している最新版」に解決されますが、その新モデルが Vertex AI プロジェクト側で有効化されていないとリクエストが失敗します。ピン留めしておけば、新モデル投入のタイミングを管理者側で制御できます。

代表的なピン留め環境変数は以下のとおりです。

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

ピンを設定しない場合のデフォルトは claude-sonnet-4-5@20250929 で、小型・高速モデルもプライマリと同じ値にフォールバックします。Vertex AI では Haiku がプロジェクトやリージョンで未有効化のことがあるため、セッションタイトル生成などのバックグラウンドタスクが Sonnet で動いてしまい、想定外のコストが発生するケースがあります。明示的に ANTHROPIC_DEFAULT_HAIKU_MODEL を設定して Haiku を有効化したリージョンを指定するのが安全です出典。

CLOUD_ML_REGION=global で運用していても、グローバルエンドポイント未対応のモデルが混じる場合があります。その場合はモデル別の VERTEX_REGION_CLAUDE_* 変数でリージョンをオーバーライドします。

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

起動時には Claude Code が「ピンしたモデルがプロジェクトで呼び出せるか」を自動チェックします。新バージョンが Model Garden で利用可能になっているとアップデートを促すプロンプトが出て、承諾すると設定ファイルに新 ID が書き込まれます。アップデートタイミングを管理者だけが握りたい場合は、設定ファイルをチームで共有して個別承諾を抑止する運用がよく取られます。

IAM 権限と専用 GCP プロジェクトの推奨構成

Claude Code を Vertex AI で動かすために必要な IAM 権限は、最小要件として aiplatform.endpoints.predict のみです。これはモデル呼び出しとトークンカウントの両方に使われます。組み込み済みのロールでは roles/aiplatform.user がこれを包含しているため、開発者個人にはこのロールを付与するのがもっとも簡潔です。

より制限を強めたい場合は、aiplatform.endpoints.predict だけを含むカスタムロールを作成し、Claude Code 用サービスアカウントに割り当てます。VPC Service Controls の境界に Vertex AI API を含めれば、本社ネットワーク外からの呼び出しを遮断する構成も組めます出典。

加えて、Anthropic 公式は Claude Code 用の専用 GCP プロジェクトを切り出すことを推奨しています。理由は (1) コスト追跡が単一の請求行に分離できること、(2) アクセス制御が他のワークロードと干渉しないこと、(3) クォータ枯渇時の影響範囲を限定できることの 3 点です。プロジェクト名は claude-code-prod のような明示的なものにし、ラベルでチーム名・コストセンターを付けておくと、月次の請求分析が一気に楽になります。

100 万トークンコンテキストの有効化と注意点

Claude Opus 4.7、Opus 4.6、Sonnet 4.6 は Vertex AI でも 100 万トークンコンテキストウィンドウをサポートしています。Claude Code は 1M バリアントを選択すると拡張コンテキストを自動有効化するため、CLI 側で追加設定は不要です。/setup-vertex ウィザードはモデルをピン留めする際に 1M オプションを提示してくれます。

手動でピン留めする場合は、モデル ID に [1m] サフィックスを付けます。例えば claude-opus-4-7[1m] を ANTHROPIC_DEFAULT_OPUS_MODEL に設定すると、そのモデルだけ 1M コンテキストで動作します。1M モードは入出力トークン単価が標準の 200K モードより高い料金階層になるため、巨大コードベースの一括把握や長時間セッションのように、明確にコンテキスト量が必要なタスクだけで有効化するのが原則です。

実機目線でいうと、Claude Code の /compact や /clear を上手く使えば 200K コンテキストでも十分回せるユースケースは多く、1M を「常時 ON」にする必要はほとんどありません。月次コストを見ながら、特定リポジトリやエージェントワークフローだけ 1M に切り替えるピン留め運用が現実解です。

よくあるエラーとトラブルシュート

Vertex AI 経由の Claude Code で頻発するエラーは、以下の 4 パターンに集約されます。原因と対処をセットで覚えておくと、初回セットアップで詰まる時間を大幅に削減できます。

1. 「Could not load default credentials」エラー: Application Default Credentials が未設定の状態。gcloud auth application-default login を実行するか、GOOGLE_APPLICATION_CREDENTIALS をサービスアカウントキーファイルのパスに設定する。
2. モデルが見つかりません 404 エラー: Model Garden でモデルが有効化されていない、もしくは指定リージョンで未提供。Model Garden で「サポートされている機能」を確認し、global エンドポイント非対応のモデルは VERTEX_REGION_CLAUDE_* で個別リージョンを指定する。
3. 429 Too Many Requests エラー: リージョン別エンドポイントでクォータ不足。CLOUD_ML_REGION=global に切り替えるか、Cloud Console でクォータ増加をリクエストする。プライマリと Haiku モデルの両方がそのリージョンでサポートされているかも確認する。
4. クォータ不足 / 「Resource Exhausted」エラー: プロジェクトの Vertex AI クォータが枯渇。Cloud Console の Quotas ページで online_prediction_requests_per_base_model などの該当クォータを確認し、増加申請を出す出典。

加えて、Claude Code v2.1.121 以降は X.509 証明書ベースのワークロード ID フェデレーションにも対応しています。社内 PKI で発行した証明書を使った認証情報設定ファイルを GOOGLE_APPLICATION_CREDENTIALS に指定すると、サービスアカウントキーを配布せずに済むため、よりセキュアな構成が組めます。

トラブル発生時は、まず claude --version でクライアント側のバージョンを確認し、続いて gcloud config list と gcloud auth list で認証コンテキストを点検する流れが鉄板です。原因の 8 割は「期待していないプロジェクト・アカウントで動いている」もしくは「Model Garden でアクセス未承認」のどちらかに集中しています出典。

Anthropic 直 API・AWS Bedrock との使い分け

Claude Code は Vertex AI 経由のほかに、Anthropic 直 API と AWS Bedrock 経由でも動作します。三者の使い分けは、課金経路と既存クラウド統合で判断するのが実務的です。

Anthropic 直 API は 新モデルの先行公開・最速アクセスが強みで、Pro/Max プランや Anthropic Console の請求に紐づきます。Vertex AI 経由は GCP との一体運用(IAM・VPC SC・Cloud Logging・Workspace SSO)が強みで、社内ガバナンスを Google Cloud に寄せている組織に向きます。AWS Bedrock 経由は同様に AWS との一体運用が利点で、IAM・KMS・CloudTrail で統制する組織に最適です。CLAUDE_CODE_USE_BEDROCK=1 を有効化する点だけが Vertex AI と異なります。

価格はどの経路でもベースのトークン単価はほぼ同等ですが、Vertex AI と Bedrock では各クラウドの請求書に統合されるため、年間契約や Reserved 利用枠との組み合わせが可能になります。複数経路を併用する場合は、設定ファイルや環境変数で経路を明示的に切り替える運用にし、誤って Anthropic 直 API に request が流れて二重課金になる事故を防ぎます。

最後に、Google が Anthropic に累計約 25 億ドル出資し、独自 AI チップ TPU を最大 100 万基提供する多年契約を結んでいることも踏まえると、Vertex AI 上の Claude 提供は今後も拡充されていく見込みです出典。GCP に主軸を置く組織にとって、Claude Code を Vertex AI 経由で標準化する選択は、長期的なベンダーロックインリスクを抑えながら最新モデルにアクセスできる、もっとも合理的なルートと言えます。