Déploiement et exploitation de la passerelle Claude apps

Enregistrez la passerelle auprès de votre fournisseur d'identité, créez le conteneur, déployez sur Kubernetes ou Cloud Run, et exploitez-la : vérifications de santé, rotation des secrets, mises à jour et sécurité.

[!NOTE]

Planifiez d'abord le réseau de votre passerelle. Lors de la connexion, Claude Code refuse une passerelle Claude apps dont le nom d'hôte se résout en une adresse IP publique, même si celle-ci n'est pas accessible depuis Internet.

Une passerelle Claude apps peut envoyer des paramètres vers les machines des utilisateurs, y compris des hooks qui exécutent des commandes shell. Cette vérification aide à éviter que les utilisateurs ne se connectent accidentellement à une passerelle malveillante sur l'Internet public. Gardez également votre propre passerelle hors d'Internet.

Choisissez l'adresse de la passerelle avant de choisir où elle s'exécute. Il s'agit généralement d'une adresse privée que les utilisateurs atteignent sur votre réseau interne ou via un VPN. Si votre réseau interne utilise des plages IPv4 publiques, vous pouvez indiquer une plage qui contient à la fois la passerelle et les machines de vos utilisateurs. Claude Code considère cette correspondance comme un signe que la passerelle se trouve sur votre réseau interne. Consultez Choisir une adresse pour la passerelle. Si aucune de ces options ne convient à votre réseau, contactez l'équipe chargée de votre compte Anthropic.

Cette page couvre l'aspect opérationnel de l'exécution de la passerelle Claude apps : enregistrement d'un client OAuth auprès de votre fournisseur d'identité (IdP), déploiement de la passerelle en tant que conteneur, et son exploitation au quotidien. Pour chaque option du fichier gateway.yaml que la passerelle lit au démarrage, consultez la Référence de configuration.

Un déploiement en production suit quatre étapes dans l'ordre, et les sections ci-dessous les correspondent. Les deux premières sont des choix à faire ; les deux dernières sont des documents de référence à consulter une fois qu'elle est en cours d'exécution.

1. Configurer votre fournisseur d'identité : enregistrez le client OAuth et consultez les notes spécifiques à chaque IdP pour Okta, Entra et Google
2. Déployer la passerelle : créez une image de conteneur épinglée et exécutez-la sur Kubernetes, Cloud Run ou votre propre plateforme. Cette section couvre également les décisions concernant les coûts, le contournement, les passerelles multiples et les environnements sans serveur
3. Configurer les opérations : journaux, sondes de santé, comportement en cas de panne, rotation des secrets et mises à jour. Référence pour le moment où vous configurez la surveillance et les runbooks
4. Examiner la posture de sécurité : où les données circulent, le modèle de menace et les réponses de conformité. Référence pour un examen de sécurité

Si une connexion ou un démarrage échoue en cours de route, allez directement à Dépannage, qui est indexé sur l'erreur que vous voyez.

Configuration du fournisseur d'identité

Enregistrez une application web OAuth/OpenID Connect (OIDC) confidentielle auprès d'un seul URI de redirection, https://<gateway>/oauth/callback, et assignez-la aux utilisateurs ou groupes qui doivent avoir accès à la passerelle. La passerelle s'authentifie auprès de l'IdP avec le secret client de l'enregistrement, ou avec un certificat que vous téléversez dans l'enregistrement si votre IdP utilise plutôt des identifiants par certificat.

Tout IdP conforme à OIDC fonctionne : Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate et autres. L'IdP doit répondre à trois exigences :

• Servir /.well-known/openid-configuration, via HTTPS en production ; la passerelle accepte un émetteur http://, et un émetteur de bouclage local nécessite en outre CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Supporter le flux de code d'autorisation. PKCE (Proof Key for Code Exchange) est activé par défaut ; désactivez-le avec oidc.use_pkce: false pour les IdP qui ne le supportent pas
• Retourner email et optionnellement groups dans l'id_token, ou les servir à partir du point de terminaison userinfo avec oidc.userinfo_fallback: true

Pour l'infrastructure à clé publique privée, définissez oidc.ca_cert_pem.

Quelques fournisseurs gèrent les revendications d'email et de groupe différemment :

• Okta : le serveur d'autorisation de l'organisation à https://example.okta.com retourne un id_token mince qui omet email et groups, donc définissez oidc.userinfo_fallback: true chaque fois que vous l'utilisez comme issuer. Un serveur d'autorisation personnalisé tel que https://example.okta.com/oauth2/default qui inclut email et optionnellement groups dans l'id_token les émet directement et n'a besoin d'aucun fallback. Okta émet groups uniquement lorsque la portée groups est demandée dans oidc.scopes et que le filtre de revendication de groupes de l'application le permet ; userinfo_fallback ne peut pas remplir une revendication pour laquelle l'IdP n'a pas été interrogé.
• Microsoft Entra ID : issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra émet des ID d'objet de groupe plutôt que des noms, donc utilisez les GUID dans managed.policies.match.groups, ou utilisez les rôles d'application pour des noms lisibles par l'homme. Si votre locataire émet des rôles sous roles au lieu de groups, définissez oidc.groups_claim: roles.
• Google Workspace : issuer = https://accounts.google.com. L'id_token de Google ne porte pas de groupes. Pour utiliser allowed_groups basé sur les groupes ou managed.policies avec Google comme IdP, configurez oidc.google_groups, qui recherche les groupes de chaque utilisateur via l'API Directory du SDK Admin en utilisant un compte de service avec délégation au niveau du domaine. Sans cela, utilisez oidc.allowed_email_domains pour le contrôle d'accès à l'adhésion et managed.policies.match.email_domain pour l'attribution de politique. Google ignore également la portée standard offline_access. Pour les jetons d'actualisation, définissez oidc.scopes: [openid, profile, email] et oidc.extra_auth_params: { access_type: offline, prompt: consent }.

[!WARNING]

Les jetons d'actualisation permettent à la passerelle de renouveler la session d'un développeur silencieusement, sans renvoyer le développeur au navigateur. Ils pilotent également le déprovisionnement, car lorsque l'IdP désactive un utilisateur, l'actualisation suivante échoue et la session se termine dans ttl_hours. La passerelle demande offline_access par défaut pour obtenir un jeton d'actualisation. Si votre IdP nécessite un consentement explicite pour l'accès hors ligne, configurez le client OAuth pour l'autoriser.

Si votre IdP ne peut pas du tout émettre de jetons d'actualisation, la passerelle fonctionne toujours, mais il n'y a pas de renouvellement silencieux, donc les développeurs réexécutent la connexion au navigateur lorsque leur session expire. Pour éviter que cela ne se produise toutes les heures, augmentez session.ttl_hours à 8 ou 12. Le compromis est la latence de déprovisionnement, car sans jetons d'actualisation un utilisateur désactivé conserve l'accès jusqu'à l'expiration du TTL plus long.

