Passer au contenu principal
Un déploiement de passerelle Claude apps est configuré par un fichier YAML, conventionnellement gateway.yaml. Le fichier définit tout ce que fait la passerelle : où elle écoute, comment les développeurs se connectent, où va l’inférence et quelles politiques et télémétrie s’appliquent. Cette page est la référence pour chaque option de ce fichier. Pour écrire votre première, commencez par le démarrage rapide, qui crée une configuration minimale fonctionnelle et l’exécute. Une fois que vous avez une configuration avec laquelle vous êtes satisfait, le guide de déploiement couvre la conteneurisation et l’hébergement sur Kubernetes, Cloud Run ou votre propre plateforme. La passerelle lit le fichier une fois, au démarrage, avec claude gateway --config /path/to/gateway.yaml. Chaque option est validée par rapport à un schéma au démarrage, donc une configuration mal formée échoue au démarrage avec une erreur au niveau du champ plutôt qu’à la première utilisation. L’exemple complet à la fin de cette page exerce chaque section.

Structure du fichier

Cinq sections sont requises. Chaque autre section est optionnelle, et une section omise prend ses valeurs par défaut. Les clés inconnues échouent au démarrage, donc une faute de frappe apparaît comme une erreur nommée plutôt qu’un paramètre silencieusement ignoré. Sections requises :
  • listen : adresse de liaison, URL publique, terminaison TLS
  • oidc : votre fournisseur d’identité (IdP), y compris l’émetteur, le client, le mappage des réclamations et qui peut se connecter
  • session : les jetons porteurs que la passerelle émet, avec secret et durée de vie
  • store : PostgreSQL, pour les subventions d’appareils et les compteurs de limite de débit
  • upstreams : où l’inférence va, qu’il s’agisse d’Anthropic, Amazon Bedrock, Claude Platform sur AWS, Agent Platform de Google Cloud ou Microsoft Foundry
Sections optionnelles :
  • admin : authentification de l’API Admin et rétention pour les limites de dépenses
  • enforcement : comportement de limite de dépenses fail-open ou fail-closed
  • models et auto_include_builtin_models : liste de modèles curée par l’administrateur et IDs par upstream
  • managed : politiques de paramètres gérés par groupe IdP
  • telemetry : transfert OTLP vers votre pile d’observabilité
  • access_control, limits, timeouts, rate_limits : autorisation/refus IP, plafonds de taille de requête, time-to-first-byte upstream et limites de connexion par IP

Expansion des secrets

N’écrivez pas de secrets tels que client_secret, jwt_secret ou postgres_url directement dans gateway.yaml. Référencez-les avec l’une des formes ci-dessous, et la passerelle résout la valeur au démarrage à partir d’une variable d’environnement ou d’un fichier :

Sections requises

listen

Le bloc listen contrôle où la passerelle sert : l’adresse de liaison et le port, l’origine visible en externe, et la terminaison TLS optionnelle.

oidc

Le bloc oidc connecte la passerelle à votre fournisseur d’identité et décide qui peut se connecter. Il nomme l’émetteur et le client OAuth, mappe les réclamations qui portent l’e-mail et les groupes, et restreint la connexion par domaine d’e-mail ou groupe. OpenID Connect (OIDC) est le protocole SSO que la passerelle utilise avec votre fournisseur d’identité ; voir Configuration du fournisseur d’identité pour ce qu’il faut enregistrer du côté IdP.

session

Le bloc session façonne les jetons porteurs que la passerelle émet après la connexion : le secret qui les signe et combien de temps ils vivent.

store

