Claude Code en la Plataforma de Agentes de Google Cloud

Requisitos previos

Antes de configurar Claude Code con Google Cloud’s Agent Platform de Google Cloud, anteriormente conocido como Vertex AI, asegúrese de tener:

Una cuenta de Google Cloud Platform (GCP) con facturación habilitada
Un proyecto de GCP con la API de Google Cloud’s Agent Platform habilitada
Acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.6)
Google Cloud SDK (gcloud) instalado y configurado
Cuota asignada en la región de GCP deseada

Para iniciar sesión con sus propias credenciales de Google Cloud’s Agent Platform, siga Iniciar sesión con Google Cloud’s Agent Platform a continuación. Para implementar Claude Code en un equipo, utilice los pasos de configuración manual y fije las versiones de su modelo antes de implementar. Si tiene credenciales de Google Cloud y desea comenzar a usar Claude Code a través de Agent Platform de Google Cloud, el asistente de inicio de sesión lo guía a través del proceso. Completa los requisitos previos del lado de GCP una vez por proyecto; el asistente maneja el lado de Claude Code.

Habilitar modelos Claude en su proyecto de GCP

Habilite la API de Agent Platform de Google Cloud para su proyecto, luego solicite acceso a los modelos Claude que desee en el Model Garden de Agent Platform de Google Cloud. Consulte Configuración de IAM para los permisos que su cuenta necesita.

Inicie Claude Code y elija Agent Platform de Google Cloud

Ejecute claude. En el mensaje de inicio de sesión, seleccione 3rd-party platform, luego Google Vertex AI, la etiqueta que el mensaje de inicio de sesión aún utiliza para Agent Platform de Google Cloud. Si ya ha iniciado sesión, ejecute /login para abrir el mismo menú.

Siga los mensajes del asistente

Elija cómo se autentica en Google Cloud: Credenciales predeterminadas de aplicación de gcloud, un archivo de clave de cuenta de servicio, o credenciales ya en su entorno. El asistente detecta su proyecto y región, verifica qué modelos Claude puede invocar su proyecto, y le permite fijarlos. Guarda el resultado en el bloque env de su archivo de configuración de usuario, por lo que no necesita exportar variables de entorno usted mismo.

Después de haber iniciado sesión, ejecute /setup-vertex en cualquier momento para reabrirlo el asistente y cambiar sus credenciales, proyecto, región o fijaciones de modelo. El paso de fijación de modelo comienza desde sus modelos actualmente fijados. El asistente escribe en ~/.claude/settings.json, o en $CLAUDE_CONFIG_DIR/settings.json cuando CLAUDE_CONFIG_DIR está configurado.

Configuración de región

Claude Code admite puntos finales de Google Cloud’s Agent Platform globales, multirregión y regionales. Establezca CLOUD_ML_REGION en global, una ubicación multirregión como eu o us, o una región específica como us-east5. Claude Code selecciona el nombre de host correcto de Google Cloud’s Agent Platform para cada formulario, incluidos los hosts aiplatform.eu.rep.googleapis.com y aiplatform.us.rep.googleapis.com para ubicaciones multirregión.

Google Cloud’s Agent Platform puede no admitir los modelos predeterminados de Claude Code en todos los tipos de puntos finales. La disponibilidad del modelo varía según regiones específicas, ubicaciones multirregión y puntos finales globales. Es posible que deba cambiar a una ubicación compatible o especificar un modelo compatible.

Configurar manualmente

Para configurar Google Cloud’s Agent Platform a través de variables de entorno en lugar del asistente, por ejemplo en CI o una implementación empresarial con script, siga los pasos a continuación.

Habilitar la API de Agent Platform

Habilite la API de Agent Platform de Google Cloud en su proyecto de GCP. Reemplace YOUR-PROJECT-ID con su ID de proyecto de GCP aquí y en el paso de configuración a continuación:

# Establezca su ID de proyecto
gcloud config set project YOUR-PROJECT-ID

# Habilitar la API de Agent Platform
gcloud services enable aiplatform.googleapis.com

Solicitar acceso al modelo

Solicite acceso a los modelos Claude en Google Cloud’s Agent Platform:

Navegue al Google Cloud’s Agent Platform Model Garden
Busque modelos “Claude”
Solicite acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.6)
Espere la aprobación (puede tomar 24-48 horas)

Configurar credenciales de GCP

