跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
前置条件

在使用 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 凭证处理。 Claude Code 在 Vertex AI 上默认禁用 MCP tool search，因此 MCP 工具定义会预先加载。Vertex AI 支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本的工具搜索。设置 ENABLE_TOOL_SEARCH=true 以在这些模型上启用它。Vertex AI 上的早期模型不接受所需的 beta 标头，如果您对它们启用工具搜索，请求将失败。

​
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
小型/快速模型与主模型相同
后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Vertex AI 上，Claude Code 默认将其设置为主模型，因为 Haiku 可能不会在每个项目或区域中启用。要为后台任务使用 Haiku，请将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设置为在您的项目中可用的模型 ID。 要进一步自定义模型： 
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 以获得更好的可用性

​
其他资源