Déploiement et exploitation de la passerelle Claude apps

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é

​

Configuration du fournisseur d’identité

• 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

• 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 }.

​

Déploiement

• 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.

• 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.

​

Choisir une adresse pour la passerelle

• 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.

​

Image de conteneur

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.

• Une image basée sur glibc : les seules dépendances dynamiques du build glibc sont les bibliothèques glibc. Les images basées sur Musl ont besoin du build linux-x64-musl ou linux-arm64-musl, dont la seule dépendance dynamique est musl.
• 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

• 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

​

Cloud Run

• 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

​

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

​

Déploiements à grande échelle

• 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 seule limite. La passerelle consigne un avertissement la première fois qu’elle ignore un en-tête X-Forwarded-For. Si l’équilibreur de charge a sa place dans listen.trusted_proxies, ajoutez-le à la liste avant de modifier quoi que ce soit d’autre. Si les développeurs partagent toujours une seule adresse, augmentez rate_limits.
• 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.

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

​

Opérations

​

Journaux

• É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
  • guardrail.trace enregistre quel filtre s’est déclenché, sans le texte correspondant
  • 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.

​

Écrire les journaux opérationnels au format JSON

{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

​

Santé

​

Demandes en amont concurrentes

• 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.

​

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

• 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.

​

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

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

​

Comportement en cas de panne

• 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.

​

Période de grâce de disponibilité

​

Rotation du secret JWT

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.

​

Postgres

• 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.

​

Dimensionner le pool de connexions

• 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.

• 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

• 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

• 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

​

Sécurité

​

Flux de données

​

Résumé du modèle de menace

• 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.

• 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

​

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

• 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é

​

Dépannage

• Problème de passerelle : la sortie stderr de la passerelle pour la période concernée, 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, ainsi que 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, puis envoie ce fichier ainsi que le log d’audit de la passerelle pour la même période
• Problème d’inférence : le modèle demandé, les upstreams configurés et le log d’audit de la passerelle pour la requête, qui indique quel upstream l’a servie et le statut de la réponse

​

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

• 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 des deux ne s’applique, ou l’erreur 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

• 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
• groups sur un upstream : détermine quels upstreams servent un développeur
• Plafonds de dépenses rbac_group : déterminent quels plafonds de groupe s’appliquent à un développeur

​

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

• 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 au bout d’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.

​

Confirmer la cause

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

​

Choisir une valeur

​

Fournir la valeur dans une politique

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

​

Longue réflexion sur un upstream Anthropic API

• 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 au bout d’environ 20 minutes avec les paramètres par défaut, et plus tard une fois la variable augmentée.
• 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.

​

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