Claude Code utiliza la autenticación estándar de Google Cloud. Para obtener más información, consulte la documentación de autenticación de Google Cloud. Claude Code admite Federación de identidad de carga de trabajo basada en certificados X.509 a través de la misma cadena de credenciales de aplicación predeterminada. Establezca GOOGLE_APPLICATION_CREDENTIALS en la ruta de su archivo de configuración de credenciales.

Claude Code dirige las solicitudes de Google Cloud’s Agent Platform al proyecto en ANTHROPIC_VERTEX_PROJECT_ID, incluso cuando GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, o el archivo de credenciales referenciado por GOOGLE_APPLICATION_CREDENTIALS lleva un proyecto diferente.

Configuración avanzada de credenciales

Claude Code admite la actualización automática de credenciales para GCP a través de la configuración gcpAuthRefresh. Agréguela a su archivo de configuración de Claude Code, por ejemplo ~/.claude/settings.json. Cuando Claude Code detecta que sus credenciales de GCP han expirado o no se pueden cargar, ejecuta el comando configurado para obtener nuevas credenciales antes de reintentar la solicitud.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

Antes de ejecutar el comando, Claude Code solicita un token de acceso con sus credenciales actuales para confirmar que realmente han expirado, y omite el comando cuando aún funcionan. Si la verificación no se completa en cinco segundos, Claude Code también omite el comando y lo ejecuta solo después de que una solicitud falla con un error de credenciales. Antes de v2.1.261, una verificación que agotó el tiempo de espera se contaba como una credencial expirada, por lo que el comando podría abrir su navegador al inicio incluso aunque sus credenciales aún fueran válidas. Claude Code le muestra la salida del comando, pero no puede enviar entrada interactiva al comando. Esto funciona bien para flujos de autenticación basados en navegador donde la CLI muestra una URL y usted completa la autenticación en el navegador. El comando de actualización agota el tiempo de espera después de tres minutos si la autenticación no se completa. Si establece gcpAuthRefresh en la configuración del proyecto como .claude/settings.json, Claude Code lo ejecuta bajo la misma regla de confianza del espacio de trabajo que los hooks en archivos de configuración, que incluye sesiones -p en carpetas que nunca ha confiado.

Configurar Claude Code

Establezca las siguientes variables de entorno:

# Habilitar la integración de Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Anular la URL del punto final de Agent Platform para puntos finales personalizados o puertas de enlace
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Cuando CLOUD_ML_REGION=global, anule la región para modelos que no admiten puntos finales globales
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

La mayoría de las versiones de modelo tienen una variable VERTEX_REGION_CLAUDE_* correspondiente. Consulta la referencia de variables de entorno para obtener la lista completa. Revisa Google Cloud’s Agent Platform Model Garden para determinar qué modelos admiten endpoints globales frente a solo regionales. Si un valor de región no tiene forma de nombre de región o ubicación, Claude Code lo trata como no establecido. Por ejemplo, Claude Code trata un valor que contiene una barra diagonal, punto o espacio como no establecido. Claude Code retrocede a una fuente diferente para cada variable:

VERTEX_REGION_CLAUDE_*: Claude Code retrocede a CLOUD_ML_REGION.
CLOUD_ML_REGION: Claude Code retrocede a us-east5.

Prompt caching se habilita automáticamente. Para deshabilitarlo, establezca DISABLE_PROMPT_CACHING=1. Para solicitar un TTL de caché de 1 hora en lugar del predeterminado de 5 minutos, establezca ENABLE_PROMPT_CACHING_1H=1; las escrituras de caché con un TTL de 1 hora se facturan a una tarifa más alta. Para establecer diferentes TTL para su conversación principal y para las solicitudes que Claude Code realiza fuera de ella, elija el TTL usted mismo. Para aumentar sus límites de velocidad, póngase en contacto con el soporte de Google Cloud. Al usar Google Cloud’s Agent Platform, el comando /logout no está disponible ya que la autenticación se maneja a través de credenciales de Google Cloud. Claude Code decide entre búsqueda de herramientas MCP y carga por adelantado según la generación del modelo:

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 y posterior: Claude Code habilita la búsqueda de herramientas de forma predeterminada.
Modelos anteriores: Claude Code carga las definiciones de herramientas MCP por adelantado, porque sus pilas de servicio de Agent Platform rechazan el encabezado beta requerido. Establecer ENABLE_TOOL_SEARCH=true no sobrescribe esto.

