在 Claude Code 中使用 Google Cloud 上的 Claude 模型（由 Anthropic 管理）

Google Cloud 上的 Claude 模型（由 Anthropic 管理）是由 Anthropic 运行、通过您的 Google Cloud 项目访问的 Claude API。要在 Claude Code 中使用它，请登录 Google Cloud 并设置三个环境变量。

Google Cloud 还通过 Google Cloud 的 Agent Platform（前身为 Vertex AI）提供 Claude，该平台由 Google 管理。如果您使用的是 Agent Platform，请改为参阅 Google Cloud Agent Platform 上的 Claude Code。要确定您使用的是哪一种，请参阅 Which offering are you using?

开始之前，请安装 Claude Code v2.1.307 或更高版本。要检查版本，请在 shell 中运行 claude --version。要更新，请运行 claude update。

前提条件

一个已完成账户设置的 Google Cloud 项目
运行 Claude Code 的每个 Google 账号或服务账号在该项目上都具有 roles/claude.user IAM 角色
您的项目 ID 和工作区 ID（以 wrkspc_ 开头）
如果您使用 Google 账号而非服务账号密钥文件登录，则需要 gcloud CLI

设置 Claude Code

创建应用默认凭据

Google 账号
服务账号密钥文件

在 shell 中运行以下命令，并使用具有 roles/claude.user 角色的 Google 账号登录：

gcloud auth application-default login

即使您已经运行过 gcloud auth login，也请运行此命令。如果设置了 GOOGLE_APPLICATION_CREDENTIALS，请取消设置。只要设置了该变量，Claude Code 就会使用它指定的文件，并忽略该命令保存的凭据。

在运行 Claude Code 的 shell 或 CI 作业中，将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号密钥文件的路径。有关其他凭据来源，请参阅如何进行身份验证。

将变量添加到设置中

将三个变量添加到用户设置文件 ~/.claude/settings.json 的 env 块中。如果该文件不存在，请使用以下内容创建它：

{
  "env": {
    "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD": "1",
    "ANTHROPIC_GOOGLE_CLOUD_PROJECT": "my-project-id",
    "ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID": "wrkspc_01ABCDEFGHIJKLMN"
  }
}

请使用您自己的项目 ID 和工作区 ID 替换 my-project-id 和 wrkspc_ 值。如果要改为仅配置单个 shell 或 CI 作业，请在该环境中设置相同的三个变量。您无需登录 Anthropic 账户，也无需注销 Anthropic 账户。

启动 Claude Code 并检查提供商

在 shell 中运行 claude，然后在 Claude Code 提示符处运行 /status。API provider 行包含 on Google Cloud，其后的各行显示您的 Workspace ID、GCP project 和 GCP location。要从 shell 或 CI 作业中输出相同的内容，请运行 claude auth status --text。如果您看到 on Google Cloud，请发送一条提示词，或在 CI 作业中运行 claude -p "hello"。收到回复即表示您的凭据和 IAM 角色正常工作。如果您没有看到它，或者 Claude Code 显示错误，请排查提供商设置问题。

为团队设置 Claude Code

将设置 Claude Code 第 2 步中的 env 块放入每位开发者计算机上的托管设置文件中。为每位开发者授予该项目上的 roles/claude.user 角色，并让每位开发者在自己的计算机上运行 gcloud auth application-default login。

固定模型版本

如果您面向团队进行部署，请固定模型 ID，以免 Claude Code 更新时所有人同时切换到更新的模型。将以下变量添加到包含设置 Claude Code 中三个变量的 env 块中：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  }
}

请使用您从模型概览中选择的 Claude API 模型 ID 替换示例值。

环境变量

变量	是否必需	说明
`CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD`	是	设置为 `1` 可将模型请求发送到 Google Cloud 上的 Claude 模型（由 Anthropic 管理）
`ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`	是，除非您设置了 `ANTHROPIC_GOOGLE_CLOUD_BASE_URL`	您的工作区 ID
`ANTHROPIC_GOOGLE_CLOUD_PROJECT`	推荐	您的 Google Cloud 项目 ID。如果未设置，Claude Code 将使用 `GOOGLE_CLOUD_PROJECT`
`ANTHROPIC_GOOGLE_CLOUD_LOCATION`	否	请求 URL 中的位置。默认为 `global`
`ANTHROPIC_GOOGLE_CLOUD_BASE_URL`	否	替换 Claude Code 根据项目、位置和工作区 ID 构建的基础 URL，例如替换为 LLM 网关的地址。Claude Code 会追加 API 路径，例如 `/v1/messages`
`CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH`	否	当网关自行附加 Google 凭据时设置为 `1`，这样 Claude Code 就不会发送 Google 访问令牌

