结论先说
- 名称变化不影响配置: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 条评论
还没有评论,来抢沙发~