在 Google Cloud 上设置 Claude（Google 托管）

当您的公司通过 Google Cloud 的 Agent Platform 购买 Claude 时，Claude Code、Claude Desktop 以及您构建的所有应用都会通过您自己的 Google Cloud 项目访问 Claude。 您使用 Google Cloud 凭据登录，因此不需要 Anthropic API 密钥，用量由 Google Cloud 计费。

设置分为四个部分。先由某人一次性让项目就绪，然后每个人各自为自己授予访问权限。接下来，您从终端向 Claude 发送一个请求并获取回复。之后，您将所用的应用指向该项目。如果您只从自己的代码中调用 Claude，可以在收到回复后就停止。对于 Claude Code，当它回答您，且 /status 显示出您的项目 ID 时，就算完成了。

Google Cloud 将 Claude 作为两种服务出售，设置方式各不相同。因此第一步是确认您拥有的是哪一种。

确认您拥有的是哪种服务

这两种服务的区别在于由谁来运行 Claude。 在 Claude Models on Google Cloud（Google 托管）中，Google 作为 Google Cloud 的 Agent Platform（原 Vertex AI）的一部分来运行 Claude 模型。Agent Platform 是 Google Cloud 中这些步骤所涉及的部分：您需要开启其 API、获取它的某个角色，您的用量会作为 Agent Platform 用量计费。而在 Anthropic 托管服务中，是由 Anthropic 来运行 Claude API。

要判断您所使用的是哪一种，请查看您已经拥有的某些信息。下表列出了需要查看的内容。

Model Garden 是 Google Cloud 控制台中的一个部分，其中每个模型都有自己的卡片。

请求 URL 是第三个判断依据。在 Google 托管服务上，它们指向 Agent Platform 主机，URL 路径中包含 .../publishers/anthropic/models/{model}。两种服务概述 列出了这些主机。

如果您使用的是 Anthropic 托管服务，请改为参阅在 Google Cloud 上设置 Claude（Anthropic 托管）。如果您使用 API 密钥调用 api.anthropic.com，则您使用的两种服务都不是。

您需要准备什么，以及费用如何

在开始之前，请准备好以下内容：

• 一个已开启计费功能的 Google Cloud 项目，及其项目 ID
• 在您将使用的区域内，您所用 Claude 模型的配额。Google 的 Anthropic Claude 模型配额 列出了默认配额，并说明在哪里查看您项目的配额或申请增加配额。
• gcloud CLI，Google Cloud 的命令行工具
• curl 和一个 Bash shell，用于发送测试请求
• Claude Code（2.1.293 或更高版本），如果您将使用它的话。要更新它，请运行 claude update。

下方命令中出现 YOUR-PROJECT-ID 或 PROJECT_ID 的地方，请将其替换为您的项目 ID。

如果您刚安装了 gcloud CLI，请使用 gcloud auth login 或 gcloud init 登录。这是 gcloud CLI 自身的登录方式，测试请求会用到它。Application Default Credentials（Claude Code 会用到它）是一种单独的登录方式，属于“为自己授予访问权限”部分。

Google Cloud 会将用量作为 Agent Platform 用量计费。 这包括您从 Claude Code 或 Claude Desktop 发送的内容。要查询价格，请从此服务文档页面的计费部分开始。

一次性让项目就绪

在任何人可以从某个项目调用 Claude 之前，该项目需要开启 Agent Platform API 并启用一个 Claude 模型。这些步骤每个 Google Cloud 项目只需做一次，通常由管理员完成。 如果已经有人为您的项目完成了这些步骤，请直接跳到“为自己授予访问权限”。

1. 开启 Agent Platform API。将 gcloud 指向该项目，然后启用 aiplatform.googleapis.com 服务。

   bash

   gcloud config set project YOUR-PROJECT-ID
   gcloud services enable \
     aiplatform.googleapis.com

   Google 的 Claude 模型使用前准备步骤 涵盖了这一步和计费检查。

2. 在 Model Garden 中启用您将使用的 Claude 模型。Google 列出了 Claude 模型卡片。打开每个模型的卡片并点击 Enable。对于 Claude Code，请启用 claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5 和 claude-sonnet-5。您将在连接 Claude Code 时固定前三个模型。不要固定 Claude Sonnet 5。固定这些模型后，它会成为自动模式下检查操作的默认模型，而自动模式正是该服务上交互式会话默认启动的模式，除非您设置了其他模式。如果不固定，Claude Code 会使用一个默认的 Claude Sonnet 模型，而该模型在此服务上已弃用。