Déploiement

La passerelle est un seul binaire Linux sans état qui se coordonne via Postgres, donc déployez-la comme vous déployez tout autre service sans état dans votre environnement. Gardez-la à l'intérieur de votre réseau, où vos développeurs peuvent la joindre via HTTPS et où elle peut joindre votre IdP, et traitez-la comme tout service détenant des identifiants de production.

Quelques décisions façonnent le déploiement au-delà de l'endroit où il s'exécute :

• Coûts : pas de licence séparée ou de frais par siège. La passerelle fait partie du binaire claude, donc vous payez l'inférence via votre engagement existant, plus le calcul qu'elle exécute.
• Contournement : la passerelle n'impose pas que la seule route vers un modèle passe par elle. Un développeur avec sa propre credential peut toujours appeler le fournisseur directement, donc fermer ce chemin est une décision de politique réseau, par exemple bloquer la sortie vers api.anthropic.com sauf depuis la passerelle. Bloquer cette sortie casse également la vérification de sécurité du domaine WebFetch, qui appelle api.anthropic.com depuis la machine de chaque développeur. Définissez skipWebFetchPreflight: true dans la politique gérée pour la désactiver.
• Passerelles multiples : chaque est un déploiement séparé avec sa propre configuration, et le CLI stocke la confiance et les credentials par nom d'hôte de passerelle, donc les équipes peuvent utiliser différentes passerelles sans conflit. Pour servir plusieurs émetteurs OIDC, exécutez des instances séparées.
• Sans serveur : Cloud Run fonctionne si vous définissez min-instances: 1 pour éviter la découverte OIDC à froid. Lambda et Cloud Functions ne fonctionnent pas, car la passerelle est un serveur HTTP de longue durée.

Chaque topologie de production ici place un proxy L7, tel qu'une Ingress, le front-end de Cloud Run ou un ALB, devant les répliques HTTP simples. Définissez listen.trusted_proxies sur les plages sources du proxy afin que la passerelle lise les adresses IP des clients à partir de X-Forwarded-For. La passerelle honore l'en-tête uniquement lorsque le pair TCP est de confiance. Les exemples travaillés Google Cloud et AWS ont des valeurs concrètes par topologie. Sans proxies de confiance, chaque demande semble provenir de l'adresse IP du proxy, ce qui réduit les limites de débit par IP en un seul compartiment partagé et enregistre l'adresse IP du proxy dans les événements d'audit.

Ne redirigez pas les demandes vers les points de terminaison d'autorisation d'appareil et de jeton de la passerelle, par exemple avec une réécriture HTTP-vers-HTTPS ou de canonicalisation d'hôte à l'entrée. Claude Code ne suit pas les redirections sur ces demandes, donc une règle d'entrée qui les redirige casse la connexion et l'actualisation des jetons.

Donnez au proxy un délai d'inactivité plus long que l'intervalle de maintien de la connexion de la passerelle, qui dépend de l'amont :

• Sur chaque amont sauf provider: anthropic, la passerelle écrit un ping SSE une fois qu'un flux a été silencieux pendant environ 15 secondes.
• Sur provider: anthropic, la passerelle transmet la réponse inchangée, y compris les propres pings de l'API Anthropic.

Une valeur par défaut telle que les 60 secondes de l'ALB est suffisante pour garder un flux silencieux ouvert. L'exemple travaillé AWS l'augmente à une heure de toute façon, et sa ligne de dépannage couvre les passerelles antérieures à v2.1.229, qui n'envoyaient rien pendant les périodes silencieuses sur les amonts qui reçoivent maintenant des pings.

Choisir une adresse pour la passerelle

Claude Code accepte l'adresse d'une passerelle de l'une de deux manières :

• Adresse privée : placez la passerelle derrière un équilibreur de charge interne ou un VPN, avec un nom d'hôte qui se résout uniquement en adresses privées, telles que RFC 1918 ou CGNAT 100.64.0.0/10. Les machines des utilisateurs peuvent avoir n'importe quelle adresse. Le prérequis de réseau privé liste les plages acceptées.
• Bloc déclaré : si votre réseau interne utilise un espace IPv4 public que possède votre organisation, listez le bloc dans le paramètre géré gatewayInternalNetworks. La passerelle et la machine de l'utilisateur doivent toutes deux se trouver dans ce bloc. Consultez Autoriser une passerelle sur un espace d'adressage public que vous possédez.

Si aucun bloc unique ne contient les deux, attribuez plutôt une adresse privée à la passerelle.

Image de conteneur

Créez votre propre image autour du binaire claude natif de la version standard de Claude Code :

1. Téléchargez la version Linux pour l'architecture de votre image à partir d'une version épinglée ; consultez Installer une version spécifique pour l'URL de téléchargement.
2. Vérifiez-la par rapport au manifest.json signé GPG de la version comme décrit dans Intégrité binaire et signature de code.
3. Copiez-la dans le contexte de construction.

Miroitez la version dans votre registre interne si vos constructions ne peuvent pas atteindre l'hôte de version, et épinglez la version que votre flotte exécute.

Au-delà du binaire, l'image a besoin de :

• Une image basée sur glibc : la seule dépendance dynamique de la version glibc est les bibliothèques glibc. Les images basées sur Musl ont besoin de la version linux-x64-musl ou linux-arm64-musl plus des packages supplémentaires ; consultez Configuration Alpine Linux.
• Un répertoire d'état inscriptible : la passerelle s'exécute en tant qu'utilisateur quelconque, mais les images minimales n'ont pas de répertoire personnel inscriptible. Définissez CLAUDE_CONFIG_DIR sur un chemin inscriptible tel que /tmp/.claude.
• La commande du conteneur : claude gateway --config /etc/claude/gateway.yaml, avec le fichier de configuration monté en lecture seule et les secrets fournis en tant que variables d'environnement ; la passerelle écoute sur listen.port, par défaut 8080.

Kubernetes

Exécutez la passerelle en tant que Deployment, comme tout service sans état :

• Montez la configuration à partir d'une ConfigMap et les secrets à partir d'un Secret ; référencez les secrets dans le YAML via ${file:/path/to/secret} ou en tant que variables d'environnement
• Terminez TLS à l'Ingress et définissez listen.public_url sur le nom d'hôte de l'Ingress
• Pointez la sonde de disponibilité sur GET /readyz et la sonde de vivacité sur GET /healthz

Pour un exemple travaillé complet sur AWS, couvrant ECS Fargate ou EKS, Amazon RDS et AWS Secrets Manager, consultez Déployer sur AWS.

