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になるのは、この不一致が典型です。

サインインからモデルの許可申請までの全体像は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を設定済み

初回のセットアップは、ログイン画面で「3rd-party platform」から「Google Vertex AI」を選ぶと開くウィザードでも済ませられます。サインイン後は/setup-vertexでいつでも開き直せます。ウィザードはプロジェクトとリージョンを尋ね、呼び出せるClaudeモデルを確認してユーザー設定ファイルのenvブロックに保存するため、環境変数を手で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

3種類の値をどう選ぶか

CLOUD_ML_REGIONにはglobal以外の値も設定できます。euやusはマルチリージョン、us-east5のような値は特定リージョンです。

# マルチリージョン
export CLOUD_ML_REGION=eu
 
# 特定リージョン
export CLOUD_ML_REGION=us-east5

選び方の軸は、モデルの可用性・処理場所の指定・提供モデルの違いです。

429の回避先としてglobalを挙げているのはClaude Codeの公式の案内で、可用性が上がる理由までは書かれていません。単一リージョンでも提供されないモデルがあるという点は、次の404の節で扱います。

モデルごとに上書きするVERTEX_REGION_CLAUDE_*

CLOUD_ML_REGION=globalを設定したうえで、globalに対応しないモデルだけ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

変数名で戸惑うのは、並び順が統一されていない点です。環境変数リファレンスの一覧では、HAIKU_4_5のように名前が先に来るものと、4_6_SONNETや5_5_OPUSのように版が先に来るものが混在しています。思い込みで組み立てず、一覧と突き合わせます。

「記載なし」は、リファレンスの該当行に追加バージョンの注記が無いという意味です。新しいモデルが出ると対応する変数も増えるので、使うモデルの変数が存在するかは環境変数リファレンスで確かめます。どのモデルがglobalに対応するかは変わっていくため、Model Gardenの「Supported features」欄が確実です。

実際にどのリージョンが使われるか

値がリージョン名やロケーション名の形をしていないと、その変数は「未設定」として扱われます。たとえばスラッシュ・ドット・スペースを含む値がそうです。URLの一部やパスを貼り間違えると起きやすく、上書きが黙って無視されるので気づきにくい失敗です。

リージョンは、モデルごとに次の順で決まります。

この順序から、組み合わせごとの結果を導けます。次の表は上の優先順位を当てはめた読み方で、実際に接続して確かめた結果ではありません。

最後の2行が、複数プロジェクトの設定を使い回すときの落とし穴です。意図したリージョンでなくても、エラーにならずにus-east5へ向かいます。

404が出たときの切り分け

特定のモデルだけ404になるときは、次の順に確認します。

リージョンとは別に決まる設定

リージョンだけ見ていても解決しない問題があります。混同しやすい設定を分けておきます。

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

1Mトークンのコンテキストウィンドウも別の設定です。Agent Platformで対応するのはSonnet 5・Opus 4.6以降・Sonnet 4.6です。Sonnet 5は常に1Mで動き、[1m]を付ける対象ではありません。Opus 4.6以降とSonnet 4.6は、モデルIDに[1m]を付けると1Mが有効になります。手順はClaude Code Bedrock/Vertexで1Mコンテキストを有効化する方法にあります。

モデルを固定していないときの既定値とバックグラウンドタスク

リージョンを設定しても、どのモデルが呼ばれるかは別の設定で決まります。環境変数でモデルを固定していないとき、Agent Platform上の既定は次のとおりです。

セッションタイトルの生成のようなバックグラウンドタスクは、通常はHaiku系のsmall/fastモデルが担います。Agent Platformでは、プロジェクトやリージョンによってHaikuが有効でないことがあるため、既定のSonnetを使います。Haikuに戻したいときは、ANTHROPIC_DEFAULT_HAIKU_MODELに自分のプロジェクトで使えるモデルIDを入れます。

--model、ANTHROPIC_MODEL、model設定のいずれかでメインのモデルを選んだときは、バックグラウンドタスクもそのモデルを使います。

バックグラウンドタスクが使うモデルも、メインのモデルと同じく提供場所の制約を受けます。公式のトラブルシューティングは、特定リージョンを使うときにメインとsmall/fastの両方の提供状況を確認するよう案内しています。

起動時には、使おうとするモデルがプロジェクトで呼び出せるかも確認されます。モデルを固定しておらず既定が使えないとき、Claude Codeはそのセッションだけ古い版などに切り替え、通知を出します。切り替えは保存されません。呼び出せないと判明したモデルは、この端末に最長1日記憶されます。

Model Gardenで有効化した直後に反映されないときは、CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1で記憶を切れます(v2.1.285以降)。現行の既定モデルについての拒否の記憶は、前回の確認から10分たった次の起動で再確認されます。

設定を確認する

環境変数を設定したらClaude Codeを起動し、/statusを実行します。

/status

API providerの行がGoogle Vertex AIになっていれば、プロバイダーの切り替えは効いています。あわせてGCP project・Default region・Modelの各行に、プロジェクトID・リージョン・解決されたモデルが出ているかを見ます。API providerの行が出ないときは、環境変数がClaude Codeを起動したプロセスに届いていません。exportし忘れていないか、設定ファイルのenvブロックに書いたつもりで書けていないかを確認します。

よくあるつまずき

429エラーが頻発する。特定リージョンを使っているなら、メインとsmall/fastの両方がそのリージョンで提供されているかを確認します。それでも改善しないときは、CLOUD_ML_REGION=globalへの切り替えが公式の案内です。レート上限そのものを引き上げたいときは、Google Cloudのサポートに問い合わせます。

「Could not load the default credentials」エラー。これはリージョンとは別の認証の問題です。対処は2通りです。1つはgcloud auth application-default loginでApplication Default Credentialsを設定する方法です。もう1つは、GOOGLE_APPLICATION_CREDENTIALSにサービスアカウントキーのパスを入れる方法です。

モデル別の上書きが効かない。変数名の並び順の違いと、値の形(スラッシュ・ドット・スペースを含むなど、リージョン名らしくない値)を疑います。無効な値はCLOUD_ML_REGIONに落ちるだけで、エラーにはなりません。

まとめ

リージョン周りの不具合の多くは、モデルの提供場所と、黙って別の値に落ちるフォールバックの組み合わせで起きます。複数人に設定を配る場合は、/statusでDefault regionを確かめてから展開すると、us-east5への意図しない落ち込みに早く気づけます。