点击 Enable 的人必须在身份和访问管理（IAM）中拥有 Consumer Procurement Entitlement Manager 角色。其 ID 为 roles/consumerprocurement.entitlementManager。

为自己授予访问权限

项目已准备就绪，但您自己的账户仍需要调用 Claude 的权限，以及一种 Claude Code 可以使用的登录方式。每个人都要为自己的账户执行以下步骤。

1. 将 gcloud 指向该项目。

   bash

   gcloud config set project YOUR-PROJECT-ID

2. 获取一个能让您调用 Claude 的角色。发起调用的身份需要一个包含 aiplatform.endpoints.predict 权限的 IAM 角色，例如 Agent Platform User（roles/aiplatform.user）。以下命令会授予该角色：

   bash

   gcloud projects add-iam-policy-binding \
     PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/aiplatform.user

   将 PRINCIPAL 替换为 user: 加上您的电子邮箱地址，例如 user:you@example.com。Google 关于授予访问权限的页面 展示了 PRINCIPAL 可以采用的其他形式。如果您没有权限更改该项目的 IAM 策略，请请管理员代您运行该命令。

3. 使用 Application Default Credentials 登录。这是 Claude Code 在调用 Claude 时使用的 Google Cloud 凭据。

   bash

   gcloud auth application-default login

向 Claude 发送一个测试请求

在连接应用之前，先向 Claude 发送一个请求。 收到回复即表示项目和您的访问权限都正常工作。该请求会直接调用 Agent Platform API，就像您构建的应用所做的那样。

1. 确认 gcloud CLI 当前登录的账户。该请求会从 gcloud CLI 自身的登录中获取令牌，而不是来自 Application Default Credentials。

   bash

   gcloud auth list

   当前活动账户必须是在“为自己授予访问权限”中获得角色的那个账户。如果不是，请运行 gcloud auth login。

2. 发送请求。请先将 YOUR-PROJECT-ID 替换为您的实际项目 ID。Google Cloud 会像对待其他请求一样对此请求计费。

   bash

   curl https://aiplatform.googleapis.com/v1/projects/YOUR-PROJECT-ID/locations/global/publishers/anthropic/models/claude-opus-5-5:rawPredict \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "anthropic_version": "2026-10-21",
       "messages": [{"role": "user", "content": "Hey Claude!"}],
       "max_tokens": 100
     }'

   此请求使用 global 区域。如果您需要数据驻留（data residency），主机和路径都会发生变化。文档中展示了在 us 多区域上的相同请求。

3. 阅读回复。回复是 JSON 格式，Claude 的话在 type 为 text 的 content 条目中。您实际得到的内容在措辞和字段数量上都会和以下这份精简版不同：

   json

   {
     "type": "message",
     "role": "assistant",
     "content": [{"type": "text", "text": "Hello! Nice to meet you."}],
     "stop_reason": "end_turn"
   }

错误同样以 JSON 形式返回，其中包含以下代码之一：

这些代码可在 Google 的 API 错误列表 中查到。收到回复后，如果某个应用无法连接到 Claude，请先检查该应用的登录状态和设置。

连接 Claude Code 或 Claude Desktop

在项目已就绪、您的访问权限已到位，并且已收到 Claude 的回复之后，将您所使用的应用指向该项目。两个应用都会要求提供相同的两个值：您的项目 ID 和一个区域。以下步骤使用 global 区域。

如果您需要数据驻留，请使用 us 或 eu 多区域。 它比 global（将请求发送到任何有可用容量的区域）贵 10%。区域端点仅服务于 Claude Sonnet 4.6 及更早版本的模型。文档中比较了 global、多区域和区域端点。

Claude Code

登录向导会处理 Claude Code 这一侧的设置。

1. 启动 Claude Code。

   bash

   claude

2. 选择 Agent Platform。 在登录提示中，选择 3rd-party platform，然后选择 Google Vertex AI。这是登录提示中目前仍用来指代 Google Cloud 的 Agent Platform 的标签。如果您已经登录，请运行 /login 打开同一菜单。