Establece ENABLE_TOOL_SEARCH=false para deshabilitar la búsqueda de herramientas en todos los modelos.

Fijar versiones de modelo

Fije versiones de modelo específicas al implementar para varios usuarios. Sin fijar, alias de modelo como sonnet y opus se resuelven al valor predeterminado integrado de Claude Code para Google Cloud’s Agent Platform, que puede estar rezagado con respecto a la versión más reciente y puede que aún no esté habilitado en su proyecto. Claude Code retrocede a una versión anterior o modelo de nivel inferior al inicio cuando el valor predeterminado no está disponible, pero fijar le permite controlar cuándo sus usuarios se mueven a un nuevo modelo.

Establezca estas variables de entorno en ID de modelo específicos de Google Cloud’s Agent Platform. Sin ANTHROPIC_DEFAULT_OPUS_MODEL, el alias opus en Google Cloud’s Agent Platform se resuelve a Opus 5.5, y sin ANTHROPIC_DEFAULT_SONNET_MODEL, el alias sonnet se resuelve a Sonnet 4.5. Este ejemplo fija cada alias a una versión específica:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Para los ID de modelo actuales y heredados, consulte Descripción general de modelos. Consulte Configuración de modelo para obtener la lista completa de variables de entorno. Claude Code utiliza estos modelos predeterminados cuando no se establecen variables de fijación:

Tipo de modelo	Valor predeterminado
Modelo principal	`claude-opus-5-5`
Modelo pequeño/rápido	`claude-sonnet-4-5@20250929`

Antes de v2.1.280, el modelo principal en Google Cloud’s Agent Platform se establecía de forma predeterminada en Opus 5 y el alias opus se resolvía a Opus 5 desde v2.1.219. Las tareas en segundo plano como la generación de títulos de sesión utilizan el modelo pequeño/rápido, normalmente un modelo de clase Haiku. En Google Cloud’s Agent Platform, Claude Code utiliza el modelo Sonnet predeterminado para tareas en segundo plano porque Haiku puede no estar habilitado en todos los proyectos o regiones. Dos selecciones cambian qué modelo las realiza:

Cuando selecciona un modelo principal con --model, ANTHROPIC_MODEL, o la configuración model, las tareas en segundo plano utilizan ese modelo. Cuando Claude Code inicia la sesión en el modelo que establece con ANTHROPIC_DEFAULT_MODEL, las tareas en segundo plano utilizan ese modelo también. Establecer ANTHROPIC_DEFAULT_OPUS_MODEL sin ANTHROPIC_DEFAULT_SONNET_MODEL también cuenta como una selección, porque el modelo Sonnet integrado puede no estar habilitado en un proyecto que dirige su propio Opus.
Para usar Haiku para tareas en segundo plano, establezca ANTHROPIC_DEFAULT_HAIKU_MODEL en un ID de modelo que esté disponible en su proyecto.

Los modelos Opus tienen un precio por token más alto que los modelos Sonnet, por lo que si no fijas un modelo principal, se te factura a la tarifa de Opus. Para usar Sonnet 4.5 como el modelo principal, establece ANTHROPIC_MODEL en su ID de modelo completo. Un despliegue que dirige el valor predeterminado con ANTHROPIC_DEFAULT_SONNET_MODEL y no establece ANTHROPIC_DEFAULT_OPUS_MODEL mantiene su modelo Sonnet dirigido como el valor predeterminado.

Para personalizar aún más los modelos:

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Verificar su configuración

Inicie Claude Code y ejecute /status para confirmar la configuración. La línea API provider muestra Google Vertex AI, y las líneas GCP project, Default region y Model muestran su ID de proyecto, región y modelo resuelto. Si falta la línea del proveedor, las variables de entorno no llegan al proceso. Confirme que se exportan en el shell donde lanzó claude, o establézcalas en el bloque env de su archivo de configuración.

Verificaciones de modelo al inicio

Cuando Claude Code se inicia con Google Cloud’s Agent Platform configurado, verifica que los modelos que pretende usar sean accesibles en su proyecto. Es posible que hayas fijado una versión de modelo más antigua que el valor predeterminado actual de Claude Code. Si tu proyecto puede invocar la versión más reciente, Claude Code te pide que actualices la fijación:

Si aceptas: Claude Code escribe el nuevo ID de modelo en tu archivo de configuración de usuario y se reinicia
Si rechazas: Claude Code recuerda tu elección hasta el próximo cambio de versión predeterminada

