Guide complet des variables d’environnement Claude Code : résoudre l’erreur de compatibilité AWS Bedrock en un seul réglage

Note de l'auteur : Explication détaillée du rôle et de la configuration des plus de 60 variables d'environnement de Claude Code, avec un focus sur CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS pour résoudre les erreurs de header anthropic-beta sur les plateformes tierces.

Lors de l'utilisation de Claude Code pour se connecter à AWS Bedrock, Google Vertex AI ou d'autres passerelles de grands modèles de langage tiers, vous avez probablement rencontré cette erreur : "Unexpected value(s) for the anthropic-beta header". La racine de ce problème est que Claude Code envoie par défaut des en-têtes Beta expérimentaux spécifiques à l'API Anthropic, que les plateformes tierces comme AWS Bedrock ne reconnaissent pas.

La solution tient en une seule ligne de configuration : CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Cependant, les variables d'environnement de Claude Code ne se limitent pas à celle-ci — la documentation officielle répertorie plus de 60 variables d'environnement, couvrant la configuration de l'authentification, la sélection du modèle, l'optimisation des performances, les commutateurs de fonctions, etc. Cet article va structurer systématiquement ces variables pour vous aider à localiser et résoudre rapidement divers problèmes de configuration de Claude Code.

Valeur ajoutée : À la fin de cet article, vous maîtriserez l'écosystème complet des variables d'environnement de Claude Code, vous saurez résoudre rapidement les problèmes de compatibilité avec AWS Bedrock/Vertex AI, et vous apprendrez à optimiser votre expérience utilisateur et vos coûts via ces configurations.

Points clés des variables d'environnement de Claude Code

Les plus de 60 variables d'environnement de Claude Code peuvent être divisées en 6 grandes catégories. Voici les variables essentielles auxquelles vous devez prêter attention :

Deux façons de configurer les variables d'environnement de Claude Code

Méthode 1 : Variable d'environnement Shell (effet temporaire)

Définissez-la dans le terminal avant de lancer Claude Code, elle n'est valable que pour la session actuelle :

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="votre-cle-api"
claude

Méthode 2 : Configuration dans settings.json (effet permanent)

Configurez le champ env dans ~/.claude/settings.json, il sera chargé automatiquement à chaque démarrage :

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "votre-cle-api"
  }
}

🎯 Recommandation : Pour les paramètres devant être permanents (comme la clé API ou les correctifs de compatibilité plateforme), il est conseillé d'utiliser le fichier settings.json pour éviter de devoir faire un export manuel à chaque fois. Si votre clé API provient d'une plateforme tierce comme APIYI (apiyi.com), configurez-la également ici.

Décryptage des variables d'environnement Claude Code : Résoudre les problèmes de compatibilité AWS Bedrock

Focus sur CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

C'est la variable clé de cet article. Lorsque vous utilisez Claude Code via des passerelles tierces comme AWS Bedrock, Google Vertex AI ou LiteLLM, Claude Code ajoute automatiquement des identifiants Beta expérimentaux d'Anthropic dans les en-têtes de requête, par exemple :

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

Ces identifiants Beta sont des fonctionnalités spécifiques à l'API directe d'Anthropic. Les plateformes tierces comme AWS Bedrock ne les reconnaissent pas et renvoient donc une erreur :

Error: Unexpected value(s) for the anthropic-beta header

Solution :

# Option 1 : Commande Shell
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Option 2 : settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

En réglant cette valeur sur 1, Claude Code cessera d'envoyer ces en-têtes Beta expérimentaux, assurant ainsi la compatibilité avec toutes les plateformes tierces.

Problèmes connus et solutions temporaires

Selon les tickets GitHub, certaines versions de Claude Code (après la 2.1.18) présentent un problème où cette variable d'environnement n'est pas totalement prise en compte : même avec CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, certains nouveaux en-têtes Beta (comme advanced-tool-use-2025-11-20) continuent d'être envoyés.

Si vous rencontrez toujours des difficultés, vous pouvez essayer ces mesures complémentaires :

• Rétrograder la version de Claude Code : Revenez à une version stable connue comme la 2.1.68.
• Utiliser la passerelle LiteLLM : LiteLLM propose un fichier de configuration anthropic_beta_headers_config.json qui permet de contrôler précisément quels en-têtes Beta sont transmis.
• Activer simultanément DISABLE_PROMPT_CACHING : Désactiver la mise en cache des invites permet d'éviter les en-têtes Beta liés à prompt-caching-scope.

# Configuration de compatibilité totale
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Guide de référence des variables d'environnement Claude Code

Catégorie 1 : Authentification et configuration API

Il s'agit de la catégorie la plus fondamentale, contrôlant la manière dont Claude Code se connecte au service API :

