{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# Google Vertex AI 上的 Claude Code

> 了解如何通过 Google Vertex AI 配置 Claude Code，包括设置、IAM 配置和故障排除。

export const ContactSalesCard = ({surface}) => {
  const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;
  const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <line x1="5" y1="12" x2="19" y2="12" />
      <polyline points="12 5 19 12 12 19" />
    </svg>;
  const STYLES = `
.cc-cs {
  --cs-slate: #141413;
  --cs-clay: #d97757;
  --cs-clay-deep: #c6613f;
  --cs-gray-000: #ffffff;
  --cs-gray-700: #3d3d3a;
  --cs-border-default: rgba(31, 30, 29, 0.15);
  font-family: inherit;
}
.dark .cc-cs {
  --cs-slate: #f0eee6;
  --cs-gray-000: #262624;
  --cs-gray-700: #bfbdb4;
  --cs-border-default: rgba(240, 238, 230, 0.14);
}
.cc-cs-card {
  display: flex; align-items: center; justify-content: space-between;
  gap: 16px; padding: 14px 16px; margin: 0;
  background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);
  border-radius: 8px; flex-wrap: wrap;
}
.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }
.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }
.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
.cc-cs-btn-clay {
  display: inline-flex; align-items: center; gap: 8px;
  background: var(--cs-clay-deep); color: #fff; border: none;
  border-radius: 8px; padding: 8px 14px;
  font-size: 13px; font-weight: 500;
  transition: background-color 0.15s; white-space: nowrap;
}
.cc-cs-btn-clay:hover { background: var(--cs-clay); }
.cc-cs-btn-ghost {
  display: inline-flex; align-items: center; gap: 8px;
  background: transparent; color: var(--cs-gray-700);
  border: 0.5px solid var(--cs-border-default);
  border-radius: 8px; padding: 8px 14px;
  font-size: 13px; font-weight: 500;
}
.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }
.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }
@media (max-width: 720px) {
  .cc-cs-actions { width: 100%; }
}
`;
  return <div className="cc-cs not-prose">
      <style>{STYLES}</style>
      <div className="cc-cs-card">
        <div className="cc-cs-text">
          <strong>正在为你的组织部署 Claude Code？</strong>与销售团队讨论企业计划、SSO 和集中计费。
        </div>
        <div className="cc-cs-actions">
          <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">
            查看计划
          </a>
          <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">
            联系销售 {iconArrowRight()}
          </a>
        </div>
      </div>
    </div>;
};

<ContactSalesCard surface="vertex" />

## 前提条件

在通过 Vertex AI 配置 Claude Code 之前，请确保你拥有：

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

要使用你自己的 Vertex AI 凭据登录，请按照下面的[使用 Vertex AI 登录](#使用-vertex-ai-登录)操作。要跨团队部署 Claude Code，请使用[手动设置](#手动设置)步骤并在推出前[固定你的模型版本](#5-固定模型版本)。

## 使用 Vertex AI 登录

如果你有 Google Cloud 凭据并想开始通过 Vertex AI 使用 Claude Code，登录向导会引导你完成。你只需为每个项目完成一次 GCP 端的前提条件；向导处理 Claude Code 端。

<Note>
  Vertex AI 设置向导需要 Claude Code v2.1.98 或更高版本。运行 `claude --version` 检查。
</Note>

<Steps>
  <Step title="在你的 GCP 项目中启用 Claude 模型">
    为你的项目[启用 Vertex AI API](#1-启用-vertex-ai-api)，然后在 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中请求访问你想要的 Claude 模型。有关你的账户所需的权限，请参阅 [IAM 配置](#iam-配置)。
  </Step>

  <Step title="启动 Claude Code 并选择 Vertex AI">
    运行 `claude`。在登录提示中，选择 **3rd-party platform**，然后选择 **Google Vertex AI**。
  </Step>

  <Step title="按照向导提示操作">
    选择你如何认证到 Google Cloud：来自 `gcloud` 的 Application Default Credentials、服务账户密钥文件，或环境中的凭据。向导检测你的项目和区域，验证你的项目可以调用哪些 Claude 模型，并让你固定它们。它将结果保存到你的[用户设置文件](/en/settings)的 `env` 块中，因此你无需自己导出环境变量。
  </Step>
</Steps>

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

## 区域配置

Claude Code 支持 Vertex AI [全球](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai)、多区域和区域端点。将 `CLOUD_ML_REGION` 设置为 `global`、多区域位置（如 `eu` 或 `us`），或特定区域（如 `us-east5`）。Claude Code 为每种形式选择正确的 Vertex AI 主机名，包括多区域位置的 `aiplatform.eu.rep.googleapis.com` 和 `aiplatform.us.rep.googleapis.com` 主机。

<Note>
  Vertex AI 可能并非在每种端点类型上都支持 Claude Code 默认模型。模型可用性在[特定区域](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models)、多区域位置和[全球端点](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)之间有所不同。你可能需要切换到受支持的位置或指定受支持的模型。
</Note>

## 手动设置

要通过环境变量而非向导配置 Vertex AI（例如在 CI 或脚本化的企业部署中），请按照以下步骤操作。

### 1. 启用 Vertex AI API

在你的 GCP 项目中启用 Vertex AI API：

```bash theme={null}
# 设置你的项目 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](https://console.cloud.google.com/vertex-ai/model-garden)
2. 搜索 "Claude" 模型
3. 请求访问所需的 Claude 模型（例如 Claude Sonnet 4.6）
4. 等待批准（可能需要 24-48 小时）

### 3. 配置 GCP 凭据

Claude Code 使用标准的 Google Cloud 认证。

有关更多信息，请参阅 [Google Cloud 认证文档](https://cloud.google.com/docs/authentication)。

Claude Code v2.1.121 或更高版本通过相同的 Application Default Credentials 链支持[基于 X.509 证书的 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为你的凭据配置文件路径。

<Note>
  Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作为 Vertex AI 请求的项目 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 环境变量以及 `GOOGLE_APPLICATION_CREDENTIALS` 引用的凭据文件优先于它。如果这些都未设置，项目 ID 从你的 `gcloud` 配置或附加的服务账户解析。
</Note>

#### 高级凭据配置

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

```json theme={null}
{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}
```

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

### 4. 配置 Claude Code

设置以下环境变量：

```bash theme={null}
# 启用 Vertex AI 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可选：为自定义端点或网关覆盖 Vertex 端点 URL
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

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

# 可选：请求 1 小时提示缓存 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_*` 变量。完整列表请参阅[环境变量参考](/en/env-vars)。检查 [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以确定哪些模型支持全球端点而非仅区域端点。

[提示缓存](/en/prompt-caching)默认启用。要禁用它，设置 `DISABLE_PROMPT_CACHING=1`。要请求 1 小时缓存 TTL 而非默认的 5 分钟，设置 `ENABLE_PROMPT_CACHING_1H=1`；1 小时 TTL 的缓存写入按更高费率计费。如需更高的速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，`/logout` 命令不可用，因为认证通过 Google Cloud 凭据处理。

Claude Code 默认在 Vertex AI 上禁用 [MCP 工具搜索](/en/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定义预先加载。Vertex AI 支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本的工具搜索。设置 `ENABLE_TOOL_SEARCH=true` 以在这些模型上启用它。Vertex AI 上的早期模型不接受所需的 beta 标头，如果你对它们启用工具搜索，请求会失败。

### 5. 固定模型版本

<Warning>
  部署给多个用户时请固定特定模型版本。不固定的话，`sonnet` 和 `opus` 等模型别名会解析到最新版本，当 Anthropic 发布更新时该版本可能尚未在你的 Vertex AI 项目中启用。当最新版本不可用时，Claude Code 在启动时[回退](#启动时模型检查)到上一版本，但固定让你控制用户何时迁移到新模型。
</Warning>

将这些环境变量设置为特定的 Vertex AI 模型 ID。

没有 `ANTHROPIC_DEFAULT_OPUS_MODEL` 时，Vertex 上的 `opus` 别名解析到 Opus 4.6。将其设置为 Opus 4.7 ID 以使用最新模型：

```bash theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
```

有关当前和旧版模型 ID，请参阅[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。有关环境变量的完整列表，请参阅[模型配置](/en/model-config#pin-models-for-third-party-deployments)。

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

| 模型类型         | 默认值                       |
| :--------------- | :--------------------------- |
| 主要模型         | `claude-sonnet-4-5@20250929` |
| 小型/快速模型    | 与主要模型相同               |

会话标题生成等后台任务使用小型/快速模型，通常是 Haiku 级模型。在 Vertex AI 上，Claude Code 默认将其设为主要模型，因为 Haiku 可能未在每个项目或区域中启用。要对后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为你的项目中可用的模型 ID。

要进一步自定义模型：

```bash theme={null}
export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
```

## 启动时模型检查

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

如果你固定的模型版本比当前 Claude Code 默认版本旧，且你的项目可以调用更新的版本，Claude Code 会提示你更新固定。接受会将新模型 ID 写入你的[用户设置文件](/en/settings)并重启 Claude Code。拒绝会被记住直到下一次默认版本更改。

如果你没有固定模型且当前默认在你的项目中不可用，Claude Code 会在当前会话中回退到上一版本并显示通知。回退不会持久化。在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中启用更新的模型或[固定版本](#5-固定模型版本)以使选择永久化。

## IAM 配置

分配所需的 IAM 权限：

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

* `aiplatform.endpoints.predict` - 模型调用和令牌计数所需

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

有关详情，请参阅 [Vertex IAM 文档](https://cloud.google.com/vertex-ai/docs/general/access-control)。

<Note>
  为 Claude Code 创建专用的 GCP 项目以简化成本跟踪和访问控制。
</Note>

## 100 万令牌上下文窗口

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Vertex AI 上支持[100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)。当你选择 100 万模型变体时，Claude Code 自动启用扩展上下文窗口。

[设置向导](#使用-vertex-ai-登录)在固定模型时提供 100 万上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详情，请参阅[为第三方部署固定模型](/en/model-config#pin-models-for-third-party-deployments)。

## 故障排除

如果你遇到 "Could not load the default credentials" 错误：

* 运行 `gcloud auth application-default login` 设置 Application Default Credentials
* 将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为服务账户密钥文件路径
* 有关所有选项，请参阅[配置 GCP 凭据](#3-配置-gcp-凭据)

如果你遇到配额问题：

* 通过 [Cloud Console](https://cloud.google.com/docs/quotas/view-manage) 检查当前配额或请求增加配额

如果你遇到 "model not found" 404 错误：

* 在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中确认模型已启用
* 验证模型在你指定的位置可用。某些模型仅在 `global` 或多区域位置（如 `eu` 和 `us`）提供，不在特定区域中
* 如果使用 `CLOUD_ML_REGION=global`，在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 的 "Supported features" 下检查你的模型是否支持全球端点。对于不支持全球端点的模型，可以：
  * 通过 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 指定支持的模型，或
  * 使用 `VERTEX_REGION_<MODEL_NAME>` 环境变量设置区域或多区域位置

如果你遇到 429 错误：

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

## 附加资源

* [Vertex AI 文档](https://cloud.google.com/vertex-ai/docs)
* [Vertex AI 定价](https://cloud.google.com/vertex-ai/pricing)
* [Vertex AI 配额和限制](https://cloud.google.com/vertex-ai/docs/quotas)