Claude Code sur la Plateforme Agent de Google Cloud

Conditions préalables

Avant de configurer Claude Code avec Google Cloud’s Agent Platform, anciennement Vertex AI, assurez-vous que vous disposez de :

Un compte Google Cloud Platform (GCP) avec facturation activée
Un projet GCP avec l’API Google Cloud’s Agent Platform activée
Accès aux modèles Claude souhaités (par exemple, Claude Sonnet 4.6)
Google Cloud SDK (gcloud) installé et configuré
Quota alloué dans la région GCP souhaitée

Pour vous connecter avec vos propres identifiants Google Cloud’s Agent Platform, suivez Se connecter avec Google Cloud’s Agent Platform ci-dessous. Pour déployer Claude Code dans une équipe, utilisez les étapes de configuration manuelle et épinglez vos versions de modèle avant le déploiement. Si vous disposez d’identifiants Google Cloud et souhaitez commencer à utiliser Claude Code via Agent Platform de Google Cloud, l’assistant de connexion vous guide tout au long du processus. Vous remplissez les prérequis côté GCP une fois par projet ; l’assistant gère la partie Claude Code.

Activer les modèles Claude dans votre projet GCP

Activez l’API Agent Platform de Google Cloud pour votre projet, puis demandez l’accès aux modèles Claude souhaités dans le Model Garden d’Agent Platform de Google Cloud. Consultez la section Configuration IAM pour connaître les permissions dont votre compte a besoin.

Démarrer Claude Code et choisir Agent Platform de Google Cloud

Exécutez claude. À l’invite de connexion, sélectionnez 3rd-party platform, puis Google Vertex AI, le libellé que l’invite de connexion utilise encore pour Agent Platform de Google Cloud. Si vous êtes déjà connecté, exécutez /login pour ouvrir le même menu.

Suivre les instructions de l'assistant

Choisissez votre méthode d’authentification auprès de Google Cloud : Application Default Credentials depuis gcloud, un fichier de clé de compte de service, ou des identifiants déjà présents dans votre environnement. L’assistant vous demande votre projet et votre région, vérifie quels modèles Claude votre projet peut invoquer et vous permet de les épingler. Il enregistre le résultat dans le bloc env de votre fichier de paramètres utilisateur, vous n’avez donc pas besoin d’exporter vous-même les variables d’environnement.

Une fois connecté, exécutez /setup-vertex à tout moment pour rouvrir l’assistant et modifier vos identifiants, votre projet, votre région ou vos modèles épinglés. L’étape d’épinglage des modèles part de vos modèles actuellement épinglés. L’assistant écrit dans ~/.claude/settings.json, ou dans $CLAUDE_CONFIG_DIR/settings.json lorsque CLAUDE_CONFIG_DIR est défini.

Configuration de la région

Claude Code prend en charge les points de terminaison Google Cloud’s Agent Platform globaux, multi-régions et régionaux. Définissez CLOUD_ML_REGION sur global, un emplacement multi-région tel que eu ou us, ou une région spécifique telle que us-east5. Claude Code sélectionne le nom d’hôte Google Cloud’s Agent Platform correct pour chaque formulaire, y compris les hôtes aiplatform.eu.rep.googleapis.com et aiplatform.us.rep.googleapis.com pour les emplacements multi-régions.

Google Cloud’s Agent Platform peut ne pas prendre en charge les modèles par défaut de Claude Code sur tous les types de points de terminaison. La disponibilité des modèles varie selon les régions spécifiques, les emplacements multi-régions et les points de terminaison globaux. Vous devrez peut-être basculer vers un emplacement pris en charge ou spécifier un modèle pris en charge.

Configuration manuelle

Pour configurer Google Cloud’s Agent Platform via des variables d’environnement au lieu de l’assistant, par exemple dans CI ou un déploiement d’entreprise scriptée, suivez les étapes ci-dessous.

Activer l’API Agent Platform

