Appearance
Claude Code 接入 Google Vertex AI
将 Claude Code 接入 Google Vertex AI，让你通过自己的 GCP 项目调用 Claude 模型——数据驻留在你的云账户内，费用走 GCP 账单。本文涵盖：登录向导（个人快速接入）、环境变量手动配置（CI/企业批量部署）、IAM 权限最小化设置、模型版本锁定，以及 1M token 上下文窗口的启用方式。同时提供 404 模型未找到、429 配额超限的排查步骤。
前置条件
使用 Vertex AI 接入 Claude Code 之前，需要：
- 已开通计费的 Google Cloud Platform（GCP）账号
- 已启用 Vertex AI API 的 GCP 项目
- 目标 Claude 模型的访问权限（如 Claude Sonnet 4.6）
- 已安装并配置 Google Cloud SDK（
gcloud） - 目标区域已分配配额
登录向导（快速接入）
如果你有 Google Cloud 凭据，想快速体验 Vertex AI 上的 Claude Code，使用登录向导最省事。GCP 侧的前置操作只需做一次，向导帮你处理 Claude Code 侧的所有配置。
在 Claude Code 中运行 /setup-vertex 进入向导，随时可以重新打开来更改凭据、项目、区域或模型锁定配置。
区域配置
Claude Code 同时支持 Vertex AI 全局端点和区域端点。
手动配置（推荐用于 CI 和企业部署）
如果需要通过环境变量配置——例如在 CI 流水线或脚本化的企业批量部署中——按照以下步骤操作。
1. 启用 Vertex AI API
bash
# 设置项目 ID
gcloud config set project YOUR-PROJECT-ID
# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com2. 申请模型访问权限
- 进入 Vertex AI Model Garden
- 搜索 "Claude" 模型
- 申请你需要的 Claude 模型访问权限（如 Claude Sonnet 4.6）
- 等待审批（通常需要 24~48 小时）
3. 配置 GCP 凭据
Claude Code 使用标准 Google Cloud 认证，详见 Google Cloud 认证文档。
4. 配置 Claude Code 环境变量
bash
# 启用 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
# 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 可以查看哪些模型支持全局端点、哪些只支持区域端点。
使用 Vertex AI 时，/login 和 /logout 命令不可用，认证由 Google Cloud 凭据处理。
5. 锁定模型版本
向团队批量部署时，建议锁定模型版本以保证一致性：
bash
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'未设置锁定变量时，Claude Code 的默认模型为：
| 模型类型 | 默认值 |
|---|---|
| 主要模型 | claude-sonnet-4-5@20250929 |
| 小型/快速模型 | claude-haiku-4-5@20251001 |
如需进一步自定义：
bash
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'启动时模型检查
Claude Code 启动时（需 v2.1.98+），会验证配置的模型在你的 GCP 项目中是否可用。
- 如果锁定的模型版本低于当前默认版本，且你的项目能调用更新版本，Claude Code 会提示升级锁定配置。接受后，新模型 ID 写入用户设置文件并自动重启。
- 如果未锁定模型且当前默认版本在你的项目中不可用，Claude Code 会回退到上一版本并提示。回退不持久，需要在 Model Garden 启用新模型或锁定版本才能永久生效。
IAM 权限配置
roles/aiplatform.user 角色包含以下必要权限：
aiplatform.endpoints.predict：模型调用和 token 计数所需
如需更严格的权限控制，可创建只包含上述权限的自定义角色。详见 Vertex IAM 文档。
1M token 上下文窗口
Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 在 Vertex AI 上支持 1M token 上下文窗口。选择 1M 模型变体后，Claude Code 自动启用扩展上下文窗口。
为锁定的模型启用 1M 上下文窗口：在模型 ID 末尾加 [1m]，详见第三方部署模型锁定。
故障排查
配额问题
通过 Cloud Console 查看当前配额或申请提升。
404 模型未找到
- 确认模型在 Model Garden 中已启用
- 验证你是否有该区域的访问权限
- 使用
CLOUD_ML_REGION=global时，检查模型是否支持全局端点（Model Garden 的"Supported features"中可查） - 不支持全局端点的模型：通过
ANTHROPIC_MODEL或ANTHROPIC_DEFAULT_HAIKU_MODEL指定支持的模型，或用VERTEX_REGION_<MODEL_NAME>指定区域端点
429 请求超限
- 区域端点：确认主模型和小型模型都在你选择的区域中可用
- 考虑切换到
CLOUD_ML_REGION=global以获得更好的可用性
其他资源
常见问题
Q: 用 Vertex AI 时 /login 命令为什么不能用？
使用 Vertex AI 时，认证完全由 Google Cloud 凭据（gcloud 或 Workload Identity）接管，不走 Anthropic 的 OAuth 登录流程，所以 /login 和 /logout 在这个模式下不可用。
Q: 环境变量设置好了但 Claude Code 还是连不上 Vertex AI，怎么排查？
先确认 CLAUDE_CODE_USE_VERTEX=1 已设置，然后运行 gcloud auth application-default print-access-token 验证 GCP 凭据有效。还要检查目标区域是否已分配配额，以及 Vertex AI API 是否已在该项目中启用。
Q: 为什么建议在部署前锁定模型版本？
Claude Code 默认模型会随新版本更新而变化。如果不锁定版本，某次 Claude Code 升级后可能使用你项目中未启用的新模型，导致部署中断。锁定版本可以确保团队环境一致，变更可控。