Claude Code官方文档GCPVertex AI云部署

Claude Code on Google Vertex AI - GCP 配置与 IAM 完整指南

通过 Google Vertex AI 配置 Claude Code，包括登录向导、区域端点、IAM 配置、模型固定和故障排除。

· 阅读约 15 分钟

Google Vertex AI 上的 Claude Code

了解如何通过 Google Vertex AI 配置 Claude Code，包括设置、IAM 配置和故障排除。

跨组织部署 Claude Code？ 与销售人员讨论企业计划、SSO 和集中式计费。查看计划 | 联系销售

前置条件

在使用 Vertex AI 配置 Claude Code 之前，请确保您拥有：

  • 启用了计费的 Google Cloud Platform (GCP) 账户
  • 启用了 Vertex AI API 的 GCP 项目
  • 对所需 Claude 模型的访问权限（例如，Claude Sonnet 4.6）
  • 已安装并配置的 Google Cloud SDK (gcloud)
  • 在所需 GCP 区域中分配的配额

要使用您自己的 Vertex AI 凭证登录，请按照下面的使用 Vertex AI 登录进行操作。要在团队中部署 Claude Code，请使用手动设置步骤并在推出前固定您的模型版本。

使用 Vertex AI 登录

如果您拥有 Google Cloud 凭证并想开始通过 Vertex AI 使用 Claude Code，登录向导会引导您完成整个过程。您需要在每个项目中完成一次 GCP 端的前置条件；向导会处理 Claude Code 端的事务。

ℹ️ Vertex AI 设置向导需要 Claude Code v2.1.98 或更高版本。运行 claude --version 来检查。

步骤 1：在您的 GCP 项目中启用 Claude 模型

为您的项目启用 Vertex AI API，然后在 Vertex AI Model Garden 中请求访问您想要的 Claude 模型。有关您的账户需要的权限，请参阅 IAM 配置。

步骤 2：启动 Claude Code 并选择 Vertex AI

运行 claude。在登录提示处，选择 3rd-party platform，然后选择 Google Vertex AI。

步骤 3：按照向导提示进行操作

选择您如何向 Google Cloud 进行身份验证：来自 gcloud 的应用默认凭证、服务账户密钥文件或已在您的环境中的凭证。向导会检测您的项目和区域，验证您的项目可以调用哪些 Claude 模型，并让您固定它们。它将结果保存到您的用户设置文件的 env 块中，因此您无需自己导出环境变量。

登录后，您可以随时运行 /setup-vertex 来重新打开向导并更改您的凭证、项目、区域或模型固定。

区域配置

Claude Code 支持 Vertex AI 全局、多区域和区域端点。将 CLOUD_ML_REGION 设置为 global、多区域位置（如 eu 或 us）或特定区域（如 us-east5）。Claude Code 为每种形式选择正确的 Vertex AI 主机名，包括多区域位置的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com 主机。

ℹ️ Vertex AI 可能不支持 Claude Code 默认模型在每个端点类型上。模型可用性在特定区域、多区域位置和全局端点之间有所不同。您可能需要切换到支持的位置或指定支持的模型。

手动设置

要通过环境变量而不是向导配置 Vertex AI，例如在 CI 或脚本化企业推出中，请按照下面的步骤进行。

1. 启用 Vertex AI API

在您的 GCP 项目中启用 Vertex AI API：

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

# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com

2. 请求模型访问权限

请求访问 Vertex AI 中的 Claude 模型：

  1. 导航到 Vertex AI Model Garden
  2. 搜索”Claude”模型
  3. 请求访问所需的 Claude 模型（例如，Claude Sonnet 4.6）
  4. 等待批准（可能需要 24-48 小时）

3. 配置 GCP 凭证

Claude Code 使用标准的 Google Cloud 身份验证。

有关更多信息，请参阅 Google Cloud 身份验证文档。

Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持基于 X.509 证书的工作负载身份联合。将 GOOGLE_APPLICATION_CREDENTIALS 设置为您的凭证配置文件的路径。

ℹ️ Claude Code 使用 ANTHROPIC_VERTEX_PROJECT_ID 作为 Vertex AI 请求的项目 ID。GCLOUD_PROJECT 和 GOOGLE_CLOUD_PROJECT 环境变量以及 GOOGLE_APPLICATION_CREDENTIALS 引用的凭证文件优先于它。如果这些都未设置，项目 ID 将从您的 gcloud 配置或附加的服务账户解析。

高级凭证配置

