Variables d'environnement Claude Code : documentation officielle

En bref

Définissez ANTHROPIC_API_KEY dans votre shell rc ou un fichier .env. Claude Code lit la variable au démarrage :

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Pour un proxy d'entreprise ou un autre modèle, utilisez ANTHROPIC_BASE_URL et ANTHROPIC_MODEL. Détails complets ci-dessous.

Variables d'environnement : principe et sources de lecture

Une variable d'environnement est une valeur nommée stockée dans votre session shell, accessible par n'importe quel programme qui s'y exécute. Imaginez des post-its collés à chaque processus : au démarrage, Claude Code les lit et adapte son comportement en conséquence.

Claude Code lit les variables d'environnement depuis quatre sources, dans cet ordre :

1. Environnement système (/etc/environment, /etc/profile.d/) — portée machine, défini par les administrateurs
2. Fichiers rc shell (~/.bashrc, ~/.zshrc, ~/.profile) — réglages persistants par utilisateur
3. Fichier .env dans le dossier du projet courant — surcharges par projet (chargé automatiquement)
4. Paramètre VS Code claudeCode.environmentVariables — injection depuis l'éditeur (voir section dédiée)

Les flags CLI et les clés équivalentes dans settings.json prennent le dessus sur les variables d'environnement quand un équivalent direct existe.

Variables d'authentification

ANTHROPIC_API_KEY

# Persistance dans le fichier rc de votre shell
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

# Surcharge ponctuelle pour une seule commande
ANTHROPIC_API_KEY="sk-ant-..." claude --print "bonjour"

# GitHub Actions : passer depuis un secret chiffré
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_AUTH_TOKEN="bearer-token-de-votre-proxy"

Certaines passerelles AI d'entreprise utilisent leur propre format de token. Utilisez cette variable quand votre proxy retourne 401 Unauthorized malgré une ANTHROPIC_API_KEY valide.

ANTHROPIC_BASE_URL

# Passerelle AI d'entreprise
export ANTHROPIC_BASE_URL="https://passerelle-ia.entreprise.com/anthropic"

# Serveur mock local pour les tests
export ANTHROPIC_BASE_URL="http://localhost:8080"

Cette variable écrase le champ customApiUrl de settings.json. Utile quand le trafic API passe par un proxy géré par l'entreprise ou un endpoint régional.

ANTHROPIC_MODEL / CLAUDE_MODEL

# Haiku pour la vitesse et l'économie
export CLAUDE_MODEL="claude-haiku-4-5"

# Opus pour les tâches de raisonnement complexe
export CLAUDE_MODEL="claude-opus-4-6"

# Surcharge ponctuelle sans toucher au fichier rc
CLAUDE_MODEL="claude-opus-4-6" claude --print "tâche difficile"

ANTHROPIC_MODEL est un alias accepté pour CLAUDE_MODEL. Les deux fonctionnent de façon identique. Utilisez CLAUDE_MODEL dans les nouvelles configurations pour rester cohérent avec la doc officielle.

Identifiants de modèles courants :

• claude-haiku-4-5 : Rapide et économique, bon pour l'automatisation
• claude-sonnet-4-6 : Équilibre recommandé entre capacités et coût
• claude-opus-4-6 : Raisonnement le plus profond, coût le plus élevé

CLAUDE_CODE_USE_BEDROCK

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
# Authentification via AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
# ou via rôle IAM sur EC2/ECS

Quand cette variable est définie, Claude Code utilise le SDK AWS pour s'authentifier. ANTHROPIC_API_KEY est ignorée ; les credentials AWS sont utilisés à la place.

CLAUDE_CODE_USE_VERTEX

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-central1"
export ANTHROPIC_VERTEX_PROJECT_ID="votre-projet-gcp"
# S'authentifier via gcloud application-default login

Variables de comportement

MAX_THINKING_TOKENS

# Réduire le budget pour diminuer les coûts sur les tâches courantes
export MAX_THINKING_TOKENS=10000

# Budget complet pour les sessions d'architecture ou de débogage complexe
export MAX_THINKING_TOKENS=31999

# Désactiver de fait le raisonnement profond (valeur minimale)
export MAX_THINKING_TOKENS=1000

Active uniquement quand alwaysThinkingEnabled: true dans settings.json, ou quand Extended Thinking est déclenché manuellement. Réduire cette valeur raccourcit la chaîne de pensée interne et diminue le coût en tokens associé.

BASH_MAX_OUTPUT_LENGTH

# Valeur par défaut, convient à la plupart des commandes
export BASH_MAX_OUTPUT_LENGTH=10000

# Augmenter pour les commandes à sortie volumineuse (logs de build, suites de tests)
export BASH_MAX_OUTPUT_LENGTH=50000

# Réduire pour protéger la fenêtre de contexte sur les modèles coûteux
export BASH_MAX_OUTPUT_LENGTH=5000

Quand une commande produit plus de caractères que cette limite, Claude Code tronque le résultat et ajoute une note. Cela évite qu'un simple cat fichier-volumineux.log ne sature toute la fenêtre de contexte.

BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS

