​
先決條件

在使用 Vertex AI 配置 Claude Code 之前，請確保您具備：

  • 已啟用計費的 Google Cloud Platform (GCP) 帳戶
  • 已啟用 Vertex AI API 的 GCP 專案
  • 對所需 Claude 模型的存取權限（例如 Claude Sonnet 4）
  • 已安裝並配置的 Google Cloud SDK (gcloud)
  • 在所需 GCP 區域中分配的配額

​
區域配置

Claude Code 可以與 Vertex AI 全域和區域端點一起使用。

Vertex AI 可能不支援所有區域的 Claude Code 預設模型。您可能需要切換到支援的區域或模型。

Vertex AI 可能不支援全域端點上的 Claude Code 預設模型。您可能需要切換到區域端點或支援的模型。

​
設定

​
1. 啟用 Vertex AI API

在您的 GCP 專案中啟用 Vertex AI API：

# 設定您的專案 ID
gcloud config set project YOUR-PROJECT-ID

# 啟用 Vertex AI API
gcloud services enable aiplatform.googleapis.com

​
2. 請求模型存取權限

在 Vertex AI 中請求 Claude 模型的存取權限：

  1. 導航至 Vertex AI Model Garden
  2. 搜尋「Claude」模型
  3. 請求對所需 Claude 模型的存取權限（例如 Claude Sonnet 4）
  4. 等待核准（可能需要 24-48 小時）

​
3. 配置 GCP 憑證

Claude Code 使用標準的 Google Cloud 身份驗證。

如需更多資訊，請參閱 Google Cloud 身份驗證文件。

進行身份驗證時，Claude Code 將自動使用來自 ANTHROPIC_VERTEX_PROJECT_ID 環境變數的專案 ID。要覆蓋此設定，請設定以下環境變數之一：GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT 或 GOOGLE_APPLICATION_CREDENTIALS。

​
4. 配置 Claude Code

設定以下環境變數：

# 啟用 Vertex AI 整合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可選：如有需要，停用提示快取
export DISABLE_PROMPT_CACHING=1

# 當 CLOUD_ML_REGION=global 時，為不支援的模型覆蓋區域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# 可選：為其他特定模型覆蓋區域
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1

當您指定 cache_control 臨時標誌時，會自動支援提示快取。要停用它，請設定 DISABLE_PROMPT_CACHING=1。如需提高速率限制，請聯絡 Google Cloud 支援。

使用 Vertex AI 時，/login 和 /logout 命令會被停用，因為身份驗證是透過 Google Cloud 憑證處理的。

​
5. 模型配置

Claude Code 為 Vertex AI 使用以下預設模型：

模型類型預設值
主要模型claude-sonnet-4@20250514
小型/快速模型claude-3-5-haiku@20241022

要自訂模型：

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
IAM 配置

分配所需的 IAM 權限：

roles/aiplatform.user 角色包含所需的權限：

  • aiplatform.endpoints.predict - 模型調用所需
  • aiplatform.endpoints.computeTokens - 代幣計數所需

對於更嚴格的權限，請建立僅包含上述權限的自訂角色。

如需詳細資訊，請參閱 Vertex IAM 文件。

我們建議為 Claude Code 建立專用的 GCP 專案，以簡化成本追蹤和存取控制。

​
1M 代幣上下文視窗

Claude Sonnet 4 在 Vertex AI 上支援 1M 代幣上下文視窗。

1M 代幣上下文視窗目前處於測試階段。要使用擴展的上下文視窗，請在您的 Vertex AI 請求中包含 context-1m-2025-08-07 測試標頭。

​
故障排除

如果您遇到配額問題：

如果您遇到「找不到模型」404 錯誤：

  • 確認模型在 Model Garden 中已啟用
  • 驗證您有權存取指定的區域
  • 如果使用 CLOUD_ML_REGION=global，請在 Model Garden 的「支援功能」下檢查您的模型是否支援全域端點。對於不支援全域端點的模型，請執行以下任一操作：
    • 透過 ANTHROPIC_MODEL 或 ANTHROPIC_SMALL_FAST_MODEL 指定支援的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 環境變數設定區域端點

如果您遇到 429 錯誤：

  • 對於區域端點，請確保主要模型和小型/快速模型在您選擇的區域中受支援
  • 考慮切換到 CLOUD_ML_REGION=global 以獲得更好的可用性

​
其他資源