Google Cloud Agent Platform

通过 Google Cloud 的 Agent Platform（原 Vertex AI）使用 Claude Code：登录向导、区域配置、手动设置、固定模型、IAM 与排障。

本页讲通过 Google Cloud 的 Agent Platform（原 Vertex AI）配置 Claude Code。

前置条件

启用了计费的 Google Cloud Platform（GCP）账号
启用了 Agent Platform API 的 GCP 项目
对想要的 Claude 模型的访问权限（如 Claude Sonnet 4.6）
已安装并配置的 Google Cloud SDK（gcloud）
在所需 GCP 区域分配的配额

用 Agent Platform 登录

如果你有 Google Cloud 凭据并想通过 Agent Platform 开始使用 Claude Code，登录向导会带你完成（GCP 侧的前置条件每个项目完成一次，向导处理 Claude Code 一侧）：

为你的项目启用 Agent Platform API，然后在 Model Garden 请求对想要的 Claude 模型的访问权限
运行 claude。在登录提示处选 3rd-party platform，然后选 Google Vertex AI（登录提示仍用这个标签指代 Agent Platform）。如果你已经登录，运行 /login 打开同样的菜单
选择如何向 Google Cloud 认证：来自 gcloud 的应用默认凭据（ADC）、服务账号密钥文件，或你环境里已有的凭据。向导会询问你的项目和区域，验证你的项目能访问哪些 Claude 模型

登录之后，随时运行 /setup-vertex 重新打开向导，更改凭据、项目、区域或模型固定。

区域配置

Claude Code 支持 Agent Platform 的全局、多区域和区域端点。把 CLOUD_ML_REGION 设为 global、多区域位置或具体区域。Agent Platform 可能并非在每种端点类型上都支持 Claude Code 的默认模型；模型可用性因区域而异。

手动设置

想通过环境变量而不是向导配置，按以下步骤。

1. 启用 Agent Platform API

在你的 GCP 项目里启用 Agent Platform API（把 YOUR-PROJECT-ID 换成你的 GCP 项目 ID）：

# 设置你的项目 ID
gcloud config set project YOUR-PROJECT-ID

# 启用 Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. 请求模型访问

在 Agent Platform 里请求对 Claude 模型的访问：打开 Model Garden，搜索「Claude」模型，请求对想要的 Claude 模型的访问（如 Claude Sonnet 4.6），然后等待批准（可能需要 24–48 小时）。

3. 配置 GCP 凭据

Claude Code 使用标准的 Google Cloud 认证。Claude Code 把 Agent Platform 的请求发往 ANTHROPIC_VERTEX_PROJECT_ID 里的项目，即使 GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT 或 GOOGLE_APPLICATION_CREDENTIALS 引用的凭据文件带有不同的项目。

Claude Code 通过 gcpAuthRefresh 设置支持 GCP 凭据的自动刷新。把它加到你的 Claude Code 设置文件里（如 ~/.claude/settings.json）：

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

Claude Code 检测到你的 GCP 凭据已过期时会运行这条命令；运行之前，它会用当前凭据请求一个访问令牌来确认它们确实过期了，凭据仍有效时跳过命令。Claude Code 会显示命令的输出，但不能给命令发送交互式输入，所以适合基于浏览器的认证流程。

4. 配置 Claude Code

设置下面的环境变量：

# 启用 Agent Platform 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可选：为自定义端点或网关覆盖 Agent Platform 端点 URL
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 当 CLOUD_ML_REGION=global 时，为不支持全局端点的模型覆盖区域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

大多数模型版本都有对应的 VERTEX_REGION_CLAUDE_* 变量。如果区域值的形态不像区域或位置名，Claude Code 把它视为未设置：VERTEX_REGION_CLAUDE_* 回退到 CLOUD_ML_REGION，CLOUD_ML_REGION 回退到 us-east5。

5. 固定模型版本

向多个用户部署时要固定特定的模型版本，否则 sonnet 和 opus 这类别名会解析为 Claude Code 对 Agent Platform 的内置默认值，它可能落后于最新发布，也可能尚未在你的项目里启用。

没有 ANTHROPIC_DEFAULT_OPUS_MODEL 时，Agent Platform 上的 opus 别名解析为 Opus 5.5；没有 ANTHROPIC_DEFAULT_SONNET_MODEL 时，sonnet 别名解析为 Sonnet 4.5。这个例子把每个别名固定到特定版本：

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@20251001'

没有设置固定变量时，Claude Code 的默认模型是：主模型 claude-opus-5-5，小型/快速模型 claude-sonnet-4-5@20250929。想进一步定制：

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

6. 验证你的配置

启动 Claude Code 并运行 /status 确认设置：API provider 一行显示 Google Vertex AI，GCP project、Default region 和 Model 几行显示你的项目 ID、区域和解析出的模型。

IAM 配置

分配 roles/aiplatform.user 角色，它包含所需权限：aiplatform.endpoints.predict（模型调用和 token 计数所需）。想要更严格的权限，创建只包含上述权限的自定义角色。建议为 Claude Code 创建专用的 GCP 项目，以简化成本追踪和访问控制。

排障

「Could not load the default credentials」：运行 gcloud auth application-default login 设置应用默认凭据；或把 GOOGLE_APPLICATION_CREDENTIALS 设为服务账号密钥文件路径
配额问题：通过 Cloud Console 检查当前配额或申请提高配额
「model not found」404 错误：确认模型在 Model Garden 里是 Enabled；确认模型在你指定的位置可用（有些模型只在 global 或 eu、us 这类多区域位置提供，而不在特定区域）；使用 CLOUD_ML_REGION=global 时，在 Model Garden 的「Supported features」下检查你的模型是否支持全局端点，不支持的话，用 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定受支持的模型，或用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域或多区域位置
429 错误：对区域端点，确保主模型和小型/快速模型在所选区域受支持；考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性