Le bloc store pointe la passerelle vers sa base de données PostgreSQL, qui contient les subventions d’appareils et les compteurs de limite de débit. Pour le développement local, pointez postgres_url sur un conteneur Postgres jetable, par exemple docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams est une liste ordonnée. La passerelle transfère l’inférence au premier upstream qui résout le modèle demandé. Sur 5xx, 429, 401, 403, 404, ou timeout, elle bascule vers le suivant ; les autres 4xx ne le font pas, car ces erreurs sont attribuables à la demande plutôt qu’à l’upstream. Un 401 ou 403 signifie que l’identifiant propre de la passerelle a échoué contre cet upstream, et un 404 signifie que cet upstream ne sert pas le modèle demandé, donc un upstream ultérieur dans la liste peut toujours le faire. Le basculement sur 404 nécessite la passerelle v2.1.198 ou ultérieure. Les versions antérieures retournaient le premier 404 au client même lorsqu’un upstream ultérieur dans la liste servait le modèle. Plusieurs upstreams du même fournisseur doivent définir un name: distinct. Les clients Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform et Microsoft Foundry sont construits une fois au démarrage, et leurs SDKs actualisent les identifiants en interne, donc la rotation des identifiants cloud ne nécessite pas un redémarrage. Les clés API Anthropic statiques et les porteurs sont lus au démarrage ; voir Anthropic API.

Anthropic API

L’upstream Anthropic minimal est une clé API de la Console Claude :
Les deux formes d’identifiants diffèrent dans l’en-tête qu’elles envoient :
  • api_key : envoie x-api-key. Faites-la pivoter dans la Console Claude et mettez à jour la variable env.
  • oauth_token : envoie Authorization: Bearer. Utilisez la forme porteur lorsque votre organisation émet des jetons de courte durée au lieu de clés API de longue durée. Le porteur est lu une fois au démarrage, donc actualisez en remontant le secret et en redémarrant.
Au lieu d’une clé statique ou d’un porteur, vous pouvez utiliser Workload Identity Federation. Créez une règle de fédération en suivant le guide Workload Identity Federation, puis montez le JWT OIDC de votre charge de travail en tant que fichier, tel qu’un jeton de compte de service projeté Kubernetes ou un id-token de plateforme CI. La passerelle échange le JWT pour un porteur de courte durée et l’actualise automatiquement. Le fichier de jeton est relu à chaque échange, donc les jetons projetés pivotés sont récupérés sans redémarrage.

Amazon Bedrock

Pour le déploiement Bedrock côté client que la passerelle remplace ou fronts, voir Claude Code sur Amazon Bedrock. L’upstream côté passerelle :
Un bloc auth vide utilise la chaîne d’identifiants par défaut du SDK AWS : variables env, ~/.aws/credentials, rôle de tâche ECS, métadonnées d’instance EC2 ou IRSA sur EKS. En production, donnez au pod de la passerelle un rôle IAM au lieu d’intégrer des clés statiques dans une image de conteneur. Les identifiants explicites doivent être complets : la passerelle échoue au démarrage lorsque aws_access_key_id et aws_secret_access_key ne sont pas définis ensemble, ou lorsque aws_session_token est défini sans eux. Avant v2.1.207, un bloc auth: partiel passait la validation.

Claude Platform on AWS

Claude Platform on AWS sert l’API Anthropic propriétaire sur l’infrastructure AWS à aws-external-anthropic.<region>.api.aws. Il utilise les IDs de modèle propriétaires, honore les en-têtes anthropic-beta tels qu’envoyés, et sert count_tokens, donc aucune des traductions spécifiques à Bedrock ne s’applique. Le fournisseur anthropicAws nécessite Claude Code v2.1.198 ou ultérieur ; les versions antérieures de la passerelle le rejettent au démarrage. Pour le déploiement côté client de la même plateforme, voir Claude Code sur Claude Platform on AWS. L’upstream côté passerelle :
La plateforme s’exécute dans un compte AWS séparé d’Amazon Bedrock et signe les demandes SigV4 pour son propre nom de service, aws-external-anthropic, donc un rôle IAM limité à Bedrock ne l’autorise pas. Une clé API dans auth.api_key prend la priorité lorsque les identifiants SigV4 sont également définis. Un bloc auth vide utilise la chaîne d’identifiants par défaut du SDK AWS, la même chaîne que l’upstream Amazon Bedrock utilise. Parce que la plateforme résout les IDs de modèle propriétaires, le catalogue intégré route vers elle sans bloc models:. Lorsque vous organisez une liste models:, indexez l’entrée anthropicAws: avec l’ID propriétaire.