Préférez l'identité de charge de travail de la plateforme aux clés statiques ; la référence upstreams a des détails de configuration par plateforme. Pour un appairage inter-cloud, tel qu'un amont Bedrock sur GKE, définissez des credentials explicites dans le bloc auth de l'amont à la place.

Cloud Run

Configurez le service comme suit :

• Laissez listen.port à sa valeur par défaut de 8080, qui correspond au PORT par défaut de Cloud Run, ou définissez port: ${PORT}
• Définissez public_url sur l'origine accessible de l'extérieur. Pour la production, c'est normalement le nom d'hôte d'un équilibreur de charge interne, car /login rejette les adresses publiques et l'URL *.run.app se résout en une, donc l'URL Cloud Run seule fonctionne uniquement pour un test de fumée curl ou navigateur. L'exception est un réseau où *.run.app se résout en privé via Private Service Connect et une zone privée Cloud DNS ; dans cette topologie l'URL Cloud Run est un public_url valide. L'exemple travaillé Google Cloud couvre les deux.
• Montez la configuration en tant que volume secret
• Définissez min-instances: 1 pour éviter une découverte OIDC à froid à la première demande

Pour un exemple travaillé complet sur Google Cloud, couvrant Cloud Run ou GKE, Cloud SQL et Secret Manager, consultez Déployer sur Google Cloud.

Envoyer l'URL de la passerelle aux machines des développeurs

Une fois que la passerelle est en service, envoyez forceLoginMethod, forceLoginGatewayUrl et parentSettingsBehavior: "merge" à la machine de chaque développeur via les paramètres gérés, via MDM ou en écrivant directement le fichier managed-settings.json par système d'exploitation.

Une fois que vous déployez les clés, Claude Code cesse d'utiliser une clé API restante ou une connexion claude.ai sur la machine, donc planifiez l'envoi avec vos instructions de connexion. La politique de l'administrateur nécessite une connexion à la passerelle Cloud décrit les messages que les développeurs voient.

Consultez où chaque mécanisme stocke la politique pour les chemins de fichiers, et Paramètres gérés côté client pour l'équivalent bootstrapUrl de Claude Desktop.

Déploiements à grande échelle

La connexion est limitée en débit par adresse IP client, et les valeurs par défaut conviennent à une petite équipe. Chaque adresse obtient 30 démarrages de connexion et 10 soumissions de code toutes les 10 minutes. Un déploiement pour des milliers de développeurs peut atteindre ces limites le premier matin, pour l'une de deux raisons :

• La passerelle ne peut pas voir au-delà de votre équilibreur de charge. Sans listen.trusted_proxies, chaque développeur semble provenir de l'adresse de l'équilibreur de charge et partage une limite. Définissez-le avant toute autre chose. La passerelle enregistre un avertissement la première fois qu'elle ignore un en-tête X-Forwarded-For.
• De nombreux développeurs partagent quelques adresses de sortie NAT ou VPN. Ils partagent les limites de ces adresses même lorsque trusted_proxies est correct. Augmentez rate_limits pour l'adapter.

Pour dimensionner max, divisez les développeurs par les adresses de sortie qu'ils partagent. Estimez combien d'entre eux se connectent dans une période window_seconds, qui est 10 minutes par défaut. Puis doublez-le pour couvrir les tentatives et les développeurs qui se connectent à la fois à Claude Code et Claude Desktop.

Par exemple, 10 000 développeurs derrière 4 adresses de sortie se connectent uniformément sur une heure. C'est 2 500 développeurs par adresse et environ 420 d'entre eux dans chaque 10 minutes, que vous doublez et arrondissez à 1 000. L'exemple ci-dessous définit les deux limites à 1 000 :

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

device_verify est ce qui empêche quelqu'un de deviner le code de connexion d'un autre développeur, donc augmentez-le uniquement autant que votre estimation le nécessite. Même à ces limites, un code est 8 caractères d'un alphabet de 20 caractères et expire après 10 minutes, donc deviner reste impraticable ; consultez Résistance à la force brute du code utilisateur.

Lorsque votre IdP émet des jetons d'actualisation, Claude Code renouvelle les sessions silencieusement, donc vous pouvez remettre la limite après le déploiement. Sans jetons d'actualisation, les développeurs se connectent à nouveau tous les session.ttl_hours. Dimensionnez les deux limites pour ce débit régulier aussi et laissez-les augmentées.

Lorsqu'une limite est atteinte, Claude Code v2.1.274 ou ultérieur affiche The gateway is limiting sign-in attempts right now. Une passerelle sur v2.1.274 ou ultérieur affiche Too many attempts came from your network address sur la page de vérification, avec les paramètres à vérifier. Elle écrit également une ligne de journal sign-in refused qui nomme le paramètre à modifier.

Opérations

Une fois que la passerelle traite le trafic, l'exploitation au quotidien consiste à lire ses journaux, à sonder sa santé et à faire tourner ses secrets selon votre calendrier. Les sous-sections couvrent chacun, plus ce que Postgres détient et comment les mises à jour et les restaurations se comportent.

Journaux

La passerelle écrit deux flux sur stderr, tous deux JSON-friendly :

• Événements d'audit : JSON sur une seule ligne par événement pertinent pour la sécurité. Canalisez stderr vers votre agrégateur de journaux.

  Les événements émis incluent config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert et admin.limit.delete. Les champs varient selon l'événement :

  • Les événements de mint et refresh réussis portent sub, email, client_ip et le résultat
  • auth.denied et access.denied portent la raison et l'adresse IP du client, plus le chemin de la demande pour auth.denied, car aucune identité utilisateur n'existe à ces refus. Deux raisons access.denied changent ce que l'événement porte :
    • xff_unparseable : l'événement porte également l'entrée X-Forwarded-For qui n'a pas pu être lue
    • client_ip_unknown : l'événement ne porte pas d'adresse IP client, car la connexion n'avait pas d'adresse de pair tandis qu'une liste access_control était définie
  • access.public_client porte l'adresse IP du client de la première demande par processus à arriver d'une adresse publique tandis que access_control.allow_cidrs est vide. La passerelle sert la demande comme d'habitude ; l'événement signale que la passerelle peut être accessible depuis l'internet public. Consultez la référence access_control pour ce qui compte comme public et pour la liste d'autorisation recommandée.
  • inference enregistre quel amont a servi la demande et le statut de la réponse
  • desktop_bootstrap.denied enregistre une récupération de bootstrap Claude Desktop rejetée avec la raison (not_configured, policy_not_opted_in ou no_policy_matched) et l'identité de l'utilisateur
  • admin.denied enregistre une tentative d'authentification d'API admin rejetée avec l'adresse IP du client, la méthode, le chemin et une raison, sans le matériel de clé présenté : invalid_key quand une x-api-key a été présentée mais ne correspondait à aucune clé configurée, bearer_rejected quand seul un en-tête Authorization a été présenté et il n'a pas vérifié comme une session de passerelle dans admin.admin_groups, ou no_credentials quand aucun en-tête n'a été présenté

