在 Google Cloud 上設定 Claude（Google 託管）

當貴公司透過 Google Cloud's Agent Platform 購買 Claude 時，Claude Code、Claude Desktop 以及您建置的應用程式，全都是透過您自己的 Google Cloud 專案連接到 Claude。 您使用 Google Cloud 憑證登入，因此不需要 Anthropic API 金鑰，並且由 Google Cloud 計費使用量。

設定分為四個部分。由某人一次性準備好專案，然後每個人再為自己授予存取權限。接下來，您從終端機向 Claude 發送一次請求並取得其回覆。之後，您將所使用的應用程式指向該專案。如果您只從自己的程式碼呼叫 Claude，到取得回覆就可以停止了。對於 Claude Code，當它回應您，且 /status 顯示您的專案 ID 時，就算完成了。

Google Cloud 以兩種服務出售 Claude，而它們的設定方式不同。因此，第一項工作是確認您擁有的是哪一種。

確認您擁有的是哪一種服務

這兩種服務的差異在於由誰來操作 Claude。 在 Claude Models on Google Cloud（Google 託管）中，Google 作為 Google Cloud's Agent Platform（原名 Vertex AI）的一部分，負責操作 Claude 模型。Agent Platform 是 Google Cloud 中這些步驟所適用的部分：您在其中啟用 API、取得其中一個角色，而您的使用量會以 Agent Platform 用量計費。在 Anthropic 託管服務中，則是由 Anthropic 操作 Claude API。

要分辨您擁有的是哪一種，請查看您已經擁有的東西。下表顯示要查看的內容。

Model Garden 是 Google Cloud 主控台中每個模型都有自己卡片的部分。

請求 URL 是第三個跡象。在 Google 託管中，它們指向 Agent Platform 主機，而 URL 路徑包含 .../publishers/anthropic/models/{model}。這兩種服務的總覽列出了這些主機。

如果您使用的是 Anthropic 託管，請改為遵循在 Google Cloud 上設定 Claude（Anthropic 託管）。如果您使用 API 金鑰呼叫 api.anthropic.com，則兩種服務您都沒有使用。

您需要什麼，以及費用為何

在開始之前，請準備好以下項目：

• 一個已開啟計費功能的 Google Cloud 專案，以及其專案 ID
• 您將使用的 Claude 模型在您將使用的區域中的配額。Google 的適用於 Anthropic Claude 模型的配額列出了預設配額，並說明在哪裡可以檢視您專案的配額或申請更多配額。
• gcloud CLI，Google Cloud 的命令列工具
• curl 和一個 Bash shell，用來發送測試請求
• Claude Code，版本 2.1.293 或更新版本，如果您將使用它。若要更新，請執行 claude update。

無論下方指令中出現 YOUR-PROJECT-ID 或 PROJECT_ID 的地方，都請替換為您的專案 ID。

如果您剛安裝好 gcloud CLI，請使用 gcloud auth login 或 gcloud init 登入。這是 gcloud CLI 自己的登入方式，測試請求會使用它。Claude Code 使用的 Application Default Credentials，則是另一種登入方式，屬於「為自己授予存取權限」的部分。

由 Google Cloud 以 Agent Platform 用量的方式計費使用量。 這包括您從 Claude Code 或 Claude Desktop 發送的內容。若要查詢價格，請從此服務文件頁面的計費章節開始。

一次性準備好專案

在任何人能從專案呼叫 Claude 之前，該專案需要啟用 Agent Platform API，並啟用一個 Claude 模型。這些步驟每個 Google Cloud 專案只需做一次，通常由管理員執行。 如果已經有人為您的專案完成這些步驟，請前往「為自己授予存取權限」。

1. 開啟 Agent Platform API。將 gcloud 指向該專案，然後啟用服務 aiplatform.googleapis.com。

   bash

   gcloud config set project YOUR-PROJECT-ID
   gcloud services enable \
     aiplatform.googleapis.com

   Google 的使用 Claude 模型前的準備步驟涵蓋此步驟以及計費檢查。

2. 在 Model Garden 中啟用您將使用的 Claude 模型。Google 列出了Claude 模型卡片。開啟每個模型的卡片並點擊 Enable。對於 Claude Code，請啟用 claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5 以及 claude-sonnet-5。當您連接 Claude Code 時，會固定前三個版本。請勿固定 Claude Sonnet 5。有了這些固定版本，它就是在自動模式下檢查動作的預設模型，而自動模式是此服務上互動式工作階段預設啟動的模式，除非您設定了其他模式。若未固定版本，Claude Code 會使用一個預設的 Claude Sonnet 模型，而該模型在此服務上已被棄用。

