​
Prerrequisitos

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 de Claude deseados (por ejemplo, Claude Sonnet 4)
  • Google Cloud SDK (gcloud) instalado y configurado
  • Cuota asignada en la región de GCP deseada

Vertex AI puede no soportar los modelos predeterminados de Claude Code en regiones que no sean us-east5. Asegúrate de estar usando us-east5 y tener cuota asignada, o cambia a modelos soportados.

​
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 de Claude en Vertex AI:

  1. Navega al Jardín de Modelos de Vertex AI
  2. Busca modelos “Claude”
  3. Solicita acceso a los modelos de Claude deseados (por ejemplo, Claude Sonnet 4)
  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.

​
4. Configurar Claude Code

Establece las siguientes variables de entorno:

# Habilitar integración con Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Deshabilitar caché de prompts si no está habilitado
export DISABLE_PROMPT_CACHING=1

Para límites de velocidad elevados y habilitación de caché de prompts, contacta al soporte de Google Cloud. Una vez habilitado, elimina la configuración DISABLE_PROMPT_CACHING.

​
5. Configuración del modelo

Claude Code utiliza estos modelos predeterminados para Vertex AI:

Tipo de modeloValor predeterminado
Modelo principalclaude-sonnet-4@20250514
Modelo pequeño/rápidoclaude-3-5-haiku@20241022

Para personalizar modelos:

export ANTHROPIC_MODEL='claude-opus-4@20250514'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
Configuración de IAM

Otorga los roles de IAM requeridos para Claude Code.

Para 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.

​
Solución de problemas

Si encuentras problemas de cuota:

  • Verifica las cuotas actuales o solicita un aumento de cuota a través de la Consola de Cloud

Si encuentras errores 404 de “modelo no encontrado”:

  • Verifica que tienes acceso a la región especificada
  • Confirma que el modelo está Habilitado en el Jardín de Modelos

Si encuentras errores 429:

  • Asegúrate de que el modelo principal y el modelo pequeño/rápido estén soportados en tu región seleccionada

​
Recursos adicionales