在 Google Cloud Agent Platform 上使用 Claude Code¶

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

前提条件¶

在配置 Claude Code 使用 Google Cloud Agent Platform 之前，确保具备以下条件：

• 已启用计费的 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 侧的配置。

设置向导需要 Claude Code v2.1.98 或更高版本。运行 claude --version 检查。

配置步骤：

1. 在 GCP 项目中启用 Claude 模型 - 为项目启用 Agent Platform API，然后在 Google Cloud Agent Platform Model Garden 中申请访问所需的 Claude 模型。权限信息参见 IAM 配置
2. 启动 Claude Code 并选择 Google Vertex AI - 运行 claude。在登录提示处选择 3rd-party platform，然后选择 Google Vertex AI（登录提示中仍沿用此名称代指 Google Cloud Agent Platform）
3. 按向导提示操作 - 选择 Google Cloud 认证方式：来自 gcloud 的 Application Default Credentials、服务账户密钥文件，或环境中已有的凭证。向导检测你的项目和区域，验证项目可调用哪些 Claude 模型，并允许你固定版本。结果保存到用户设置文件的 env 块中，无需手动导出环境变量

登录后，随时运行 /setup-vertex 可重新打开向导，更改凭证、项目、区域或模型固定设置。模型固定步骤从你当前已固定的模型开始。向导将配置写入 ~/.claude/settings.json，如果设置了 CLAUDE_CONFIG_DIR 则写入 $CLAUDE_CONFIG_DIR/settings.json。

区域配置¶

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

Google Cloud Agent Platform 可能不在每种端点类型上都支持 Claude Code 默认模型。模型可用性在特定区域、多区域位置和 global 端点之间有差异。你可能需要切换到支持的位置或指定支持的模型。

手动配置¶

通过环境变量配置 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 使用 ANTHROPIC_VERTEX_PROJECT_ID 作为 Google Cloud Agent Platform 请求的项目 ID。GCLOUD_PROJECT 和 GOOGLE_CLOUD_PROJECT 环境变量以及 GOOGLE_APPLICATION_CREDENTIALS 引用的凭证文件优先级高于它。如果都未设置，则从 gcloud 配置或关联的服务账户解析项目 ID。

高级凭证配置¶

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

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

命令输出会显示给用户，但不支持交互式输入。适合基于浏览器的认证流程——CLI 显示 URL，你在浏览器中完成认证。刷新命令在认证未完成时三分钟后超时。如果在项目设置（如 .claude/settings.json）中设置 gcpAuthRefresh，命令仅在你接受工作区信任提示后运行。

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 时，为不支持 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 确定哪些模型支持 global 端点、哪些仅支持区域端点。

Prompt 缓存默认自动启用。设置 DISABLE_PROMPT_CACHING=1 可禁用。设置 ENABLE_PROMPT_CACHING_1H=1 请求 1 小时缓存 TTL（默认 5 分钟）；1 小时 TTL 的缓存写入费率更高。如需更高速率限制，联系 Google Cloud 支持。使用 Google Cloud Agent Platform 时 /logout 命令不可用，因为认证通过 Google Cloud 凭证处理。

Claude Code 在 Google Cloud Agent Platform 上默认禁用 MCP 工具搜索，MCP 工具定义会预先加载。Google Cloud Agent Platform 对 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本支持工具搜索。设置 ENABLE_TOOL_SEARCH=true 可在这些模型上启用。更早的模型不接受所需的 beta header，启用工具搜索时请求会失败。

5. 固定模型版本¶

部署到多用户时务必固定特定模型版本。不固定的话，sonnet 和 opus 等别名会解析为 Claude Code 内置的 Google Cloud Agent Platform 默认值，该默认值可能落后于最新发布且未在你的项目中启用。Claude Code 在启动时如果默认版本不可用会回退到更早或更低级别的模型，但固定版本让你能控制用户何时切换到新模型。

设置以下环境变量为特定的 Google Cloud Agent Platform 模型 ID。

