在 Google Cloud 的 Agent Platform 上使用 Claude Code

了解如何通过 Google Cloud 的 Agent Platform（原 Vertex AI）配置 Claude Code，包括设置、IAM 配置和故障排除。

前提条件

在通过 Google Cloud 的 Agent Platform（原 Vertex AI）配置 Claude Code 前，请确保具备：

• 已启用结算功能的 Google Cloud Platform（GCP）账号
• 已启用 Google Cloud Agent Platform API 的 GCP 项目
• 所需 Claude 模型（例如 Claude Sonnet 4.6）的访问权限
• 已安装并配置 Google Cloud SDK（gcloud）
• 在所需 GCP 区域中已分配配额

要使用自己的 Google Cloud Agent Platform 凭据登录，请按照下文的使用 Agent Platform 登录操作。要在团队中部署 Claude Code，请执行手动设置步骤，并在推广部署前固定模型版本。

使用 Agent Platform 登录

如果已有 Google Cloud 凭据，并希望通过 Google Cloud 的 Agent Platform 开始使用 Claude Code，登录向导会引导你完成设置。每个项目只需完成一次 GCP 端的前提条件，Claude Code 端则由向导处理。

登录后，可随时运行 /setup-vertex 重新打开向导，更改凭据、项目、区域或固定的模型版本。

区域配置

Claude Code 支持 Google Cloud Agent Platform 的全局、多区域和区域端点。将 CLOUD_ML_REGION 设为 global、eu 或 us 等多区域位置，或者 us-east5 等特定区域。Claude Code 会为每种形式选择正确的 Google Cloud Agent Platform 主机名，包括多区域位置使用的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com。

手动设置

如果希望通过环境变量而不是向导配置 Google Cloud 的 Agent Platform（例如在 CI 或脚本化的企业推广部署中），请按以下步骤操作。

1. 启用 Agent Platform API

在 GCP 项目中启用 Google Cloud Agent Platform API：

# 设置您的项目 ID
gcloud config set project YOUR-PROJECT-ID

# 启用 Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. 申请模型访问权限

在 Google Cloud 的 Agent Platform 中申请 Claude 模型访问权限：

1. 前往 Google Cloud Agent Platform Model Garden
2. 搜索“Claude”模型
3. 申请访问所需的 Claude 模型（例如 Claude Sonnet 4.6）
4. 等待批准（可能需要 24–48 小时）

3. 配置 GCP 凭据

Claude Code 使用标准 Google Cloud 身份验证。

详情请参阅 Google Cloud 身份验证文档。

Claude Code v2.1.121 或更高版本通过同一个 Application Default Credentials 链支持基于 X.509 证书的 Workload Identity Federation。请将 GOOGLE_APPLICATION_CREDENTIALS 设为凭据配置文件的路径。

高级凭据配置

Claude Code 通过 gcpAuthRefresh 设置支持自动刷新 GCP 凭据。当 Claude Code 检测到 GCP 凭据已过期或无法加载时，会运行所配置的命令获取新凭据，然后重试请求。

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

命令输出会显示给用户，但不支持交互式输入。它很适合基于浏览器的身份验证流程：CLI 显示一个 URL，用户在浏览器中完成身份验证。如果身份验证未在三分钟内完成，刷新命令会超时。如果将 gcpAuthRefresh 配置在 .claude/settings.json 等项目设置中，只有接受工作区信任提示后，命令才会运行。

4. 配置 Claude Code

设置以下环境变量：

# 启用 Agent Platform 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可选：覆盖 Agent Platform 端点 URL，以使用自定义端点或网关
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 可选：按需禁用 Prompt 缓存
export DISABLE_PROMPT_CACHING=1

# 可选：请求使用 1 小时的 Prompt 缓存 TTL，而非默认的 5 分钟
export ENABLE_PROMPT_CACHING_1H=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_* 变量。完整列表请参阅环境变量参考。要确定哪些模型支持全局端点、哪些只支持区域端点，请查看 Google Cloud Agent Platform Model Garden。

Prompt 缓存会自动启用。如需禁用，请设置 DISABLE_PROMPT_CACHING=1。要请求 1 小时缓存 TTL，而不是默认的 5 分钟，请设置 ENABLE_PROMPT_CACHING_1H=1；写入使用 1 小时 TTL 的缓存会按更高费率计费。如需提高速率限制，请联系 Google Cloud 支持。使用 Google Cloud 的 Agent Platform 时，身份验证由 Google Cloud 凭据处理，因此 /logout 命令不可用。

