它到底是什么

/setup-vertex 是 Claude Code 会话内的 Slash 命令，用于重新打开 Vertex AI 设置向导，让你修改 Google Cloud 凭证、GCP 项目、区域或模型版本绑定，而无需退出当前会话。

向导将结果写入用户设置文件的 env 块，所以你无需手动 export 环境变量。

前置要求（来自官方文档）：

怎么触发 / 怎么使用

1. 首次配置：通过登录向导进入

首次运行 claude 时，在登录提示处选择认证方式：

$ claude
# 登录提示出现后：
# → 选择 "3rd-party platform"
# → 选择 "Google Vertex AI"
# → 按向导提示选择认证方式、项目、区域、模型版本

向导会依次：

1. 让你选择 Google Cloud 认证方式（gcloud 的 Application Default Credentials、Service Account key 文件，或环境中已有凭证）
2. 自动检测当前项目与区域（官方原文：the wizard detects your project and region）
3. 验证所选项目中哪些 Claude 模型可调用
4. 提供模型版本绑定（含 1M token 上下文选项）
5. 将配置写入用户设置文件的 env 块

2. 修改已有配置：在会话内执行

/setup-vertex

随时在会话中输入该命令，重新打开向导以变更凭证、项目、区域或模型绑定。

3. 手动配置：通过环境变量（CI / 企业批量部署）

若不使用向导，可手动设置以下环境变量：

# 必须：启用 Vertex AI 模式
export CLAUDE_CODE_USE_VERTEX=1

# 必须：区域（global / eu / us / 具体区域如 us-east5）
export CLOUD_ML_REGION=global

# 项目 ID（优先级最低，见下方说明）
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

可选变量：

# 覆盖 Vertex 端点（自定义网关场景）
export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 禁用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 启用 1 小时 cache TTL（写入费率更高）
export ENABLE_PROMPT_CACHING_1H=1

# global 区域下，为不支持 global endpoint 的模型单独指定区域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

# 启用 MCP tool search（仅 Sonnet 4.5+ 和 Opus 4.5+ 支持）
export ENABLE_TOOL_SEARCH=true

项目 ID 解析优先级（高 → 低）： GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT、以及 GOOGLE_APPLICATION_CREDENTIALS 指向的凭证文件（三者并列同级，官方未给出彼此之间的相对顺序）> ANTHROPIC_VERTEX_PROJECT_ID > gcloud 配置 / 附加的 Service Account

官方原文：The GCLOUD_PROJECT and GOOGLE_CLOUD_PROJECT environment variables and the credential file referenced by GOOGLE_APPLICATION_CREDENTIALS take precedence over it [ANTHROPIC_VERTEX_PROJECT_ID].

保存 / 配置 / 集成

向导写入位置

向导将所有配置保存到用户设置文件的 env 块中，不需要在 shell profile 里 export。

自动凭证刷新（gcpAuthRefresh）

当 GCP 凭证过期时，可配置自动刷新命令，避免手动重新登录：

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

• 命令输出会展示给用户，但不支持交互式输入
• 超时时间：3 分钟
• 若写在项目级 .claude/settings.json 中，该命令仅在用户接受 workspace trust 提示后才会执行

模型版本绑定

企业批量部署时强烈建议绑定具体版本，否则模型别名（sonnet、opus）解析到 Claude Code 内置默认值，该默认值可能在项目中尚未启用：

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

# 或覆盖主模型：
export ANTHROPIC_MODEL='claude-opus-4-8'

Vertex AI 默认模型（无绑定时）：

注：Vertex AI 上 Claude Code 的后台任务（如会话标题生成）默认使用主模型，因为 Haiku 不一定在所有项目/区域中启用。

1M Token 上下文

Opus 4.6+、Sonnet 4.6 在 Vertex AI 上支持 1M token 上下文。向导会提供选项；手动配置时在模型 ID 末尾追加 [1m]：

export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6[1m]'

IAM 权限

最小权限角色：roles/aiplatform.user，包含必须的 aiplatform.endpoints.predict 权限。

运行约束 / 限制

跟同类原语对比

经典使用场景

• 切换 GCP 项目或区域：团队多项目轮转时，在会话中执行 /setup-vertex 即可切换，不用退出重新配置。
• 企业 Vertex AI 部署：通过 gcpAuthRefresh + 环境变量实现无人值守的凭证刷新，配合 ANTHROPIC_DEFAULT_*_MODEL 锁定版本，保证所有用户使用相同模型。
• 全局端点 + 模型区域精调：设置 CLOUD_ML_REGION=global 获得更高可用性，再用 VERTEX_REGION_* 为不支持 global 端点的模型单独指定区域。
• 使用 GCP Credits 替代 Anthropic 订阅：公司已有 GCP 合同和 committed use 折扣，通过 Vertex AI 走统一账单，不需要额外 Anthropic API Key。

常见坑

1. "Could not load the default credentials"：最常见原因是没有运行 gcloud auth application-default login，或 GOOGLE_APPLICATION_CREDENTIALS 指向了不存在的文件。先跑一遍 gcloud auth application-default print-access-token 验证凭证是否正常。

2. Model 404 / "model not found"：在 Vertex AI Model Garden 里申请模型访问后，审批可能需要 24–48 小时。另一常见原因是所选区域/端点不支持该模型。官方原文明确：使用 CLOUD_ML_REGION=global 时若模型不支持 global 端点，报的就是 404（model not found）——在 Model Garden 的 "Supported features" 里确认，再用 ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL 换支持的模型，或用 VERTEX_REGION_<MODEL_NAME> 为该模型单独指定区域/multi-region。

3. 区域端点下 429 报错：官方原文将 429 归在区域端点场景——确保主模型和后台小模型都在所选区域受支持；或考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性。注意:global 端点上模型不可用是 404 而非 429（见上条）。

4. 模型别名漂移：不绑定具体版本时，Claude Code 内置默认值在新版本发布后会静默变更，可能导致项目中未启用新版本而报错。生产环境务必设置 ANTHROPIC_DEFAULT_*_MODEL。

5. MCP 工具在 Vertex AI 上失败：旧版模型（Sonnet 4.5 之前）不接受 tool search 的 beta 请求头，若误设 ENABLE_TOOL_SEARCH=true，所有带工具的请求均会失败。确认模型版本后再启用。

来源

• Claude Code on Google Vertex AI — 官方文档
• Commands — Claude Code 官方文档