让 Claude Code 走 Google Vertex AI 与 Microsoft Foundry：两条云上接入路径的配置差异

2026-08-18

公司要求模型调用走自己的云账号——合规上说得通，账单也统一。于是问题落到你头上：Claude Code 到底怎么接到 Google Cloud 或者 Azure 上去，两边各要填什么。

麻烦的地方在于，这两条路径的官方文档不是同一个模子刻出来的。Google 那一页有向导、有区域配置、有启动时的模型可用性检查；Microsoft Foundry 那一页明确写了”没有交互式向导”。照着其中一页的经验去配另一边，会在几个地方扑空。本文把两页摆在一起逐项对齐，只对照两边都白纸黑字写了的维度，一方没写的直接说没写。

先说清一个命名：Google 侧这套东西，官方文档现在写作 “Google Cloud’s Agent Platform, formerly Vertex AI”。但文档同时写明，Claude Code 登录提示里用的标签仍然是 Google Vertex AI——这是文档自己点出来的口径不一致，你在登录菜单里要找的是旧名字。

一、前置条件：两边要的不是一类东西

这一段最容易被跳过，但两条路径卡人的地方恰恰都在这里。

Google Cloud 侧，文档列的前置条件是：一个已开启计费的 GCP 账号；一个已启用 Agent Platform API 的 GCP 项目；对目标 Claude 模型的访问权限；已安装并配置好的 Google Cloud SDK（gcloud）；以及目标区域里已分配的配额。

Microsoft Foundry 侧，文档列的是：一个能访问 Microsoft Foundry 的 Azure 订阅；创建 Foundry 资源与 deployment 所需的 RBAC 权限；Azure CLI——这一条文档标注为 optional，原文写明”只有在你没有其它获取凭据的机制时才需要”。

差异在这里就出现了两处：Google 侧把 gcloud 列为必须，Foundry 侧把 Azure CLI 列为可选；Google 侧明确要求”目标区域里已分配配额”，而 Foundry 页面没有提到任何区域或配额层面的前置条件——这一点在 Foundry 文档里没有对应说明，不做对比。

还有一个不对称的必做动作：Foundry 要你先在门户里为每个模型创建 deployment，并记住你给它起的名字，因为后面模型变量填的就是这些 deployment 名，不是模型 ID。Google 侧对应的动作是在 Model Garden 里申请模型访问权限并等审批通过（文档写明是要等的，不是点一下就能用）。

二、认证：Foundry 给了三条，Google 走 ADC 链

Foundry 的三种认证方式，文档是并列写的：

Option A：API key。从资源的 Endpoints and keys 处取到 key，设 ANTHROPIC_FOUNDRY_API_KEY。
Option B：Microsoft Entra ID。文档写明，当 ANTHROPIC_FOUNDRY_API_KEY 和 ANTHROPIC_FOUNDRY_AUTH_TOKEN 都没设时，Claude Code 自动走 Azure SDK 的默认凭据链。本地常见做法是 az login。
Option C：Bearer token。设 ANTHROPIC_FOUNDRY_AUTH_TOKEN，Claude Code 会把这个值以 Authorization: Bearer 头发在每个请求上。这一项文档写明要求 Claude Code v2.1.203 或更新版本，低于这个版本时文档没有把它列为可用选项，铺开前先把客户端版本门槛核一遍。

优先级文档写得很明确：ANTHROPIC_FOUNDRY_AUTH_TOKEN 高于 ANTHROPIC_FOUNDRY_API_KEY，也高于默认凭据链。文档只写了这个先后关系，三者同时存在时会不会给出提示，官方文档没有说明这一点——所以排查”我明明换了 key 怎么没变”的时候，先确认环境里有没有残留的 ANTHROPIC_FOUNDRY_AUTH_TOKEN。

Google 侧没有并列的”三选一”，文档说的是”使用标准的 Google Cloud 认证”，也就是 ADC 那一套。文档额外写明支持基于 X.509 证书的 Workload Identity Federation，走的是同一条 Application Default Credentials 链，把 GOOGLE_APPLICATION_CREDENTIALS 指向凭据配置文件即可。

Google 侧有一处优先级陷阱值得单独记：Claude Code 用 ANTHROPIC_VERTEX_PROJECT_ID 作为请求的项目 ID，但文档写明 GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT 这两个环境变量，以及 GOOGLE_APPLICATION_CREDENTIALS 指向的凭据文件里的项目，优先级都高于它。三者都没有时才回落到 gcloud 配置或附着的服务账号。也就是说，你设了 ANTHROPIC_VERTEX_PROJECT_ID 却发现请求打到了另一个项目，八成是被上面那几个盖掉了。

还有一个 Foundry 侧没有对应物的能力：gcpAuthRefresh。这是写在 Claude Code settings 文件里的一个设置项，当 Claude Code 发现 GCP 凭据过期或加载不了时，会执行你配的命令去拿新凭据再重试：

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

