Variables d'environnement de Claude Code

Les variables d'environnement sont un moyen important de contrôler le comportement de Claude Code, permettant d'ajuster de manière flexible divers paramètres sans modifier les fichiers de configuration. Ce chapitre détaille toutes les variables d'environnement prises en charge par Claude Code, leurs objectifs, leurs méthodes de configuration et les scénarios d'utilisation courants.


Aperçu des variables d'environnement

Claude Code utilise des variables d'environnement pour contrôler son comportement. Ces variables peuvent être définies des manières suivantes :

  • Directement dans le shellexport
  • Dans~/.claude/settings.jsondeenvConfigurer dans le champ
  • Au niveau du projet.claude/settings.jsonConfigurer dans
  • Configurer via l'interface de paramètres du plugin IDE

Priorité des variables d'environnement, de la plus élevée à la plus faible : ligne de commande > settings.json au niveau du projet > settings.json au niveau de l'utilisateur > variables d'environnement du shell. Les variables configurées dans settings.json sont automatiquement transmises au processus Claude.


Variables liées à l'authentification

Nom de la variable Description Valeur
ANTHROPIC_API_KEY Clé API Claude (obtenue depuis claude.ai) Chaîne de clé API
ANTHROPIC_BASE_URL Adresse cible pour les requêtes API (utilisée pour un proxy ou des points de terminaison personnalisés) Adresse URL
ANTHROPIC_AUTH_TOKEN Jeton d'authentification (utilisé pour des scénarios tels que le plugin VS Code) Chaîne de jeton

Exemples de configuration

Exemple

# Définir dans le shell
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Exemple

// Configurer dans settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://custom-proxy.com/v1"
  }
}

Variables de configuration du modèle

Nom de la variable Description Valeur
ANTHROPIC_MODEL Modèle par défaut utilisé claude-opus-4-5、claude-sonnet-4-5、claude-haiku-3-5wait
ANTHROPIC_SMALL_FAST_MODEL Modèle utilisé en mode de réponse rapide (pour les tâches simples) Nom du modèle
CLAUDE_CODE_SUBAGENT_MODEL Définir uniformément le modèle utilisé par tous les sous-agents Nom du modèle
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Désactiver les fonctionnalités expérimentales lors de l'utilisation du format Anthropic Messages avec Bedrock ou Vertex 1

Scénarios d'utilisation

Les sous-agents héritent par défaut du modèle de la conversation principale. Grâce àCLAUDE_CODE_SUBAGENT_MODELvous pouvez les configurer uniformément, en assignant les tâches simples à Haiku et les analyses complexes à Sonnet pour optimiser les coûts :

Exemple

# La conversation principale utilise Opus pour le raisonnement complexe, les sous-agents utilisent uniformément Sonnet
export ANTHROPIC_MODEL="claude-opus-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

Variables d'outils et de commandes

Nom de la variable Description Valeur
CLAUDE_CODE_DISABLE_SLASH_COMMANDS Désactiver toutes les commandes slash 1
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS Désactiver les prompts système intégrés liés à Git (priorité supérieure à celle dans settings.jsonincludeGitInstructions) 1
CLAUDE_CODE_USE_POWERSHELL_TOOL Activer les outils PowerShell sur Windows (nécessitedefaultShell: "powershell"par défaut) 1
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL Ignorer l'installation automatique de l'extension IDE (alternativeautoInstallIdeExtensionpar défaut) 1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Désactiver la fonctionnalité des tâches en arrière-plan 1

Variables de permissions et de sécurité

Nom de la variable Description Valeur
CLAUDE_CODE_PERMISSION_MODE Définir le mode d'autorisation par défaut (voir la section sous-agent pour plus de détails) default、acceptEdits、dontAsk、bypassPermissions、plan
CLAUDE_CODE_ALLOWED_TOOLS Liste blanche des outils que Claude est autorisé à utiliser (séparés par des virgules) Liste d'outils
CLAUDE_CODE_DISALLOWED_TOOLS Liste noire des outils interdits à Claude Liste d'outils

Modes de permission expliqués

  • default: Invite de permission normale, demander avant chaque opération
  • acceptEdits: Accepter automatiquement les modifications de fichiers sans confirmation
  • dontAsk: Rejeter automatiquement les opérations non autorisées sans interrompre l'exécution
  • bypassPermissions: Ignorer toutes les vérifications de permission (uniquement pour les environnements entièrement fiables)
  • plan: Mode de planification en lecture seule, aucune opération d'écriture

Exemple

# Utiliser le mode lecture seule dans l'environnement CI
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Variables de journalisation et de débogage

Nom de la variable Description Valeur
CLAUDE_CODE_DEBUG Activer la sortie de débogage 1
CLAUDE_CODE_ENABLE_TELEMETRY Activer la collecte de données de télémétrie 1
OTEL_METRICS_EXPORTER Exportateur de métriques OpenTelemetry otlpwait

Variables de session et d'historique

Nom de la variable Description Valeur
CLAUDE_CODE_DISABLE_HISTORY Désactiver l'enregistrement de l'historique des conversations 1
CLAUDE_CODE_SESSION_TIMEOUT Délai d'expiration de session (secondes) Number
CLAUDE_CODE_MAX_SESSIONS Nombre maximal de sessions enregistrées Number

