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 shell
export - 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
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
Exemple
{
"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
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érationacceptEdits: Accepter automatiquement les modifications de fichiers sans confirmationdontAsk: Rejeter automatiquement les opérations non autorisées sans interrompre l'exécutionbypassPermissions: 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
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
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
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
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
$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) :
- Ligne de commande
exportParamètres - Niveau projet
.claude/settings.json - Niveau utilisateur
~/.claude/settings.json - Valeurs par défaut de Claude Code
Dans
settings.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 seule
plan - Débogage en production : activer
CLAUDE_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.