文档对它划了三条边界：一，Claude Code 会把命令输出显示给你，但不能向命令发送交互式输入，所以它适配的是”CLI 打印一个 URL、你去浏览器里完成认证”这类流程；二，刷新命令有超时（文档写明是三分钟），超时未完成就不再等；三，如果把它写在项目级 settings（如 .claude/settings.json）里，Claude Code 会按与 settings 文件中 hooks 相同的工作区信任规则执行它，其中包括你从未信任过的目录下的 -p 会话——这是安全边界，别当成普通配置项。Foundry 文档里没有对应的凭据自动刷新设置。

三、要设的环境变量：一边有区域，一边有资源名

Google 侧的开关与核心变量：

# Enable Agent Platform integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Override the Agent Platform endpoint URL for custom endpoints or gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

Foundry 侧：

# Enable Microsoft Foundry integration
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure resource name (replace {resource} with your resource name)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# Or provide the full base URL:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

对齐着看，两边都有”总开关 + 可选的 base URL 覆盖”这一组，但中间那一项完全不同：Google 要的是区域 + 项目 ID，Foundry 要的是资源名（端点 URL 由资源名拼出来）。

区域这一维是 Google 独有的。文档写明 CLOUD_ML_REGION 可设为 global、eu / us 这类多区域位置，或 us-east5 这类具体区域，Claude Code 会为每种形态选对应主机名，多区域位置对应 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com。文档还给了逐模型覆盖区域的变量形态，例如 VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5，用于 CLOUD_ML_REGION=global 时某些模型不支持全局端点的情况。Foundry 文档里没有任何区域配置项，Google 侧那套”模型在这个区域有没有”的排查思路，在 Foundry 上没有对应入口。

模型固定（pin）两边都要做，但填的东西不一样。 Foundry 侧文档说得最直白：模型变量要填成你第一步创建的 deployment 名。

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

以上取自官方文档当时的示例，其中的具体模型 ID 只是示例值，平台上有哪些模型、叫什么名字随时在变，不要当成清单用；Foundry 侧这几个值应换成你自己的 deployment 名。Google 侧的变量名是同一组，语义也是”固定版本”，但值是 Agent Platform 的模型 ID。

两边的告警措辞差别很关键。Google 侧写的是”部署给多个用户时请固定版本”，并说明未固定时别名会解析到 Claude Code 的内置默认值，而这个内置默认可能落后于最新发布、也可能在你的项目里还没启用；Foundry 侧写的是”每一个 deployment 都要固定版本”，理由是”Microsoft Foundry 没有启动时的模型检查，默认模型不可用时请求会直接失败”。这句是两页里最值得单独抄下来的一句差异。

Google 侧的启动检查具体做什么，文档也写了：启动时校验它打算用的模型在你项目里是否可访问；你固定的版本比当前默认旧、项目又能调用更新版本时，会提示你更新固定值；你没固定、当前默认又不可用时，会为当前会话回落并给出提示，且这次回落不会被持久化。文档还写明，模型别名（如 opus）不算固定，Claude Code 不认识的模型 ID 也不算。

后台任务（例如生成会话标题）用的”小/快模型”，两边的兜底也不同：Google 侧文档写明使用默认 Sonnet 模型，理由是 Haiku 未必在每个项目或区域都启用；Foundry 侧写明兜底到主模型，理由是不是每个账号都有 Haiku deployment。两边都说，要让后台任务用 Haiku，就把 ANTHROPIC_DEFAULT_HAIKU_MODEL 设成你那边确实可用的模型 / deployment。

四、边界：这些地方别按另一边的经验推

