跳转到主要内容

​
前置条件

在使用 Vertex AI 配置 Claude Code 之前，请确保您拥有：
  • 启用了计费的 Google Cloud Platform (GCP) 账户
  • 启用了 Vertex AI API 的 GCP 项目
  • 对所需 Claude 模型的访问权限（例如，Claude Sonnet 4.6）
  • 已安装并配置的 Google Cloud SDK (gcloud)
  • 在所需 GCP 区域中分配的配额
如果您要将 Claude Code 部署给多个用户，请固定您的模型版本，以防止在 Anthropic 发布新模型时出现中断。

​
区域配置

Claude Code 可以与 Vertex AI 全局和区域端点一起使用。
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.6）
  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

# 可选：如果需要，禁用 prompt caching
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 临时标志时，Prompt caching 会自动支持。要禁用它，请设置 DISABLE_PROMPT_CACHING=1。如需提高速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，/login 和 /logout 命令被禁用，因为身份验证通过 Google Cloud 凭证处理。

​
5. 固定模型版本

为每个部署固定特定的模型版本。如果您使用模型别名（sonnet、opus、haiku）而不固定版本，当 Anthropic 发布更新时，Claude Code 可能会尝试使用在您的 Vertex AI 项目中未启用的较新模型版本，从而破坏现有用户。
将这些环境变量设置为特定的 Vertex AI 模型 ID： 
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'
有关当前和旧版模型 ID，请参阅模型概览。有关完整的环境变量列表，请参阅模型配置。 当未设置固定变量时，Claude Code 使用这些默认模型：
模型类型默认值
主模型claude-sonnet-4-6
小型/快速模型claude-haiku-4-5@20251001
要进一步自定义模型： 
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
IAM 配置

分配所需的 IAM 权限： roles/aiplatform.user 角色包括所需的权限：
  • aiplatform.endpoints.predict - 模型调用和令牌计数所需
对于更严格的权限，请创建仅包含上述权限的自定义角色。 有关详细信息，请参阅 Vertex IAM 文档。
为 Claude Code 创建专用的 GCP 项目，以简化成本跟踪和访问控制。

​
1M token context window

Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 在 Vertex AI 上支持 1M token context window。当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。 要为您固定的模型启用 1M context window，请在模型 ID 后附加 [1m]。有关详细信息，请参阅为第三方部署固定模型。

​
故障排除

如果您遇到配额问题： 如果您遇到”模型未找到”404 错误：
  • 确认模型在 Model Garden 中已启用
  • 验证您有权访问指定的区域
  • 如果使用 CLOUD_ML_REGION=global，请检查您的模型是否在 Model Garden 中的”支持的功能”下支持全局端点。对于不支持全局端点的模型，请执行以下任一操作：
    • 通过 ANTHROPIC_MODEL 或 ANTHROPIC_SMALL_FAST_MODEL 指定支持的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域端点
如果您遇到 429 错误：
  • 对于区域端点，请确保主模型和小型/快速模型在您选择的区域中受支持
  • 考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性

​
其他资源