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

Al autenticarse, Claude Code utilizará automáticamente el ID del 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:

# 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 es necesario
export DISABLE_PROMPT_CACHING=1

# Opcional: Anular regiones para modelos específicos
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
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-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4

El caché de prompts es soportado automáticamente cuando especificas la bandera efímera cache_control. Para deshabilitarlo, establece DISABLE_PROMPT_CACHING=1. Para límites de velocidad elevados, contacta al 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 las 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@20250514
Modelo pequeño/rápidoclaude-3-5-haiku@20241022

Para personalizar modelos:

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

​
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 del modelo
  • aiplatform.endpoints.computeTokens - Requerido para el conteo de tokens

Para permisos más restrictivos, crea un rol personalizado con solo los permisos anteriores.

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 Cloud Console

Si encuentras errores 404 de “modelo no encontrado”:

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

Si encuentras errores 429:

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

​
Recursos adicionales