不设置 ANTHROPIC_DEFAULT_OPUS_MODEL 时，Agent Platform 上的 opus 别名解析为 Opus 5；不设置 ANTHROPIC_DEFAULT_SONNET_MODEL 时，sonnet 别名解析为 Sonnet 4.5。以下示例将每个别名固定到特定版本：

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 使用的默认模型：

在 Google Cloud Agent Platform 上，Claude Code 使用默认 Sonnet 模型处理后台任务， 因为 Haiku 可能未在每个项目或区域启用。以下两项设置会改变后台任务使用的模型：

• 通过 --model、ANTHROPIC_MODEL 或 model 设置选择主模型时，后台任务使用该模型。仅设置 ANTHROPIC_DEFAULT_OPUS_MODEL 而未设置 ANTHROPIC_DEFAULT_SONNET_MODEL 也算做选择，因为内置 Sonnet 模型可能未在只配置了自定义 Opus 的项目中启用
• 要使用 Haiku 处理后台任务，将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设为项目中可用的模型 ID

关于 Opus 计费的注意事项： Opus 模型的每 token 价格高于 Sonnet 模型。未固定主模型的部署从 v2.1.207 起按 Opus 费率计费。要保持 Sonnet 4.5 为主模型，将 ANTHROPIC_MODEL 设为其完整模型 ID。如果部署通过 ANTHROPIC_DEFAULT_SONNET_MODEL 指定默认模型且未设置 ANTHROPIC_DEFAULT_OPUS_MODEL，则保留其指定的 Sonnet 模型作为默认。

版本历史：

进一步自定义模型：

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

6. 验证配置¶

启动 Claude Code 并运行 /status 确认配置正确。 API provider 行显示 Google Vertex AI，GCP project、Default region 和 Model 行分别显示你的项目 ID、区域和解析后的模型。如果 provider 行缺失，说明环境变量未到达进程。确认它们在启动 claude 的 shell 中已导出，或在设置文件的 env 块中设置。

启动时模型检查¶

Claude Code 启动时会验证它要使用的模型在你的项目中是否可访问。 此检查需要 Claude Code v2.1.98 或更高版本。

如果你固定的模型版本低于当前 Claude Code 默认值，且你的项目可以调用新版本，Claude Code 会提示你更新固定设置。接受则将新模型 ID 写入用户设置文件并重启 Claude Code。拒绝将被记住，直到下一次默认版本变更。

如果你未固定模型且当前默认在项目中不可用，Claude Code 会在当前会话回退并显示通知。它优先尝试默认模型的早期版本；如果默认是 Opus 模型且没有任何 Opus 版本可用，则回退到默认 Sonnet 模型。回退不会持久化。在 Model Garden 中启用新模型或固定版本以使选择永久生效。

通过 --model、ANTHROPIC_MODEL 或 model 设置指定的模型版本（v2.1.211+）作为会话的固定默认值。 此时跳过可用性检查，不显示回退通知。

注意：opus 等模型别名不视为固定，Claude Code 不识别的模型 ID 同样不视为固定。

IAM 配置¶

分配所需的 IAM 权限：

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

• aiplatform.endpoints.predict - 模型调用和 token 计数所需

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

详情参见 Google Cloud Agent Platform IAM 文档。

建议为 Claude Code 创建专用 GCP 项目以简化成本追踪和访问控制。

1M token 上下文窗口¶

Claude Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 在 Google Cloud Agent Platform 上支持 1M token 上下文窗口。 当你选择 1M 模型变体时，Claude Code 自动启用扩展上下文窗口。Sonnet 5 始终以 1M 窗口运行，无需选择 [1m] 变体。

设置向导在固定模型时提供 1M 上下文选项。要为手动固定的模型启用，在模型 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 中已启用
• 验证模型在你指定的位置可用。某些模型仅在 global 或多区域位置（如 eu 和 us）提供，不在特定区域
• 如果使用 CLOUD_ML_REGION=global，检查模型是否在 Model Garden 的 "Supported features" 下支持 global 端点。对于不支持 global 端点的模型，可以：
• 通过 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支持的模型
• 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域或多区域位置

如果遇到 429 错误：

• 对于区域端点，确保主模型和 small/fast 模型在你选择的区域受支持
• 考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性

相关资源¶

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