Claude Code 接入 Google Vertex AI 完整步驟:CLAUDE_CODE_USE_VERTEX、gcloud 登入與區域配置

公司用 Google Cloud 怎麼跑 Claude Code?本文按官方文檔整理接入 Vertex AI 的四步流程:Model Garden 模型啟用、IAM 權限、gcloud ADC 登入、global 與單區域配置及報錯排查。

NNathaniel bigo··原創首發·AI 輔助撰寫
12 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. 名稱變化不影響配置:Google 官方把平台改名為 Google Cloud's Agent Platform(原 Vertex AI),但 Claude Code 登入選單裏的選項仍是 Google Vertex AI,環境變量也繼續使用 CLAUDE_CODE_USE_VERTEX=1。
  2. 本地認證必須跑 gcloud auth application-default login:只運行普通的 gcloud auth login 僅供命令行自身使用,Claude Code 讀取的是應用預設憑據(ADC)。
  3. 無數據駐留硬要求時,優先把 CLOUD_ML_REGION 設為 global:全球端點支持動態路由分流,可用模型更全且不容易觸發單區域 429 容量限流。
  4. 支持交互式嚮導 /setup-vertex:首次登入選 第三方平台(3rd-party platform)> Google Vertex AI,或在已有會話裏輸入 /setup-vertex,即可引導完成檢查並寫入用戶設定。
  5. Claude Code 訂閱與高配額開通入口:國內無境外卡可通過本站 iOS 免上號自助卡密開通 Claude Pro 會員 或 5 倍以上額度的 Claude Max 會員,完整檔位選型見 Claude Code 訂閱說明頁。

接入 Google Vertex AI 四步

圖:本站根據 Claude Code 官方文檔:Claude Code on Google Vertex AI 整理的示意圖

本文根據 Claude Code 官方文檔《Claude Code on Google Vertex AI》《Enterprise deployment overview》《Model configuration》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 或 Google 官方網站。

適用於誰

  • 搜「claude code 配置 vertex ai」「CLAUDE_CODE_USE_VERTEX 怎麼配」,希望複用企業 Google Cloud(GCP)帳單與贈金調用 Claude Code 的開發者;
  • 運行了 gcloud auth login 卻仍然報找不到預設憑據,或者選錯區域報 404 Model not found 的人;
  • 需要在全球端點(global)與數據駐留單區域端點(如 us-east5、europe-west1)之間做配置取捨的團隊。

如果你還不清楚三大雲廠商平台與直連 Anthropic 訂閱的區別,可先閱讀 Claude Code 可以使用其他模型嗎。

一、第一步:在 GCP 項目啟用 API、模型與 IAM 角色

在終端配置環境變量前,先確保你的 Google Cloud 項目已完成三項前置準備:

  1. 開啟計費並啟用 API:確認目標 GCP 項目已綁定有效結算帳戶,然後在終端啟用 Vertex AI 接口:
bash
gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com
  1. 在 Model Garden 申請 Claude 模型權限:打開 Google Cloud 控制檯的 Vertex AI Model Garden,篩選 Anthropic 供應商,逐一啟用計劃調用的 Claude Sonnet、Opus 與 Haiku 模型。官方文檔提醒,部分新帳號提交申請後可能需要等待 24 至 48 小時完成審核。
  2. 分配 IAM 角色:調用接口與計算 Token 需要端點預測權限,官方推薦直接給研發帳號或服務帳號授予內置角色 roles/aiplatform.user:
bash
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
  --member="user:[email protected]" \
  --role="roles/aiplatform.user"

二、第二步:用 gcloud 配置本地應用預設憑據(ADC)

Claude Code 通過 Google Cloud 標準憑據鏈向 Vertex AI 鑑權,個人開發機最穩妥的做法是安裝 Google Cloud SDK 後執行以下兩條命令:

bash
# 生成供 SDK 和 Claude Code 讀取的 ADC 憑據文件
gcloud auth application-default login

# 將配額與計費歸屬明確綁定到目標 GCP 項目(防 403 配額項目報錯)
gcloud auth application-default set-quota-project YOUR-PROJECT-ID

如果在無瀏覽器的遠程開發機或自動化容器裏運行,則改用服務帳號密鑰文件,設定環境變量 GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json 即可。

三、第三步:配置 CLAUDE_CODE_USE_VERTEX 與區域策略

方式 A:使用內置嚮導 /setup-vertex

終端運行 claude,在初始登入介面依次選擇 第三方平台(3rd-party platform)> Google Vertex AI;若此前已登入過別的帳號,可在聊天框輸入 /login 或直接敲 /setup-vertex 打開配置嚮導,按提示填入項目 ID 與區域。

方式 B:手動寫入 settings.json 或環境變量

想把配置持久化到本機全局設定(文件層級說明見 Claude Code settings.json 配置詳解),編輯 ~/.claude/settings.json 的 env 字段:

json
{
  "env": {
    "CLAUDE_CODE_USE_VERTEX": "1",
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-gcp-project-id",
    "CLOUD_ML_REGION": "global",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5@20251001"
  }
}