向导只有一边有。 Google 侧有登录向导：运行 claude，在登录提示里选 3rd-party platform，再选 Google Vertex AI；已登录的话用 /login 打开同一菜单。向导让你在 gcloud 的 Application Default Credentials、服务账号 key 文件、环境里已有的凭据这三者中选一种，会检测项目与区域、校验项目能调用哪些模型并允许固定，结果写入用户 settings 文件的 env 块（~/.claude/settings.json，设了 CLAUDE_CONFIG_DIR 时则写到 $CLAUDE_CONFIG_DIR/settings.json）。之后随时可用 /setup-vertex 重开向导。Foundry 文档则明写：不像 Amazon Bedrock 和 Google Cloud’s Agent Platform，Microsoft Foundry 没有交互式设置向导，环境变量是唯一配置路径。
/logout 两边都不可用。 两页都写明，认证由云侧凭据接管，因此 /logout 命令不可用。这是少数两边完全一致的点。
托管位置的选择只有 Foundry 文档提到。 Foundry 配置 deployment 时还要选 hosting option，文档写明它决定推理是跑在 Azure 上还是跑在 Anthropic 的基础设施上。Google 那一页没有对应说明，不比。
MCP tool search 的行为只有 Google 那一页写了。 文档写明 Claude Code 按模型代际决定用 tool search 还是前置加载：较新代际默认启用；更早的模型（含全部 Claude 3.x）走前置加载，原因是它们在 Agent Platform 上的服务栈会拒绝所需的 beta 头，此时设 ENABLE_TOOL_SEARCH=true 也覆盖不了。要在所有模型上关掉则设 ENABLE_TOOL_SEARCH=false。文档另注明，在 v2.1.221 之前，该平台上所有模型默认关闭 tool search，除非显式设 ENABLE_TOOL_SEARCH=true。Foundry 页没有相关段落。
提示缓存两边都自动开，但可调项不同。 两页都写明提示缓存自动启用，也都写明设 ENABLE_PROMPT_CACHING_1H=1 可请求 1 小时的缓存 TTL、以替代文档所说的更短的默认 TTL，并都注明 1 小时 TTL 的缓存写入计费更高（具体费率以官方定价页为准，本文不写数值）。关闭缓存的 DISABLE_PROMPT_CACHING=1 只在 Google 那一页出现，Foundry 页没写。
扩展上下文窗口的选择方式只有 Google 那一页写了：部分模型支持扩展上下文窗口，选中对应模型变体时会自动启用；手动固定模型时在模型 ID 后追加 [1m] 后缀，向导在固定模型时也会提供这个选项；文档同时写明有的模型始终以扩展窗口运行、没有 [1m] 变体可选。Foundry 页没有对应说明。
权限最小化的写法两边都给了，但落在不同体系上。 Google 侧：分配 roles/aiplatform.user，其中包含所需的 aiplatform.endpoints.predict（文档写明模型调用与 token 计数都要它），要更严就用只含该权限的自定义角色。Foundry 侧：Azure AI User 与 Cognitive Services User 两个默认角色已包含调用所需权限，要更严则建自定义角色，文档给的 dataActions 是 Microsoft.CognitiveServices/accounts/providers/*。
Windows 侧要留意写法。 这两页给出的都是 export ... 形式的 POSIX shell 命令，也就是 Linux / macOS 的写法；官方这两页没有给出 Windows 上的等价命令，本文不替它编。可落地的替代是走 settings 文件的 env 块——Google 那一页明确写了向导就是把结果写进用户 settings 文件的 env 块，其排查段也写明”确认这些变量在你启动 claude 的那个 shell 里已导出，或在 settings 文件的 env 块里设置”。Foundry 页只说 Claude Code 从环境读取这些变量，没有提 settings 文件这条路径，这一点照实标出来。

上述命令与配置片段均按官方文档中的参数语义组合，未经实测，以官方文档与 --help 的实际输出为准。该产品迭代频繁，环境变量名、默认值与版本门槛都随版本变动。

五、怎么确认配对了

两边的验证入口是同一个：启动 Claude Code 后运行 /status，看 API provider 那一行。

Google 侧应显示 Google Vertex AI（又一次的旧名字），并且 GCP project、Default region、Model 三行会分别显示你的项目 ID、区域和解析出来的模型。文档写明：如果 provider 那一行根本不出现，说明环境变量没到进程里——确认它们在启动 claude 的那个 shell 里导出了，或者写进 settings 文件的 env 块。
Foundry 侧应显示 Microsoft Foundry，以及你配的资源名或 base URL。

再往下的两条排查线索也是文档写明的。Foundry 侧如果报 Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed，文档给的处置是在环境上配好 Entra ID，或者改设 ANTHROPIC_FOUNDRY_API_KEY；如果第一个 prompt 上反复连接失败，文档要你检查 ANTHROPIC_FOUNDRY_RESOURCE 是不是还留着占位符没换成真实资源名——端点 URL 是从这个值拼出来的，名字不对就会指向一台不存在的主机。

Google 侧文档给的三类报错处置：Could not load the default credentials 走 gcloud auth application-default login，或把 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号 key 文件；model not found 的 404 要回 Model Garden 确认模型是 Enabled，并确认它在你指定的位置可用（文档写明有些模型只在 global 或 eu / us 这类多区域位置提供）；429 则要确认主模型与小/快模型在所选区域都受支持，文档给的另一条建议是改用 CLOUD_ML_REGION=global。

两页对齐下来，选型上真正会咬到你的是两处：Foundry 没有启动模型检查，模型固定值配错的代价是请求直接失败，而不是像 Google 侧那样先回落再提示；以及Foundry 没有向导，配置都得自己写进环境，团队铺开时更依赖变量下发这件事做对。其余维度上缺依据的那一侧，我们就不比。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

本文对照的是同一产品在两家云平台上的两条接入路径，依据均为上述官方文档，不对两条路径做优劣排名，选型结论只在官方文档写明的能力边界内成立。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。