export BASH_DEFAULT_TIMEOUT_MS=120000   # 2 min par défaut par commande
export BASH_MAX_TIMEOUT_MS=600000       # 10 min plafond (l'utilisateur ne peut pas dépasser)

Augmentez BASH_DEFAULT_TIMEOUT_MS pour les builds lents ou les longues suites de tests. BASH_MAX_TIMEOUT_MS est le plafond que l'utilisateur ne peut pas dépasser en overridant le timeout manuellement dans la conversation.

CLAUDE_CODE_MAX_OUTPUT_TOKENS

# Plafonner les réponses pour contrôler les coûts en automatisation
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

# Autoriser de longues réponses pour la génération de code
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

DISABLE_AUTOUPDATER

export DISABLE_AUTOUPDATER=1

À toujours définir en CI/CD. Une mise à jour automatique pendant un pipeline peut changer le comportement de façon inattendue. Combinez avec une installation en version fixe : npm install -g @anthropic-ai/claude-code@x.y.z.

DISABLE_TELEMETRY

export DISABLE_TELEMETRY=1

DISABLE_ERROR_REPORTING

export DISABLE_ERROR_REPORTING=1

DISABLE_COST_WARNINGS

export DISABLE_COST_WARNINGS=1

Pratique dans les scripts non-interactifs où la bannière polluerait le parsing de stdout.

CLAUDE_CONFIG_DIR

# Configuration isolée par projet
export CLAUDE_CONFIG_DIR="$(pwd)/.claude-config"

# Config partagée sur un agent CI
export CLAUDE_CONFIG_DIR="/opt/claude-code/config"

# Config éphémère pour les conteneurs jetables
export CLAUDE_CONFIG_DIR="/tmp/claude-ci-$$"

CLAUDE_CODE_DISABLE_TERMINAL_TITLE

export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1

Utile pour les utilisateurs de tmux et les multiplexeurs de terminal qui exploitent la chaîne de titre pour le suivi des volets.

Variables réseau et proxy

HTTP_PROXY / HTTPS_PROXY

# Proxy sans authentification
export HTTP_PROXY="http://proxy.entreprise.com:8080"
export HTTPS_PROXY="http://proxy.entreprise.com:8080"

# Proxy avec authentification (encoder les caractères spéciaux du mot de passe en URL)
export HTTPS_PROXY="http://jdoe:m%40tdepasse@proxy.entreprise.com:8080"

# Proxy SOCKS5
export HTTPS_PROXY="socks5://proxy.entreprise.com:1080"

Dans les réseaux d'entreprise, ce sont les variables les plus fréquemment à configurer. Claude Code les utilise pour toutes les requêtes sortantes, y compris les appels API vers api.anthropic.com.

NO_PROXY

export NO_PROXY="localhost,127.0.0.1,::1,*.corp.exemple.com"

# Combiner avec HTTPS_PROXY
export HTTPS_PROXY="http://proxy.entreprise.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.intranet.entreprise.com"

Variables MCP

MCP_TIMEOUT / MCP_TOOL_TIMEOUT

export MCP_TIMEOUT=30000         # 30 s pour les serveurs MCP lents au démarrage
export MCP_TOOL_TIMEOUT=120000   # 2 min pour les appels d'outils longue durée

MAX_MCP_OUTPUT_TOKENS

export MAX_MCP_OUTPUT_TOKENS=50000

claudeCode.environmentVariables dans VS Code

L'extension officielle Claude Code pour VS Code expose le paramètre claudeCode.environmentVariables, un objet JSON injecté dans chaque processus Claude Code lancé depuis l'éditeur. C'est la méthode la plus propre pour configurer des valeurs par workspace sans toucher aux fichiers shell globaux.

Ouvrez settings.json (niveau User ou Workspace) et ajoutez :

{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://passerelle-ia.entreprise.com/anthropic",
    "CLAUDE_MODEL": "claude-sonnet-4-6",
    "DISABLE_AUTOUPDATER": "1",
    "BASH_MAX_OUTPUT_LENGTH": "30000",
    "NO_PROXY": "localhost,127.0.0.1,*.intranet"
  }
}

Le nom du paramètre s'écrit en camelCase : claudeCode.environmentVariables. Les clés internes sont sensibles à la casse : ANTHROPIC_API_KEY n'est pas équivalent à anthropic_api_key.

Persister les variables selon les environnements

Fichiers rc shell (développement local)

# Ajouter dans ~/.bashrc ou ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-4-6"
export DISABLE_TELEMETRY=1

Exécutez source ~/.zshrc (ou ouvrez un nouveau terminal) après modification.

Service systemd utilisateur

Si vous exécutez Claude Code via un service systemd :

# ~/.config/systemd/user/claude-code.service
[Service]
Environment=ANTHROPIC_API_KEY=sk-ant-api03-...
Environment=CLAUDE_MODEL=claude-sonnet-4-6
Environment=DISABLE_AUTOUPDATER=1

Ou utilisez EnvironmentFile=/etc/claude-code/env pour charger depuis un fichier séparé et ne pas stocker de secrets dans l'unité de service.

Docker