Para una fijación en el bloque env de la configuración administrada, Claude Code no ejecuta ninguna verificación ni muestra ninguna solicitud. Si la solicitud de actualización sigue apareciendo para esta fijación, actualiza Claude Code a la v2.1.314 o posterior. Antes de la v2.1.314, la fijación administrada seguía vigente después de que aceptabas, por lo que la solicitud volvía a aparecer en el siguiente inicio. Si no ha fijado un modelo y el valor predeterminado actual no está disponible en su proyecto, Claude Code retrocede para la sesión actual y muestra un aviso. Intenta primero versiones anteriores del modelo predeterminado y, cuando el valor predeterminado es un modelo Opus y no hay ninguna versión de Opus disponible, retrocede al modelo Sonnet predeterminado. El retroceso no se persiste. Habilite el modelo más reciente en Model Garden o fije una versión para hacer la opción permanente.

Iniciar una sesión en un modelo específico

Cuando inicia la sesión en una versión específica de Sonnet u Opus, por ejemplo con --model, ANTHROPIC_MODEL, o la configuración model, esa versión actúa como el valor predeterminado fijado de la sesión para el alias sonnet u opus correspondiente. Claude Code omite la verificación de disponibilidad para el valor predeterminado integrado que su modelo reemplaza e inicia en el modelo que configuró, sin aviso de retroceso. Cuando inicias una sesión en un alias de modelo como opus o en un ID de modelo que Claude Code no reconoce, ese valor no actúa como fijación.

Rechazos de modelo recordados

Cuando las verificaciones de modelo al inicio encuentran un modelo que tu proyecto no puede invocar, Claude Code puede recordar el rechazo en esta máquina durante hasta un día. Una vez que han pasado diez minutos desde la última verificación, Claude Code vuelve a verificar al iniciar un rechazo recordado de un modelo predeterminado actual. Así, un valor predeterminado que tu administrador vuelve a habilitar regresa. Para desactivar la memoria, establece CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1.

Cuando tu organización aplica una lista de modelos permitidos

Si estableces enforceAvailableModels en la configuración administrada, las verificaciones de modelo al inicio usan solo los modelos que permite tu lista availableModels. Esto requiere Claude Code v2.1.287 o posterior. Una lista sin enforceAvailableModels no restringe estas verificaciones. Las verificaciones comparan cada entrada con el ID de modelo que enviarían a Agent Platform, así que escribe la lista con esos IDs. Este ejemplo permite Opus 4.8 y Sonnet 4.5:

{
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],
  "enforceAvailableModels": true
}

Para alias, prefijos de versión y entradas de modelOverrides, consulta Fijar modelos para despliegues de terceros.

Cuando un modelo se deshabilita durante la sesión

Cuando Agent Platform rechaza el modelo de tu sesión por no estar disponible en tu proyecto o región, Claude Code cambia tu sesión a otro modelo y puedes seguir trabajando. Verás un mensaje que comienza con Switched to <fallback> because <model> is not available. Esto ocurre, por ejemplo, cuando un administrador deshabilita el modelo en Model Garden o cuando no se ofrece en tu región. Si configuraste una cadena de modelos de respaldo, Claude Code cambia a tu respaldo configurado en su lugar. Sin una cadena, la solicitud falla en casos como estos:

Tu sesión está en un modelo fijado o en una versión específica que elegiste
Ninguno de los modelos que Claude Code intenta está disponible. En modo automático, Claude Code solo cambia a un modelo que el modo automático admite en Agent Platform.

Para seguir trabajando, ejecuta /model en la sesión y presiona s sobre un modelo disponible en tu proyecto y región, lo cual deja tu valor predeterminado sin cambios. Para que las solicitudes rechazadas fallen en lugar de cambiar, establece CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1. Si configuraste una cadena de modelos de respaldo, elimínala también, porque Claude Code sigue cambiando a ese respaldo.

Configuración de IAM

Asigne el rol roles/aiplatform.user, que incluye los permisos requeridos:

aiplatform.endpoints.predict - Requerido para la invocación de modelo y conteo de tokens

Para permisos más restrictivos, cree un rol personalizado con solo los permisos anteriores. Para obtener más detalles, consulte la documentación de IAM de Google Cloud Agent Platform.

Cree 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

