Claude CodeでVertex AIのリージョンを設定する — CLOUD_ML_REGIONの挙動

CLOUD_ML_REGIONで何が変わるか

CLOUD_ML_REGIONは、Claude CodeがGoogle CloudのAgent Platform(旧Vertex AI)へリクエストを送る接続先を決める環境変数です。設定できる値は3種類あります。globalのようなグローバルエンドポイント、euやusのようなマルチリージョン、us-east5のような特定リージョンです。Claude Codeは値の形式を見てaiplatform.eu.rep.googleapis.comやaiplatform.us.rep.googleapis.comのようなホスト名を自動で選び分けるため、開発者がエンドポイントURLを自分で組み立てる必要はありません。

ここでつまずきやすいのが、モデルごとの対応エンドポイントが揃っていない点です。globalエンドポイントに対応していないモデルもあれば、特定リージョンでしか提供されていないモデルもあります。CLOUD_ML_REGION=globalに切り替えた直後、一部のモデルだけ404エラーになるのはこの不一致が原因です。対応状況はGoogle CloudのAgent Platform Model Gardenで確認できます。

Claude CodeをGoogle CloudのAgent Platform経由で使う設定全体(サインインからモデルの許可申請まで)はClaude Code完全ガイドにまとめてあります。本記事はそのうちリージョン設定だけを深掘りします。

設定の前提条件

リージョン設定を試す前に、次の3点を済ませておきます。

• GCPプロジェクトでAgent Platform APIを有効化済み(gcloud services enable aiplatform.googleapis.com)
• Model Gardenで使いたいClaudeモデルへのアクセスを申請済み(承認まで24〜48時間かかることがあります)
• CLAUDE_CODE_USE_VERTEX=1とANTHROPIC_VERTEX_PROJECT_IDを設定済み

初回のセットアップ自体は/setup-vertexウィザードに任せる方法もあります。プロジェクトとリージョンを自動検出し、呼び出せるモデルを確認したうえで設定ファイルに書き込んでくれるため、環境変数を手でexportする必要がありません。手順の詳細は/setup-vertexウィザードの手順を参照してください。本記事は、ウィザードが自動化する部分をCIや社内の一括ロールアウトで環境変数として手動設定したい場合の手順です。

# プロジェクトIDを指定
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
 
# Agent Platform経由の呼び出しを有効化
export CLAUDE_CODE_USE_VERTEX=1
 
# リージョンをglobalエンドポイントに設定
export CLOUD_ML_REGION=global

リージョンをマルチリージョンや特定リージョンに切り替える

CLOUD_ML_REGIONにはglobal以外の値も設定できます。euやusはマルチリージョン、us-east5のような値は特定リージョンです。データレジデンシー要件でリクエストを特定の地理的範囲に留めたい場合や、レイテンシーを優先したい場合は、globalではなくこちらを使います。

# マルチリージョン(EU圏内に処理を留める)
export CLOUD_ML_REGION=eu
 
# 特定リージョン
export CLOUD_ML_REGION=us-east5

3種類のエンドポイントは、可用性・レイテンシー・データの所在という3つの軸でトレードオフが変わります。

globalエンドポイント非対応モデルをVERTEX_REGION_CLAUDE_*で上書きする

CLOUD_ML_REGION=globalを設定したあと、globalエンドポイントに対応していないモデルだけはVERTEX_REGION_CLAUDE_*の環境変数で個別に上書きします。ほとんどのモデルバージョンには対応するVERTEX_REGION_CLAUDE_*変数があり、値にはCLOUD_ML_REGIONと同じくリージョンやマルチリージョンの名前を指定します。

export CLOUD_ML_REGION=global
 
# globalエンドポイント非対応のモデルだけリージョンを上書き
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

変数名はモデルごとに固定されています。たとえばVERTEX_REGION_CLAUDE_5_OPUSはv2.1.219で、VERTEX_REGION_CLAUDE_5_SONNETはv2.1.197で追加されました。新しいモデルが公開されるたびに対応する変数も増えるため、使っているモデルに変数が存在するかは環境変数リファレンスで確認します。どのモデルがglobalエンドポイントに対応しているかは固定ではなく変わっていくため、都度Model Gardenの「Supported features」欄で確認するのが確実です。

値が読み取れないときのフォールバック挙動

設定した値がリージョンやロケーション名の形をしていないと、Claude Codeはその変数を「未設定」として扱います。具体的には、値にスラッシュ・ドット・スペースが含まれていると無効と判定されます。コピー&ペーストでURLの一部やパスを紛れ込ませてしまうミスはこのパターンで起きやすく、意図した上書きが静かに無視されるので気づきにくいのが厄介な点です。