Variables liées à MCP

Lorsque Claude Code exécute des outils MCP, les variables d'environnement suivantes sont définies :

Nom de la variable Description Valeur
CLAUDE_CODE_MCP_SERVER_NAME Nom du serveur MCP String
CLAUDE_CODE_MCP_TOOL_NAME Nom de l'outil MCP appelé String
CLAUDE_CODE_MCP_TOOL_ARGS Paramètres transmis à l'outil MCP Chaîne JSON

Variables liées au workflow

Nom de la variable Description Valeur
CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS Cycle de nettoyage automatique des worktrees orphelins Jours
CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP Désactiver le nettoyage automatique des worktrees 1

Variables spécifiques à GitHub Actions

Nom de la variable Description Valeur
ANTHROPIC_VERTEX_PROJECT_ID ID de projet Vertex AI (défini par l’étape d’authentification lors de l’utilisation de Vertex) ID de projet GCP
CLOUD_ML_REGION Région Vertex AI Code de région (par ex.,us-east5)

Méthode de configuration settings.json

Toutes les variables d’environnement peuvent être configurées danssettings.json, ce qui est plus déclaratif et portable :

Exemple

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-3-5",
    "CLAUDE_CODE_PERMISSION_MODE": "plan",
    "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Glob,Bash",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

Configuration du plugin VS Code

Lorsque vous utilisez le plugin Claude Code dans VS Code, vous pouvez configurerenvironmentVariablesparamètres :

Exemple

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://custom-proxy.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "votre-jeton-ici"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "claude-sonnet-4-5"
    }
  ]
}

Scénarios d'utilisation courants

Scénario 1 : Utilisation d'un proxy ou d'un point de terminaison API personnalisé

Exemple

# Accéder à l'API Claude via un proxy interne d'entreprise
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="votre-clé-api"

Scénario 2 : Optimisation de la configuration des coûts

Exemple

# La conversation principale utilise Sonnet, les sous-agents utilisent uniformément Haiku
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-3-5"

Scénario 3 : Configuration de sécurité de l'environnement CI/CD

Exemple

# Utiliser le mode lecture seule dans l'environnement CI
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_DISABLE_HISTORY="1"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Scénario 4 : Environnement Windows PowerShell

Exemple

# Activer PowerShell sous Windows
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
# Définir defaultShell dans settings.json

Priorité et surcharge

Priorité des variables d'environnement (de la plus élevée à la plus faible) :

  1. Ligne de commandeexportParamètres
  2. Niveau projet.claude/settings.json
  3. Niveau utilisateur~/.claude/settings.json
  4. Valeurs par défaut de Claude Code

Danssettings.jsonLes variables configurées dans remplaceront les variables d'environnement du shell portant le même nom. Cela est dû au fait que settings.json est explicitement lu au démarrage du processus Claude Code, ce qui lui donne une priorité plus élevée.


Afficher la configuration actuelle

Utiliser/configLa commande peut afficher la configuration complète actuelle :

/config

Cela affichera tous les paramètres actuellement effectifs, y compris les variables d'environnement et les configurations dans settings.json.


Bonnes pratiques

1. Gestion des informations sensibles

  • Les informations sensibles telles que les clés API ne doivent pas être codées en dur dans settings.json
  • Utilisez des variables d'environnement ou des fichiers de configuration du shell (~/.bashrc、~/.zshrc)
  • Assurez-vous que les fichiers contenant des informations sensibles ne sont pas dans le contrôle de version git

2. Configurer par environnement

  • Développement local : utilisez un mode d'autorisation plus permissif
  • CI/CD : utilisez le mode lecture seuleplan
  • Débogage en production : activerCLAUDE_CODE_DEBUG

3. Gestion centralisée

  • La configuration commune va dans~/.claude/settings.json
  • La configuration spécifique au projet va dans le répertoire du projet.claude/settings.json
  • La configuration sensible est fournie via des variables d'environnement du shell ou des secrets CI

FAQ

Q : Qu'est-ce qui est prioritaire, les variables d'environnement ou settings.json ?

Les variables configurées dans settings.json ont une priorité plus élevée et remplaceront les variables d'environnement du shell portant le même nom.

Q : Comment faire en sorte que Claude Code utilise un point de terminaison d'API différent ?

SetANTHROPIC_BASE_URLla variable d'environnement pour pointer vers votre proxy ou votre point de terminaison personnalisé.

Q : Comment les sous-agents contrôlent-ils le modèle qu'ils utilisent ?

Vous pouvezCLAUDE_CODE_SUBAGENT_MODELdéfinir le modèle pour tous les sous-agents de manière uniforme, ou le spécifier individuellement dans le frontmatter de chaque sous-agent.

Q : Comment activer PowerShell sur Windows ?

Définir la variable d'environnementCLAUDE_CODE_USE_POWERSHELL_TOOL=1, et le définir également dans settings.jsondefaultShell: "powershell"。

Q : Comment désactiver toutes les commandes slash ?

SetCLAUDE_CODE_DISABLE_SLASH_COMMANDS=1la variable d'environnement.

Autres extensions