GCP Vertex AI

GCP Vertex AI

如果你的公司在 Google Cloud 上深耕，账号、组织、IAM、审计、成本都跑在 GCP——那让 Claude Code 走 GCP Vertex AI 是最顺的：模型调用不离开 GCP 项目，认证复用 Google Cloud 身份，CI 里用 Workload Identity Federation（WIF）短期凭证，账单和现有 Vertex 用量一起出。

这一篇讲清楚 Vertex 模式怎么开、怎么认证、怎么跳过认证接网关、怎么在 GitHub Actions 里跑。

一句话开启 Vertex

export CLAUDE_CODE_USE_VERTEX=1

设上这个环境变量，Claude Code 就把模型调用切到 Vertex AI，不再走 Anthropic 公网 API。剩下的工作是让 Claude Code 能认证到 Vertex。

Google Cloud 认证：三种走法

Vertex 模式下，认证方式按场景分三种：

方式	适用	怎么配
应用默认凭证 ADC	开发者本机日常	gcloud auth application-default login
跳过认证（接 LLM 网关）	走企业网关统一管控	CLAUDE_CODE_SKIP_VERTEX_AUTH=1
GitHub Actions WIF	CI	Workload Identity Federation + 短期 token

方式一：应用默认凭证 ADC

最贴近开发者日常。Google Cloud 的标准做法是「应用默认凭证」（Application Default Credentials，ADC）。开发者在本机跑一次：

gcloud auth application-default login

凭证就存好了，所有支持 ADC 的客户端（包括 Vertex 模式下的 Claude Code）自动用它。Claude Code 启动时检测 ADC，自动完成认证，开发者不用再单独配任何东西。

如果是 Service Account 跑在服务器上，把 SA 的 JSON key 路径塞进环境变量也行：

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

方式二：跳过认证接 LLM 网关

如果你的公司搭了统一 LLM 网关（自建或第三方），所有模型调用都走网关、由网关自己认证 Vertex——那 Claude Code 这一层就不必再认证一次：

export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

配上 CLAUDE_CODE_SKIP_VERTEX_AUTH=1，Claude Code 跳过 Vertex 自身的认证步骤，把请求直接送到你配置的网关端点。详见 网络与 LLM 网关。

方式三：GitHub Actions WIF

CI 里跑 Claude Code，不要把 GCP Service Account 的 JSON key 塞进 secret——用 Workload Identity Federation（WIF）更安全。WIF 让 GitHub Actions 不持有任何长期凭证，每次 job 用 OIDC token 换一个短期 GCP token。

.github/workflows/claude-vertex.yml：

name: Claude Code on Vertex
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  id-token: write   # 关键：让 GitHub 发 OIDC token
  contents: read
  pull-requests: write

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Auth to GCP via Workload Identity Federation
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: projects/123456789012/locations/global/workloadIdentityPools/github-pool/providers/github-provider
          service_account: [email protected]
      - name: Run Claude Code
        env:
          CLAUDE_CODE_USE_VERTEX: "1"
          ANTHROPIC_VERTEX_PROJECT_ID: "your-project"
          CLOUD_ML_REGION: "us-east5"
        run: |
          claude -p "审查这个 PR 的改动，给出改进建议" --output-format json

注意几个要点：

• permissions.id-token: write 让 GitHub 给你的 job 发 OIDC token。
• GCP 那边要配 Workload Identity Pool + Provider，信任 token.actions.githubusercontent.com，并按 repo / branch 限定。
• Pool 里绑的 Service Account 要有 Vertex AI User 角色。
• google-github-actions/auth@v2 action 注入的 ADC，会被 Claude Code 自动用，不需要额外配 key。

WIF 的好处是没有长期凭证可泄——每次 job 拿到的是短期 token，job 结束就失效。

Region 与项目

Vertex 模式下，模型调用需要知道走哪个 GCP 项目、哪个 Region。常用环境变量：

# 项目 ID
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Region
export CLOUD_ML_REGION=us-east5

具体的可用 Region 以 Vertex AI 文档为准——Claude 系列模型并不是所有 Region 都开了，配置前先确认你选的 Region 支持你要用的模型。

一张速查表

想做的事	设这个
切到 Vertex	CLAUDE_CODE_USE_VERTEX=1
本机走 ADC	gcloud auth application-default login
SA 跑在服务器	GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
跳过认证接网关	CLAUDE_CODE_SKIP_VERTEX_AUTH=1
指定项目	ANTHROPIC_VERTEX_PROJECT_ID=your-project
指定 Region	CLOUD_ML_REGION=us-east5
CI 用 WIF	permissions.id-token: write + google-github-actions/auth@v2

常见踩坑

• Region 没开模型：Vertex 的 Claude 系列模型不是所有 Region 都开了，配前先确认。
• Service Account 权限不够：要给 Vertex AI User 角色，否则调模型会 403。
• WIF Pool 信任写错：GitHub OIDC 的 subject 长这样 repo:owner/repo:ref:refs/heads/main，配 attribute mapping 时要 match 上。
• ADC 没登录：开发者忘了跑 gcloud auth application-default login，结果一直报认证失败。注意是 application-default，不是普通的 gcloud auth login。

Bedrock vs Vertex：怎么选

维度	AWS Bedrock	GCP Vertex AI
认证	AWS SSO / OIDC / 凭证脚本	ADC / WIF
CI 集成	aws-actions/configure-aws-credentials	google-github-actions/auth@v2
Region	AWS Region	GCP Region
适合	AWS 重度用户	GCP 重度用户
跳过认证接网关	CLAUDE_CODE_SKIP_BEDROCK_AUTH=1	CLAUDE_CODE_SKIP_VERTEX_AUTH=1

选哪个，基本看你公司在哪朵云上深耕。模型本身是同一套 Claude，体验一致。

Vertex 模式下，你的 Claude Code 依然跑得飞快，只是数据没出 GCP 项目、认证复用了你已有的体系。下一站：网络与 LLM 网关。