Activez l’API Agent Platform de Google Cloud dans votre projet GCP. Remplacez YOUR-PROJECT-ID par votre ID de projet GCP ici et à l’étape de configuration ci-dessous :

# Définissez votre ID de projet
gcloud config set project YOUR-PROJECT-ID

# Activez l'API Agent Platform
gcloud services enable aiplatform.googleapis.com

Demander l’accès au modèle

Demandez l’accès aux modèles Claude dans Google Cloud’s Agent Platform :

Accédez au Google Cloud’s Agent Platform Model Garden
Recherchez les modèles « Claude »
Demandez l’accès aux modèles Claude souhaités (par exemple, Claude Sonnet 4.6)
Attendez l’approbation (peut prendre 24 à 48 heures)

Configurer les identifiants GCP

Claude Code utilise l’authentification Google Cloud standard. Pour plus d’informations, consultez la documentation d’authentification Google Cloud. Claude Code prend en charge la Fédération d’identité de charge de travail basée sur certificat X.509 via la même chaîne Application Default Credentials. Définissez GOOGLE_APPLICATION_CREDENTIALS sur le chemin de votre fichier de configuration des identifiants.

Claude Code adresse les demandes Google Cloud’s Agent Platform au projet dans ANTHROPIC_VERTEX_PROJECT_ID, même lorsque GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, ou le fichier d’identifiants référencé par GOOGLE_APPLICATION_CREDENTIALS porte un projet différent.

Configuration avancée des identifiants

Claude Code prend en charge l’actualisation automatique des identifiants GCP via le paramètre gcpAuthRefresh. Ajoutez-le à votre fichier de paramètres Claude Code, par exemple ~/.claude/settings.json. Lorsque Claude Code détecte que vos identifiants GCP ont expiré ou ne peuvent pas être chargés, il exécute la commande configurée pour obtenir de nouveaux identifiants avant de réessayer la demande.

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

Avant d’exécuter la commande, Claude Code demande un jeton d’accès avec vos identifiants actuels pour confirmer qu’ils sont réellement expirés, et ignore la commande lorsqu’ils fonctionnent toujours. Si la vérification ne se termine pas dans les cinq secondes, Claude Code ignore également la commande et l’exécute uniquement après l’échec d’une demande avec une erreur d’identifiants. Avant v2.1.261, une vérification qui a expiré était comptée comme un identifiant expiré, donc la commande pouvait ouvrir votre navigateur au démarrage même si vos identifiants étaient toujours valides. Claude Code vous affiche la sortie de la commande, mais ne peut pas envoyer d’entrée interactive à la commande. Cela fonctionne bien pour les flux d’authentification basés sur navigateur où l’interface de ligne de commande affiche une URL et vous complétez l’authentification dans le navigateur. La commande d’actualisation expire après trois minutes si l’authentification ne se termine pas. Si vous définissez gcpAuthRefresh dans les paramètres du projet tels que .claude/settings.json, Claude Code l’exécute selon la même règle de confiance de l’espace de travail que les hooks dans les fichiers de paramètres, qui inclut les sessions -p dans les dossiers que vous n’avez jamais approuvés.

Configurer Claude Code

Définissez les variables d’environnement suivantes :

# Activez l'intégration Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optionnel : Remplacez l'URL du point de terminaison Agent Platform pour les points de terminaison personnalisés ou les passerelles
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Quand CLOUD_ML_REGION=global, remplacez la région pour les modèles qui ne prennent pas en charge les points de terminaison globaux
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

La plupart des versions de modèle ont une variable VERTEX_REGION_CLAUDE_* correspondante. Consultez la référence des variables d’environnement pour la liste complète. Vérifiez Google Cloud’s Agent Platform Model Garden pour déterminer quels modèles prennent en charge les endpoints globaux par rapport aux endpoints régionaux uniquement. Si une valeur de région ne ressemble pas à un nom de région ou d’emplacement, Claude Code la traite comme non définie. Par exemple, Claude Code traite une valeur contenant une barre oblique, un point ou un espace comme non définie. Claude Code revient à une source différente pour chaque variable :

