Claude Code est l'outil de programmation en ligne de commande lancé par Anthropic ; il se connecte par défaut à l'interface officielle d'Anthropic. En pratique, les équipes locales le pointent souvent vers une passerelle auto-hébergée ou tierce afin de résoudre des questions de stabilité d'accès, de facturation unifiée et de gestion des quotas. « Connecter une API personnalisée » revient essentiellement à modifier trois choses : où la requête est envoyée (Base URL), avec quelle identité elle est authentifiée (clé), et quel modèle est appelé (nom du modèle).

Cet article suit l'ordre installation, variables d'environnement, fichier de configuration, choix du modèle, vérification de la connexion, déploiement en équipe et sécurité, pour proposer un flux réutilisable. Les commandes concernent surtout macOS et Linux ; les différences Windows sont signalées séparément.

Note : Claude et Anthropic sont des marques de leurs titulaires respectifs. Cet article n'a qu'une visée d'explication technique et n'implique aucune affiliation avec les éditeurs concernés. Les versions de Claude Code évoluent vite : variables d'environnement, options de configuration et noms de menus peuvent changer. Référez-vous à claude --help, à la documentation officielle et aux instructions d'intégration du site.

1. Trois points à vérifier avant de commencer

Claude Code utilise le protocole Anthropic Messages, et non le protocole Chat Completions d'OpenAI. Une API personnalisée doit donc au minimum fournir un point d'entrée /v1/messages compatible Anthropic, avec des noms de modèles identiques à ceux réellement proposés par la passerelle. Une passerelle qui n'expose qu'une entrée compatible OpenAI ne peut pas être configurée directement dans Claude Code, sauf si elle propose aussi une route compatible Anthropic.

Préparez trois éléments :

  • Base URL : l'adresse racine de la passerelle, par exemple https://ai.zhongshangqihang.com. La présence de /v1 dépend de l'implémentation ; suivez les instructions d'intégration du site.
  • Clé API : créée dans la console, avec un plafond de quota et une date d'expiration. N'utilisez pas pour les tests une clé durable sans limite.
  • Nom du modèle : copié depuis la console ou la page des prix, jamais saisi de mémoire. Une erreur d'une lettre, de casse ou de tiret peut produire une erreur de modèle inexistant.

Si vous n'avez pas encore de compte, commencez par la page d'inscription et créez une clé de test à faible quota.

2. Installer Claude Code

Claude Code est généralement distribué via npm, avec d'autres modes d'installation possibles. Voici le flux le plus courant :

  1. Vérifiez que Node.js est installé. Privilégiez une version LTS encore maintenue ; la version minimale exacte figure dans la documentation officielle.
  2. Lancez npm install -g @anthropic-ai/claude-code pour une installation globale.
  3. Exécutez claude --version pour confirmer que la commande répond et notez le numéro de version.
  4. Placez-vous dans un répertoire de test, lancez claude et suivez les invites de première configuration (thème, confiance accordée au répertoire, etc.).
  5. Si l'équipe impose une gestion des versions, verrouillez la version et documentez-la ; validez toute mise à jour dans un projet de test avant généralisation.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

Avec une API personnalisée, il n'est généralement pas nécessaire de se connecter à un compte Anthropic, mais le fait de pouvoir ignorer la connexion dépend de la version et du mode de configuration. Si l'outil demande quand même une connexion au démarrage, vérifiez d'abord que les variables d'environnement sont actives dans le même shell que celui qui lance Claude Code.

3. Variables d'environnement : BASE_URL et AUTH_TOKEN

Claude Code lit deux variables d'authentification courantes :

  • ANTHROPIC_BASE_URL : l'adresse racine des requêtes.
  • ANTHROPIC_AUTH_TOKEN : envoyé sous la forme Authorization: Bearer, fréquent avec une passerelle.
  • ANTHROPIC_API_KEY : envoyé sous la forme x-api-key, proche de l'authentification native d'Anthropic.

Une seule des deux clés suffit. Si la passerelle authentifie en Bearer, utilisez ANTHROPIC_AUTH_TOKEN ; si elle authentifie en mode natif, utilisez ANTHROPIC_API_KEY. Lorsque les deux sont définies, la priorité peut varier selon la version, d'où des « 401 alors que tout semble correct » : ne conservez qu'une seule variable.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-votre-cle"
claude