3. 按照向导的提示操作。 当它询问您如何向 Google Cloud 进行身份验证时，选择来自 gcloud 的 Application Default Credentials，这是您在“为自己授予访问权限”中设置好的。然后提供您的项目 ID 和区域 global。向导会验证您的项目可以调用哪些 Claude 模型，并让您固定这些模型。将三个都固定：claude-opus-5-5、claude-sonnet-5-5 和 claude-haiku-5-5。如果向导默认显示的是某个模型的其他版本，请在固定之前先更改它。固定了一个 Haiku 模型后，Claude Code 会用它来处理后台任务。向导会将结果保存到您的用户设置文件中，因此您无需自行导出环境变量。

4. 向 Claude Code 发送一条消息。 当它回答时，说明 Claude Code 正在通过 Google Cloud 访问 Claude。

检查它使用的是您所指定的项目。 运行 /status。API provider 一行会显示 Google Vertex AI。GCP project、Default region 和 Model 这几行会显示您的项目 ID、区域以及解析出的模型。将该项目 ID 与“一次性让项目就绪”中的项目进行比较。

Claude Opus 模型的单位令牌价格高于 Sonnet 模型。 即使三个模型都已固定，Claude Code 的主模型仍然是 Opus，因此在您使用 /model 切换模型之前，都会按 Opus 费率计费。要在之后更改模型固定、项目、区域或凭据，请运行 /setup-vertex 重新打开向导。

要在不使用向导的情况下设置 Claude Code（例如在 CI 或脚本化部署中），请在启动 claude 的 shell 中设置以下环境变量：

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-5-5'

如果此后 /status 没有显示 API provider 一行，说明这些变量没有传递到进程中。手动设置步骤 涵盖了其余内容，包括如何为团队固定模型版本。

Claude Desktop

Claude Desktop 可以通过同一个项目使用 Claude 模型，Claude Cowork 会话也在该应用中运行。IT 管理员通常会将其部署到每台设备上，所以请先询问您的设备上是否已经部署。要在一台设备上试用，请手动填写相同的值。

1. 打开应用内配置窗口。 依次进入 Help → Troubleshooting → Enable Developer Mode，然后 Developer → Configure Third-Party Inference…。

2. 选择提供方。 在 Connection 部分，将 Inference provider 设置为 Vertex AI。

3. 填写 Vertex AI 凭据卡片。 在 GCP project ID 中填入您的项目 ID，在 GCP region 中填入一个区域。该区域可以是 global。然后提供恰好一种凭据来源。GCP credentials file path 接受 gcloud auth application-default login 生成的文件。Google 列出了该文件的保存位置。

4. 添加一个模型。 在 Models 下，添加至少一条 Model list 条目，使用您已启用的某个模型的发布者模型 ID，例如 claude-opus-5-5。

5. 应用设置。 点击 Apply Changes。应用会仅将该配置写入此设备，并以该配置重新启动。然后发送一条消息，检查 Claude 是否作答。

在 Google Cloud 的 Agent Platform 上以第三方方式部署 Claude Desktop 涵盖了其他登录方式，以及如何将设置推送到每台设备。

如果无法正常工作

以下错误可能会导致 Claude Code 无法连接到 Claude。在表中找到您遇到的情况，然后应用相应的修复方法。

某个模型可能在某个位置不可用。 有些模型仅在 global 或诸如 eu 和 us 这样的多区域位置提供，而不在特定区域提供。如果您更改区域，请确认您的模型在该区域可用。

这些修复方法来自 Claude Code on Google Cloud's Agent Platform 的故障排除，其中内容更详细。对于 Claude Desktop，请从其自身的故障排除部分开始。

下一步该做什么

请将您的项目 ID 和区域保存在方便查找的地方。 Claude Code、Claude Desktop 以及各种 SDK 客户端都会要求提供这些信息。

• 要学习 Claude Code， 请先学习 Claude Code 101，再学习 Claude Code in action。
• 要学习 Claude Cowork， 请学习 Claude Cowork 简介。
• 要从您自己的代码中调用 Claude， 请参阅 Google 托管文档页面。它展示了如何安装 SDK，以及如何使用 AnthropicVertex 客户端发出请求。

关于该服务本身的更多信息，文档中针对以下每个主题都有专门的章节：

• 全局、多区域和区域端点
• 速率限制
• 监控和日志记录
• 计费