Google Cloud Agent Platform

Pour la configuration équivalente côté client, voir Claude Code sur Google Cloud. L’upstream côté passerelle :
Un bloc auth vide utilise les identifiants par défaut d’application : GOOGLE_APPLICATION_CREDENTIALS, métadonnées GCE ou Workload Identity GKE. Les fichiers de clé JSON de compte de service sont pris en charge mais déconseillés ; utilisez Workload Identity ou attachez un compte de service à l’instance GCE ou Cloud Run. Définissez region: global pour utiliser le point de terminaison global d’Agent Platform au lieu d’un point de terminaison régional. Google route ensuite chaque demande vers une région disponible, donc vous ne suivez pas la disponibilité du modèle par région. Définir une région spécifique épingle chaque demande à celle-ci.

Microsoft Foundry

Pour le déploiement Foundry côté client, voir Claude Code sur Microsoft Foundry. L’upstream côté passerelle :
use_azure_ad: true résout via DefaultAzureCredential : Managed Identity sur AKS, ACI ou App Service ; l’Azure CLI ; ou les identifiants d’environnement. Les clés API fonctionnent mais sont à l’échelle du projet et ne pivotent pas automatiquement. Le point de terminaison de Foundry est dérivé de resource: ; définissez le base_url optionnel pour le remplacer pour les clouds souverains tels que Azure Government.

Plusieurs upstreams

Le même fournisseur peut apparaître plus d’une fois avec un name: distinct. Cela couvre différentes régions, différents comptes via différentes chaînes d’identifiants, débit provisionné par rapport à la demande, et basculement inter-fournisseur. La passerelle essaie les upstreams dans l’ordre. 5xx, 429, 401, 403, 404, timeouts et point de terminaison manquant (501) basculent ; les autres 4xx ne le font pas. 429 est la capacité par upstream, donc l’épuisement du débit provisionné (PT) bascule vers la demande. 404 est la disponibilité du modèle par upstream, donc un upstream qui n’a pas activé un modèle ne bloque pas un upstream ultérieur qui le sert. Un upstream qui ne peut pas résoudre le modèle demandé est ignoré sans un aller-retour réseau. Cet exemple route une allocation Bedrock de débit provisionné en premier, déborde vers la demande et un deuxième compte, et revient à l’API Anthropic en dernier :
Le basculement entre les fournisseurs cloud ou vers l’API Anthropic directe change quel accord, géographie et autres conditions régissent la demande. Le CLI applique le même contrôle de fonctionnalité aux passerelles indépendamment de quel upstream sert une demande donnée, donc le basculement n’envoie pas un champ de corps qu’un upstream rejetterait.

Sections optionnelles

admin

Optionnel. Active /v1/organizations/spend_limits, qui reflète l’API Admin publique d’Anthropic, et l’application de dépenses par développeur sur /v1/messages. Voir Limites de dépenses pour comment les plafonds sont définis et appliqués ; cette section couvre les clés gateway.yaml qui activent la fonctionnalité et l’ajustent.

enforcement

Le bloc enforcement contrôle comment les vérifications de limite de dépenses se comportent lorsque le magasin n’est pas disponible.

models

Le bloc models est une liste de modèles curée par l’administrateur optionnelle, servie à /v1/models et utilisée pour traduire les IDs de modèle par upstream. Elle est requise pour les régions Bedrock non-US, les ARNs de débit provisionné Bedrock et les noms de déploiement Foundry.

managed

