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）
- 已安装并配置的 Google Cloud SDK (
gcloud) - 在所需 GCP 区域中分配的配额
⚠️ 警告： Vertex AI 可能不支持非
us-east5区域的 Claude Code 默认模型。请确保您使用的是us-east5并已分配配额，或切换到支持的模型。
设置
1. 启用 Vertex AI API
在您的 GCP 项目中启用 Vertex AI API：
# 设置您的项目 ID
gcloud config set project YOUR-PROJECT-ID
# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com2. 请求模型访问权限
在 Vertex AI 中请求访问 Claude 模型：
- 导航到 Vertex AI Model Garden
- 搜索 "Claude" 模型
- 请求访问所需的 Claude 模型（例如，Claude Sonnet 4）
- 等待批准（可能需要 24-48 小时）
3. 配置 GCP 凭据
Claude Code 使用标准的 Google Cloud 身份验证。
有关更多信息，请参阅 Google Cloud 身份验证文档。
ℹ️ 注意： 进行身份验证时，Claude Code 将自动使用来自
ANTHROPIC_VERTEX_PROJECT_ID环境变量的项目 ID。要覆盖此设置，请设置以下环境变量之一：GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT或GOOGLE_APPLICATION_CREDENTIALS。
4. 配置 Claude Code
设置以下环境变量：
# 启用 Vertex AI 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
# 可选：如需要，禁用提示缓存
export DISABLE_PROMPT_CACHING=1
# 可选：为特定模型覆盖区域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
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-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4ℹ️ 注意： 当您指定
cache_control临时标志时，会自动支持提示缓存。要禁用它，请设置DISABLE_PROMPT_CACHING=1。如需提高速率限制，请联系 Google Cloud 支持。
ℹ️ 注意： 使用 Vertex AI 时，
/login和/logout命令被禁用，因为身份验证通过 Google Cloud 凭据处理。
5. 模型配置
Claude Code 为 Vertex AI 使用以下默认模型：
| 模型类型 | 默认值 |
|---|---|
| 主要模型 | claude-sonnet-4@20250514 |
| 小型/快速模型 | claude-3-5-haiku@20241022 |
要自定义模型：
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'IAM 配置
分配所需的 IAM 权限：
roles/aiplatform.user 角色包含所需权限：
aiplatform.endpoints.predict- 模型调用所需aiplatform.endpoints.computeTokens- 令牌计数所需
对于更严格的权限，请仅使用上述权限创建自定义角色。
有关详细信息，请参阅 Vertex IAM 文档。
ℹ️ 注意： 我们建议为 Claude Code 创建专用的 GCP 项目，以简化成本跟踪和访问控制。
故障排除
如果您遇到配额问题：
- 通过 Cloud Console 检查当前配额或请求增加配额
如果您遇到"模型未找到"404 错误：
- 验证您是否有权访问指定区域
- 确认模型在 Model Garden 中已启用
如果您遇到 429 错误：
- 确保主要模型和小型/快速模型在您选择的区域中受支持