Appearance
Claude Code on Google Vertex AI
在 GCP 环境中通过 Google Vertex AI 使用 Claude Code，获得完整的 IAM 角色控制和 GCP 原生集成。
前提条件
- 已启用结算的 GCP 账户
- 已启用 Vertex AI API 的 GCP 项目
- 已申请 Claude 模型访问权限（如 Claude Sonnet 4.6）
- 已安装并配置 Google Cloud SDK（
gcloud） - 在所需 GCP 区域已分配配额
如果向多个用户部署，请固定模型版本。
区域配置
Claude Code 同时支持 Vertex AI 全局端点和区域端点。
Vertex AI 并非在所有区域或全局端点都支持 Claude Code 默认模型。你可能需要切换到受支持的区域、使用区域端点或指定受支持的模型。
设置步骤
1. 启用 Vertex AI API
bash
# 设置项目 ID
gcloud config set project YOUR-PROJECT-ID
# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com2. 申请模型访问权限
- 导航到 Vertex AI Model Garden
- 搜索 "Claude" 模型
- 申请访问所需 Claude 模型
- 等待审批（可能需要 24-48 小时）
3. 配置 GCP 凭据
Claude Code 使用标准 Google Cloud 认证。
认证时，Claude Code 自动使用
ANTHROPIC_VERTEX_PROJECT_ID环境变量中的项目 ID。要覆盖，设置GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT或GOOGLE_APPLICATION_CREDENTIALS之一。
4. 配置 Claude Code
bash
# 启用 Vertex AI 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
# 可选：禁用提示缓存
export DISABLE_PROMPT_CACHING=1
# 当 CLOUD_ML_REGION=global 时，覆盖不支持的模型区域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5
# 可选：覆盖其他特定模型的区域
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5使用 Vertex AI 时，/login 和 /logout 命令被禁用，认证通过 Google Cloud 凭据处理。
5. 固定模型版本
重要
为每次部署固定特定模型版本，防止 Anthropic 发布新模型时中断现有用户。
bash
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'未设置固定变量时的默认模型：
| 模型类型 | 默认值 |
|---|---|
| 主模型 | claude-sonnet-4-6 |
| 小型/快速模型 | claude-haiku-4-5@20251001 |
1M Token 上下文窗口
Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 在 Vertex AI 上支持 1M token 上下文窗口。Claude Code 在你选择 1M 模型变体时自动启用扩展上下文窗口。
在固定的模型 ID 后附加 [1m] 启用：
bash
export ANTHROPIC_MODEL='claude-sonnet-4-6[1m]'IAM 配置
roles/aiplatform.user 角色包含所需权限：aiplatform.endpoints.predict（用于模型调用和 token 计数）。
对于更严格的权限，创建仅包含上述权限的自定义角色。
建议为 Claude Code 创建专用 GCP 项目，简化成本追踪和访问控制。
故障排除
配额问题：
- 通过 Cloud Console 检查当前配额或申请增加
"model not found" 404 错误：
- 确认模型在 Model Garden 中已启用
- 验证你有权访问指定区域
- 如果使用
CLOUD_ML_REGION=global，检查模型是否支持全局端点
429 错误：
- 确保主模型和小型/快速模型在所选区域受支持
- 考虑切换到
CLOUD_ML_REGION=global获得更好的可用性