Los modelos Fable, Sonnet 5 y posteriores, y Opus 4.7 y posteriores se ejecutan de forma predeterminada con la ventana de contexto de 1M de tokens en Google Cloud’s Agent Platform, sin necesidad del sufijo [1m]. Para mantener una ventana de 200K en su lugar, establece CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Opus 4.6 y Sonnet 4.6 alcanzan la ventana de 1M cuando seleccionas su variante [1m]. El asistente de configuración ofrece una opción de contexto de 1M cuando fija modelos. Para habilitarlo para un modelo fijado manualmente en su lugar, agrega [1m] al ID del modelo. Consulta Fijar modelos para despliegues de terceros para obtener detalles, incluida la forma de usar la ventana de 1M sin cambiar la fijación. Antes de la v2.1.287, los modelos Fable y Opus 4.7 y posteriores se ejecutaban de forma predeterminada con una ventana de 200K en Google Cloud’s Agent Platform y alcanzaban la ventana de 1M mediante un sufijo [1m].

Solución de problemas

Si encuentra errores “No se pudieron cargar las credenciales predeterminadas”:

Ejecute gcloud auth application-default login para configurar las credenciales predeterminadas de la aplicación
Establezca GOOGLE_APPLICATION_CREDENTIALS en una ruta de archivo de clave de cuenta de servicio
Consulte Configurar credenciales de GCP para todas las opciones

Si encuentra problemas de cuota:

Verifique las cuotas actuales o solicite un aumento de cuota a través de Cloud Console

Si encuentra errores “modelo no encontrado” 404:

Confirme que el modelo está habilitado en Model Garden
Verifique que el modelo esté disponible en la ubicación que especificó. Algunos modelos se ofrecen solo en ubicaciones global o multirregión como eu y us, no en regiones específicas
Si utilizas CLOUD_ML_REGION=global, verifica que tus modelos admitan endpoints globales en Model Garden en “Supported features”. Para modelos que no admiten endpoints globales, puedes:
- Especificar un modelo compatible a través de ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, o
- Establecer una región o ubicación multirregión usando la variable VERTEX_REGION_CLAUDE_* del modelo, que aparece en la referencia de variables de entorno

Si encuentra errores 429:

Para puntos finales regionales, asegúrese de que el modelo principal y el modelo pequeño/rápido sean compatibles en su región seleccionada
Considere cambiar a CLOUD_ML_REGION=global para una mejor disponibilidad

Configuración y acceso

Despliegue

Gateways

Uso y costos

Seguridad y datos

Adopción

Claude Code en la Plataforma de Agentes de Google Cloud

Requisitos previos

Configuración de región

Configurar manualmente

Habilitar la API de Agent Platform

Solicitar acceso al modelo

Configurar credenciales de GCP

Configuración avanzada de credenciales

Configurar Claude Code

Fijar versiones de modelo

Verificar su configuración

Verificaciones de modelo al inicio

Iniciar una sesión en un modelo específico

Rechazos de modelo recordados

Cuando tu organización aplica una lista de modelos permitidos

Cuando un modelo se deshabilita durante la sesión

Configuración de IAM

Ventana de contexto de 1M de tokens

Solución de problemas

Recursos adicionales

​Requisitos previos

​Iniciar sesión con Agent Platform

​Configuración de región

​Configurar manualmente

​ Habilitar la API de Agent Platform

​ Solicitar acceso al modelo

​ Configurar credenciales de GCP

​Configuración avanzada de credenciales

​ Configurar Claude Code

​ Fijar versiones de modelo

​ Verificar su configuración

​Verificaciones de modelo al inicio

​Iniciar una sesión en un modelo específico

​Rechazos de modelo recordados

​Cuando tu organización aplica una lista de modelos permitidos

​Cuando un modelo se deshabilita durante la sesión

​Configuración de IAM

​Ventana de contexto de 1M de tokens

​Solución de problemas

​Recursos adicionales

Requisitos previos

Iniciar sesión con Agent Platform

Configuración de región

Configurar manualmente

Habilitar la API de Agent Platform

Solicitar acceso al modelo

Configurar credenciales de GCP

Configuración avanzada de credenciales

Configurar Claude Code

Fijar versiones de modelo

Verificar su configuración

Verificaciones de modelo al inicio

Iniciar una sesión en un modelo específico

Rechazos de modelo recordados

Cuando tu organización aplica una lista de modelos permitidos

Cuando un modelo se deshabilita durante la sesión

Configuración de IAM

Ventana de contexto de 1M de tokens

Solución de problemas

Recursos adicionales