VERTEX_REGION_CLAUDE_* : Claude Code revient à CLOUD_ML_REGION.
CLOUD_ML_REGION : Claude Code revient à us-east5.

La mise en cache des invites est activée automatiquement. Pour la désactiver, définissez DISABLE_PROMPT_CACHING=1. Pour demander une TTL de cache d’1 heure au lieu de la valeur par défaut de 5 minutes, définissez ENABLE_PROMPT_CACHING_1H=1 ; les écritures de cache avec une TTL d’1 heure sont facturées à un taux plus élevé. Pour définir différentes TTL pour votre conversation principale et pour les demandes que Claude Code effectue en dehors de celle-ci, choisissez vous-même la TTL. Pour augmenter vos limites de débit, contactez le support Google Cloud. Lors de l’utilisation de Google Cloud’s Agent Platform, la commande /logout est indisponible car l’authentification est gérée via les identifiants Google Cloud. Claude Code décide entre la recherche d’outils MCP et le chargement à l’avance par génération de modèle :

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 et versions ultérieures : Claude Code active la recherche d’outils par défaut.
Modèles antérieurs : Claude Code charge les définitions d’outils MCP à l’avance, car leurs piles de service Agent Platform rejettent l’en-tête bêta requis. Définir ENABLE_TOOL_SEARCH=true ne remplace pas cela.

Définissez ENABLE_TOOL_SEARCH=false pour désactiver la recherche d’outils sur tous les modèles.

Épingler les versions de modèle

Épinglez les versions de modèle spécifiques lors du déploiement pour plusieurs utilisateurs. Sans épinglage, les alias de modèle tels que sonnet et opus se résolvent à la valeur par défaut intégrée de Claude Code pour Google Cloud’s Agent Platform, qui peut être en retard par rapport à la version la plus récente et peut ne pas encore être activée dans votre projet. Claude Code revient à un modèle antérieur ou de niveau inférieur au démarrage lorsque la valeur par défaut n’est pas disponible, mais l’épinglage vous permet de contrôler quand vos utilisateurs passent à un nouveau modèle.

Définissez ces variables d’environnement sur des ID de modèle Google Cloud’s Agent Platform spécifiques. Sans ANTHROPIC_DEFAULT_OPUS_MODEL, l’alias opus sur Google Cloud’s Agent Platform se résout à Opus 5.5, et sans ANTHROPIC_DEFAULT_SONNET_MODEL, l’alias sonnet se résout à Sonnet 4.5. Cet exemple épingle chaque alias à une version spécifique :

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'

Pour les ID de modèle actuels et hérités, consultez Aperçu des modèles. Consultez Configuration du modèle pour la liste complète des variables d’environnement. Claude Code utilise ces modèles par défaut lorsqu’aucune variable d’épinglage n’est définie :

Type de modèle	Valeur par défaut
Modèle principal	`claude-opus-5-5`
Modèle petit/rapide	`claude-sonnet-4-5@20250929`

Avant v2.1.280, le modèle principal sur Google Cloud’s Agent Platform était par défaut Opus 5 et l’alias opus se résolvait à Opus 5 à partir de v2.1.219. Les tâches en arrière-plan telles que la génération de titre de session utilisent le modèle petit/rapide, normalement un modèle de classe Haiku. Sur Google Cloud’s Agent Platform, Claude Code utilise le modèle Sonnet par défaut pour les tâches en arrière-plan car Haiku peut ne pas être activé dans tous les projets ou régions. Deux sélections changent le modèle qui les exécute :

Lorsque vous sélectionnez un modèle principal avec --model, ANTHROPIC_MODEL, ou le paramètre model, les tâches en arrière-plan utilisent ce modèle. Lorsque Claude Code démarre la session sur le modèle que vous définissez avec ANTHROPIC_DEFAULT_MODEL, les tâches en arrière-plan utilisent ce modèle aussi. Définir ANTHROPIC_DEFAULT_OPUS_MODEL sans ANTHROPIC_DEFAULT_SONNET_MODEL compte également comme une sélection, car le modèle Sonnet intégré peut ne pas être activé dans un projet qui oriente son propre Opus.
Pour utiliser Haiku pour les tâches en arrière-plan, définissez ANTHROPIC_DEFAULT_HAIKU_MODEL sur un ID de modèle disponible dans votre projet.

