跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
先決條件

在使用 Vertex AI 設定 Claude Code 之前，請確保您具有：
  • 已啟用計費的 Google Cloud Platform (GCP) 帳戶
  • 已啟用 Vertex AI API 的 GCP 專案
  • 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
  • 已安裝並設定 Google Cloud SDK (gcloud)
  • 在所需的 GCP 區域中分配的配額
若要使用您自己的 Vertex AI 認證登入，請遵循下方的使用 Vertex AI 登入。若要在整個團隊中部署 Claude Code，請使用手動設定步驟並在推出前固定您的模型版本。

​
使用 Vertex AI 登入

如果您有 Google Cloud 認證並想開始透過 Vertex AI 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。
Vertex AI 設定精靈需要 Claude Code v2.1.98 或更新版本。執行 claude --version 以檢查。
1

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

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

啟動 Claude Code 並選擇 Vertex AI

執行 claude。在登入提示處，選擇第三方平台，然後選擇 Google Vertex AI。
3

遵循精靈提示

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

​
區域設定

Claude Code 支援 Vertex AI 全球、多區域和區域端點。將 CLOUD_ML_REGION 設定為 global、多區域位置（例如 eu 或 us）或特定區域（例如 us-east5）。Claude Code 為每種形式選擇正確的 Vertex AI 主機名稱，包括多區域位置的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com 主機。
Vertex AI 可能不支援每個端點類型上的 Claude Code 預設模型。模型可用性在特定區域、多區域位置和全球端點之間有所不同。您可能需要切換到支援的位置或指定支援的模型。

​
手動設定

若要透過環境變數而不是精靈來設定 Vertex AI，例如在 CI 或指令碼化企業推出中，請遵循下列步驟。

​
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.6）
  4. 等待核准（可能需要 24-48 小時）

​
3. 設定 GCP 認證

Claude Code 使用標準的 Google Cloud 驗證。 如需詳細資訊，請參閱 Google Cloud 驗證文件。 Claude Code v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 X.509 憑證型 Workload Identity Federation。將 GOOGLE_APPLICATION_CREDENTIALS 設定為您的認證設定檔案路徑。
Claude Code 使用 ANTHROPIC_VERTEX_PROJECT_ID 作為 Vertex AI 要求的專案 ID。GCLOUD_PROJECT 和 GOOGLE_CLOUD_PROJECT 環境變數以及 GOOGLE_APPLICATION_CREDENTIALS 參考的認證檔案優先於它。如果這些都未設定，專案 ID 會從您的 gcloud 設定或附加的服務帳戶解析。

​
進階認證設定

Claude Code 透過 gcpAuthRefresh 設定支援 GCP 的自動認證重新整理。當 Claude Code 偵測到您的 GCP 認證已過期或無法載入時，它會執行設定的命令以在重試要求之前取得新認證。 
{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}
命令的輸出會顯示給使用者，但不支援互動式輸入。這適用於瀏覽器型驗證流程，其中 CLI 顯示 URL，您在瀏覽器中完成驗證。如果驗證未在三分鐘內完成，重新整理命令會逾時。如果您在專案設定（例如 .claude/settings.json）中設定 gcpAuthRefresh，命令只會在您接受工作區信任提示後執行。

​
4. 設定 Claude Code

設定下列環境變數： 
# 啟用 Vertex AI 整合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

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

# 選用：如需要，停用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 選用：要求 1 小時 prompt cache TTL 而不是 5 分鐘預設值
export ENABLE_PROMPT_CACHING_1H=1

# 當 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_* 變數。如需完整清單，請參閱環境變數參考。檢查 Vertex Model Garden 以確定哪些模型支援全球端點與僅限區域端點。 Prompt caching 會自動啟用。若要停用它，請設定 DISABLE_PROMPT_CACHING=1。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 ENABLE_PROMPT_CACHING_1H=1；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Vertex AI 時，/login 和 /logout 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。 Claude Code 在 Vertex AI 上預設停用 MCP tool search，因此 MCP 工具定義會預先載入。Vertex AI 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 ENABLE_TOOL_SEARCH=true 以在這些模型上啟用它。Vertex AI 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。

​
5. 固定模型版本

在部署到多個使用者時固定特定模型版本。如果不固定，模型別名（例如 sonnet 和 opus）會解析為最新版本，當 Anthropic 發佈更新時，該版本可能尚未在您的 Vertex AI 專案中啟用。Claude Code 在啟動時會在最新版本無法使用時回退到先前版本，但固定可讓您控制使用者何時移至新模型。
將這些環境變數設定為特定的 Vertex AI 模型 ID。 如果沒有 ANTHROPIC_DEFAULT_OPUS_MODEL，Vertex 上的 opus 別名會解析為 Opus 4.6。將其設定為 Opus 4.7 ID 以使用最新模型： 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
如需目前和舊版模型 ID，請參閱模型概覽。如需完整的環境變數清單，請參閱模型設定。 Claude Code 使用這些預設模型，當未設定固定變數時：
模型類型預設值
主要模型claude-sonnet-4-5@20250929
小型/快速模型與主要模型相同
背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Vertex AI 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個專案或區域中啟用。若要使用 Haiku 進行背景工作，請將 ANTHROPIC_DEFAULT_HAIKU_MODEL 設定為您專案中可用的模型 ID。 若要進一步自訂模型： 
export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

​
啟動模型檢查

當 Claude Code 以設定的 Vertex AI 啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。此檢查需要 Claude Code v2.1.98 或更新版本。 如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的使用者設定檔並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。 如果您尚未固定模型，且目前預設值在您的專案中無法使用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在 Model Garden 中啟用較新模型或固定版本以使選擇永久化。

​
IAM 設定

指派所需的 IAM 權限： roles/aiplatform.user 角色包含所需的權限：
  • aiplatform.endpoints.predict - 模型呼叫和權杖計數所需
如需更嚴格的權限，請建立只包含上述權限的自訂角色。 如需詳細資訊，請參閱 Vertex IAM 文件。
為 Claude Code 建立專用的 GCP 專案，以簡化成本追蹤和存取控制。

​
1M token context window

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Vertex AI 上支援 1M token context window。當您選擇 1M 模型變體時，Claude Code 會自動啟用擴展 context window。 設定精靈在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 [1m]。如需詳細資訊，請參閱為第三方部署固定模型。

​
故障排除

如果您遇到「無法載入預設認證」錯誤：
  • 執行 gcloud auth application-default login 以設定應用程式預設認證
  • 將 GOOGLE_APPLICATION_CREDENTIALS 設定為服務帳戶金鑰檔案路徑
  • 請參閱 設定 GCP 認證 以了解所有選項
如果您遇到配額問題： 如果您遇到「找不到模型」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 以獲得更好的可用性

​
其他資源