Ajouter ces lignes à ~/.zshrc ou ~/.bashrc rend la configuration persistante ; après modification, exécutez source ~/.zshrc. Sous Windows PowerShell, utilisez $env:ANTHROPIC_BASE_URL="...", qui ne vaut que pour la fenêtre courante ; pour persister, passez par l'interface des variables système ou setx, puis rouvrez le terminal.

N'inscrivez pas les export dans un script de projet que vous validez ensuite. Une fois qu'une clé entre dans l'historique Git, supprimer le fichier ne supprime pas l'historique.

4. settings.json : figer la configuration dans un fichier

Les variables d'environnement conviennent aux bascules temporaires ; pour un usage durable, écrivez la configuration dans le fichier settings de Claude Code. Trois niveaux existent :

  • utilisateur : ~/.claude/settings.json, appliqué à tous les projets de la machine ;
  • projet : .claude/settings.json, versionnable dans le dépôt, adapté aux configurations non sensibles partagées par l'équipe ;
  • projet local : .claude/settings.local.json, non versionné, adapté aux surcharges personnelles.

Exemple :

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-votre-cle"
  },
  "model": "claude-sonnet-4-5"
}

Attention : la clé dans settings.json est en clair. Cela peut passer sur une machine personnelle, mais jamais sur une machine partagée, dans une CI ou dans un dépôt de code. Dans le fichier de projet, ne mettez que la Base URL et le nom du modèle ; confiez la clé aux variables d'environnement ou à un gestionnaire de secrets. L'ordre de priorité général est : configuration d'entreprise, arguments de ligne de commande, projet local, projet, utilisateur, chacun écrasant le précédent ; vérifiez la documentation de votre version.

5. Choisir le modèle : une gamme par usage

Les modèles Claude se répartissent généralement en trois gammes, adaptées à des tâches différentes :

Gamme Usages typiques Compromis
Opus Refactorisations complexes, analyse multi-fichiers, agents à long enchaînement Capacités supérieures, coût généralement plus élevé, vitesse parfois plus lente
Sonnet Codage quotidien, correction de bugs, revue de code Bon équilibre entre capacité et coût, adapté comme gamme par défaut
Haiku Complétion simple, formatage, petites tâches en lot Rapide et économique, mais limité sur les tâches complexes

Dans Claude Code, ANTHROPIC_MODEL désigne le modèle principal ; ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL et ANTHROPIC_DEFAULT_HAIKU_MODEL permettent de remplacer séparément le mapping de chaque gamme. Les variables prises en charge varient selon la version ; consultez claude --help ou la documentation officielle avant de configurer.

Le nom du modèle doit correspondre au catalogue de la passerelle. Celle-ci peut utiliser sa propre nomenclature pour les modèles en amont, et un nom copié de la documentation officielle ne correspondra pas forcément. Les modèles disponibles et leur facturation figurent dans les prix des modèles ; les prix évoluent avec les versions de modèles et les politiques des fournisseurs.

6. Vérifier la connexion : curl d'abord, Claude Code ensuite

Contournez d'abord Claude Code pour vérifier que la passerelle répond avec curl :

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Réponds seulement OK"}]
  }'

Si la passerelle utilise l'authentification Bearer, remplacez x-api-key par Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. Un code 200 avec un contenu normal indique qu'au moins une combinaison Base URL, clé et modèle fonctionne.

Revenez ensuite à Claude Code et vérifiez dans l'ordre :

  1. claude --version pour confirmer que le client s'exécute.
  2. claude doctor dans le répertoire du projet (si la version propose cette commande) pour contrôler l'installation et la configuration.
  3. Lancez claude et consultez /status pour voir le modèle et les informations de compte actuels.
  4. Demandez une tâche à faible risque, par exemple « explique la structure de ce répertoire sans modifier les fichiers ».
  5. Observez si la réponse arrive normalement et si des erreurs 401, 404 ou « modèle inexistant » apparaissent.

Tableau des symptômes courants :

Symptôme À vérifier en priorité Traitement
401 Clé, nom de variable, en-tête Recopier la clé ; ne garder qu'une variable d'authentification
404 /v1 en trop ou manquant dans la Base URL Suivre la documentation de la passerelle : adresse racine ou entrée compatible
model not found Nom du modèle différent du catalogue Copier depuis la console ou la page des prix
Délai d'attente dépassé Réseau, DNS, proxy Tester avec un autre réseau ; vérifier si le proxy réécrit les en-têtes
429 Limite de concurrence ou de quota Réduire la concurrence ; vérifier le quota de la clé