Le bloc managed définit les politiques d’accès basées sur les rôles indexées sur les groupes IdP ou le domaine d’e-mail. Les politiques sont évaluées dans l’ordre ; la première correspondance est sélectionnée, puis fusionnée sur la base de capture-tout match: {} décrite ci-dessous. Elles sont servies par utilisateur à GET /managed/settings avec mise en cache ETag/304.
Une capture-tout match: {}, conventionnellement listée en dernier, est traitée comme une couche de base. Chaque autre politique hérite de toute clé qu’elle ne définit pas de la capture-tout, donc les entrées par rôle n’ont besoin que de lister ce qui diffère de la valeur par défaut de l’organisation. Les règles de fusion dépendent du type de clé :
  • Listes d’autorisation : availableModels et permissions.allow. La liste d’une politique spécifique remplace complètement celle de la base.
  • Listes de refus et tableaux de hooks : permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces et chaque tableau de type d’événement hooks. Ceux-ci prennent l’union de la base et de la politique, donc un refus à l’échelle de l’organisation ou un hook d’audit ne peut pas être accidentellement supprimé par un remplacement par rôle.
  • Clés de type enregistrement : env, modelOverrides et skillOverrides. Ceux-ci fusionnent superficiellement, donc un bloc env par rôle remplace les clés qu’il définit et hérite du reste de la base.
availableModels est également appliqué côté serveur à /v1/messages, donc un modèle refusé retourne 400 indépendamment de ce que le client envoie. Un utilisateur authentifié qui ne correspond à aucune politique obtient les valeurs par défaut de la passerelle, ce qui signifie chaque modèle du catalogue et aucun paramètre géré. Ajoutez une capture-tout match: {} en dernier si vous voulez une politique par défaut garantie.
La passerelle ne garde aucun répertoire d’utilisateurs de son propre. Elle autorise chaque demande à partir du jeton IdP de l’utilisateur, en lisant l’appartenance au groupe à partir de la réclamation groups du jeton et en évaluant les politiques par rapport à celle-ci. Il n’y a pas de liste à énumérer et pas de comptes à pré-créer, et donc pas de point de terminaison SCIM, car il n’y a rien pour que SCIM se synchronise.Exécutez la gestion du cycle de vie des utilisateurs et des groupes à la source de vérité, qui est la mise en service SCIM native de votre IdP ou une plateforme de gouvernance d’identité dédiée. L’appartenance et la déprovision gouvernées là-bas s’écoulent dans la passerelle automatiquement via le jeton. Si vous voulez la mise en service SCIM des comptes Claude eux-mêmes, c’est une capacité Claude for Enterprise.Deux horloges de propagation s’appliquent :
  • Contenu de la politique : éditer une politique et redéployer atteint les clients connectés lors de leur prochain sondage de paramètres gérés, dans une heure
  • Appartenance au groupe : changer l’appartenance au groupe d’un utilisateur change quelle politique les correspond. Cela prend effet lors de la prochaine remise en monnaie de session, ce qui signifie le prochain rafraîchissement silencieux, limité par session.ttl_hours.

Ce qui va dans cli

Chaque valeur cli est un document complet managed-settings.json de Claude Code, le même schéma que vous déploieriez via MDM ou /etc/claude-code/managed-settings.json, exprimé ici en YAML. Le CLI applique le document livré au niveau géré, au-dessus des paramètres utilisateur et projet. La passerelle valide chaque document par rapport au schéma de paramètres du CLI au démarrage, donc une clé de niveau supérieur non reconnue ou une clé reconnue avec une valeur mal formée échoue au démarrage avec une erreur nommant chaque clé offensante. Les parties délibérément ouvertes du schéma acceptent toujours des valeurs arbitraires, car les clients plus récents peuvent reconnaître les entrées que le schéma de la passerelle ne reconnaît pas. Ces clés ouvertes sont env, pluginConfigs et les clés imbriquées sous permissions. Parce que la validation utilise le schéma fourni avec la version installée de la passerelle, mettre une clé de paramètres de niveau supérieur introduite par une version plus récente de Claude Code dans la configuration gérée nécessite de mettre à niveau la passerelle en premier. Testez une nouvelle politique sur un client avant de la déployer largement. La référence de clé complète est dans Paramètres Claude Code. Les clés que les opérateurs atteignent en premier :
Parce que ces paramètres arrivent sur le réseau, le CLI affiche à chaque développeur un dialogue d’approbation de sécurité unique avant d’appliquer quoi que ce soit qui puisse exécuter une commande shell ou modifier où le trafic va. Le dialogue couvre :
  • hooks
  • Variables env qui ne sont pas sur la liste sûre intégrée du CLI
  • Paramètres d’exécution shell tels que apiKeyHelper et statusLine
  • Contenu CLAUDE.md géré
