Claude Code en la Plataforma de Agentes de Google Cloud
Aprenda a configurar Claude Code a través de la Plataforma de Agentes de Google Cloud, anteriormente Vertex AI, incluida la configuración, la configuración de IAM y la solución de problemas.
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.
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.
3
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.
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.
1. Habilitar la API de Agent Platform
Habilite la API de Agent Platform de Google Cloud en su proyecto de GCP:
# Establezca su ID de proyecto
gcloud config set project YOUR-PROJECT-ID# Habilitar la API de Agent Platform
gcloud services enable aiplatform.googleapis.com
2. Solicitar acceso al modelo
Solicite acceso a los modelos Claude en Google Cloud's Agent Platform:
Claude Code admite la actualización automática de credenciales para GCP a través de la configuración gcpAuthRefresh. 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.
La salida del comando se muestra al usuario, pero la entrada interactiva no es compatible. 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, el comando se ejecuta solo después de que acepte el mensaje de confianza del espacio de trabajo.
4. Configurar Claude Code
Establezca las siguientes variables de entorno:
# Habilitar la integración de Agent Platformexport CLAUDE_CODE_USE_VERTEX=1export 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# Opcional: Deshabilitar el almacenamiento en caché de indicaciones si es necesarioexport DISABLE_PROMPT_CACHING=1# Opcional: Solicitar TTL de caché de indicaciones de 1 hora en lugar del predeterminado de 5 minutosexport ENABLE_PROMPT_CACHING_1H=1# Cuando CLOUD_ML_REGION=global, anule la región para modelos que no admiten puntos finales globalesexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
La mayoría de las versiones de modelo tienen una variable VERTEX_REGION_CLAUDE_* correspondiente. Consulte la referencia de variables de entorno para obtener la lista completa. Verifique Google Cloud's Agent Platform Model Garden para determinar qué modelos admiten puntos finales globales frente a solo regionales.
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 límites de velocidad elevados, 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 deshabilita MCP tool search de forma predeterminada en Google Cloud's Agent Platform, por lo que las definiciones de herramientas MCP se cargan por adelantado. Google Cloud's Agent Platform admite búsqueda de herramientas para Claude Sonnet 4.5 y posterior y Claude Opus 4.5 y posterior. Establezca ENABLE_TOOL_SEARCH=true para habilitarlo en esos modelos. Los modelos anteriores en Google Cloud's Agent Platform no aceptan el encabezado beta requerido, y las solicitudes fallan si habilita la búsqueda de herramientas con ellos.
5. Fijar versiones de 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 4.8, 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:
Claude Code utiliza estos modelos predeterminados cuando no se establecen variables de fijación:
Tipo de modelo
Valor predeterminado
Modelo principal
claude-opus-4-8
Modelo pequeño/rápido
claude-sonnet-4-5@20250929
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. 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.
{/* min-version: 2.1.207 */}Antes de v2.1.207, el modelo principal en Google Cloud's Agent Platform se establecía de forma predeterminada en Sonnet 4.5, el alias opus se resolvía a Opus 4.6, y las tareas en segundo plano siempre utilizaban el modelo principal.
Cuando Claude Code se inicia con Google Cloud's Agent Platform configurado, verifica que los modelos que pretende usar sean accesibles en su proyecto.
Si ha fijado una versión de modelo que es más antigua que el valor predeterminado actual de Claude Code, y su proyecto puede invocar la versión más reciente, Claude Code le solicita que actualice la fijación. Aceptar escribe el nuevo ID de modelo en su archivo de configuración de usuario y reinicia Claude Code. Rechazar se recuerda hasta el próximo cambio de versión predeterminada.
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.
Configuración de IAM
Asigne los permisos de IAM requeridos:
El rol roles/aiplatform.user 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.
Claude Sonnet 5, Opus 4.6 y posteriores, y Sonnet 4.6 admiten la ventana de contexto de 1M de tokens en Google Cloud's Agent Platform. Sonnet 5 siempre se ejecuta con la ventana de 1M, sin ninguna variante [1m] para seleccionar. Para los otros modelos, Claude Code habilita automáticamente la ventana de contexto extendida cuando selecciona una variante de modelo de 1M.
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 utiliza CLOUD_ML_REGION=global, verifique que sus modelos admitan puntos finales globales en Model Garden en "Características compatibles". Para modelos que no admiten puntos finales globales, ya sea:
Especifique un modelo compatible a través de ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, o
Establezca una región o ubicación multirregión usando variables de entorno VERTEX_REGION_<MODEL_NAME>
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
115Despué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.115Despué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`](/es/env-vars#variables) está configurado.
118 Configuración de región118 Configuración de región
223</h3>223</h3>
224224
225<Warning>225<Warning>
226 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](#startup-model-checks) a la versión anterior al inicio cuando el valor predeterminado no está disponible, pero fijar le permite controlar cuándo sus usuarios se mueven a un nuevo modelo.226 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](#startup-model-checks) 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.
227</Warning>227</Warning>
228228
229Establezca estas variables de entorno en ID de modelo específicos de Google Cloud's Agent Platform.229Establezca estas variables de entorno en ID de modelo específicos de Google Cloud's Agent Platform.
230230
231Sin estas variables, el alias `opus` en Google Cloud's Agent Platform se resuelve a Opus 4.8 y el alias `sonnet` se resuelve a Sonnet 4.5. Establezca cada variableparafijarsu alias a una versión específica:231Sin `ANTHROPIC_DEFAULT_OPUS_MODEL`, el alias `opus` en Google Cloud's Agent Platform se resuelve a Opus 4.8, y sin `ANTHROPIC_DEFAULT_SONNET_MODEL`, el alias `sonnet` se resuelve a Sonnet 4.5. Esteejemplofijacada alias a una versión específica:
241Claude Code utiliza estos modelos predeterminados cuando no se establecen variables de fijación:241Claude Code utiliza estos modelos predeterminados cuando no se establecen variables de fijación:
242242
243| Tipo de modelo | Valor predeterminado |243| Tipo de modelo | Valor predeterminado |
245| Modelo principal | `claude-opus-4-8` |245| Modelo principal | `claude-opus-4-8` |
246| Modelo pequeño/rápido | Igual que el modelo principal |246| Modelo pequeño/rápido | `claude-sonnet-4-5@20250929` |
247247
248Las 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 establecepordefectoestoalmodeloprincipal porque Haiku puede no estar habilitado en todos los proyectos o regiones. Para usar Haiku para tareas en segundo plano, establezca `ANTHROPIC_DEFAULT_HAIKU_MODEL` enunIDde modelo que esté disponible en suproyecto.248Las 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 utilizaelmodeloSonnetpredeterminadoparatareasen segundo plano porque Haiku puede no estar habilitado en todos los proyectos o regiones. Dosseleccionescambianqué modelo lasrealiza:
249
250* Cuando selecciona un modelo principal con `--model`, `ANTHROPIC_MODEL`, o la configuración `model`, las tareas en segundo plano utilizan ese modelo. 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.
251* Para usar Haiku para tareas en segundo plano, establezca `ANTHROPIC_DEFAULT_HAIKU_MODEL` en un ID de modelo que esté disponible en su proyecto.
252
253<Warning>
254 Los modelos Opus tienen un precio por token más alto que los modelos Sonnet, por lo que una implementación que no fija un modelo principal se factura a la tarifa de Opus una vez que se actualiza a v2.1.207 o posterior. Para mantener Sonnet 4.5 como el modelo principal, establezca `ANTHROPIC_MODEL` en su ID de modelo completo. Una implementación 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.
255</Warning>
256
257{/* min-version: 2.1.207 */}Antes de v2.1.207, el modelo principal en Google Cloud's Agent Platform se establecía de forma predeterminada en Sonnet 4.5, el alias `opus` se resolvía a Opus 4.6, y las tareas en segundo plano siempre utilizaban el modelo principal.
249258
250Para personalizar aún más los modelos:259Para personalizar aún más los modelos:
251260
262271
263Si ha fijado una versión de modelo que es más antigua que el valor predeterminado actual de Claude Code, y su proyecto puede invocar la versión más reciente, Claude Code le solicita que actualice la fijación. Aceptar escribe el nuevo ID de modelo en su [archivo de configuración de usuario](/es/settings) y reinicia Claude Code. Rechazar se recuerda hasta el próximo cambio de versión predeterminada.272Si ha fijado una versión de modelo que es más antigua que el valor predeterminado actual de Claude Code, y su proyecto puede invocar la versión más reciente, Claude Code le solicita que actualice la fijación. Aceptar escribe el nuevo ID de modelo en su [archivo de configuración de usuario](/es/settings) y reinicia Claude Code. Rechazar se recuerda hasta el próximo cambio de versión predeterminada.
264273
265Si no ha fijado un modelo y el valor predeterminado actual no está disponible en su proyecto, Claude Code retrocede a la versión anterior para la sesión actual y muestra un aviso. El retroceso no se persiste. Habilite el modelo más reciente en [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) o [fije una versión](#5-pin-model-versions) para hacer la opción permanente.274Si 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](https://console.cloud.google.com/vertex-ai/model-garden) o [fije una versión](#5-pin-model-versions) para hacer la opción permanente.
286 Ventana de contexto de 1M de tokens295 Ventana de contexto de 1M de tokens
287</h2>296</h2>
288297
289Claude Sonnet 5, Opus 4.6 y posteriores, y Sonnet 4.6 admiten la [ventana de contexto de 1M de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) en Google Cloud's Agent Platform. Sonnet 5 siempre se ejecuta con la ventana de 1M, sin ninguna variante `[1m]` para seleccionar. Para los otros modelos, Claude Code habilita automáticamente la ventana de contexto extendida cuando selecciona una variante de modelo de 1M.298Claude Sonnet 5, Opus 4.6 y posteriores, y Sonnet 4.6 admiten la [ventana de contexto de 1M de tokens](https://platform.claude.com/docs/es/build-with-claude/context-windows#context-window-sizes-by-model) en Google Cloud's Agent Platform. Sonnet 5 siempre se ejecuta con la ventana de 1M, sin ninguna variante `[1m]` para seleccionar. Para los otros modelos, Claude Code habilita automáticamente la ventana de contexto extendida cuando selecciona una variante de modelo de 1M.
290299
291El [asistente de configuración](#sign-in-with-agent-platform) ofrece una opción de contexto de 1M cuando fija modelos. Para habilitarlo para un modelo fijado manualmente en su lugar, agregue `[1m]` al ID del modelo. Consulte [Fijar modelos para implementaciones de terceros](/es/model-config#pin-models-for-third-party-deployments) para obtener detalles.300El [asistente de configuración](#sign-in-with-agent-platform) ofrece una opción de contexto de 1M cuando fija modelos. Para habilitarlo para un modelo fijado manualmente en su lugar, agregue `[1m]` al ID del modelo. Consulte [Fijar modelos para implementaciones de terceros](/es/model-config#pin-models-for-third-party-deployments) para obtener detalles.
