先決條件

在使用 Google Cloud 的 Agent Platform（前身為 Vertex AI）設定 Claude Code 之前，請確保您具有：

• 已啟用計費的 Google Cloud Platform (GCP) 帳戶
• 已啟用 Google Cloud 的 Agent Platform API 的 GCP 專案
• 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
• 已安裝並設定 Google Cloud SDK (gcloud)
• 在所需的 GCP 區域中分配的配額

若要使用您自己的 Google Cloud 的 Agent Platform 認證登入，請遵循下方的使用 Google Cloud 的 Agent Platform 登入。若要在整個團隊中部署 Claude Code，請使用手動設定步驟並在推出前固定您的模型版本。

使用 Agent Platform 登入

如果您有 Google Cloud 認證並想開始透過 Google Cloud 的 Agent Platform 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。

登入後，您可以隨時執行 /setup-vertex 以重新開啟精靈並變更您的認證、專案、區域或模型固定。模型固定步驟會從您目前固定的模型開始。精靈會寫入 ~/.claude/settings.json，或在設定 CLAUDE_CONFIG_DIR 時寫入 $CLAUDE_CONFIG_DIR/settings.json。

區域設定

Claude Code 支援 Google Cloud 的 Agent Platform 全球、多區域和區域端點。將 CLOUD_ML_REGION 設定為 global、多區域位置（例如 eu 或 us）或特定區域（例如 us-east5）。Claude Code 為每種形式選擇正確的 Google Cloud 的 Agent Platform 主機名稱，包括多區域位置的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com 主機。

手動設定

若要透過環境變數而非精靈來設定 Google Cloud 的 Agent Platform，例如在 CI 或指令碼化企業推出中，請遵循下列步驟。

1. 啟用 Agent Platform API

在您的 GCP 專案中啟用 Google Cloud 的 Agent Platform API。將 YOUR-PROJECT-ID 替換為您的 GCP 專案 ID，並在下方的設定步驟中使用：

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

# 啟用 Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. 要求模型存取權

要求在 Google Cloud 的 Agent Platform 中存取 Claude 模型：

1. 前往 Google Cloud 的 Agent Platform Model Garden
2. 搜尋「Claude」模型
3. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
4. 等待核准（可能需要 24-48 小時）

3) 設定 GCP 認證

Claude Code 使用標準 Google Cloud 驗證。

如需詳細資訊，請參閱 Google Cloud 驗證文件。

Claude Code 透過相同的 Application Default Credentials 鏈支援 X.509 憑證型 Workload Identity Federation。將 GOOGLE_APPLICATION_CREDENTIALS 設定為您的認證設定檔路徑。

進階認證設定

Claude Code 透過 gcpAuthRefresh 設定支援 GCP 的自動認證重新整理。將其新增至您的 Claude Code 設定檔，例如 ~/.claude/settings.json。當 Claude Code 偵測到您的 GCP 認證已過期或無法載入時，它會執行已設定的命令以在重試要求前取得新認證。

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

在執行命令前，Claude Code 會使用您目前的認證要求存取權杖，以確認認證確實已過期，並在認證仍然有效時略過命令。

如果檢查未在五秒內完成，Claude Code 也會略過命令，並僅在要求因認證錯誤而失敗後才執行。在 v2.1.261 之前，逾時的檢查會被視為過期的認證，因此即使您的認證仍然有效，命令也可能在啟動時開啟您的瀏覽器。

Claude Code 會向您顯示命令的輸出，但無法傳送命令互動式輸入。這適用於 CLI 顯示 URL 且您在瀏覽器中完成驗證的瀏覽器型驗證流程。如果驗證未完成，重新整理命令會在三分鐘後逾時。如果您在專案設定（例如 .claude/settings.json）中設定 gcpAuthRefresh，Claude Code 會在與設定檔中 hooks 相同的工作區信任規則下執行，其中包括您從未信任的資料夾中的 -p 工作階段。

4. 設定 Claude Code

設定下列環境變數：

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

# 選用：覆寫 Agent Platform 端點 URL 以用於自訂端點或閘道
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 當 CLOUD_ML_REGION=global 時，覆寫不支援全域端點的模型的區域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

大多數模型版本都有對應的 VERTEX_REGION_CLAUDE_* 變數。請參閱環境變數參考以取得完整清單。檢查 Google Cloud 的 Agent Platform Model Garden 以判斷哪些模型支援全域端點與僅限區域端點。

如果區域值的格式不像區域或位置名稱，Claude Code 會將其視為未設定。例如，Claude Code 會將包含斜線、點或空格的值視為未設定。Claude Code 會針對每個變數回退到不同的來源：

• VERTEX_REGION_CLAUDE_*：Claude Code 回退到 CLOUD_ML_REGION。
• CLOUD_ML_REGION：Claude Code 回退到 us-east5。

Prompt caching 會自動啟用。若要停用，請設定 DISABLE_PROMPT_CACHING=1。若要要求 1 小時快取 TTL 而非 5 分鐘預設值，請設定 ENABLE_PROMPT_CACHING_1H=1；具有 1 小時 TTL 的快取寫入會以更高的費率計費。若要為您的主要對話和 Claude Code 在其外部進行的要求設定不同的 TTL，請自行選擇 TTL。

若要提高您的速率限制，請聯絡 Google Cloud 支援。使用 Google Cloud 的 Agent Platform 時，/logout 命令無法使用，因為驗證是透過 Google Cloud 認證處理。

