文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

Google Vertex AI 上的 Claude Code

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

前提条件

在通过 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 端。

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 的 Application Default Credentials、服务账户密钥文件，或环境中的凭据。向导检测你的项目和区域，验证你的项目可以调用哪些 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（例如在 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 或更高版本通过相同的 Application Default Credentials 链支持基于 X.509 证书的 Workload Identity Federation。将 GOOGLE_APPLICATION_CREDENTIALS 设置为你的凭据配置文件路径。

高级凭据配置

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

# 可选：如需要禁用提示缓存
export DISABLE_PROMPT_CACHING=1

# 可选：请求 1 小时提示缓存 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 以确定哪些模型支持全球端点而非仅区域端点。

提示缓存默认启用。要禁用它，设置 DISABLE_PROMPT_CACHING=1。要请求 1 小时缓存 TTL 而非默认的 5 分钟，设置 ENABLE_PROMPT_CACHING_1H=1；1 小时 TTL 的缓存写入按更高费率计费。如需更高的速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，/logout 命令不可用，因为认证通过 Google Cloud 凭据处理。

Claude Code 默认在 Vertex AI 上禁用 MCP 工具搜索，因此 MCP 工具定义预先加载。Vertex AI 支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本的工具搜索。设置 ENABLE_TOOL_SEARCH=true 以在这些模型上启用它。Vertex AI 上的早期模型不接受所需的 beta 标头，如果你对它们启用工具搜索，请求会失败。

5. 固定模型版本

将这些环境变量设置为特定的 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 使用以下默认模型：

会话标题生成等后台任务使用小型/快速模型，通常是 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 文档。

100 万令牌上下文窗口

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Vertex AI 上支持100 万令牌上下文窗口。当你选择 100 万模型变体时，Claude Code 自动启用扩展上下文窗口。

设置向导在固定模型时提供 100 万上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 [1m]。有关详情，请参阅为第三方部署固定模型。

故障排除

如果你遇到 "Could not load the default credentials" 错误：

• 运行 gcloud auth application-default login 设置 Application Default Credentials
• 将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账户密钥文件路径
• 有关所有选项，请参阅配置 GCP 凭据

如果你遇到配额问题：

• 通过 Cloud Console 检查当前配额或请求增加配额

如果你遇到 "model not found" 404 错误：

• 在 Model Garden 中确认模型已启用
• 验证模型在你指定的位置可用。某些模型仅在 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 以获得更好的可用性

附加资源

• Vertex AI 文档
• Vertex AI 定价
• Vertex AI 配额和限制