La liste sûre détermine quelles variables env s’appliquent sans approbation :
  • Sur la liste sûre : variables de mise à jour automatique et de nom de modèle
  • Pas sur la liste sûre : variables de proxy, variables d’URL de base et OTEL_EXPORTER_OTLP_ENDPOINT
La configuration de télémétrie de la passerelle pousse OTEL_EXPORTER_OTLP_ENDPOINT, donc définir telemetry.forward_to déclenche le dialogue sur chaque client interactif. Le dialogue protège la machine du développeur d’une passerelle compromise ou hostile, pas l’organisation du développeur. Une exécution non interactive avec l’indicateur -p ne peut pas afficher le dialogue. Elle applique les paramètres poussés pour cette exécution uniquement et ne les enregistre pas comme approuvés, donc la prochaine session interactive du développeur affiche toujours le dialogue. Avant v2.1.207, une exécution non interactive enregistrait les paramètres comme approuvés et aucune session interactive ultérieure n’affichait le dialogue pour eux. Si un développeur refuse, Claude Code se termine plutôt que d’appliquer la politique. Pousser un nouveau hook ou une variable env non sûre vers une politique large signifie donc une invite d’approbation au démarrage suivant de chaque développeur correspondant. La clé cli s’appelait settings dans les versions antérieures. Cette orthographe est toujours acceptée comme alias, mais les nouveaux déploiements doivent utiliser cli.

Précédence avec d’autres sources gérées

Si un appareil a également une managed-settings.json locale ou une politique livrée par MDM, les sources gérées ne fusionnent pas. La source de priorité la plus élevée fournit tous les paramètres de politique, classés dans cet ordre avec la priorité la plus élevée en premier :
  1. L’assistant de politique
  2. Paramètres livrés par la passerelle
  3. MDM, via le registre HKLM sur Windows ou un plist sur macOS
  4. Le fichier managed-settings.json
  5. Le registre HKCU, sur Windows uniquement
Les hôtes d’intégration peuvent fournir une politique via l’option SDK managedSettings. Elle est ignorée par défaut et s’applique uniquement lorsqu’une source gérée opte pour parentSettingsBehavior: "merge", filtrée pour qu’elle puisse resserrer la politique mais pas l’assouplir. L’exception est un petit ensemble de clés inter-sources, honorées lorsqu’une source admin les définit ; le niveau HKCU inscriptible par l’utilisateur est exclu :
  • sandbox.network.allowManagedDomainsOnly et sandbox.filesystem.allowManagedReadPathsOnly : lorsqu’elles sont verrouillées, les listes d’autorisation correspondantes sont unies entre les sources
  • allowAllClaudeAiMcps : remplacement d’autorisation uniquement pour la liste d’autorisation du serveur MCP claude.ai
  • sandbox.bwrapPath et sandbox.socatPath : chemins du système de fichiers vers les binaires d’aide sandbox
  • forceRemoteSettingsRefresh : bloque le démarrage jusqu’à ce que les paramètres gérés distants soient fraîchement récupérés, donc une politique MDM ou fichier qui la définit est honorée même lorsqu’une charge utile distante mise en cache qui manque la clé est la source de priorité la plus élevée