# Passer au build (config non-secrète uniquement)
ARG CLAUDE_MODEL=claude-sonnet-4-6
ENV CLAUDE_MODEL=$CLAUDE_MODEL
ENV DISABLE_AUTOUPDATER=1
ENV BASH_MAX_OUTPUT_LENGTH=30000

# Passer les secrets au runtime — ne jamais les intégrer dans l'image
docker run \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e CLAUDE_MODEL=claude-haiku-4-5 \
  mon-image-claude

Gestionnaires de secrets

Pour les pipelines de production, évitez de stocker les clés API brutes dans les fichiers shell. Récupérez-les au runtime :

# AWS Secrets Manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id prod/anthropic-api-key \
  --query SecretString \
  --output text)

# HashiCorp Vault
export ANTHROPIC_API_KEY=$(vault kv get -field=value secret/anthropic)

Sécurité

• Ajoutez .env à .gitignore et à votre .gitignore_global pour prévenir les commits accidentels.
• Ne hardcodez jamais ANTHROPIC_API_KEY dans un Dockerfile, un fichier YAML de CI ou tout fichier versionné.
• Utilisez les secrets de dépôt (GitHub Secrets, variables GitLab CI) pour les pipelines CI/CD.
• Faites tourner votre clé API tous les 90 jours au minimum. Rotation immédiate si une exposition est suspectée.
• Auditez qui a accès en lecture aux fichiers contenant la clé (~/.bashrc, /etc/environment).

# Entrées .gitignore minimales
.env
.env.local
.env.*.local
*.key

Ordre de priorité

Quand le même réglage est présent dans plusieurs sources, Claude Code les résout dans cet ordre. Les sources plus tardives gagnent :

Les flags CLI gagnent toujours. Les valeurs settings.json prennent le dessus sur les variables d'environnement quand une clé équivalente directe existe.

Dépannage

Vérifier quelles variables sont visibles par Claude Code

# Lister toutes les variables contenant "claude" ou "anthropic" (insensible à la casse)
env | grep -iE "claude|anthropic|proxy"

# Vérifier le format de la clé (doit commencer par sk-ant-)
echo $ANTHROPIC_API_KEY | cut -c1-12

Confirmer qu'une variable est définie dans un nouveau shell

# Ouvrir un nouveau shell et tester
bash -c 'echo $ANTHROPIC_API_KEY'

Si le résultat est vide alors que votre session courante a la valeur, l'export est absent de votre fichier rc (la variable peut être définie sans export).

Déboguer les problèmes au démarrage

# Affichage de la version (confirme que l'installation est fonctionnelle)
claude --version

# Tester que la clé API atteint Anthropic
claude --print "bonjour" 2>&1 | head -20

Variable définie mais ignorée

Causes possibles :

• La variable est définie mais non exportée (VAR=valeur au lieu de export VAR=valeur)
• Une clé settings.json de priorité plus haute la surcharge
• Une faute de frappe dans le nom de la variable (utilisez env | grep pour vérifier)
• Dans VS Code, le settings.json Workspace surcharge le settings.json User avec une valeur conflictuelle

# Vérifier que la variable est exportée, pas seulement définie
export -p | grep ANTHROPIC

ANTHROPIC_BASE_URL est ignoré

Vérifiez que HTTPS_PROXY n'intercepte pas et ne reroutte pas la requête. Ajoutez le nom d'hôte de la base URL à NO_PROXY :

export ANTHROPIC_BASE_URL="https://passerelle-ia.entreprise.com/anthropic"
export HTTPS_PROXY="http://proxy.entreprise.com:8080"
export NO_PROXY="passerelle-ia.entreprise.com,localhost,127.0.0.1"

Tableau de référence complet

*Sauf si authentifié via claude login (compte Claude.ai Max)

Exemples de configuration

Développement local

# ~/.zshrc ou ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-4-6"
export MAX_THINKING_TOKENS=10000
export DISABLE_TELEMETRY=1

CI/CD (GitHub Actions)

# .github/workflows/claude.yml
jobs:
  claude-task:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      CLAUDE_MODEL: claude-haiku-4-5
      DISABLE_AUTOUPDATER: "1"
      DISABLE_COST_WARNINGS: "1"
      CLAUDE_CODE_MAX_OUTPUT_TOKENS: "4096"
      BASH_MAX_OUTPUT_LENGTH: "20000"
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code@latest
      - run: claude --print --max-turns 5 "Vérifie la qualité du code"

Réseau d'entreprise avec proxy

# /etc/environment ou profil système
ANTHROPIC_API_KEY="sk-ant-..."
ANTHROPIC_BASE_URL="https://passerelle-ia.entreprise.com"
HTTPS_PROXY="http://proxy-web.entreprise.com:8080"
NO_PROXY="localhost,127.0.0.1,passerelle-ia.entreprise.com,*.interne.entreprise.com"
DISABLE_AUTOUPDATER=1
CLAUDE_CONFIG_DIR="/opt/claude-code/config"

FAQ

Prochaines étapes

• settings.json : guide complet : Toutes les clés de configuration et leur priorité sur les variables d'environnement
• CLI : référence complète : Tous les flags de la commande claude
• Cheatsheet : Référence rapide des commandes slash et raccourcis clavier