Les modèles Opus ont un prix par token plus élevé que les modèles Sonnet, donc si vous n’épinglez pas de modèle principal, vous êtes facturé au taux Opus. Pour utiliser Sonnet 4.5 comme modèle principal, définissez ANTHROPIC_MODEL sur son ID de modèle complet. Un déploiement qui oriente la valeur par défaut avec ANTHROPIC_DEFAULT_SONNET_MODEL et ne définit pas ANTHROPIC_DEFAULT_OPUS_MODEL conserve son modèle Sonnet orienté comme valeur par défaut.

Pour personnaliser davantage les modèles :

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

Vérifier votre configuration

Démarrez Claude Code et exécutez /status pour confirmer la configuration. La ligne API provider affiche Google Vertex AI, et les lignes GCP project, Default region et Model affichent votre ID de projet, votre région et votre modèle résolu. Si la ligne du fournisseur est manquante, les variables d’environnement n’atteignent pas le processus. Confirmez qu’elles sont exportées dans le shell où vous avez lancé claude, ou définissez-les dans le bloc env de votre fichier de paramètres.

Vérifications du modèle au démarrage

Lorsque Claude Code démarre avec Google Cloud’s Agent Platform configuré, il vérifie que les modèles qu’il a l’intention d’utiliser sont accessibles dans votre projet. Vous avez peut-être épinglé une version de modèle plus ancienne que la valeur par défaut actuelle de Claude Code. Si votre projet peut invoquer la version plus récente, Claude Code vous demande de mettre à jour l’épingle :

Si vous acceptez : Claude Code écrit le nouvel ID de modèle dans votre fichier de paramètres utilisateur et redémarre
Si vous refusez : Claude Code mémorise votre choix jusqu’au prochain changement de version par défaut

Pour une épingle dans le bloc env des paramètres gérés, Claude Code n’exécute aucune vérification et n’affiche aucune demande. Si la demande de mise à jour apparaît toujours pour cette épingle, mettez à jour Claude Code vers la v2.1.314 ou ultérieure. Avant la v2.1.314, l’épingle gérée restait en vigueur après votre acceptation, de sorte que la demande réapparaissait au démarrage suivant. Si vous n’avez pas épinglé un modèle et que la valeur par défaut actuelle n’est pas disponible dans votre projet, Claude Code revient à la version précédente pour la session actuelle et affiche un avis. Il essaie d’abord les versions antérieures du modèle par défaut et, lorsque la valeur par défaut est un modèle Opus et qu’aucune version Opus n’est disponible, revient au modèle Sonnet par défaut. Le retour n’est pas persistant. Activez le modèle plus récent dans Model Garden ou épinglez une version pour rendre le choix permanent.

Démarrer une session sur un modèle spécifique

Lorsque vous démarrez la session sur une version spécifique de Sonnet ou Opus, par exemple avec --model, ANTHROPIC_MODEL, ou le paramètre model, cette version agit comme la valeur par défaut épinglée de la session pour l’alias sonnet ou opus correspondant. Claude Code ignore la vérification de disponibilité pour la valeur par défaut intégrée que votre modèle remplace et démarre sur le modèle que vous avez configuré, sans avis de retour. Lorsque vous démarrez une session sur un alias de modèle tel que opus ou sur un ID de modèle que Claude Code ne reconnaît pas, cette valeur n’agit pas comme une épingle.

Refus de modèle mémorisés