默认情况下，Claude Code 会在 Google Cloud 的 Agent Platform 上禁用 MCP 工具搜索，因此 MCP 工具定义会预先加载。Google Cloud 的 Agent Platform 支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本的工具搜索。设置 ENABLE_TOOL_SEARCH=true 可在这些模型上启用。Google Cloud Agent Platform 上的早期模型不接受所需的 beta 请求头；如果为它们启用工具搜索，请求会失败。

5. 固定模型版本

将以下环境变量设为具体的 Google Cloud Agent Platform 模型 ID。

如果未设置 ANTHROPIC_DEFAULT_OPUS_MODEL，Google Cloud Agent Platform 上的 opus 别名会解析为 Opus 4.6。要使用最新模型，请将其设为 Opus 4.8 ID：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

当前和旧版模型 ID 请参阅模型概述。完整的环境变量列表请参阅模型配置。

未设置任何固定模型变量时，Claude Code 使用以下默认模型：

生成会话标题等后台任务使用小型/快速模型，通常是 Haiku 类模型。在 Google Cloud 的 Agent Platform 上，Claude Code 默认使用主模型处理这些任务，因为并非每个项目或区域都已启用 Haiku。要让后台任务使用 Haiku，请将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设为项目中可用的模型 ID。

如需进一步自定义模型：

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

启动时模型检查

Claude Code 在配置 Google Cloud Agent Platform 后启动时，会验证准备使用的模型是否能在项目中访问。此项检查需要 Claude Code v2.1.98 或更高版本。

如果固定的模型版本早于当前 Claude Code 默认版本，且项目可以调用较新版本，Claude Code 会提示更新固定版本。接受后，系统会将新的模型 ID 写入用户设置文件，然后重启 Claude Code。拒绝后，系统会记住该选择，直到下一次默认版本发生变化。

如果未固定模型，而且项目无法使用当前默认模型，Claude Code 会在当前会话中回退到上一版本并显示通知。该回退不会持久保存。请在 Model Garden 中启用较新模型，或固定版本以永久保存选择。

IAM 配置

分配所需 IAM 权限：

roles/aiplatform.user 角色包含所需权限：

• aiplatform.endpoints.predict - 调用模型和计算 Token 时需要

如需实施更严格的权限，请创建只包含上述权限的自定义角色。

详情请参阅 Google Cloud Agent Platform IAM 文档。

100 万 Token 上下文窗口

Claude Sonnet 5、Opus 4.6 及更高版本和 Sonnet 4.6 在 Google Cloud 的 Agent Platform 上支持 100 万 Token 上下文窗口。Sonnet 5 始终使用 100 万 Token 窗口，没有可供选择的 [1m] 变体。对于其他模型，选择 100 万 Token 模型变体后，Claude Code 会自动启用扩展上下文窗口。

设置向导在固定模型时会提供 100 万 Token 上下文选项。要为手动固定的模型启用此功能，请在模型 ID 后附加 [1m]。详情请参阅为第三方部署固定模型。

故障排除

如果遇到“Could not load the default credentials”错误：

• 运行 gcloud auth application-default login 设置 Application Default Credentials
• 将 GOOGLE_APPLICATION_CREDENTIALS 设为服务账号密钥文件路径
• 所有选项请参阅配置 GCP 凭据

如果遇到配额问题：

• 通过 Cloud Console 查看当前配额或申请提高配额

如果遇到“model not found”404 错误：

• 确认模型在 Model Garden 中处于 Enabled 状态
• 确认模型在指定位置可用。部分模型只在 global 或 eu、us 等多区域位置提供，而不在特定区域提供
• 如果使用 CLOUD_ML_REGION=global，请在 Model Garden 的“Supported features”下确认模型支持全局端点。对于不支持全局端点的模型，可以：
  • 通过 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定受支持的模型，或
  • 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域或多区域位置

如果遇到 429 错误：

• 对于区域端点，确认主模型和小型/快速模型在所选区域均受支持
• 考虑改用 CLOUD_ML_REGION=global，以获得更高可用性

其他资源

• Google Cloud Agent Platform 文档
• Google Cloud Agent Platform 定价
• Google Cloud Agent Platform 配额和限制