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

圖:本站根據 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 項目已完成三項前置準備:
- 開啟計費並啟用 API:確認目標 GCP 項目已綁定有效結算帳戶,然後在終端啟用 Vertex AI 接口:
bash
gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com
- 在 Model Garden 申請 Claude 模型權限:打開 Google Cloud 控制檯的 Vertex AI Model Garden,篩選 Anthropic 供應商,逐一啟用計劃調用的 Claude Sonnet、Opus 與 Haiku 模型。官方文檔提醒,部分新帳號提交申請後可能需要等待 24 至 48 小時完成審核。
- 分配 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 方案。
四、常見報錯排查

圖:本站根據 Claude Code 官方文檔:Claude Code on Google Vertex AI 整理的示意圖
更多通用狀態碼含義可參考 Claude Code 常見報錯與解決,針對 Vertex AI 專有報錯按下面四條定位:
Could not load the default credentials:說明本機還沒有生成 ADC 憑據,或憑據已過期,回到終端重新執行gcloud auth application-default login。403 Permission denied或提示缺少serviceusage.services.use:先核查目標項目是否已賦權roles/aiplatform.user,再執行gcloud auth application-default set-quota-project修正本地 ADC 關聯的計費項目。404 Publisher Model ... was not found or your project does not have access:要麼該型號在當前CLOUD_ML_REGION未部署(可改設global測試),要麼尚未在 Model Garden 點同意條款開通該版本。- 老會話裏殘留
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 settings.json 配置詳解:文件位置、優先級與常用示例
- Claude Code 切換模型:/model 命令、模型別名、effort 與 fast 模式
- Claude Code 常見報錯與解決:403、400、Error editing file
參考資料
- 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
0 條評論
還沒有評論,來搶沙發~