🎯 Note pour les utilisateurs de plateformes tierces : Si vous utilisez une plateforme API tierce comme APIYI (apiyi.com), vous devez configurer simultanément ANTHROPIC_API_KEY et ANTHROPIC_BASE_URL. Claude Code utilisera prioritairement la clé API des variables d'environnement, même si vous êtes déjà connecté avec un compte Anthropic.

Catégorie 2 : Sélection et configuration du modèle

Contrôle quel modèle Claude Code utilise ainsi que ses paramètres de comportement :

Catégorie 3 : Compatibilité plateforme et passerelles

Ces variables sont dédiées à la résolution des problèmes de compatibilité entre Claude Code et les différentes plateformes cloud ou passerelles LLM :

Catégorie 4 : Interrupteurs de fonctionnalités

Désactivez des fonctions spécifiques via les préfixes DISABLE_ ou CLAUDE_CODE_DISABLE_ :

Catégorie 5 : Gestion du contexte et performance

Contrôle la gestion de la fenêtre de contexte et l'utilisation des ressources par Claude Code :

🎯 Conseil d'optimisation : Si vous remarquez que Claude Code compresse trop souvent le contexte lors de longues conversations, vous pouvez abaisser CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (par exemple à 50). Cela déclenchera la compression plus tôt et réduira potentiellement la perte d'informations. Ces configurations sont également supportées lors d'appels via APIYI (apiyi.com).

Prise en main rapide des variables d'environnement Claude Code

Exemple minimaliste : configurer Claude Code pour se connecter à une plateforme API tierce

# Lancer Claude Code après avoir configuré les variables d'environnement dans le terminal
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Conseil : Si vous ne voulez pas vous embêter avec les configurations complexes d'AWS Bedrock ou d'Azure, vous pouvez utiliser directement toute la gamme des modèles Claude via APIYI (apiyi.com). Il suffit de configurer deux variables, la clé API et l'URL de base, sans avoir à gérer l'authentification et les problèmes de compatibilité des plateformes cloud.

Questions fréquentes

Résumé

Points clés des variables d'environnement Claude Code :

1. Résoudre l'erreur AWS Bedrock : Définissez CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 pour désactiver les en-têtes Beta expérimentaux. Une seule ligne de configuration suffit pour corriger l'erreur « Unexpected value(s) for the anthropic-beta header ».
2. Plus de 60 variables réparties en 6 catégories : Configuration d'authentification, sélection du modèle, compatibilité plateforme, commutateurs de fonctionnalités, gestion du contexte et autres paramètres.
3. Deux méthodes de configuration : Export Shell (temporaire) et settings.json (permanent). Il est recommandé d'utiliser le fichier settings.json pour une configuration durable.
4. Solution simplifiée via plateforme tierce : En passant par une plateforme API unifiée comme APIYI (apiyi.com), il suffit de configurer deux variables, ANTHROPIC_API_KEY et ANTHROPIC_BASE_URL, sans avoir à gérer l'authentification complexe des plateformes cloud ou les problèmes de compatibilité des en-têtes Beta.

Nous vous recommandons d'utiliser APIYI (apiyi.com) pour tester rapidement Claude Code. La plateforme offre des crédits gratuits et une interface unifiée, vous évitant ainsi les nombreux pièges de configuration liés à AWS Bedrock ou Vertex AI.

📚 Ressources complémentaires

1. Documentation officielle Claude Code – Variables d'environnement : Liste complète et description des variables d'environnement.

   • Lien : code.claude.com/docs/en/env-vars
   • Description : La référence officielle pour l'ensemble des 60+ variables d'environnement.

2. Documentation officielle Claude Code – Paramètres : Portée de la configuration et spécifications du fichier settings.json.

   • Lien : code.claude.com/docs/en/settings
   • Description : Pour comprendre le système de configuration à quatre niveaux (Managed/User/Project/Local).

3. Documentation officielle Claude Code – Amazon Bedrock : Guide d'intégration AWS Bedrock.

   • Lien : code.claude.com/docs/en/amazon-bedrock
   • Description : Configurations spécifiques à Bedrock et résolution des problèmes courants.

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS ne s'applique pas totalement : Rapport de bug de la communauté.

   • Lien : github.com/anthropics/claude-code/issues/22893
   • Description : Pour connaître les limitations connues de cette variable d'environnement et les solutions temporaires.

5. LiteLLM – Gestion des en-têtes Beta Claude Code : Solution de filtrage des en-têtes Beta au niveau de la passerelle.

   • Lien : docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • Description : Contrôle précis des en-têtes Beta lors de l'utilisation de la passerelle LiteLLM.

Auteur : Équipe technique APIYI
Échanges techniques : N'hésitez pas à partager vos expériences de configuration de Claude Code dans la section commentaires. Pour plus de tutoriels, visitez notre centre de documentation sur APIYI (docs.apiyi.com).