Google Cloud 的 Agent Platform 上的 Claude Code

先決條件

在使用 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，請使用手動設定步驟並在推出前固定您的模型版本。如果您有 Google Cloud 認證並想開始透過 Google Cloud 的 Agent Platform 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。

在您的 GCP 專案中啟用 Claude 模型

為您的專案啟用 Google Cloud 的 Agent Platform API，然後在 Google Cloud 的 Agent Platform Model Garden 中要求存取您想要的 Claude 模型。請參閱 IAM 設定以了解您的帳戶需要的權限。

啟動 Claude Code 並選擇 Google Cloud 的 Agent Platform

執行 claude。在登入提示處，選擇第三方平台，然後選擇 Google Vertex AI，這是登入提示仍然用於 Google Cloud 的 Agent Platform 的標籤。如果您已經登入，執行 /login 以開啟相同的選單。

遵循精靈提示

選擇您如何向 Google Cloud 進行驗證：來自 gcloud 的應用程式預設認證、服務帳戶金鑰檔案，或已在您的環境中的認證。精靈會偵測您的專案和區域，驗證您的專案可以呼叫哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的使用者設定檔的 env 區塊，因此您不需要自己匯出環境變數。

登入後，您可以隨時執行 /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 可能不支援每個端點類型上的 Claude Code 預設模型。模型可用性在特定區域、多區域位置和全球端點之間有所不同。您可能需要切換到支援的位置或指定支援的模型。

手動設定

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

啟用 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

要求模型存取權

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

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

設定 GCP 認證

Claude Code 使用標準 Google Cloud 驗證。如需詳細資訊，請參閱 Google Cloud 驗證文件。 Claude Code 透過相同的 Application Default Credentials 鏈支援 X.509 憑證型 Workload Identity Federation。將 GOOGLE_APPLICATION_CREDENTIALS 設定為您的認證設定檔路徑。

Claude Code 將 Google Cloud 的 Agent Platform 要求定址到 ANTHROPIC_VERTEX_PROJECT_ID 中的專案，即使 GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT 或 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 工作階段。

設定 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。

釘選模型版本

在部署到多個使用者時釘選特定模型版本。不釘選的情況下，模型別名（例如 sonnet 和 opus）會解析為 Claude Code 針對 Google Cloud 的 Agent Platform 的內建預設值，這可能會落後最新版本，且可能尚未在您的專案中啟用。Claude Code 在啟動時會在預設值無法使用時回退到較早或較低階的模型，但釘選可讓您控制使用者何時移至新模型。

將這些環境變數設定為特定 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 會使用這些預設模型：

模型類型	預設值
主要模型	`claude-opus-5-5`
小型/快速模型	`claude-sonnet-4-5@20250929`

背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 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。

Opus 模型的每權杖價格高於 Sonnet 模型，因此不釘選主要模型的部署在更新至 v2.1.207 或更新版本後會以 Opus 費率計費。若要將 Sonnet 4.5 保持為主要模型，請將 ANTHROPIC_MODEL 設定為其完整模型 ID。引導預設值為 ANTHROPIC_DEFAULT_SONNET_MODEL 且未設定 ANTHROPIC_DEFAULT_OPUS_MODEL 的部署會將其引導的 Sonnet 模型保持為預設值。

在 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'

驗證您的設定

啟動 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 文件。

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

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]。如需詳細資訊，請參閱為第三方部署固定模型，包括如何在不變更固定設定的情況下使用 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 上的 Claude Code

先決條件

區域設定

手動設定

啟用 Agent Platform API

要求模型存取權

設定 GCP 認證

進階認證設定

設定 Claude Code

釘選模型版本

驗證您的設定

啟動模型檢查

IAM 設定

1M token context window

故障排除

其他資源

​先決條件

​使用 Agent Platform 登入

​區域設定

​手動設定

​ 啟用 Agent Platform API

​ 要求模型存取權

​ 設定 GCP 認證

​進階認證設定

​ 設定 Claude Code

​ 釘選模型版本

​ 驗證您的設定

​啟動模型檢查

​IAM 設定

​1M token context window

​故障排除

​其他資源

先決條件

使用 Agent Platform 登入

區域設定

手動設定

啟用 Agent Platform API

要求模型存取權

設定 GCP 認證

進階認證設定

設定 Claude Code

釘選模型版本

驗證您的設定

啟動模型檢查

IAM 設定

1M token context window

故障排除

其他資源