Déployer une passerelle LLM pour votre organisation

​

Prérequis

• Une passerelle déployée sur votre infrastructure, servant HTTPS à l’adresse exacte que vous distribuerez aux développeurs, pas une adresse qui redirige vers elle, et configurée pour router les noms de modèles Claude vers votre fournisseur
• Une identifiant de fournisseur pour que la passerelle le transfère avec :
  • Pour l’API Anthropic : une clé API de la Console Claude
  • Pour un fournisseur cloud : des identifiants cloud avec accès aux modèles. Consultez les prérequis sur la page Amazon Bedrock, Google Cloud’s Agent Platform, ou Microsoft Foundry
• Un moyen de livrer des fichiers de paramètres aux machines des développeurs, comme MDM ou gestion de configuration
  • Si vous n’en avez pas encore, comment les paramètres atteignent les appareils compare les options

​

Exigences de la passerelle

• Accepter un format API pris en charge : l’un des formats du tableau des formats API. Les étapes de déploiement ci-dessous supposent l’API Messages Anthropic à POST /v1/messages, que la plupart des passerelles servent
• Diffuser les réponses : transmettre les événements envoyés par le serveur au fur et à mesure qu’ils arrivent, y compris les pings de maintien de connexion, au lieu de mettre en mémoire tampon la réponse entière ; la section streaming couvre ce que la mise en mémoire tampon ou les pings supprimés cassent
• Router les noms de modèles Claude : mapper chaque nom que les développeurs utilisent à un modèle en amont. Claude Code envoie un nom de modèle tel que claude-sonnet-4-6 dans chaque requête ; dans la plupart des produits de passerelle, le mappage est une liste de modèles ou une table de routage dans la propre configuration de la passerelle
• Transférer les en-têtes et le corps inchangés : transmettre anthropic-beta, anthropic-version, et le corps de la requête dans les deux sens ; le tableau de passage des fonctionnalités mappe chacun à la fonctionnalité qui se casse sans lui
• Retourner les erreurs en amont non modifiées : la récupération automatique de Claude Code correspond au libellé de l’erreur, donc envelopper les erreurs dans l’enveloppe propre de la passerelle la casse, sauf si l’enveloppe du message porte l’un des jetons capability_rejected: qu’une passerelle d’applications Claude substitue au libellé d’erreur des fournisseurs cloud
• Exempter le chemin de l’inspection WAF du corps de la requête : les invites Claude Code contiennent du code source et des balises de style XML qui correspondent aux règles du corps de cross-site-scripting ; un WAF devant la passerelle retourne 403 sur les vraies sessions tandis que les courtes demandes de test passent

​

Étapes du déploiement

1. Confirmer que la passerelle achemine vos modèles
2. Émettre une credential pour chaque développeur
3. Tester Claude Code par rapport à la passerelle
4. Distribuer l’URL de base et les credentials
5. Vérifier à partir d’une machine développeur

​

Confirmer que la passerelle achemine vos modèles

• <gateway-key> est la credential qui vous permet d’appeler la passerelle en ce moment : une clé administrative, une clé de test, ou votre propre clé développeur si vous en avez déjà émis une. Tous les produits de passerelle n’ont pas une credential d’administration séparée ; si le vôtre n’en a pas, émettez-vous d’abord une clé développeur dans Émettre une credential pour chaque développeur
• model est un nom de modèle Claude que votre passerelle est configurée pour acheminer. L’exemple utilise claude-sonnet-4-6 ; remplacez par un nom que vous avez configuré

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

​

Émettre une credential pour chaque développeur

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

​

Tester Claude Code par rapport à la passerelle

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

claude -p "Reply with one word: connected"