• Journaux opérationnels : lignes lisibles par l'homme avec préfixe [gateway] pour le démarrage, les avertissements et les erreurs en amont. La variable d'environnement CLAUDE_GATEWAY_LOG_LEVEL contrôle la verbosité et accepte debug, info, warn ou error, avec info par défaut. À debug, chaque connexion et actualisation enregistre également les noms, pas les valeurs, des revendications dans l'id_token, plus les noms des revendications userinfo quand userinfo_fallback en a fourni, afin que vous puissiez diagnostiquer les paramètres email_claim et groups_claim sans enregistrer les PII. Cela n'affecte pas les événements d'audit, qui sont toujours émis.

Santé

La passerelle sert GET /healthz comme sonde de vivacité et GET /readyz comme sonde de disponibilité. /readyz vérifie que le magasin est accessible. Si vous définissez store.readiness_grace_seconds, /readyz continue de signaler prêt pendant jusqu'à ce nombre de secondes après que le magasin cesse de répondre.

Les deux points de terminaison sont exempts de access_control.allow_cidrs, donc les sondes continuent de fonctionner sur un écouteur verrouillé.

Le document de découverte OAuth à /.well-known/oauth-authorization-server retourne également 200 uniquement après le chargement de la configuration, la découverte OIDC, la construction du client en amont et la migration Postgres réussissent, donc il double comme vérification de démarrage de bout en bout.

Demandes en amont concurrentes

Par défaut, chaque réplique de passerelle envoie au maximum 256 demandes en amont en même temps. Une réponse en streaming compte par rapport à la limite jusqu'à ce que le flux se termine.

Une demande qui arrive tandis qu'une réplique est à la limite attend à l'intérieur de la passerelle pour un créneau libre. Le développeur voit une réponse qui est lente à démarrer ou semble se bloquer. Sur une amont provider: anthropic, une demande qui attend plus longtemps que timeouts.upstream_ttfb_ms abandonne cet amont, et échoue avec un 502 quand aucun amont ultérieur ne la sert.

La ligne de journal de démarrage qui contient upstream requests: affiche la limite en vigueur. Tandis qu'une réplique a plus de demandes ouvertes que la limite, elle enregistre également un avertissement qui contient client requests are open, au maximum une fois par minute.

Pour servir plus de demandes à la fois, vous avez deux options :

• Ajouter des répliques.
• Augmenter la limite sur chaque réplique. Définissez la variable d'environnement BUN_CONFIG_MAX_HTTP_REQUESTS sur le conteneur de passerelle à un nombre entier de 1 à 65535, puis redémarrez le conteneur.

Une réplique remplit sa limite à un taux de demande d'environ la limite divisée par le nombre moyen de secondes qu'une demande reste ouverte. Par exemple, si les demandes restent ouvertes pendant 10 secondes en moyenne, une réplique à la limite par défaut de 256 la remplit à environ 26 demandes par seconde.

Si vous mettez à l'échelle automatiquement sur CPU, une réplique à la limite met en file d'attente les demandes sans déclencher une montée en charge, donc définissez la cible en dessous du niveau CPU que vos répliques affichent quand elles enregistrent l'avertissement client requests are open.

[!WARNING]

Chaque demande ouverte détient la mémoire dans le processus de passerelle tandis qu'elle diffuse en continu et tandis qu'elle attend un créneau. Si vous gardez la limite à 256, la mémoire sur une réplique surchargée croît toujours, car les demandes en attente conservent leurs corps de demande. Dimensionnez la mémoire du conteneur pour le nombre de demandes ouvertes au pic, et surveillez la mémoire quand vous changez la limite. Une réplique qui manque de mémoire est tuée et abandonne chaque flux qu'elle détient.

Maintenir API_TIMEOUT_MS au-dessus du délai de premier octet de la passerelle

Si vous abaissez API_TIMEOUT_MS pour réessayer plus tôt une requête restée sans réponse, maintenez-le au-dessus du temps que met la passerelle à envoyer les premiers octets d'une réponse en streaming. Une requête qui attend plus longtemps expire, de même que chaque nouvelle tentative qui attend aussi longtemps, jusqu'à ce que le tour se termine avec Request timed out, sauf si le délai maximal de premier octet y met fin.

• provider: anthropic : définissez API_TIMEOUT_MS au-dessus du temps maximal que met votre amont à envoyer son premier événement.
• Tous les autres amonts : définissez-le à plus de 20 secondes au-dessus du temps maximal que met votre amont à renvoyer les en-têtes de réponse. La passerelle envoie son premier ping keepalive environ 15 secondes après ces en-têtes, sauf si le premier événement de l'amont arrive plus tôt. Une passerelle antérieure à v2.1.229 n'envoie aucun ping, appliquez donc la règle provider: anthropic dans ce cas.

En plus de ce temps, prévoyez toute attente d'un créneau libre et l'attente sur un amont en panne avant le basculement. Maintenez également la valeur au-dessus de la plus longue requête sans streaming.

Réessayer plus tôt une requête restée sans réponse grâce au délai maximal de premier octet

Pour que Claude Code réessaie plus tôt une requête en streaming restée sans réponse, donnez-lui un délai maximal de premier octet en définissant CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS sur les machines de vos développeurs. Ce délai limite le temps pendant lequel la première tentative attend les en-têtes de réponse. Sans lui, cette tentative peut attendre de 5 à 6 minutes. Nécessite Claude Code v2.1.307 ou ultérieur sur la machine du développeur.

Définissez la variable sur un nombre entier positif de millisecondes, dans le bloc env d'une politique de passerelle ou dans le shell d'un développeur. Maintenez la valeur au-dessus du plus long délai de premier octet de votre passerelle, sinon Claude Code peut interrompre et renvoyer des requêtes saines dont les en-têtes mettent plus de temps à arriver. Cet exemple définit 60 secondes dans le shell d'un développeur :

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

Un renvoi resté sans réponse peut attendre de 5 à 6 minutes, jusqu'à ce que le délai d'inactivité du corps y mette fin et que Claude Code le réessaie dans la limite du budget de nouvelles tentatives. Si vous avez abaissé API_TIMEOUT_MS uniquement pour réessayer plus tôt, supprimez cette valeur, sinon un seul renvoi resté sans réponse peut terminer le tour avec No response from API.

Pour confirmer que le délai s'est déclenché, demandez à un développeur de démarrer Claude Code avec la journalisation de débogage, puis recherchez [first-byte] no response headers dans le log.

Comportement en cas de panne

Si Postgres tombe en panne, la passerelle elle-même continue de servir les développeurs connectés et les nouvelles connexions échouent. Que les développeurs continuent réellement à travailler dépend de la façon dont votre orchestrateur gère la disponibilité :

