​
先决条件

在使用 Vertex AI 配置 Claude Code 之前，请确保您具备：

  • 已启用计费的 Google Cloud Platform (GCP) 账户
  • 已启用 Vertex AI API 的 GCP 项目
  • 对所需 Claude 模型的访问权限（例如，Claude Sonnet 4）
  • 已安装并配置的 Google Cloud SDK (gcloud)
  • 在所需 GCP 区域中分配的配额

​
区域配置

Claude Code 可以与 Vertex AI 全球和区域端点一起使用。

Vertex AI 可能不支持所有区域上的 Claude Code 默认模型。您可能需要切换到支持的区域或模型。

Vertex AI 可能不支持全球端点上的 Claude Code 默认模型。您可能需要切换到区域端点或支持的模型。

​
设置

​
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）
  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=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

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

# 当 CLOUD_ML_REGION=global 时，为不支持的模型覆盖区域
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-west1

当您指定 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 项目，以简化成本跟踪和访问控制。

​
1M 令牌上下文窗口

Claude Sonnet 4 在 Vertex AI 上支持 1M 令牌上下文窗口。

1M 令牌上下文窗口目前处于测试阶段。要使用扩展的上下文窗口，请在您的 Vertex AI 请求中包含 context-1m-2025-08-07 测试版标头。

​
故障排除

如果您遇到配额问题：

如果您遇到”模型未找到”404 错误：

  • 确认模型在 Model Garden 中已启用
  • 验证您有权访问指定区域
  • 如果使用 CLOUD_ML_REGION=global，请在 Model Garden 的”支持的功能”下检查您的模型是否支持全球端点。对于不支持全球端点的模型，请：
    • 通过 ANTHROPIC_MODEL 或 ANTHROPIC_SMALL_FAST_MODEL 指定支持的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域端点

如果您遇到 429 错误：

  • 对于区域端点，请确保主要模型和小型/快速模型在您选择的区域中受支持
  • 考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性

​
其他资源