Réglages de Claude Code : le manuel du settings.json
Chaque clé de settings.json qui compte : les quatre fichiers de configuration et leur priorité, modèle et effort, règles allow/deny des permissions, le bloc env, et un vrai flux de nettoyage de settings.local.json — vérifié contre la documentation officielle.
L'essentiel
- Quatre fichiers, une hiérarchie : managed-settings.json bat la ligne de commande, qui bat .claude/settings.local.json, qui bat .claude/settings.json, qui bat ~/.claude/settings.json. Les listes allow fusionnent entre fichiers au lieu de s'écraser.
- settings.json est du JSON strict : pas de commentaires, pas de virgules finales. Ajoutez la ligne "$schema": "https://json.schemastore.org/claude-code-settings.json" et votre éditeur autocomplétera chaque clé.
- Les règles deny gagnent toujours. Une règle deny à n'importe quel niveau prime sur toute règle allow — commencez avec Read(./.env) et Bash(git push:*) et vos secrets et votre dépôt distant sont protégés en deux lignes.
- settings.local.json est votre bac à sable réservé à la machine : il prime sur les réglages partagés du projet et part automatiquement au .gitignore — vos chemins personnels et vos expérimentations ne fuient jamais dans le dépôt.
Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)
Chaîne : Terminode AI2:31
Learning In Public: Cleaning Up Claude Code Settings
Chaîne : Ben Nadel5:26
Settings — official documentation
Documentation officielle : code.claude.com/docs
Settings reference — the full key table
Documentation officielle : code.claude.com/docs
Environment variables — official reference
Documentation officielle : code.claude.com/docs
Les faits de cette page sont vérifiés contre la documentation officielle des réglages ; les deux vidéos ci-dessus sont les sources visuelles et l'inspiration du flux d'audit.
Les captures d'écran sont attribuées à leurs créateurs, avec des liens profonds vers les horodatages exacts. Aucune image de visage filmé n'est utilisée.
Configurer le settings.json de Claude Code, étape par étape
Partie 1 — Cartographier la configuration
- 1
Connaître les quatre fichiers de réglages
Claude Code lit les réglages dans quatre périmètres : ~/.claude/settings.json (vous, tous les projets), .claude/settings.json (partagé avec l'équipe, à committer), .claude/settings.local.json (vous, ce projet seulement) et managed-settings.json (votre organisation). Tout ce qui vit dans ~/.claude — CLAUDE.md, projects, skills, agents, plugins — fait partie du même paysage.
La couche globale d'un coup d'œil : chaque fichier que Claude Code lit dans ~/.claude au démarrage d'une session.Voir à 2:28 - 2
Ouvrir ou créer ~/.claude/settings.json
Sur Mac et Linux, le fichier vit dans ~/.claude/settings.json ; sur Windows, dans %USERPROFILE%\.claude\settings.json. Créez-le s'il n'existe pas — Claude Code le prendra en compte à la prochaine session. Définissez CLAUDE_CONFIG_DIR si vous voulez tout le dossier de configuration ailleurs.
settings.json pilote thèmes, choix du modèle, plugins, variables d'environnement et permissions sur tous les projets de votre machine.Voir à 0:20 - 3
Figer votre modèle et votre niveau d'effort
Réglez "model" sur un modèle précis ou sur "opusplan" (Opus planifie, Sonnet exécute) : il devient le défaut de chaque nouvelle session — le même choix que fait /model en interactif. Associez-y "effortLevel" pour plafonner la réflexion par défaut de Claude, et modelSettings pour des surcharges par modèle.
- 4
Autoriser les commandes auxquelles vous faites confiance
Dans le bloc permissions, "allow" liste des règles d'outils qui sautent le prompt d'approbation : "Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)". Les règles sont des motifs par outil — le joker * exige une espace devant lui ("Bash(git push:*)") pour ne pas avaler des noms de commande plus longs.
Une vraie liste allow issue d'un settings.local.json : chaque entrée était un prompt d'approbation qui ne réapparaîtra plus.Voir à 0:50
Partie 2 — Permissions, env et surcharges
- 5
Protéger les secrets avec des règles deny
Les règles deny sont évaluées en premier et rien, à aucun niveau, ne peut les surcharger. Commencez par "Read(./.env)" et "Read(./.env.*)" pour que les clés d'API n'entrent jamais dans le contexte, plus "Bash(git push:*)" pour que publier vers le distant reste une décision humaine. Laissez ensuite les règles ask attraper la zone grise.
- 6
Garder les surcharges locales dans settings.local.json
Quand Claude Code enregistre une permission pour vous, elle atterrit dans .claude/settings.local.json — qu'il ajoute aussi automatiquement au .gitignore. Réservez ce fichier aux chemins personnels, aux flags d'expérimentation et à tout ce que vous ne voulez pas imposer à vos coéquipiers. Les règles partagées et délibérées vont dans .claude/settings.json.
- 7
Mettre secrets et interrupteurs dans le bloc env
L'objet "env" applique des variables d'environnement à chaque session : "ANTHROPIC_API_KEY", "DISABLE_TELEMETRY": "1", "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1", ou CLAUDE_CODE_MAX_OUTPUT_TOKENS. Une heuristique pratique de la doc : les clés EN_MAJUSCULES dans settings.json appartiennent presque toujours à env.
- 8
Ne pas confondre ~/.claude.json avec les réglages
~/.claude.json est de l'état, pas de la configuration : jetons OAuth, enregistrements de serveurs MCP, décisions de confiance par projet et interrupteurs globaux y vivent. Éditez settings.json pour l'intention ; laissez Claude Code gérer .claude.json tout seul — et sauvegardez les deux, car cleanupPeriodDays régit aussi la durée de survie de l'historique des transcriptions.
Dans ~/.claude : feature flags, plugins, instantanés de shell et le fichier d'état .claude.json, facile à confondre avec un fichier de réglages.Voir à 2:00
Partie 3 — Rester propre dans la durée
- 9
Savoir ce qui vit encore dans ~/.claude
CLAUDE.md est votre fichier d'instructions global, lu au début de chaque session. projects/ stocke l'historique de conversation et la mémoire automatique par dépôt, skills/ contient les flux SKILL.md à la demande, agents/ définit les sous-agents, plugins/ suit les plugins installés et statsig/ met les feature flags en cache. settings.json orchestre tout ce petit monde.
CLAUDE.md est le fichier voisin que l'on confond avec les réglages : il porte des préférences et des conventions, pas des clés de configuration.Voir à 0:45 - 10
Faire auditer votre liste allow par Claude
Les listes allow grossissent prompt après prompt jusqu'à ce que plus personne ne sache ce qu'elles contiennent. Ouvrez Claude Code et demandez-lui de passer en revue .claude/settings.local.json à la recherche d'entrées redondantes, inutiles et risquées — Claude sait quels outils sont intégrés et quelles règles se chevauchent.
Le prompt d'audit : relire la liste allow et signaler ce qui est redondant, ce qui double des outils intégrés, et ce qui est carrément risqué.Voir à 1:40 - 11
Lire le verdict comme un relecteur
Dans l'audit réel que cette page capture, Claude a trouvé 41 entrées et les a triées : ls, grep, find, echo et cd doublonnent des outils intégrés ; les entrées en joker couvraient déjà des commandes explicites ; les chemins absolus locaux étaient inutiles parce que Claude connaît son répertoire de travail ; curl est la seule signalée comme réellement trop permissive.
Le verdict : 41 entrées triées en inutiles, redondantes et risquées — avec le remplacement pour chaque ligne.Voir à 3:05 - 12
Appliquer le nettoyage et revérifier chaque mois
Approuvez les modifications proposées et le fichier passe de 41 entrées à 15. Prenez-en l'habitude : une liste allow que plus personne ne peut lire est une surface d'attaque que plus personne ne voit. Relancez l'audit après les gros projets, et préférez des règles ciblées comme Bash(git diff:*) aux validations en bloc.
Le nettoyage appliqué : curl, chemins home explicites et scripts shell à usage unique retirés de la liste allow.Voir à 4:50
settings.json vs CLAUDE.md vs ~/.claude.json vs /config
Quatre surfaces donnent toutes l'impression d'être « les réglages de Claude Code » — elles ne sont pas interchangeables. Quel fichier possède quoi :
- 1settings.json (tous les périmètres) — configuration déclarative : model, effort, permissions, env, hooks, statusLine, plugins. JSON strict, validé par schéma, committable sans risque (sauf la version .local).
- 2CLAUDE.md — instructions et conventions en langage naturel. Elle façonne le comportement, pas la configuration ; aucun contrat clé-valeur, et elle est lue à chaque session.
- 3~/.claude.json — l'état machine : données OAuth/session, enregistrements MCP, confiance par projet, flags d'onboarding. Claude Code l'écrit ; ne l'éditez pas à la main.
- 4/config — le panneau interactif. C'est une interface au-dessus des mêmes clés : la plupart des interrupteurs écrivent dans ~/.claude/settings.json, quelques-uns (comme Show tips) vont dans settings.local.json, et les options globales atterrissent dans ~/.claude.json.
- 5managed-settings.json — la couche organisation. Elle surcharge tout (avec quelques exceptions de sécurité où la valeur la plus stricte gagne) — voilà pourquoi votre choix de modèle local peut perdre en silence sur la machine du travail.
Règle pratique : le comportement va dans CLAUDE.md, la configuration dans settings.json — et si une valeur semble vous ignorer, vérifiez si ~/.claude.json ou un fichier géré a déjà tranché.
Les réglages ne s'appliquent pas ? Premier secours
La plupart des problèmes de settings.json tiennent en cinq causes. Parcourez-les dans l'ordre :
- 1Erreurs de syntaxe JSON. settings.json est du JSON strict — une virgule de trop ou un commentaire // et tout le fichier est rejeté. Collez-le dans un validateur, ou ajoutez la ligne $schema pour que votre éditeur signale les erreurs à la frappe.
- 2Une règle plus stricte au-dessus de vous. Les réglages gérés et les clés sensibles à la sécurité (comme disableClaudeAiConnectors ou useAutoModeDuringPlan) battent votre fichier quoi qu'il arrive. Vérifiez si une machine professionnelle vous surcharge.
- 3Mauvais fichier, mauvais périmètre. Les règles de .claude/settings.json ne s'appliquent que dans ce projet ; les valeurs defaultMode auto et bypassPermissions sont ignorées par conception dans les fichiers de niveau projet.
- 4Des valeurs d'env au mauvais endroit. Les clés EN_MAJUSCULES vont dans le bloc env, pas au premier niveau. Si ANTHROPIC_API_KEY ou DISABLE_TELEMETRY semblent ignorées, elles siègent probablement un niveau trop haut.
- 5Des entrées rejetées en silence. Lancez claude doctor pour lister les entrées de réglages qui ont échoué à la validation, et /status dans une session pour voir quels fichiers sont réellement chargés.
Toujours bloqué ? Supprimez votre dernière modification, confirmez avec /status que le fichier charge, puis réappliquez le changement clé par clé — bissecter le fichier vaut mieux que le fixer des yeux.