• Sessions existantes : les jetons porteurs valident localement avec le secret JWT, les actualisations de session ne touchent pas le magasin, et le processus de passerelle peut toujours servir l'inférence
• Nouvelles connexions : échouent jusqu'à la récupération de Postgres, car le flux d'appareil et ses compteurs de limite de débit vivent dans Postgres
• Application des limites de dépenses : échoue ouvert par défaut pendant la panne, donc l'inférence continue de circuler ; basculez-la pour échouer fermé si vous préférez bloquer plutôt que de fonctionner sans compteur
• Disponibilité : par défaut /readyz signale non-prêt dès que Postgres est inaccessible, donc chaque réplique échoue sa vérification de disponibilité à la fois. Là où le trafic ne atteint que les répliques qui passent la vérification, tout le trafic, y compris l'inférence que la passerelle pourrait toujours servir, échoue jusqu'à la récupération de Postgres. La sonde de vivacité sur /healthz continue de passer tout au long.

Si votre IdP tombe en panne, les sessions existantes fonctionnent jusqu'à ttl_hours et les nouvelles connexions échouent. Une actualisation de session obtient une réponse de réessai et se termine une fois que l'IdP est de retour. Définissez un ttl_hours plus long si votre IdP a des fenêtres de maintenance fréquentes.

Période de grâce de disponibilité

Pour garder les développeurs connectés qui travaillent à travers une courte panne de Postgres telle qu'un basculement de base de données, définissez store.readiness_grace_seconds à plus long que le basculement ne prend, par exemple 300. Avec les limites de dépenses activées et le comportement par défaut fail-open, les demandes à travers une réplique qui reste prête sont sans compteur jusqu'à la récupération de Postgres, donc gardez la valeur aussi basse que couvre votre basculement. Si vous définissez enforcement.fail_closed_on_error: true, la passerelle refuse l'inférence des développeurs connectés avec le message 429 spend limit unavailable jusqu'à la récupération de Postgres, même tandis que les répliques passent toujours leur vérification de disponibilité.

Le paramètre nécessite Claude Code v2.1.282 ou ultérieur sur le serveur de passerelle. Une passerelle antérieure refuse de démarrer quand elle trouve la clé, donc mettez à niveau chaque réplique avant de l'ajouter. Mises à jour couvre la restauration.

Si vous pointez la sonde de disponibilité sur /healthz à la place, les répliques passent également à travers une panne, mais /healthz ne signale jamais non-prêt, donc une réplique dont la connexion Postgres ne se rétablit pas continue de passer aussi.

Rotation du secret JWT

Faites tourner le secret de signature en étapes afin que les sessions existantes restent valides :

1. Générez un nouveau secret. Ajoutez-le au début du tableau session.jwt_secret.
2. Déployez le déploiement. Les nouveaux jetons signent avec le nouveau secret ; les anciens jetons valident toujours.
3. Après ttl_hours plus une marge, supprimez l'ancien secret et déployez à nouveau.

La rotation est également le seul moyen de forcer les sessions à sortir avant leur expiration : les jetons porteurs valident localement par rapport au secret JWT, donc il n'y a pas de révocation par session. Remplacer le secret directement, sans conserver l'ancien dans le tableau, invalide chaque session en attente à la fois. Pour le déprovisionnement individuel, déprovisionner l'utilisateur dans votre IdP ; sa session se termine dans ttl_hours.

Postgres

La passerelle stocke son état dans une base de données PostgreSQL :

• Base de données : PostgreSQL lui-même, auto-hébergé ou managé, en version minimale ou ultérieure. Les bases de données qui implémentent uniquement le protocole Postgres, comme les bases de données SQL distribuées, ne sont pas prises en charge.
• Adresse : store.postgres_url accepte un seul hôte. Si la base de données comporte plusieurs nœuds, utilisez l'adresse placée devant eux, comme l'endpoint de votre service managé, un équilibreur de charge ou une IP virtuelle. Définissez une période de grâce de disponibilité plus longue que la durée d'un basculement.

La passerelle détient cinq tables de données plus une table _migrations, toutes créées par ses migrations au démarrage :

Une boucle de 30 secondes expire les lignes kv au-delà de leur TTL, et un balayage horaire applique les fenêtres de rétention sur les tables de dépenses, donc rien ne croît sans limite. Sans limites de dépenses configurées, seul kv est écrit. La passerelle applique ses propres migrations de schéma au démarrage et à chaque mise à jour, donc son rôle de base de données a besoin de droits pour créer et modifier les tables. Pointez-le vers une base de données ou un schéma dédié à la passerelle pour garder cette autorisation étroite.

Avec les limites de dépenses en usage, une base de données perdue signifie le suivi des dépenses et les plafonds perdus, pas seulement les re-connexions des développeurs, donc exécutez des sauvegardes régulières. Pour effacer immédiatement un développeur parti plutôt que d'attendre la rétention, exécutez DELETE FROM principal_emails WHERE principal = '<sub>' directement ; cela supprime la seule table contenant son email, son nom et ses groupes. Les lignes spend et admin_audit ne référencent que le sub OIDC pseudonyme.

Dimensionner le pool de connexions

Chaque réplique ouvre jusqu'à store.max_connections connexions Postgres, cinq par défaut. Maintenez répliques × store.max_connections inférieur ou égal aux connexions dont la base de données dispose encore pour la passerelle :

• Répliques : comptez le nombre maximal qui s'exécutent simultanément. Partez de votre maximum d'autoscaling, ou de votre nombre de répliques si vous n'utilisez pas l'autoscaling, et ajoutez les répliques supplémentaires qu'une mise à jour progressive démarre avant d'arrêter les anciennes. Sur Amazon ECS avec les paramètres par défaut, et sur Cloud Run, cela peut représenter autant à nouveau.
• Connexions disponibles : prenez le max_connections de la base de données, puis soustrayez ce que la base de données réserve et ce que détiennent les autres clients. PostgreSQL réserve superuser_reserved_connections, trois par défaut. Un service managé peut en réserver davantage, consultez donc sa documentation.

Par exemple, prenez un maximum d'autoscaling de six, des mises à jour progressives qui démarrent au plus deux répliques supplémentaires et le pool par défaut de cinq. Cela nécessite (6 + 2) × 5 = 40 connexions. Une base de données avec un max_connections de 50 et deux connexions détenues par d'autres clients en a 50 − 3 − 2 = 45 disponibles, donc le total tient.

Si votre total ne tient pas, modifiez l'un de ces éléments :

• La base de données : augmentez son max_connections
• Les répliques : exécutez-en moins, ou faites en sorte que votre orchestrateur démarre moins de répliques supplémentaires lors d'une mise à jour progressive
• Le pool : abaissez store.max_connections, mais avec les limites de dépenses activées, gardez-le suffisamment grand pour la charge de chaque réplique. Sinon, les vérifications de dépenses peuvent expirer en attendant une connexion, et la passerelle journalise spend check failed: spend precheck timed out.