Chaque autre clé, y compris allowManagedPermissionRulesOnly et disableBypassPermissionsMode, provient uniquement de la source de priorité la plus élevée. Voir Précédence des paramètres pour la même règle sur la page des paramètres. Les politiques de passerelle s’appliquent à chaque invocation de Claude Code sur la machine, y compris les exécutions non interactives claude -p et les sessions générées par le SDK Agent. Si la passerelle est inaccessible au démarrage, les sessions signées se terminent avec une erreur plutôt que de s’exécuter sans leur politique.
mcpServers à l’intérieur du bloc cli d’une politique est rejeté au démarrage de la passerelle. La distribution MCP par groupe n’est pas disponible ; déployez les serveurs MCP via le managed-mcp.json basé sur fichier sur chaque appareil ou laissez les développeurs les ajouter localement.

telemetry

Le CLI envoie le protocole OpenTelemetry (OTLP) sur les métriques, journaux et, lorsqu’ils sont activés, les traces HTTP à la passerelle, qui les relaye textuellement à chaque destination configurée. Voir Surveillance de l’utilisation pour les métriques et événements que le CLI émet. Le CLI horodate chaque export avec l’identité de l’utilisateur authentifié, lue à partir du JWT émis par la passerelle : les attributs user.id, user.email et user.groups. L’attribution du coût et de l’utilisation par développeur fonctionne donc sans aucune configuration côté développeur.
Chaque destination opte pour metrics, logs et traces indépendamment, et la valeur par défaut est les métriques uniquement. Les signaux diffèrent en sensibilité :
  • Métriques : compteurs agrégés tels que les comptages de jetons, les comptages de demandes et la latence
  • Journaux et traces : peuvent porter des commandes bash complètes, des entrées d’outils et des chemins de fichiers, couvrant tout ce que Claude Code fait sur la machine d’un développeur
Activez les journaux et les traces uniquement sur les destinations avec les contrôles d’accès et la politique de rétention que les données justifient.
La télémétrie est désactivée dans le CLI par défaut. Configurer telemetry.forward_to avec listen.public_url l’active. La passerelle pousse cinq variables env à chaque client connecté via /managed/settings :
  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
Le point de terminaison poussé est construit à partir de l’URL publique, donc les métriques et les journaux n’ont besoin d’aucune configuration OTEL des développeurs ou des politiques. La configuration poussée est appliquée au niveau géré, remplaçant les variables OTEL_* qu’un développeur définit localement. Les traces nécessitent en outre CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 sur chaque client. La passerelle ne pousse pas cette variable, donc définissez-la via le bloc env d’une politique gérée. Elle n’est pas sur la liste sûre du CLI, donc la livrer via une politique est couverte par le même dialogue d’approbation de sécurité que le point de terminaison OTLP poussé déclenche déjà. Les encodages OTLP protobuf et JSON sont relayés, et tout backend compatible OpenTelemetry fonctionne comme destination.

Réglage HTTP

Quatre blocs optionnels de niveau supérieur, access_control, limits, timeouts et rate_limits, ajustent la surface HTTP. Les valeurs par défaut conviennent à la plupart des déploiements.

Exemple complet

Cette configuration de référence complète exerce chaque section principale ; les blocs de réglage HTTP gardent leurs valeurs par défaut. Copiez-la, supprimez ce dont vous n’avez pas besoin et remplissez vos valeurs. La configuration du démarrage rapide est une version minimale de celle-ci.
gateway.yaml

Paramètres gérés côté client

Tout ce qui précède configure le serveur de passerelle. Pointer les machines des développeurs vers celui-ci est configuré séparément, sur chaque appareil, via les paramètres gérés de Claude Code. La passerelle ne peut pas pousser ces clés elle-même, car ce sont elles qui disent au client où se trouve la passerelle. Pour le CLI, définissez les deux clés dans le managed-settings.json par système d’exploitation :
Déployez ce fichier sur chaque appareil, généralement via votre plateforme MDM. Le chemin du fichier diffère selon la plateforme : forceLoginGatewayUrl et la valeur "gateway" de forceLoginMethod sont honorés uniquement à partir du niveau géré contrôlé par l’administrateur. Un développeur les définissant dans son propre ~/.claude/settings.json n’a aucun effet.