點擊 Enable 的人必須在 Identity and Access Management（IAM）中擁有 Consumer Procurement Entitlement Manager 角色。其 ID 為 roles/consumerprocurement.entitlementManager。

為自己授予存取權限

專案已準備就緒，但您自己的帳戶仍需要呼叫 Claude 的權限，以及 Claude Code 可以使用的登入方式。每個人都需要為自己的帳戶執行這些步驟。

1. 將 gcloud 指向該專案。

   bash

   gcloud config set project YOUR-PROJECT-ID

2. 取得可以呼叫 Claude 的角色。發出呼叫的身分需要一個包含 aiplatform.endpoints.predict 權限的 IAM 角色，例如 Agent Platform User（roles/aiplatform.user）。此指令會授予該角色：

   bash

   gcloud projects add-iam-policy-binding \
     PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/aiplatform.user

   將 PRINCIPAL 替換為 user: 加上您的電子郵件地址，例如 user:you@example.com。Google 關於授予存取權限的頁面列出了 PRINCIPAL 可採用的其他形式。如果您無權變更該專案的 IAM 政策，請請求管理員為您執行此指令。

3. 使用 Application Default Credentials 登入。這些是 Claude Code 呼叫 Claude 時所使用的 Google Cloud 憑證。

   bash

   gcloud auth application-default login

向 Claude 發送一次測試請求

在連接應用程式之前，先向 Claude 發送一次請求。 收到回覆代表專案和您的存取權限都正常運作。此請求會直接呼叫 Agent Platform API，就像您所建置的應用程式一樣。

1. 檢查 gcloud CLI 目前登入的帳戶為何。此請求的權杖來自 gcloud CLI 自己的登入，而非來自 Application Default Credentials。

   bash

   gcloud auth list

   作用中帳戶必須是在「為自己授予存取權限」中取得角色的那個帳戶。如果不是，請執行 gcloud auth login。

2. 發送請求。請先替換 YOUR-PROJECT-ID。Google Cloud 會像計費其他請求一樣計費此請求。

   bash

   curl https://aiplatform.googleapis.com/v1/projects/YOUR-PROJECT-ID/locations/global/publishers/anthropic/models/claude-opus-5-5:rawPredict \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "anthropic_version": "2026-10-21",
       "messages": [{"role": "user", "content": "Hey Claude!"}],
       "max_tokens": 100
     }'

   此請求使用區域 global。如果您需要資料落地，主機和路徑都會改變。文件展示了在 us 多區域上的相同請求。

3. 讀取回覆。它是 JSON 格式，Claude 的話語位於 type 為 text 的 content 項目中。您的回覆會有不同的內容，且欄位會比這個精簡版本更多：

   json

   {
     "type": "message",
     "role": "assistant",
     "content": [{"type": "text", "text": "Hello! Nice to meet you."}],
     "stop_reason": "end_turn"
   }

錯誤也會以 JSON 格式回傳，並帶有以下其中一個代碼：

這些代碼列在 Google 的 API 錯誤清單中。一旦您收到回覆後，如果某個應用程式無法連上 Claude，請先檢查該應用程式的登入和設定。

連接 Claude Code 或 Claude Desktop

在專案就緒、存取權限已設定妥當，並且已收到 Claude 的回覆之後，請將您使用的應用程式指向該專案。兩個應用程式都會要求相同的兩個值：您的專案 ID 和一個區域。以下步驟使用區域 global。

如果您需要資料落地，請使用 us 或 eu 多區域。 它的費用比 global 多 10%，而 global 會將請求發送到任何具有可用容量的區域。區域端點僅服務 Claude Sonnet 4.6 及更早期的模型。文件比較了 global、多區域和區域端點。

Claude Code

登入精靈會處理 Claude Code 端的設定。

1. 啟動 Claude Code。

   bash

   claude

2. 選擇 Agent Platform。 在登入提示中，選擇 3rd-party platform，然後選擇 Google Vertex AI。這是登入提示目前仍用於 Google Cloud's Agent Platform 的標籤。如果您已經登入，請執行 /login 以開啟相同的選單。