Mises à jour

Les répliques sont sans état, donc un redémarrage roulant ne perd aucun état de passerelle. La passerelle exécute les migrations de schéma au démarrage, ce qui signifie que le déploiement du nouveau binaire auto-migre la base de données. Les répliques concurrentes se sérialisent sur un verrou consultatif Postgres, donc seule une applique chaque migration.

Quand votre orchestrateur arrête une réplique avec SIGTERM, comme dans un redémarrage roulant ou une réduction d'échelle, la passerelle arrête d'accepter les nouvelles connexions et laisse les demandes et les flux déjà en vol se terminer avant de quitter. Elle attend jusqu'à 25 secondes, appelée la fenêtre de drainage, puis ferme tout ce qui est toujours ouvert. Un SIGINT, tel que Ctrl+C dans un terminal, démarre le même drainage, et un deuxième signal pendant le drainage ferme les demandes ouvertes et quitte immédiatement. Le drainage nécessite la passerelle v2.1.274 ou ultérieure.

Les générations longues peuvent diffuser en continu pendant des minutes. Sur Kubernetes et Amazon ECS, augmentez les deux ensemble pour donner à ces flux plus de temps :

• La fenêtre de drainage : définissez la variable d'environnement CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS sur le conteneur de passerelle à un nombre entier positif de millisecondes, tel que 120000. La passerelle ignore une valeur sous toute autre forme, telle que 120s, et conserve la valeur par défaut de 25 secondes
• La période de grâce de votre orchestrateur : terminationGracePeriodSeconds sur Kubernetes, ou stopTimeout sur Amazon ECS

La période de grâce par défaut est de 30 secondes sur les deux plates-formes. Gardez-la au moins 5 secondes plus longue que la fenêtre de drainage, ou l'orchestrateur tue la passerelle avant la fin du drainage. Sur Kubernetes, ajoutez également la durée de tout crochet preStop, car la période de grâce commence à compter avant que le crochet ne s'exécute plutôt que quand la passerelle reçoit SIGTERM.

Votre plate-forme peut également limiter la durée du drainage :

• Amazon ECS sur Fargate : stopTimeout permet au maximum 120 secondes
• Cloud Run : arrête une instance 10 secondes après SIGTERM, donc les flux ouverts obtiennent au maximum 10 secondes là, quelle que soit la fenêtre de drainage

Quand la fenêtre de drainage se termine avec des demandes toujours ouvertes, la passerelle enregistre un avertissement qui contient drain window over after, compte les demandes qu'elle a coupées, et nomme les deux paramètres à augmenter.

Les migrations sont en ajout seul, donc revenir à un binaire antérieur qui connaît moins de migrations est sûr ; il ignore les lignes supplémentaires. La restauration re-valide également le YAML par rapport au schéma du binaire plus ancien, donc une configuration qui a adopté une clé introduite par la version plus récente échoue au démarrage sur l'ancienne. Supprimez la nouvelle clé avant de revenir.

Parce que vous épinglez la version de la passerelle dans votre propre image, les correctifs dans les nouvelles versions de Claude Code, y compris les correctifs de sécurité, atteignent votre déploiement uniquement lorsque vous mettez à jour l'épingle et redéployez. Incluez la passerelle dans le même calendrier de correction que vous utilisez pour les autres services qui détiennent des credentials de production.

Sécurité

Cette section répond aux questions qu'un examen de sécurité pose : quelles données circulent à travers la passerelle et où elles vont, quelles attaques la conception défend, et quelles réponses appartiennent à un questionnaire de conformité.

Flux de données

Résumé du modèle de menace

La passerelle se trouve à l'intérieur de votre périmètre réseau, mais les ordinateurs portables des développeurs individuels ne sont pas traités comme de confiance. La conception en tient compte de trois façons :

• Les développeurs détiennent des JWT de courte durée au lieu de clés en amont brutes. La jambe CLI-à-passerelle utilise la subvention d'appareil RFC 8628, et l'échange de code d'autorisation de la passerelle avec l'IdP exécute PKCE dans la configuration par défaut, donc un code d'autorisation IdP intercepté est inutile.

• La page de vérification d'appareil applique POST de même origine et une limite de débit par IP par RFC 8628 §5.1. Consultez Résistance à la force brute du code utilisateur.

• Les demandes de la passerelle à votre IdP, vos collecteurs OTLP, et les amonts provider: anthropic passent par une protection contre la falsification de demande côté serveur (SSRF) qui résout DNS, bloque les adresses de lien local et de métadonnées cloud plus la bouclage par défaut, et épingle la connexion à l'IP résolue, donc les URL influencées par l'opérateur ne peuvent pas être redirigées vers les points de terminaison de métadonnées cloud. Les plages privées RFC 1918 sont délibérément autorisées, car les IdP et les collecteurs OTLP vivent couramment sur des adresses IP privées. Pour les autres fournisseurs, la passerelle refuse une base_url qui nomme l'une de ces adresses ou un nom d'hôte de métadonnées lorsqu'elle charge la config, et le SDK du fournisseur se connecte ensuite sans la vérification DNS.

  Si vous activez sortie proxy uniquement, cette vérification d'adresse se déplace vers votre proxy avant : la passerelle lui transmet les noms d'hôte et la liste d'autorisation du proxy doit refuser ces destinations.

  Définissez CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dans l'environnement de la passerelle uniquement lorsque quelque chose que la passerelle doit atteindre légitimement vit sur la bouclage, comme un IdP de développement local ou un collecteur OTLP sidecar sur localhost. La variable assouplit le bloc de bouclage pour chaque URL configurée par l'opérateur et ignore également l'avertissement au démarrage qui vérifie si le pod peut atteindre le point de terminaison de métadonnées cloud, donc préférez donner au collecteur sa propre adresse interne.

Si vous ajoutez vos propres contrôles de sortie, la passerelle doit atteindre le serveur de métadonnées chaque fois qu'elle utilise des credentials de métadonnées d'instance tels que l'identité de charge de travail.

Deux menaces sont hors de portée car c'est votre infrastructure à sécuriser :

• Un hôte de passerelle compromis : l'hôte détient à la fois la credential en amont et distribue les paramètres gérés à chaque développeur connecté, donc le contrôle de la configuration de la passerelle est comparable au contrôle de votre MDM. La boîte de dialogue d'approbation du CLI pour les paramètres capables de shell limite les changements silencieux mais ne remplace pas la sécurité de l'hôte.
• Un fournisseur OIDC malveillant : le fournisseur signe les id_tokens que la passerelle fait confiance, donc il peut affirmer n'importe quelle identité. L'examen et la sécurisation de votre IdP sont votre responsabilité.