Lorsque les vérifications du modèle au démarrage trouvent un modèle que votre projet ne peut pas invoquer, Claude Code peut mémoriser le refus sur cette machine pendant un jour au maximum. Une fois que dix minutes se sont écoulées depuis la dernière vérification, Claude Code vérifie à nouveau au lancement un refus mémorisé d’un modèle par défaut actuel. Une valeur par défaut que votre administrateur réactive revient alors. Pour désactiver la mémoire, définissez CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1.

Lorsque votre organisation impose une liste d’autorisation de modèles

Si vous définissez enforceAvailableModels dans les paramètres gérés, les vérifications du modèle au démarrage n’utilisent que les modèles autorisés par votre liste availableModels. Cela nécessite Claude Code v2.1.287 ou ultérieur. Une liste sans enforceAvailableModels ne restreint pas ces vérifications. Les vérifications comparent chaque entrée à l’ID de modèle qu’elles enverraient à Agent Platform ; rédigez donc la liste avec ces ID. Cet exemple autorise Opus 4.8 et Sonnet 4.5 :

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

Pour les alias, les préfixes de version et les entrées modelOverrides, consultez Épingler les modèles pour les déploiements tiers.

Lorsqu’un modèle est désactivé en cours de session

Si votre projet perd l’accès au modèle sur lequel votre session s’exécute, par exemple parce qu’un administrateur le désactive dans Model Garden, Claude Code bascule la session vers un autre modèle au lieu d’échouer à chaque demande, et affiche Switched to <fallback> because <model> is not available. Il essaie les mêmes modèles que le retour au démarrage : les versions antérieures du même niveau d’abord et, pour une session Opus sans version Opus disponible, le modèle Sonnet par défaut. Le basculement s’applique uniquement à un niveau que vous n’avez pas épinglé, la même condition que le retour au démarrage. Une session sur une version spécifique que vous avez choisie conserve son modèle et, sans une chaîne de modèle de secours, la demande échoue à la place. En mode auto, Claude Code bascule uniquement vers un modèle que le mode auto supporte sur Agent Platform. Si aucun de ces modèles n’est disponible non plus, la demande échoue. Une chaîne de modèle de secours que vous configurez remplace le basculement de niveau : sur ces refus, Claude Code bascule vers votre secours configuré à la place. Pour que les demandes refusées échouent plutôt que de basculer, définissez CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1. Une chaîne de secours que vous avez configurée bascule toujours sur ces refus ; supprimez également la chaîne si vous voulez que chaque demande refusée échoue.

Configuration IAM

Attribuez le rôle roles/aiplatform.user, qui inclut les autorisations requises :

aiplatform.endpoints.predict - Requis pour l’invocation de modèle et le comptage des jetons

Pour des autorisations plus restrictives, créez un rôle personnalisé avec uniquement les autorisations ci-dessus. Pour plus de détails, consultez la documentation IAM de Google Cloud Vertex AI.

Créez un projet GCP dédié pour Claude Code pour simplifier le suivi des coûts et le contrôle d’accès.

Fenêtre de contexte de 1M de jetons

Les modèles Fable, Sonnet 5 et versions ultérieures, ainsi qu’Opus 4.7 et versions ultérieures, s’exécutent par défaut avec la fenêtre de contexte de 1M de tokens sur la plateforme Agent de Google Cloud, sans qu’un suffixe [1m] soit nécessaire. Pour conserver plutôt une fenêtre de 200K, définissez CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Opus 4.6 et Sonnet 4.6 accèdent à la fenêtre 1M lorsque vous sélectionnez leur variante [1m]. L’assistant de configuration offre une option de contexte 1M lorsqu’il épingle les modèles. Pour l’activer pour un modèle épinglé manuellement à la place, ajoutez [1m] à l’ID du modèle. Consultez Épingler les modèles pour les déploiements tiers pour plus de détails, notamment comment utiliser la fenêtre 1M sans modifier l’épingle. Avant la v2.1.287, les modèles Fable ainsi qu’Opus 4.7 et versions ultérieures s’exécutaient par défaut avec une fenêtre de 200K sur la plateforme Agent de Google Cloud et accédaient à la fenêtre 1M via un suffixe [1m].