Claude Code 通过 gcpAuthRefresh 设置支持 GCP 的自动凭证刷新。当 Claude Code 检测到您的 GCP 凭证已过期或无法加载时，它会运行配置的命令以在重试请求之前获取新凭证。

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

命令的输出会显示给用户，但不支持交互式输入。这对于基于浏览器的身份验证流程效果很好，其中 CLI 显示 URL，您在浏览器中完成身份验证。如果身份验证未在三分钟内完成，刷新命令将超时。如果您在项目设置（如 .claude/settings.json）中设置 gcpAuthRefresh，该命令仅在您接受工作区信任提示后运行。

4. 配置 Claude Code

设置以下环境变量：

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

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

# 可选：如果需要，禁用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 可选：请求 1 小时的 prompt cache TTL 而不是 5 分钟的默认值
export ENABLE_PROMPT_CACHING_1H=1

# 当 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_* 变量。有关完整列表，请参阅环境变量参考。检查 Vertex Model Garden 以确定哪些模型支持全局端点与仅区域端点。

Prompt caching 会自动启用。要禁用它，请设置 DISABLE_PROMPT_CACHING=1。要请求 1 小时的缓存 TTL 而不是 5 分钟的默认值，请设置 ENABLE_PROMPT_CACHING_1H=1；具有 1 小时 TTL 的缓存写入按更高费率计费。如需提高速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，/login 和 /logout 命令被禁用，因为身份验证通过 Google Cloud 凭证处理。

MCP tool search 在 Vertex AI 上默认被禁用，因为端点不接受所需的 beta 标头。所有 MCP 工具定义会预先加载。要选择加入，请设置 ENABLE_TOOL_SEARCH=true。

5. 固定模型版本

⚠️ 警告：在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 sonnet 和 opus）会解析为最新版本，当 Anthropic 发布更新时，该版本可能尚未在您的 Vertex AI 项目中启用。Claude Code 在启动时当最新版本不可用时会回退到之前的版本，但固定让您可以控制用户何时迁移到新模型。

将这些环境变量设置为特定的 Vertex AI 模型 ID。

如果没有 ANTHROPIC_DEFAULT_OPUS_MODEL，Vertex 上的 opus 别名会解析为 Opus 4.6。将其设置为 Opus 4.7 ID 以使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

有关当前和旧版模型 ID，请参阅模型概览。有关完整的环境变量列表，请参阅模型配置。

Claude Code 在未设置固定变量时使用这些默认模型：

模型类型默认值
主模型claude-sonnet-4-5@20250929
小型/快速模型claude-haiku-4-5@20251001

要进一步自定义模型：

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

启动模型检查

当 Claude Code 启动并配置了 Vertex AI 时，它会验证它打算使用的模型在您的项目中是否可访问。此检查需要 Claude Code v2.1.98 或更高版本。

如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的项目可以调用较新版本，Claude Code 会提示您更新固定。接受会将新的模型 ID 写入您的用户设置文件并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。

如果您没有固定模型，并且当前默认值在您的项目中不可用，Claude Code 会在当前会话中回退到之前的版本并显示通知。回退不会被持久化。在 Model Garden 中启用较新的模型或固定一个版本以使选择永久化。

IAM 配置

分配所需的 IAM 权限：

roles/aiplatform.user 角色包括所需的权限：

  • aiplatform.endpoints.predict - 模型调用和令牌计数所需

对于更严格的权限，请创建仅包含上述权限的自定义角色。

有关详细信息，请参阅 Vertex IAM 文档。

ℹ️ 为 Claude Code 创建专用的 GCP 项目，以简化成本跟踪和访问控制。

1M token context window

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Vertex AI 上支持 1M token context window。当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。

设置向导在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 [1m]。有关详细信息，请参阅为第三方部署固定模型。

故障排除

如果您遇到”无法加载默认凭证”错误：

  • 运行 gcloud auth application-default login 来设置应用默认凭证
  • 将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账户密钥文件路径
  • 查看 配置 GCP 凭证 了解所有选项

如果您遇到配额问题：

如果您遇到”模型未找到”404 错误：

  • 确认模型在 Model Garden 中已启用
  • 验证该模型在您指定的位置可用。某些模型仅在 global 或多区域位置（如 eu 和 us）上提供，而不是在特定区域
  • 如果使用 CLOUD_ML_REGION=global，请检查您的模型是否在 Model Garden 中的”支持的功能”下支持全局端点。对于不支持全局端点的模型，请执行以下任一操作：
    • 通过 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支持的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域或多区域位置

如果您遇到 429 错误：

  • 对于区域端点，请确保主模型和小型/快速模型在您选择的区域中受支持
  • 考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性

其他资源

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。