Résistance à la force brute du code utilisateur

Le user_code qu'un développeur tape dans la page de vérification /device est 8 caractères tirés d'un alphabet de 20 caractères, ce qui donne 20⁸ ou environ 2,56×10¹⁰ combinaisons, et il expire après 10 minutes.

La passerelle applique des limites de débit par IP sur les points de terminaison de subvention d'appareil, configurables via rate_limits. Augmentez les limites si de nombreux développeurs se connectent à partir d'une seule adresse NAT d'entreprise partagée. Les déploiements à grande échelle montre comment les dimensionner. Les limites s'appliquent uniquement au flux de connexion, pas à l'inférence.

Posture de conformité

• Résidence des données : le plan de données de la passerelle elle-même n'envoie rien à Anthropic sauf si l'API Anthropic est un amont configuré ; lorsqu'elle l'est, votre accord de traitement des données existant s'applique au chemin d'inférence. La télémétrie, l'audit, l'identité et les paramètres vont uniquement aux destinations que vous configurez.
• Trafic du processus hôte : le processus hôte est le CLI Claude Code. La commande claude gateway s'exécute selon les mêmes règles tierces que les déploiements Amazon Bedrock et Google Cloud Agent Platform et n'envoie rien à Anthropic. Avant la v2.1.227, le processus hôte envoyait la télémétrie de démarrage telle que la version du produit et la plateforme, que le paramètre CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dans l'environnement du conteneur désactivait. Ces versions envoyaient également une demande HEAD au démarrage, sans corps ni credentials, à /api/hello sur https://api.anthropic.com, ou sur ANTHROPIC_BASE_URL lorsque l'environnement l'a défini, sauf si l'environnement a également défini une variable proxy telle que HTTPS_PROXY ou un certificat client mTLS. Elles ignoraient la réponse, donc bloquer cette demande au pare-feu de sortie n'affectait pas la passerelle.
• Analytique client : le CLI désactive sa propre analytique d'utilisation et le rapport d'erreurs lorsqu'il est connecté à une passerelle. Avant la première connexion, le CLI envoie toujours les événements de démarrage à Anthropic, y compris sur les machines dont les paramètres gérés forcent la connexion à la passerelle. Pour les désactiver aussi, livrez DISABLE_TELEMETRY dans les mêmes paramètres gérés côté client qui forcent la connexion à la passerelle.
• Rapport d'erreurs : le CLI désactive le rapport d'erreurs chaque fois que ses demandes de modèle vont à n'importe quel point de terminaison autre que l'API première partie d'Anthropic, comme Amazon Bedrock ou un ANTHROPIC_BASE_URL personnalisé.
• Machines client : les CLI des développeurs envoient toujours les vérifications de nom d'hôte WebFetch et les vérifications de version à Anthropic sauf si CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 et skipWebFetchPreflight: true sont définis. Les requêtes de marketplace de plugins disposent de leurs propres moyens de désactivation. Consultez utilisation des données.
• Évaluations d'enquête : lorsqu'il est connecté à une passerelle, le CLI désactive le téléchargement d'évaluation lié à Anthropic ainsi que les flux d'analytique, donc il n'envoie pas les évaluations à Anthropic.
• Partage de transcription : choisir Oui sur une invite de partage de transcription d'enquête écrit un fichier local sous ~/.claude/feedback-bundles/ au lieu de télécharger vers Anthropic.
• Mises à jour client : les vérifications de mise à jour sont séparées du trafic de passerelle. Épinglez les versions via votre propre distribution et définissez DISABLE_UPDATES si les ordinateurs portables ne doivent pas récupérer les versions. DISABLE_AUTOUPDATER arrête uniquement les mises à jour en arrière-plan tandis que claude update fonctionne toujours.
• TLS : servez public_url via HTTPS en production, soit à partir du propre écouteur de la passerelle via listen.tls, soit à partir d'une ingress terminant TLS devant les répliques HTTP simples, avec listen.public_url défini dans les deux cas. La passerelle ne refuse pas HTTP simple. L'IdP doit servir HTTPS en production, et Postgres supporte ?sslmode=require. Définissez Strict-Transport-Security à votre ingress.
• Divulgation de vulnérabilité : suivez Signaler les problèmes de sécurité

Requêtes de marketplace de plugins

Claude Code récupère les marketplaces de plugins directement depuis la machine de chaque développeur, et non via la passerelle. Exigences d'accès réseau répertorie les hôtes.

La première fois qu'un développeur démarre une session de terminal interactive, Claude Code enregistre la marketplace officielle, claude-plugins-official. Il télécharge le catalogue depuis downloads.claude.ai et, en cas d'échec, le clone depuis github.com. Quelles marketplaces et quels plugins se mettent à jour automatiquement couvre les actualisations ultérieures.

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 n'empêche pas le premier enregistrement. L'un ou l'autre de ces paramètres gérés l'empêche :

• Une liste de marketplaces : une liste d'autorisation strictKnownMarketplaces qui exclut la marketplace, ou une entrée blockedMarketplaces qui la nomme
• Une variable d'environnement : CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL définie sur "1" dans le bloc env géré

Le premier enregistrement peut s'exécuter avant que le développeur se connecte à la passerelle, lorsqu'aucune politique de passerelle n'est encore arrivée. Pour couvrir ce premier démarrage, fournissez votre choix dans les paramètres gérés côté client ainsi que dans le bloc cli ou code de la politique de passerelle.

Dépannage

Pour les questions et les commentaires, utilisez le support Claude Code, ou ouvrez un problème sur le dépôt GitHub Claude Code. Vous pouvez également contacter l'équipe chargée de votre compte Anthropic. Lors de la signalisation d'un problème, incluez :

• Problème de passerelle : la sortie d'erreur de la passerelle pour la fenêtre pertinente, votre gateway.yaml avec les secrets masqués, la version de la passerelle, affichée sur la page d'accueil à / et dans l'en-tête de réponse x-cc-gateway-version sur /managed/settings, et ce qui a changé récemment
• Problème de connexion : le développeur exécute claude --debug-file ./claude-debug.txt, reproduit le problème, et envoie ce fichier plus le journal d'audit de la passerelle pour la même fenêtre
• Problème d'inférence : le modèle demandé, les upstreams configurés, et le journal d'audit de la passerelle pour la demande, qui enregistre quel upstream l'a servie et le statut de la réponse

La sortie d'erreur de la passerelle inclut le flux d'événements d'audit, le journal d'audit enregistre les identités des développeurs, et le fichier de débogage enregistre la sortie des hooks et du serveur MCP de la machine du développeur. Examinez et masquez ces éléments avant de les publier sur un problème public.

