Saltar al contenido principal

​
Requisitos previos

Antes de configurar Claude Code con Vertex AI, asegúrate de tener:
  • Una cuenta de Google Cloud Platform (GCP) con facturación habilitada
  • Un proyecto de GCP con la API de Vertex AI habilitada
  • Acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.5)
  • Google Cloud SDK (gcloud) instalado y configurado
  • Cuota asignada en la región de GCP deseada

​
Configuración de región

Claude Code se puede usar tanto con puntos finales globales como regionales de Vertex AI.
Vertex AI puede no admitir los modelos predeterminados de Claude Code en todas las regiones. Es posible que debas cambiar a una región o modelo compatible.
Vertex AI puede no admitir los modelos predeterminados de Claude Code en puntos finales globales. Es posible que debas cambiar a un punto final regional o a un modelo compatible.

​
Configuración

​
1. Habilitar la API de Vertex AI

Habilita la API de Vertex AI en tu proyecto de GCP: 
# Establece tu ID de proyecto
gcloud config set project YOUR-PROJECT-ID

# Habilita la API de Vertex AI
gcloud services enable aiplatform.googleapis.com

​
2. Solicitar acceso al modelo

Solicita acceso a los modelos Claude en Vertex AI:
  1. Navega al Vertex AI Model Garden
  2. Busca modelos “Claude”
  3. Solicita acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.5)
  4. Espera la aprobación (puede tomar 24-48 horas)

​
3. Configurar credenciales de GCP

Claude Code utiliza la autenticación estándar de Google Cloud. Para más información, consulta la documentación de autenticación de Google Cloud.
Al autenticarse, Claude Code utilizará automáticamente el ID de proyecto de la variable de entorno ANTHROPIC_VERTEX_PROJECT_ID. Para anular esto, establece una de estas variables de entorno: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, o GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configurar Claude Code

Establece las siguientes variables de entorno: 
# Habilita la integración de Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Deshabilita el almacenamiento en caché de indicaciones si es necesario
export DISABLE_PROMPT_CACHING=1

# Cuando CLOUD_ML_REGION=global, anula la región para modelos no compatibles
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Opcional: Anula regiones para otros modelos específicos
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
El almacenamiento en caché de indicaciones se admite automáticamente cuando especificas la bandera efímera cache_control. Para deshabilitarlo, establece DISABLE_PROMPT_CACHING=1. Para límites de velocidad elevados, contacta con el soporte de Google Cloud.
Al usar Vertex AI, los comandos /login y /logout están deshabilitados ya que la autenticación se maneja a través de credenciales de Google Cloud.

​
5. Configuración del modelo

Claude Code utiliza estos modelos predeterminados para Vertex AI:
Tipo de modeloValor predeterminado
Modelo principalclaude-sonnet-4-5@20250929
Modelo pequeño/rápidoclaude-haiku-4-5@20251001
Para usuarios de Vertex AI, Claude Code no se actualizará automáticamente de Haiku 3.5 a Haiku 4.5. Para cambiar manualmente a un modelo Haiku más nuevo, establece la variable de entorno ANTHROPIC_DEFAULT_HAIKU_MODEL al nombre completo del modelo (por ejemplo, claude-haiku-4-5@20251001).
Para personalizar modelos: 
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
Configuración de IAM

Asigna los permisos de IAM requeridos: El rol roles/aiplatform.user incluye los permisos requeridos:
  • aiplatform.endpoints.predict - Requerido para la invocación de modelos y conteo de tokens
Para permisos más restrictivos, crea un rol personalizado solo con los permisos anteriores. Para más detalles, consulta la documentación de IAM de Vertex.
Recomendamos crear un proyecto de GCP dedicado para Claude Code para simplificar el seguimiento de costos y el control de acceso.

​
Ventana de contexto de 1M de tokens

Claude Sonnet 4 y Sonnet 4.5 admiten la ventana de contexto de 1M de tokens en Vertex AI.
La ventana de contexto de 1M de tokens está actualmente en beta. Para usar la ventana de contexto extendida, incluye el encabezado beta context-1m-2025-08-07 en tus solicitudes de Vertex AI.

​
Solución de problemas

Si encuentras problemas de cuota:
  • Verifica las cuotas actuales o solicita un aumento de cuota a través de Cloud Console
Si encuentras errores “modelo no encontrado” 404:
  • Confirma que el modelo está habilitado en Model Garden
  • Verifica que tengas acceso a la región especificada
  • Si usas CLOUD_ML_REGION=global, verifica que tus modelos admitan puntos finales globales en Model Garden bajo “Características compatibles”. Para modelos que no admiten puntos finales globales, ya sea:
    • Especifica un modelo compatible a través de ANTHROPIC_MODEL o ANTHROPIC_SMALL_FAST_MODEL, o
    • Establece un punto final regional usando variables de entorno VERTEX_REGION_<MODEL_NAME>
Si encuentras errores 429:
  • Para puntos finales regionales, asegúrate de que el modelo principal y el modelo pequeño/rápido sean compatibles en tu región seleccionada
  • Considera cambiar a CLOUD_ML_REGION=global para mejor disponibilidad

​
Recursos adicionales