7. Déploiement en équipe : une clé par personne, une entrée commune

En équipe, mieux vaut éviter de partager une seule clé. L'approche la plus sûre :

  • une clé par personne, avec un nom incluant l'identité ou l'usage, désactivée dès le départ de la personne ;
  • des plafonds par projet ou environnement, avec séparation de la production et des tests ;
  • une passerelle commune pour consulter l'usage, la répartition des modèles et les appels anormaux ;
  • la diffusion de la Base URL et des modèles disponibles via la configuration d'entreprise, pour réduire les erreurs de saisie ;
  • un document d'intégration décrivant les commandes de vérification et les erreurs courantes ;
  • une revue hebdomadaire ou mensuelle de l'usage, avec traitement rapide des clés anormales.

Si l'entreprise dispose de processus d'achat et de conformité, vérifiez d'abord la circulation des données : des extraits de code sont envoyés à la passerelle puis au service de modèle en amont. La conservation, sa durée et l'éventuelle utilisation pour l'entraînement dépendent des conditions de service ; ne présumez rien.

8. Limites de sécurité : clés, code et données

Quelques règles de base :

  • aucune clé dans Git, les images de conteneur, le code frontend, les captures d'écran ou les historiques de discussion ;
  • ajoutez un .gitignore couvrant au minimum .env, .env.* et .claude/settings.local.json ;
  • en cas de doute sur une fuite, révoquez d'abord l'ancienne clé, puis analysez l'usage ; ne vous contentez pas de changer un mot de passe ;
  • fixez une date d'expiration aux clés et effectuez une rotation lors des changements de personnel ;
  • sur une machine partagée, utilisez un gestionnaire de secrets ou apiKeyHelper plutôt qu'une clé en clair dans settings.json ;
  • n'installez Claude Code que depuis une source fiable et lisez les notes de version avant de mettre à jour.

Questions fréquentes

Claude Code exige-t-il forcément un compte Anthropic ?

Pas forcément. Une fois une Base URL et une variable d'authentification valides configurées, le client peut utiliser directement une API personnalisée ; les écrans de première configuration (thème, confiance accordée au répertoire) peuvent toutefois apparaître. La nécessité de se connecter dépend de la version et de la configuration ; en cas de problème, vérifiez d'abord que les variables sont actives dans le shell de lancement.

Quelle différence entre ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN ?

La première est généralement envoyée dans l'en-tête x-api-key, la seconde dans Authorization: Bearer. Le choix dépend du mode d'authentification de la passerelle ; ne définissez qu'une seule variable pour éviter les conflits d'en-têtes.

Faut-il mettre l'adresse racine ou l'adresse avec /v1 dans la Base URL ?

Claude Code attend généralement l'adresse racine et ajoute lui-même /v1/messages ; certaines passerelles demandent directement l'entrée compatible. La méthode est simple : testez en curl l'adresse racine suivie de /v1/messages. Si cela répond, gardez l'adresse racine ; sinon, ajustez selon la documentation de la passerelle.

Pourquoi curl fonctionne-t-il alors que Claude Code renvoie une erreur ?

Les causes fréquentes sont des variables de shell non transmises à l'interface graphique ou au terminal intégré de l'IDE, ou deux variables d'authentification définies en même temps. Exécutez echo $ANTHROPIC_BASE_URL dans le même terminal que celui qui lance Claude Code.

Une équipe peut-elle partager une seule clé ?

Techniquement oui, mais ce n'est pas conseillé. Une clé partagée ne permet pas de distinguer l'usage de chacun et complique l'identification des responsabilités en cas de fuite. Une clé par personne, avec quotas et expiration, coûte moins cher à administrer.

Étape suivante

Si vous n'avez pas encore de compte de passerelle, commencez par la page d'inscription, créez une clé de test à faible quota, puis validez en deux étapes avec curl et Claude Code comme décrit ci-dessus. Les modèles et la facturation figurent dans les prix des modèles ; les prix évoluent et la page en temps réel fait foi.

Lectures associées :