• Not logged in : vérifiez le journal de la passerelle pour distinguer les deux causes. S’il est vide, aucune credential n’a atteint la session et aucune demande n’a quitté la machine ; réexécutez les exports dans le shell que vous testez. S’il affiche une demande rejetée avec x-api-key dans le corps 401, la passerelle s’attend à des clés dans cet en-tête à la place ; basculez vers ANTHROPIC_API_KEY
• Failed to authenticate. API Error: 401 signifie qu’une credential a été envoyée et rejetée, et le journal de la passerelle dit où : un 401 nommant api.anthropic.com ou le point de terminaison de votre fournisseur signifie que la passerelle a atteint l’amont mais sa credential du fournisseur a été rejetée, donc la clé développeur a fonctionné et la credential du fournisseur que la passerelle détient est incorrecte ou un placeholder

​

Distribuer la configuration

​

Ce qu’il faut distribuer

​

Distribuer par le biais des paramètres gérés

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

• L’application de bureau lit l’acheminement de la passerelle à partir de sa configuration d’inférence tierce, pas à partir des paramètres gérés ; déployez ce fichier par le biais de MDM aux côtés des paramètres gérés afin que les sessions de bureau acheminent également par la passerelle. Voir la documentation de configuration tierce du bureau et la documentation de passerelle du bureau
• Les exécuteurs CI ont besoin de ANTHROPIC_BASE_URL et de la credential définis dans l’environnement de l’exécuteur
• WSL sur les machines Windows gérées lit les paramètres gérés Windows uniquement quand wslInheritsWindowsSettings est true

​

Donner aux développeurs les valeurs à définir eux-mêmes

• L’URL de la passerelle
• Leur credential personnelle
• Quelle variable mettre la credential dans : ANTHROPIC_AUTH_TOKEN pour une passerelle de jeton porteur, ou ANTHROPIC_API_KEY pour une passerelle x-api-key. Dire aux développeurs laquelle leur épargne l’essai-erreur décrit sur la page de connexion
• Toutes les variables conditionnelles du tableau Ce qu’il faut distribuer, avec leurs valeurs

​

Vérifier le déploiement

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
  -H "Authorization: Bearer <developer-key>" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  --data-binary '@-'

• Une invite de connexion signifie une lacune de credential. Exécutez /status et ouvrez l’onglet Status : quand la ligne Setting sources n’inclut pas les paramètres gérés, la distribution n’a pas atteint la machine ; quand elle le fait, la credential développeur n’a pas été livrée, donc définissez ANTHROPIC_AUTH_TOKEN ou le apiKeyHelper
• Les erreurs Failed to authenticate signifient que la passerelle rejette les demandes ; son journal dit quelle credential a échoué. Un rejet que la passerelle enregistre elle-même nomme la clé développeur, tandis qu’un 401 de api.anthropic.com ou du point de terminaison de votre fournisseur signifie que la credential du fournisseur que la passerelle détient a été rejetée
• Une invite d’approbation unique pour la clé est attendue à la première utilisation quand la passerelle s’attend à des clés dans l’en-tête x-api-key, défini comme ANTHROPIC_API_KEY. Avec ANTHROPIC_AUTH_TOKEN, aucune invite n’apparaît et la variable prend le relais silencieusement ; une connexion claude.ai précédemment enregistrée est inactive pour cette session

​

Maintenir la passerelle

​

Planifier les mises à niveau de version de Claude Code

​

Ressources connexes

• Connecter Claude Code à une passerelle LLM : les étapes de configuration côté développeur, avec la configuration par surface et un tableau de dépannage que vous pouvez remettre aux développeurs
• Guide de compatibilité de la passerelle : la référence pour les opérateurs de passerelle, couvrant les points de terminaison, les en-têtes à transférer, et le tableau de passage des fonctionnalités
• Quelle valeur Claude Code utilise : comment les paramètres gérés, de projet et utilisateur se combinent
• Mécanismes de livraison : où le fichier géré va sur chaque plateforme
• Configurer Claude Code pour votre organisation : le déploiement plus large dont cette passerelle est une partie, y compris l’application des politiques, la visibilité de l’utilisation, et la gestion des données