Clé API Claude Code — où en obtenir une, où la placer et pourquoi la mauvaise variable échoue silencieusement

Claude Code peut s'authentifier de deux façons différentes, et celle dont vous avez besoin détermine tout le reste. Une connexion d'abonnement claude.ai couvre l'utilisation dans votre forfait Pro ou Max. Une clé API est facturée au token, sans limites de forfait. Ce guide explique où obtenir une clé, où la placer précisément, les deux variables d'identification et pourquoi choisir la mauvaise entraîne un échec silencieux, ainsi que la manière de maîtriser la facture une fois que tout fonctionne.

Avez-vous réellement besoin d'une clé ?

À savoir avant de commencer : définir une clé met en pause votre abonnement. Tant qu'une variable d'identification est active, Claude Code l'utilise à la place de la connexion claude.ai enregistrée, les limites du forfait cessent de s'appliquer et l'utilisation est facturée au propriétaire de la clé. Supprimez-la et Claude Code revient à l'abonnement.

Option 1 — une clé Anthropic propriétaire

1. Connectez-vous à console.anthropic.com (un compte distinct de claude.ai).
2. Ajoutez du crédit dans Billing. L'API est prépayée et distincte de tout abonnement — un forfait Pro ne la finance pas.
3. Créez une clé dans API Keys. Elle commence par sk-ant- et n'est affichée qu'une seule fois.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Notez la deuxième étape de cet extrait. ANTHROPIC_API_KEY est envoyé dans l'en-tête x-api-key et nécessite une approbation interactive ponctuelle avant que Claude Code ne l'utilise. Si cette invite a déjà été refusée, la clé est ensuite ignorée sans aucune invite — ce qui donne exactement l'impression que la variable n'est pas lue. Réactivez-la sous /config → Use custom API key.

Option 2 — une clé moins chère par token

Claude Code lit ANTHROPIC_BASE_URL nativement ; il fonctionne donc avec tout endpoint proposant l'Anthropic Messages API — sans plugin, proxy ni binaire modifié. C'est la méthode prise en charge pour les passerelles et elle permet d'exécuter les mêmes modèles Claude à un tarif inférieur :

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL est uniquement l’origine — Claude Code ajoute lui-même /v1/messages. Conservez les lignes de modèle : la valeur par défaut intégrée de Claude Code et son alias opus pointent tous deux vers le dernier Opus, et si Kunavo ne sert pas encore ce modèle, la première requête renvoie 404. La ligne opus le fixe à Claude Opus 5.5, ce qui nécessite Claude Code v2.1.280 ou une version ultérieure (exécutez claude update avec une version plus ancienne). L’alias sonnet demande Sonnet 5.5, que Kunavo ne sert pas ; sans ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution de opusplan et les sous-agents configurés sur sonnet renvoient tous 404. Créez la clé sk-kn- dans le tableau de bord après vous être inscrit et avoir rechargé $10. Il n’y a pas de frais mensuels et le solde n’expire pas.

Cela représente environ 30% de moins que le tarif officiel pour le modèle principal. Les tarifs complets figurent dans le guide de tarification de l'API Claude, et la tarification de Claude Code compare cette méthode aux frais des forfaits Pro et Max ; la configuration complète, notamment le routage des modèles par tâche et les changements induits par une passerelle, se trouve dans le guide du routeur Claude Code. Si la CLI n'est pas encore installée, commencez par installer Claude Code.

Où va réellement la clé

Deux variables, deux en-têtes HTTP différents. Une clé placée dans l'en-tête que le serveur ne lit pas échoue avec 401 :

Si vous ne savez pas de quel type est votre clé, commencez par ANTHROPIC_AUTH_TOKEN, qui ne nécessite aucune approbation. Sur Kunavo, l'une ou l'autre variable permet également à Claude Code de découvrir la liste des modèles, car /v1/models lit la clé dans l'un ou l'autre en-tête.

Export shell ou fichier de paramètres

Un export shell s'applique uniquement à ce terminal et à ses processus enfants. Un éditeur lancé depuis le dock ne le verra pas, pas plus que les agents en arrière-plan. Pour tout réglage permanent, utilisez plutôt le bloc env de ~/.claude/settings.json — mêmes clés, appliquées partout où Claude Code s'exécute. Ne placez pas de clé dans le .claude/settings.json d'un projet ; ce fichier est versionné et partagé avec toute personne qui clone le dépôt.

Exécutez /status pour confirmer quel identifiant est actif. Une ligne Auth token ou API key mentionnant votre variable signifie que la clé est active ; une ligne Login method mentionnant un compte claude.ai signifie qu'elle ne l'est pas.

Renouveler les clés sans modifier les fichiers

Si l'identifiant expire selon un calendrier ou provient d'un coffre-fort, faites pointer apiKeyHelper vers une commande qui affiche la clé actuelle :

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Référencez-la en tant que "apiKeyHelper": "~/bin/get-key.sh" dans votre fichier de paramètres. Claude Code met la sortie en cache pendant cinq minutes et réexécute la commande lors d'un 401 ; ajustez ce comportement avec CLAUDE_CODE_API_KEY_HELPER_TTL_MS. La valeur est envoyée dans les deux en-têtes et fonctionne donc dans les deux cas.

Garder une facture prévisible

La programmation agentique consomme beaucoup de tokens — à chaque étape, le prompt système, l'historique de la tâche et le nouveau contexte des fichiers sont renvoyés. Quatre éléments comptent plus que tout le reste :

1. Dirigez le travail en arrière-plan vers Haiku. ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 couvre les résumés et les titres que Claude Code génère lui-même. C'est une seule ligne et une économie pure — particulièrement importante lorsque le travail se ramifie, ce qui est tarifé dans ce que coûte un workflow Claude Code.
2. Les mêmes deux variables routent l'Agent SDK. Il ne possède pas sa propre option d'URL de base — il lance cette CLI et transmet directement votre environnement ; un programme Agent SDK est donc routé exactement par la configuration ci-dessus.
3. Commencez de nouvelles tâches au lieu de prolonger indéfiniment la même. Le contexte est renvoyé à chaque étape, donc une longue session coûte de manière quadratique. Le choix du niveau à utiliser pour le modèle principal est traité dans Opus contre Sonnet contre Haiku, en termes de coût par tâche terminée plutôt que de coût par token.
4. Laissez la mise en cache des prompts fonctionner. Les entrées mises en cache sont facturées à 10 % du tarif d'entrée, et la route native de l'API Messages transmet cache_control sans traduction (détails).
5. Donnez à l'éditeur sa propre clé avec une limite de dépenses dans le tableau de bord, puis vérifiez l'utilisation après une semaine. Les limites par clé transforment une boucle incontrôlable en boucle plafonnée.

Dépannage

Questions fréquentes