Claude Code 根據模型世代在 MCP 工具搜尋和預先載入之間決定：

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新版本：Claude Code 預設啟用工具搜尋。
• 較早的模型，包括所有 Claude 3.x 模型：Claude Code 預先載入 MCP 工具定義，因為其 Agent Platform 服務堆疊拒絕所需的 beta 標頭。設定 ENABLE_TOOL_SEARCH=true 不會覆寫此設定。

設定 ENABLE_TOOL_SEARCH=false 以在每個模型上停用工具搜尋。在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上停用所有模型的工具搜尋，除非您設定 ENABLE_TOOL_SEARCH=true。

5. 釘選模型版本

將這些環境變數設定為特定 Google Cloud 的 Agent Platform 模型 ID。

不使用 ANTHROPIC_DEFAULT_OPUS_MODEL 的情況下，Google Cloud 的 Agent Platform 上的 opus 別名會解析為 Opus 5.5，不使用 ANTHROPIC_DEFAULT_SONNET_MODEL 的情況下，sonnet 別名會解析為 Sonnet 4.5。此範例將每個別名釘選到特定版本：

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'

如需目前和舊版模型 ID，請參閱模型概觀。請參閱模型設定以取得完整的環境變數清單。

未設定釘選變數時，Claude Code 會使用這些預設模型：

背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Google Cloud 的 Agent Platform 上，Claude Code 針對背景工作使用預設 Sonnet 模型，因為 Haiku 可能未在每個專案或區域中啟用。兩個選項會變更哪個模型執行它們：

• 當您使用 --model、ANTHROPIC_MODEL 或 model 設定選擇主要模型時，背景工作會使用該模型。當 Claude Code 在您使用 ANTHROPIC_DEFAULT_MODEL 設定的模型上啟動工作階段時，背景工作也會使用該模型。設定 ANTHROPIC_DEFAULT_OPUS_MODEL 而不設定 ANTHROPIC_DEFAULT_SONNET_MODEL 也會計為選擇，因為內建 Sonnet 模型可能未在引導其自身 Opus 的專案中啟用。
• 若要針對背景工作使用 Haiku，請將 ANTHROPIC_DEFAULT_HAIKU_MODEL 設定為您的專案中可用的模型 ID。

在 v2.1.280 之前，Google Cloud 的 Agent Platform 上的主要模型預設為 Opus 5，opus 別名從 v2.1.219 解析為 Opus 5。在 v2.1.207 至 v2.1.218 上，Google Cloud 的 Agent Platform 上的主要模型預設為 Opus 4.8，opus 別名解析為 Opus 4.8。在 v2.1.207 之前，主要模型預設為 Sonnet 4.5，opus 別名解析為 Opus 4.6，背景工作一律使用主要模型。

若要進一步自訂模型：

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

6. 驗證您的設定

啟動 Claude Code 並執行 /status 以確認設定。API provider 行顯示 Google Vertex AI，GCP project、Default region 和 Model 行顯示您的專案 ID、區域和已解析的模型。如果提供者行遺失，環境變數未到達程序。確認它們已在您啟動 claude 的殼層中匯出，或在您的設定檔的 env 區塊中設定。

啟動模型檢查

當 Claude Code 以 Google Cloud 的 Agent Platform 設定啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。

如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的使用者設定檔並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。

如果您尚未固定模型，且目前預設值在您的專案中無法使用，Claude Code 會在目前工作階段中回退並顯示通知。它會先嘗試預設模型的較早版本，當預設為 Opus 模型且沒有可用的 Opus 版本時，會回退到預設 Sonnet 模型。回退不會被保留。在 Model Garden 中啟用較新模型或固定版本以使選擇永久化。

當您在特定 Sonnet 或 Opus 版本上啟動工作階段時，例如使用 --model、ANTHROPIC_MODEL 或 model 設定，該版本會作為工作階段針對相符 sonnet 或 opus 別名的固定預設值。Claude Code 會略過您設定的模型所取代之內建預設值的可用性檢查，並在您設定的模型上啟動，不會有回退通知。

模型別名（例如 opus）不會作為固定，Claude Code 無法識別的模型 ID 也不會。

IAM 設定

指派 roles/aiplatform.user 角色，其中包含所需的權限：

• aiplatform.endpoints.predict - 模型呼叫和權杖計數所需

如需更嚴格的權限，請建立只包含上述權限的自訂角色。

如需詳細資訊，請參閱 Google Cloud 的 Agent Platform IAM 文件。

1M token context window

Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Google Cloud 的 Agent Platform 上支援 1M token context window。Sonnet 5 始終以 1M 視窗執行，沒有 [1m] 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。

設定精靈在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 [1m]。如需詳細資訊，請參閱為第三方部署固定模型。

故障排除

如果您遇到「無法載入預設認證」錯誤：

• 執行 gcloud auth application-default login 以設定應用程式預設認證
• 將 GOOGLE_APPLICATION_CREDENTIALS 設定為服務帳戶金鑰檔案路徑
• 請參閱 設定 GCP 認證 以了解所有選項

如果您遇到配額問題：

• 透過 Cloud Console 檢查目前配額或要求增加配額

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

• 確認模型在 Model Garden 中已啟用
• 驗證模型在您指定的位置中可用。某些模型僅在 global 或多區域位置（例如 eu 和 us）上提供，不在特定區域中
• 如果使用 CLOUD_ML_REGION=global，請檢查您的模型是否在 Model Garden 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：
  • 透過 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支援的模型，或
  • 使用 VERTEX_REGION_<MODEL_NAME> 環境變數設定區域或多區域位置

如果您遇到 429 錯誤：

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

其他資源

• Google Cloud 的 Agent Platform 文件
• Google Cloud 的 Agent Platform 定價
• Google Cloud 的 Agent Platform 配額和限制