3. 依照精靈的提示操作。 當它詢問您如何向 Google Cloud 進行身分驗證時，選擇來自 gcloud 的 Application Default Credentials，這是您在「為自己授予存取權限」中設定好的。然後提供您的專案 ID 和區域 global。精靈會驗證您的專案可以呼叫哪些 Claude 模型，並讓您固定這些模型版本。請固定全部三個：claude-opus-5-5、claude-sonnet-5-5 和 claude-haiku-5-5。如果精靈預設從某個模型的不同版本開始，請在固定之前先變更它。固定了 Haiku 模型後，Claude Code 會將其用於背景任務。精靈會將結果儲存到您的使用者設定檔中，因此您無需自行匯出環境變數。

4. 向 Claude Code 發送一則訊息。 當它回應時，代表 Claude Code 正透過 Google Cloud 連接到 Claude。

檢查它使用的是您所指定的專案。 執行 /status。API provider 欄位會顯示 Google Vertex AI。GCP project、Default region 和 Model 欄位會顯示您的專案 ID、您的區域以及解析出的模型。請將此專案 ID 與「一次性準備好專案」中的專案進行比對。

Claude Opus 模型的單一 token 價格比 Sonnet 模型高。 即使固定了全部三個模型，Claude Code 的主要模型仍然是 Opus，因此您會以 Opus 的費率計費，直到您使用 /model 切換模型為止。若要之後變更您的模型固定版本、專案、區域或憑證，請執行 /setup-vertex 以重新開啟精靈。

若要在不使用精靈的情況下設定 Claude Code，例如在 CI 或腳本化部署中，請在您啟動 claude 的 shell 中設定以下環境變數：

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-5-5'

如果之後 /status 沒有顯示 API provider 這一欄，代表這些變數沒有傳遞到該程序。手動設定步驟涵蓋了其餘內容，包括如何為團隊固定模型版本。

Claude Desktop

Claude Desktop 可以透過相同的專案使用 Claude 模型，而 Claude Cowork 工作階段就在該應用程式中執行。IT 管理員通常會將其部署到每台裝置上，因此請先詢問您的裝置是否已經完成部署。若要在單一裝置上試用，請手動填入相同的值。

1. 開啟應用程式內設定視窗。 前往 Help → Troubleshooting → Enable Developer Mode，然後前往 Developer → Configure Third-Party Inference…。

2. 選擇提供者。 在 Connection 區段中，將 Inference provider 設定為 Vertex AI。

3. 填寫 Vertex AI 憑證卡片。 在 GCP project ID 中填入您的專案 ID，並在 GCP region 中填入區域。該區域可以是 global。然後提供恰好一種憑證來源。GCP credentials file path 接受 gcloud auth application-default login 所產生的檔案。Google 列出了該檔案儲存的位置。

4. 新增模型。 在 Models 下，新增至少一筆 Model list 項目，使用您已啟用之模型的發行者模型 ID，例如 claude-opus-5-5。

5. 套用設定。 點擊 Apply Changes。應用程式會將設定僅寫入此裝置，並重新啟動套用該設定。然後發送一則訊息，確認 Claude 能夠回應。

透過 Google Cloud's Agent Platform 在 3P 上部署 Claude Desktop涵蓋了其他登入方式，以及如何將設定推送到每台裝置。

如果無法運作

以下錯誤可能會阻止 Claude Code 連接到 Claude。在表格中找到您遇到的錯誤，然後套用其修正方法。

某個位置可能缺少某個模型。 有些模型僅在 global 或多區域位置（例如 eu 和 us）提供，而不是在特定區域中提供。如果您變更區域，請確認您的模型在該處可用。

這些修正方法來自在 Google Cloud's Agent Platform 上 Claude Code 的疑難排解，其中有更詳盡的說明。對於 Claude Desktop，請從其自己的疑難排解章節開始。

接下來該做什麼

請將您的專案 ID 和區域保存在容易找到的地方。 Claude Code、Claude Desktop 以及 SDK 用戶端都會要求提供這些資訊。

• 要學習 Claude Code，請修習 Claude Code 101，然後修習 Claude Code in action。
• 要學習 Claude Cowork，請修習 Introduction to Claude Cowork。
• 要從您自己的程式碼呼叫 Claude，請遵循 Google 託管文件頁面。其中展示了如何安裝 SDK 並使用 AnthropicVertex 用戶端發出請求。

有關此服務本身的更多資訊，文件中針對以下每一項都有一個章節：

• 全域、多區域和區域端點
• 速率限制
• 監控與記錄
• 計費