無効あるいは未設定と判定された変数は、次の順にフォールバックします。

• VERTEX_REGION_CLAUDE_*が無効・未設定ならCLOUD_ML_REGIONの値を使う
• CLOUD_ML_REGIONが無効・未設定なら既定値のus-east5を使う

つまりVERTEX_REGION_CLAUDE_*を1つも設定しなければ、すべてのモデルがCLOUD_ML_REGIONの値をそのまま使います。逆にCLOUD_ML_REGIONを設定し忘れると、モデル別の上書きをしていないモデルはすべてus-east5にフォールバックします。複数プロジェクトの設定を使い回すときは、この既定値が意図しないリージョンになっていないか確認しておく価値があります。

リージョン以外に設定するもの — 混同しやすい変数

CLOUD_ML_REGIONはリクエストの送信先リージョンを決めるだけで、エンドポイントのホスト自体を差し替えるものではありません。カスタムエンドポイントやゲートウェイ経由でルーティングしたい場合は、別の変数ANTHROPIC_VERTEX_BASE_URLを使います。両者は役割が異なるので、リージョンを変えたいだけならCLOUD_ML_REGION、接続先のホストごと変えたいならANTHROPIC_VERTEX_BASE_URLと覚えておきます。

IAM権限の設定もリージョンとは別軸です。Google CloudのAgent Platformを呼び出すサービスアカウントやユーザーにはroles/aiplatform.userロールが必要で、これはどのリージョンを使っていても共通の要件です。チーム展開でIAMをどう割り当てるかはClaude Code Vertex AI IAM設定とチーム展開ガイドにまとめています。

モデルのバージョン固定(pin)もリージョンとは独立した設定です。1Mトークンのコンテキストウィンドウを使いたい場合は、モデルIDに[1m]を付けて固定しますが、これはどのリージョンでも同じ手順です。詳しくはClaude Code Bedrock/Vertexで1Mコンテキストを有効化する方法を参照してください。

設定を確認する

環境変数を設定したら、Claude Codeを起動して/statusを実行します。API providerの行にGoogle Vertex AIと表示され、GCP project・Default region・Modelの各行にプロジェクトID・リージョン・解決されたモデルが表示されれば設定は反映されています。API providerの行が表示されない場合は、環境変数がClaude Codeを起動したプロセスに届いていません。シェルでexportし忘れていないか、あるいは設定ファイルのenvブロックに書いたつもりで反映されていないかを確認します。

/status

よくあるつまずき

404「model not found」エラー。Model Gardenでモデルが有効化されているか、指定したロケーションでそのモデルが提供されているかを確認します。一部のモデルはglobalやマルチリージョン(eu・us)でのみ提供され、特定リージョンでは使えません。CLOUD_ML_REGION=globalを使っているなら、そのモデルがglobalエンドポイントに対応しているかをModel Gardenの「Supported features」で確認し、対応していなければANTHROPIC_MODELやANTHROPIC_DEFAULT_HAIKU_MODELで対応モデルを指定するか、VERTEX_REGION_CLAUDE_*でリージョンを個別指定します。

429エラーが頻発する。特定リージョンのエンドポイントを使っている場合、選んだリージョンでプライマリモデルとsmall/fastモデルの両方が提供されているかを確認します。改善しない場合はCLOUD_ML_REGION=globalへの切り替えが可用性の面で有効です。globalエンドポイントはリクエストを複数のロケーションに分散できるため、単一リージョンより空き容量に余裕があります。

「Could not load the default credentials」エラー。これはリージョン設定とは別の認証情報の問題です。gcloud auth application-default loginでApplication Default Credentialsを設定するか、GOOGLE_APPLICATION_CREDENTIALSにサービスアカウントキーのパスを設定します。

まとめ

CLOUD_ML_REGIONはglobal・マルチリージョン(eu/us)・特定リージョン(us-east5など)の3種類から選び、Claude Codeが対応するホスト名を自動で選び分けます。globalエンドポイントに対応していないモデルはVERTEX_REGION_CLAUDE_*で個別にリージョンを上書きし、上書きしなければCLOUD_ML_REGION、それも未設定ならus-east5にフォールバックします。値にスラッシュ・ドット・スペースが混じると無効扱いになり静かに無視される点は、複数人で設定を配布する組織ほど見落としやすいポイントです。設定後は/statusでプロジェクト・リージョン・解決モデルを確認してから展開します。