将 Claude Code 接入 Google Vertex AI，确保数据驻留在你的 GCP 项目内、费用走 GCP 账单。本文提供登录向导快速接入、手动环境变量配置（适用于CI和批量部署）、IAM 权限最小化设置、模型版本锁定，以及1M token上下文窗口启用方法，同时给出404模型未找到和429配额超限的排查步骤。

Claude Code 接入 Google Vertex AI 配置与故障排查

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.
View plans | Contact sales

前置条件

在配置 Vertex AI 集成前，确保你已具备：

一个已启用计费的 Google Cloud Platform（GCP）账号
一个已启用 Vertex AI API 的 GCP 项目
目标 Claude 模型的访问权限（例如 Claude Sonnet 4.6）
已安装并配置好了 Google Cloud SDK（gcloud）
目标 GCP 区域已分配配额

若要使用个人 Vertex AI 凭据登录，直接到下方的登录向导部分。如果要在团队中批量部署 Claude Code，则使用手动配置步骤，并在推广之前锁定模型版本。

登录向导

如果你已有 Google Cloud 凭据，想快速通过 Vertex AI 使用 Claude Code，登录向导会引导你完成全部操作。GCP 侧的前置条件每个项目只需做一次，向导会处理 Claude Code 侧的所有配置。

Vertex AI 登录向导需要 Claude Code v2.1.98 或更高版本。运行 claude --version 确认版本。

为你的项目启用 Vertex AI API，然后在 Vertex AI Model Garden 中申请你需要的 Claude 模型的访问权限。参见 IAM 权限配置了解你的账号所需的权限。
运行 claude。在登录提示中选择 第三方平台，然后选择 Google Vertex AI。
选择认证方式：使用 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 的默认模型。模型可用性因特定区域、多区域位置和全局端点而异。你可能需要切换到一个支持的位置，或指定一个支持的模型。

手动配置（建议用于 CI 和企业部署）

如果希望通过环境变量而非向导配置 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 模型的访问权限：

进入 Vertex AI Model Garden
搜索 “Claude” 模型
申请你需要的 Claude 模型（例如 Claude Sonnet 4.6）
等待审批（通常需要 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 优先级依次高于 ANTHROPIC_VERTEX_PROJECT_ID。如果都没有设置，则从 gcloud 配置或附加的服务账号中解析项目 ID。

高级凭据配置

Claude Code 通过 gcpAuthRefresh 设置支持自动刷新 GCP 凭据。当检测到 GCP 凭据过期或无法加载时，会运行配置的命令获取新凭据，然后重试请求。

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

该命令的输出会展示给用户，但不支持交互式输入。这种方式适用于基于浏览器的认证流程（CLI 显示一个 URL，你在浏览器中完成认证）。如果认证在三分钟内未完成，刷新命令会超时。如果 gcpAuthRefresh 设置在项目设置（如 .claude/settings.json）中，则只有你接受工作区信任提示后才会运行该命令。

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 时，/login 和 /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. 锁定模型版本

向多个用户部署时，务必锁定特定的模型版本。如果不锁定，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 上 Haiku 可能未在每个项目或区域启用，Claude Code 会默认使用主要模型作为后台任务模型。如果想使用 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 启动时（需要 v2.1.98 或更新版本），它会验证计划使用的模型在你的项目中是否可访问。

如果你锁定了一个比当前 Claude Code 默认版本更旧的模型版本，而你的项目可以调用较新的版本，Claude Code 会提示你更新锁定。接受后，新模型 ID 会写入你的用户设置文件并重新启动 Claude Code。拒绝则会被记住，直到下一次默认版本变更。
如果你没有锁定模型，且当前默认版本在你的项目中不可用，Claude Code 会回退到上一版本，并在当前会话中显示通知。回退不会持久。要在 Model Garden 中启用较新的模型，或锁定一个版本来永久决定。

IAM 权限配置

分配必要的 IAM 权限：

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

aiplatform.endpoints.predict — 模型调用和 token 计数所需

如需更严格的权限控制，可以创建一个仅包含上述权限的自定义角色。详情参见 Vertex IAM 文档。

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

1M token 上下文窗口

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

在登录向导中，锁定模型时会提供 1M 上下文选项。如果你想在手动锁定的模型上启用它，在模型 ID 后面追加 [1m]。详情参见第三方部署的模型锁定。

故障排查

"无法加载默认凭据"错误

运行 gcloud auth application-default login 设置应用默认凭据
设置 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号密钥文件路径
参见配置 GCP 凭据了解所有选项

配额问题

通过 Cloud Console 查看当前配额或申请提升

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？

设置三个必选环境变量：CLAUDE_CODE_USE_VERTEX=1、CLOUD_ML_REGION（如 global）、ANTHROPIC_VERTEX_PROJECT_ID 为你的 GCP 项目 ID。如果需要自定义端点或网关，可以设置 ANTHROPIC_VERTEX_BASE_URL。更多可选变量（提示缓存、区域覆盖等）参见上面的手动配置章节。

遇到 404 模型未找到错误怎么解决？

先确认模型在 Vertex AI Model Garden 中已启用。然后检查模型是否在你指定的区域可用：某些模型只支持全局端点或多区域位置（eu、us），不支持具体区域。如果使用 CLOUD_ML_REGION=global，在 Model Garden 中查看模型是否标注了 “Supports global endpoint”。不支持全局端点的模型，要么更换为支持的模型，要么用 VERTEX_REGION_<MODEL_NAME> 指定一个区域端点。

为什么建议在部署前锁定模型版本？

Claude Code 的默认模型（如 sonnet、opus 别名）会随新版本发布自动更新。如果不锁定，当 Anthropic 推出新版但你的 Vertex AI 项目尚未启用该模型时，Claude Code 启动时会先检查新版本是否可用，若不可用则回退到旧版本。锁定版本可以保证团队环境一致，避免意外中断。操作方式：设置环境变量 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 为具体的模型 ID。

Claude Code 接入 Google Vertex AI 配置与故障排查 #

前置条件 #

登录向导 #

区域配置 #

手动配置（建议用于 CI 和企业部署） #

1. 启用 Vertex AI API #

2. 申请模型访问权限 #

3. 配置 GCP 凭据 #

高级凭据配置 #

4. 配置 Claude Code #

5. 锁定模型版本 #

启动时模型检查 #

IAM 权限配置 #

1M token 上下文窗口 #

故障排查 #

其他资源 #

常见问题 #

如何用手动配置（环境变量）接入 Vertex AI？ #

遇到 404 模型未找到错误怎么解决？ #

为什么建议在部署前锁定模型版本？ #