Le message Cloud gateway sign-in was not completed nomme le nom d'hôte de la passerelle. Lorsque Claude Code a à la fois l'empreinte digitale épinglée et celle présentée, le message affiche également les 16 premiers caractères de chacune.

Si Claude Code signale couldn't load your organization's managed settings après une connexion à la passerelle, Claude Code nomme la raison, redémarre sur place et reprend la conversation. Si Claude Code ne peut pas redémarrer, par exemple dans une session d'arrière-plan, Claude Code termine la session et conserve la connexion.

En-têtes de requête trop volumineux après la connexion

Les requêtes d'un développeur peuvent échouer avec une erreur 431 après la connexion lorsque le développeur appartient à de nombreux groupes IdP.

La passerelle répond 431 lorsque le total des en-têtes d'une requête dépasse 256 Kio, ou limits.max_request_header_bytes si vous le définissez. Elle n'écrit aucune ligne de log ni aucun événement d'audit pour ces requêtes. Les versions de la passerelle antérieures à v2.1.284 répondent 431 au-delà de 16 Kio.

Commencez par le premier de ces cas qui s'applique à votre passerelle :

• Passerelle antérieure à v2.1.284 : mettez à niveau la passerelle
• limits.max_request_header_bytes défini : augmentez la valeur ou supprimez la clé
• Aucun de ces cas ne s'applique, ou le 431 persiste ensuite : faites en sorte que votre IdP émette moins de groupes. Configuration du fournisseur d'identité explique comment Okta, Microsoft Entra ID et Google Workspace fournissent les groupes

Lorsque vous réduisez la réclamation des groupes, conservez les groupes que vous avez nommés dans ces paramètres, qui déterminent l'accès, la politique et les plafonds de dépenses d'un développeur :

• oidc.allowed_groups : détermine qui peut se connecter
• admin.admin_groups : détermine qui peut appeler l'API d'administration avec sa session de passerelle
• match.groups dans managed.policies : détermine quelle politique s'applique à un développeur
• Plafonds de dépenses rbac_group : déterminent quels plafonds de groupe s'appliquent à un développeur

Une réflexion longue se termine par des délais d'expiration du proxy

Si votre upstream est provider: anthropic, consultez plutôt Réflexion longue sur un upstream API Anthropic : vous y augmentez également CLAUDE_STREAM_IDLE_TIMEOUT_MS, mais les durées et les erreurs diffèrent.

Si des tours échouent après une longue réflexion et que votre proxy journalise une requête ouverte pendant environ 12,5 minutes, puis une série d'erreurs 504, augmentez CLAUDE_STREAM_IDLE_TIMEOUT_MS dans une politique de la passerelle. Par exemple, avec un délai d'inactivité de 240 secondes sur le proxy, la série compte 10 requêtes, chacune coupée à 240 secondes.

• La première requête : un flux qui livre son premier événement de réponse, message_start, puis uniquement des pings pendant que Claude réfléchit. Avec les paramètres par défaut, Claude Code met fin à ce flux après environ 12,5 minutes.
• Les 10 autres : la même requête, envoyée sans streaming puis réessayée, soit 10 envois au total par défaut. Elles ne reçoivent aucun ping, donc une réponse lente atteint le délai d'expiration du proxy.

Vous n'avez pas besoin d'un délai d'expiration du proxy plus long pour cette correction. Si vous augmentez uniquement le délai d'expiration du proxy, les requêtes sans streaming échouent toujours dès qu'une réponse prend plus de temps que l'attente propre de Claude Code, 300 secondes par défaut.

Confirmer la cause

Demandez à un développeur de reproduire l'échec avec claude --debug-file ./claude-debug.txt, puis recherchez cette ligne dans ce fichier :

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

Si vos développeurs définissent déjà CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK sur 1, vous ne voyez aucune requête sans streaming, et le tour se termine par API Error: Stream idle timeout - no chunks received. La même correction s'applique.

Choisir une valeur

Choisissez une valeur de CLAUDE_STREAM_IDLE_TIMEOUT_MS dont la deuxième colonne couvre votre plus longue pause de réflexion, ou commencez par 1800000 si vous ne la connaissez pas. Un flux peut ne recevoir que des pings pendant environ 7,5 minutes de plus que la valeur :

Si un upstream se bloque alors que la passerelle continue d'envoyer des pings, vos développeurs attendent également aussi longtemps avant que Claude Code n'abandonne le flux. Une connexion qui devient complètement silencieuse se termine toujours après 5 à 6 minutes, car le délai d'inactivité du corps ne suit pas cette variable.

Fournir la valeur dans une politique

Ajoutez l'entrée env à chaque politique de gateway.yaml qui fournit déjà des paramètres Claude Code aux développeurs que vous souhaitez couvrir. Placez-la sous la clé code, cli ou settings que cette politique possède déjà. Pour tester la valeur d'abord, commencez par une politique qui correspond à un seul groupe. Consultez managed pour savoir comment les politiques correspondent et héritent. Cet exemple ajoute l'entrée à une politique match: {} avec la clé cli :

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_STREAM_IDLE_TIMEOUT_MS: "1800000"

Avec la clé cli, vous couvrez les sessions du terminal, de l'extension IDE et de l'Agent SDK. Pour l'onglet Code de Claude Desktop, consultez Choisir cli ou code.

Redémarrez la passerelle pour qu'elle lise le fichier modifié. Demandez ensuite aux développeurs de redémarrer Claude Code pour obtenir CLAUDE_STREAM_IDLE_TIMEOUT_MS.

Réflexion longue sur un upstream API Anthropic

Si provider: anthropic est le seul upstream du modèle et que votre proxy journalise une requête ouverte pendant environ 20 minutes, puis des erreurs 502 ou 504, augmentez CLAUDE_STREAM_IDLE_TIMEOUT_MS dans une politique de la passerelle.

• La longue requête : un flux qui livre message_start, puis uniquement des pings pendant que Claude réfléchit. Claude Code y met fin après environ 20 minutes avec les paramètres par défaut, et plus tard une fois que vous augmentez la variable.
• Les erreurs : les requêtes que Claude Code envoie ensuite sans streaming. Chacune échoue avec un 502 de la passerelle, ou avec le 504 de votre proxy si le délai d'expiration du proxy est plus court que l'attente de la passerelle. Cette attente est timeouts.upstream_ttfb_ms, que vous n'avez pas besoin d'augmenter pour cette correction.

Pour confirmer la cause, consultez Confirmer la cause.

Choisissez la valeur dont la durée couvre votre plus longue pause de réflexion : environ 20 minutes avec la valeur par défaut, 30 avec 900000 et 45 avec 1800000. Suivez ensuite Fournir la valeur dans une politique.

Connexes

• Aperçu de la passerelle Claude apps : démarrage rapide et connexion des développeurs
• Référence de configuration : chaque option du fichier gateway.yaml