不可用的 Claude Code 功能

在 Claude Models on Google Cloud（Anthropic managed）中，您无法使用的功能包括：

快速模式：您无法通过 /fast 或 fastMode 设置启用它
Remote Control 和云端会话
来自 claude.ai 的 MCP 连接器
频道
/design-sync 和 /import 命令
服务器托管设置。要为团队强制执行设置，请改为在每台计算机上使用托管设置

要查看其他不可用或仅部分支持的功能，请在功能可用性摘要中选择 Google Cloud (Anthropic managed) 选项卡。

故障排除

如果 Claude Code 要求您登录，或者 /status 中的 API provider 行不包含 on Google Cloud：

确保 CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD 为 1
确保 claude --version 输出 2.1.307 或更高版本
从您的 shell 和设置文件中移除 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_FOUNDRY 和 CLAUDE_CODE_USE_ANTHROPIC_AWS

CLAUDE_CODE_USE_VERTEX 可以保持设置。更改变量后，请重启 Claude Code。如果 /status 未显示更改，请参阅您设置的值被忽略。

`No workspace ID found`

将 ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID 设置为您的工作区 ID，然后重启 Claude Code。请忽略消息中提到的 workspaceId 构造函数选项：它适用于在自己的代码中调用 Anthropic SDK 的用户。

`No project was given`

将 ANTHROPIC_GOOGLE_CLOUD_PROJECT 设置为您的 Google Cloud 项目 ID，然后重启 Claude Code。

`Could not load Google Cloud credentials`

重复设置 Claude Code 的第 1 步；如果您使用服务账号密钥文件，请使用新密钥。

`Google Cloud credentials expired or invalid`

如果消息提示您刷新 Google Cloud 凭据，请重复设置 Claude Code 的第 1 步。如果使用服务账号密钥文件，请使用新密钥。

`Google Cloud authentication failed`

按照 Google Cloud credentials expired or invalid 中的步骤操作。如果这样仍无法消除错误：

项目：在 /status 中，确保 GCP project 行显示的是您的项目。如果显示的是其他项目，或者没有该行，请按照 No project was given 操作
工作区：在 /status 中，确保 Workspace ID 行显示的是您的工作区 ID。如果显示的是其他 ID，请按照 No workspace ID found 操作
IAM 角色：确保运行 Claude Code 的 Google 账号或服务账号在 GCP project 行所示的项目上具有 roles/claude.user 或 roles/claude.admin。要授予该角色，请使用该服务的授权命令，或请项目管理员授予
服务：确保 GCP project 行所示的项目上已启用 claude.googleapis.com 服务。要启用它，请按照该服务的账户设置步骤操作，或请项目管理员启用

Google Cloud 上的 Claude 模型（由 Anthropic 管理）：账户设置、IAM 角色、计费、数据保留和功能支持
企业部署概览：部署 Claude Code 的其他方式，以及代理和网关设置
模型配置：模型别名、固定模型版本以及限制用户可选择的模型

设置与访问

部署

网关

用量与费用

安全与数据

采用

在 Claude Code 中使用 Google Cloud 上的 Claude 模型（由 Anthropic 管理）

前提条件

设置 Claude Code

为团队设置 Claude Code

固定模型版本

环境变量

不可用的 Claude Code 功能

故障排除

`No workspace ID found`

`No project was given`

`Could not load Google Cloud credentials`

`Google Cloud credentials expired or invalid`

`Google Cloud authentication failed`

前提条件

设置 Claude Code

为团队设置 Claude Code

固定模型版本

环境变量

不可用的 Claude Code 功能

故障排除

No workspace ID found

No project was given

Could not load Google Cloud credentials

Google Cloud credentials expired or invalid

Google Cloud authentication failed

相关资源

`No workspace ID found`

`No project was given`

`Could not load Google Cloud credentials`

`Google Cloud credentials expired or invalid`

`Google Cloud authentication failed`