Résolution des problèmes

Si vous rencontrez des erreurs « Impossible de charger les identifiants par défaut » :

Exécutez gcloud auth application-default login pour configurer les identifiants par défaut de l’application
Définissez GOOGLE_APPLICATION_CREDENTIALS sur le chemin d’un fichier de clé de compte de service
Consultez Configurer les identifiants GCP pour toutes les options

Si vous rencontrez des problèmes de quota :

Vérifiez les quotas actuels ou demandez une augmentation de quota via la Console Cloud

Si vous rencontrez des erreurs « modèle non trouvé » 404 :

Confirmez que le modèle est activé dans Model Garden
Vérifiez que le modèle est disponible dans l’emplacement que vous avez spécifié. Certains modèles ne sont proposés que sur les emplacements global ou multi-régions tels que eu et us, pas dans les régions spécifiques
Si vous utilisez CLOUD_ML_REGION=global, vérifiez que vos modèles prennent en charge les endpoints globaux dans Model Garden sous « Fonctionnalités prises en charge ». Pour les modèles qui ne prennent pas en charge les endpoints globaux, soit :
- Spécifiez un modèle pris en charge via ANTHROPIC_MODEL ou ANTHROPIC_DEFAULT_HAIKU_MODEL, soit
- Définissez une région ou un emplacement multi-région à l’aide de la variable VERTEX_REGION_CLAUDE_* du modèle, répertoriée dans la référence des variables d’environnement

Si vous rencontrez des erreurs 429 :

Pour les points de terminaison régionaux, assurez-vous que le modèle principal et le modèle petit/rapide sont pris en charge dans votre région sélectionnée
Envisagez de basculer vers CLOUD_ML_REGION=global pour une meilleure disponibilité

Configuration et accès

Déploiement

Passerelles

Utilisation et coûts

Sécurité et données

Adoption

Claude Code sur la Plateforme Agent de Google Cloud

Conditions préalables

Configuration de la région

Configuration manuelle

Activer l’API Agent Platform

Demander l’accès au modèle

Configurer les identifiants GCP

Configuration avancée des identifiants

Configurer Claude Code

Épingler les versions de modèle

Vérifier votre configuration

Vérifications du modèle au démarrage

Démarrer une session sur un modèle spécifique

Refus de modèle mémorisés

Lorsque votre organisation impose une liste d’autorisation de modèles

Lorsqu’un modèle est désactivé en cours de session

Configuration IAM

Fenêtre de contexte de 1M de jetons

Résolution des problèmes

Ressources supplémentaires

​Conditions préalables

​Se connecter avec Agent Platform

​Configuration de la région

​Configuration manuelle

​ Activer l’API Agent Platform

​ Demander l’accès au modèle

​ Configurer les identifiants GCP

​Configuration avancée des identifiants

​ Configurer Claude Code

​ Épingler les versions de modèle

​ Vérifier votre configuration

​Vérifications du modèle au démarrage

​Démarrer une session sur un modèle spécifique

​Refus de modèle mémorisés

​Lorsque votre organisation impose une liste d’autorisation de modèles

​Lorsqu’un modèle est désactivé en cours de session

​Configuration IAM

​Fenêtre de contexte de 1M de jetons

​Résolution des problèmes

​Ressources supplémentaires

Conditions préalables

Se connecter avec Agent Platform

Configuration de la région

Configuration manuelle

Activer l’API Agent Platform

Demander l’accès au modèle

Configurer les identifiants GCP

Configuration avancée des identifiants

Configurer Claude Code

Épingler les versions de modèle

Vérifier votre configuration

Vérifications du modèle au démarrage

Démarrer une session sur un modèle spécifique

Refus de modèle mémorisés

Lorsque votre organisation impose une liste d’autorisation de modèles

Lorsqu’un modèle est désactivé en cours de session

Configuration IAM

Fenêtre de contexte de 1M de jetons

Résolution des problèmes

Ressources supplémentaires