Google Vertex AI 是 GCP 原生的 Claude 部署方案，支持全局端点和区域端点，并为 Claude Sonnet 4/4.6 提供 1M Token 超长上下文窗口。
前提条件
- GCP 账号，已启用计费
- 项目中已启用 Vertex AI API
- 已申请 Claude 模型访问权限（审批可能需要 24-48 小时）
- 已安装并配置 Google Cloud SDK（
gcloud） - 已在目标区域分配配额
配置步骤
Step 1：启用 Vertex AI API
bash
# 设置项目 ID
gcloud config set project YOUR-PROJECT-ID
# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.comStep 2：申请模型访问权限
- 打开 Vertex AI Model Garden
- 搜索「Claude」模型
- 申请所需模型的访问权限
- 等待审批（通常 24-48 小时）
Step 3：配置 GCP 凭证
Claude Code 使用标准 Google Cloud 认证，推荐使用应用默认凭证：
bash
# 使用 gcloud 登录（本地开发）
gcloud auth application-default login
# 或在生产环境使用服务账号
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.jsonStep 4：启用 Vertex AI 集成
使用全局端点（推荐）：
bash
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID使用区域端点：
bash
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID⚠️ 启用 Vertex AI 后，
/login和/logout命令被禁用，认证通过 GCP 凭证处理。
Step 5：全局端点的区域覆盖
使用 CLOUD_ML_REGION=global 时，部分模型可能不支持全局端点。可以为特定模型指定区域：
bash
# 为不支持全局端点的模型单独指定区域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5
# 可选：为其他模型覆盖区域
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1Step 6：固定模型版本
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-sonnet-4-6 |
| 小型快速模型 | claude-haiku-4-5@20251001 |
自定义主模型：
bash
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'
# 需要时禁用 Prompt 缓存
export DISABLE_PROMPT_CACHING=1IAM 权限配置
最简单的方式：分配 roles/aiplatform.user 角色，该角色包含所有必要权限。
最小自定义角色（只包含必要权限）：
json
{
"includedPermissions": [
"aiplatform.endpoints.predict"
]
}aiplatform.endpoints.predict 权限用于模型调用和 Token 计数，是唯一必需的权限。
1M Token 超长上下文
Claude Sonnet 4 和 Sonnet 4.6 在 Vertex AI 上支持 1M Token 上下文窗口——是标准 200K 的 5 倍。
适用场景：
- 超大代码库分析（整个仓库一次性输入）
- 长文档处理（研究报告、法律合同）
- 复杂多文件任务（无需分批处理）
常见问题排查
配额问题？
bash
# 在 Cloud Console 查看或申请增加配额
# https://cloud.google.com/docs/quotas/view-manage404「model not found」错误？
- 在 Model Garden 确认模型已启用
- 确认你的账号有该区域的访问权限
- 如用
CLOUD_ML_REGION=global，在 Model Garden 的「Supported features」确认模型支持全局端点- 不支持的模型：用
ANTHROPIC_MODEL指定，或设置VERTEX_REGION_<MODEL>区域端点
- 不支持的模型：用
429 限流错误？
- 区域端点：确认主模型和小型快速模型都在所选区域可用
- 考虑切换到
CLOUD_ML_REGION=global获得更好可用性
原文：Claude Code on Google Vertex AI | 来源：Anthropic 官方文档