配置區域(CLOUD_ML_REGION)時有兩個關鍵細節:

  • global 與單區域怎麼選:global 端點不鎖定單一機房,配額池更大;若公司合規要求請求不出特定地理邊界,可填 us-east5、europe-west1 等具體區域。
  • 按模型單獨覆蓋區域:有時某個單區域只上架了 Sonnet 卻沒上架 Haiku,導致後台輕量任務報 404。官方支持用 VERTEX_REGION_CLAUDE_3_5_HAIKU、VERTEX_REGION_CLAUDE_4_0_SONNET 等專項變量為特定型號單獨指定可用區域,其餘型號仍走主 CLOUD_ML_REGION(會話內切換型號方法見 Claude Code 切換模型)。

啟動 claude 後運行 /status,確認 API provider 一欄顯示為 Google Vertex AI 即配置成功。對於沒有 GCP 企業帳戶、也不想等待 Model Garden 審批的個人開發者,直接使用官方個人訂閱版會更快捷,有需要可查看本站 Claude Code 訂閱充值頁 或 Claude Max 方案。

四、常見報錯排查

Vertex AI 常見報錯排查對照

圖:本站根據 Claude Code 官方文檔:Claude Code on Google Vertex AI 整理的示意圖

更多通用狀態碼含義可參考 Claude Code 常見報錯與解決,針對 Vertex AI 專有報錯按下面四條定位:

  1. Could not load the default credentials:說明本機還沒有生成 ADC 憑據,或憑據已過期,回到終端重新執行 gcloud auth application-default login。
  2. 403 Permission denied 或提示缺少 serviceusage.services.use:先核查目標項目是否已賦權 roles/aiplatform.user,再執行 gcloud auth application-default set-quota-project 修正本地 ADC 關聯的計費項目。
  3. 404 Publisher Model ... was not found or your project does not have access:要麼該型號在當前 CLOUD_ML_REGION 未部署(可改設 global 測試),要麼尚未在 Model Garden 點同意條款開通該版本。
  4. 老會話裏殘留 ANTHROPIC_API_KEY 干擾:開啟 CLAUDE_CODE_USE_VERTEX=1 後路由會切往 GCP,但建議清理無用的舊環境變量並用 /status 核實當前生效後端。

常見問題

問:Vertex AI 模式下支持提示詞緩存(Prompt Caching)嗎?

答:支持。Claude Code 在 Vertex AI 上預設啟用提示詞緩存;若調試特殊計費問題需臨時關閉,可設定 DISABLE_PROMPT_CACHING=1。

問:在 Vertex AI 模式下輸入 /logout 為什麼提示不支持?

答:因為認證由本地 gcloud 憑據接管,Claude Code 自身不儲存網頁 OAuth 令牌。如需撤銷本地登入,在系統終端運行 gcloud auth application-default revoke 並移除 CLAUDE_CODE_USE_VERTEX 變量即可。

問:Vertex AI 下能用 1M 超長上下文窗口嗎?

答:取決於所選 Claude 型號與目標 GCP 區域是否支持擴展上下文及你的項目配額等級,達標後可通過 /model 選擇帶 [1m] 標識的模型變體。

問:國內沒有海外銀行卡,怎麼給 Claude Code 開通 Pro 或 Max 訂閱?

答:可在 Claude Code 訂閱頁 選擇走 iOS 訂閱鏈路的 Claude Pro 自助卡密 或 Claude Max 充值,支持支付寶、微信支付與 AlipayHK,無需交出帳號密碼;若帳號彈出身份核驗也可查看 Claude KYC 認證人工協助(失敗不收費,封號不在質保範圍)。

相關教學

參考資料

  • Claude Code 官方文檔:Claude Code on Google Vertex AI — https://code.claude.com/docs/en/google-vertex-ai
  • Claude Code 官方文檔:Enterprise deployment overview — https://code.claude.com/docs/en/third-party-integrations
  • Claude Code 官方文檔:Model configuration — https://code.claude.com/docs/en/model-config

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  2. 02

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

    企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入門教學:給 LangGraph 與原生 OpenAI / Claude 接口加調用鏈追蹤、Token 成本統計與免費層限額

    智能體多步調用總是找不到哪一輪提示詞跑偏、單次請求到底燒了多少 Token?本文按 LangSmith 官方文檔講清環境變量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 與 @traceable 追蹤原生接口,以及 Developer 免費層額度與留存規則。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效讀英文文獻:PDF 翻譯插件、批註導出精讀與防捏造參考文獻流程

    在 Zotero 裏讀英文頂會論文怎麼無縫聯動 Claude 與 ChatGPT?本文整理 Translate for Zotero 劃詞翻譯配置、高亮批註導出精讀提示詞,以及杜絕 AI 捏造假 DOI 參考文獻的核驗閉環。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 與本地 Ollama 做個人雙鏈筆記問答:主流插件配置與私隱脫敏邊界

    想在 Obsidian 裏基於自己的雙鏈筆記庫做 AI 問答又擔心私隱外泄?本文對比 Copilot 與 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 與本地 Ollama 的步驟及敏感目錄隔離規則。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~