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 条评论

登录 后参与评论

还没有评论,来抢沙发~