06 - settings.json et configuration#

Quatre fichiers, un ordre de priorite, et la reponse a la question "pourquoi mon reglage ne s'applique pas ?".

Temps de lecture : 12 min | Niveau : Intermediaire

Ce que tu sauras faire apres#

• Trouver tes fichiers de reglages sous Windows.
• Choisir la bonne portee : utilisateur, projet partage, projet local, geree.
• Savoir quelle valeur gagne quand deux fichiers se contredisent.
• Definir des variables d'environnement pour tes sessions.
• Diagnostiquer un fichier casse ou un reglage ignore.

1. Les quatre fichiers#

Claude Code lit ses reglages dans quatre fichiers. Une organisation peut en plus livrer des reglages geres depuis la console claude.ai.

Sous Windows, concretement#

~/.claude veut dire %USERPROFILE%\.claude. Pour toi, c'est donc :

C:\Users\Main\.claude\settings.json          ← tes reglages personnels
C:\Users\Main\.claude.json                   ← etat interne, n'y touche pas
C:\Users\Main\projets\mon-projet\.claude\settings.json        ← reglages d'equipe
C:\Users\Main\projets\mon-projet\.claude\settings.local.json  ← tes reglages locaux

Pour ranger les fichiers du dossier personnel ailleurs, definis la variable d'environnement CLAUDE_CONFIG_DIR. Claude Code y stockera alors tes reglages, ton historique de sessions et tes plugins.

Le fichier ~/.claude.json est un cinquieme fichier que Claude Code ecrit pour lui-meme : ta session de connexion, tes serveurs MCP, l'etat par projet. Tu n'as pas a l'editer.

Ces fichiers n'existent pas par defaut#

Installer Claude Code ne cree aucun fichier de reglages. Si tu en as un, c'est que :

• ton organisation l'a deploye (geree) ;
• ton projet en avait un commite (projet partage) ;
• Claude Code l'a cree tout seul. Deux cas :
  • il ecrit ~/.claude/settings.json la premiere fois que tu changes dans /config une option qui se range la, le theme par exemple ;
  • il ecrit .claude/settings.local.json la premiere fois que tu accordes une approbation permanente dans une boite de permission.

2. L'ordre de priorite#

Quand la meme cle apparait a plusieurs endroits, Claude Code prend la valeur du niveau le plus haut qui la definit.

1. Reglages geres        ← managed-settings.json, MDM, console claude.ai
2. Ligne de commande     ← claude --settings '{...}'
3. Projet local          ← .claude/settings.local.json
4. Projet partage        ← .claude/settings.json
5. Utilisateur           ← ~/.claude/settings.json

Trois consequences pratiques :

1. Le projet bat l'utilisateur. Si ton equipe met "model": "claude-sonnet-5" dans .claude/settings.json et que tu veux Opus, mets ton choix dans .claude/settings.local.json, pas dans ~/.claude/settings.json.
2. Les listes fusionnent au lieu de s'ecraser. Pour permissions.allow et les autres cles de type liste, Claude Code combine les listes. Chaque fichier peut donc ajouter des entrees sans supprimer celles des autres.
3. Les variables d'environnement ne sont pas un niveau de cette pile. Quand un comportement a une variable shell et une cle de reglage, la regle se decide par paire. Par exemple, ANTHROPIC_MODEL est lu avant la cle model : tant que cette variable est definie, la cle model de tes fichiers ne s'applique pas. ANTHROPIC_DEFAULT_MODEL, elle, fixe le modele sur lequel demarrent les nouvelles sessions (a partir de la version 2.1.236).

3. Editer un fichier de reglages#

Ouvre le fichier de la portee voulue et ajoute une cle. C'est du JSON strict : un commentaire // ou une virgule finale est une erreur de syntaxe, et Claude Code signalera une Settings Error au demarrage suivant.

Exemple minimal dans ~/.claude/settings.json :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(make lint)",
      "Bash(make test-unit)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

La ligne $schema pointe vers le schema JSON publie. Elle donne l'autocompletion et la validation dans VS Code, Cursor et tout editeur qui gere les schemas JSON. Ce schema peut avoir du retard sur les versions recentes du CLI : un avertissement sur une cle recemment documentee ne veut pas dire que ta configuration est invalide.

Changer un reglage sans editer de fichier#

Quand les modifications prennent effet#

Claude Code surveille tes fichiers de reglages et les recharge quand ils changent. La plupart des modifications s'appliquent sans redemarrer, y compris permissions, hooks et apiKeyHelper.

Deux exceptions que tu vas rencontrer :

• model : utilise /model pour changer en cours de session.
• effortLevel et modelSettings : utilise /effort.

4. Les variables d'environnement#

Tu peux definir des variables pour tes sessions Claude Code dans le bloc env d'un fichier de reglages.

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

Les variables definies dans un fichier de reglages ont la priorite sur celles de ton shell. Une session en cours applique les nouvelles valeurs des que le fichier est sauvegarde, mais les fonctionnalites qui lisent leur variable au demarrage exigent un relancement.

Quelques variables utiles :

A noter. Claude Code ignore certaines variables dans les fichiers de reglages d'un depot, notamment CLAUDE_CONFIG_DIR et les variables d'export OpenTelemetry. Mets-les dans ton shell, dans ton ~/.claude/settings.json personnel, ou dans les reglages geres.

5. Un exemple complet, commente#

Ton fichier personnel#

Sauvegarde dans C:\Users\Main\.claude\settings.json. Voici la version copiable, sans commentaires :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "editorMode": "vim",
  "theme": "light-daltonized",
  "spinnerTipsEnabled": false,
  "preferredNotifChannel": "terminal_bell",
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(git status *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  },
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 20
}

Ce que fait chaque cle :

• model : le modele sur lequel chaque session demarre. Tu peux mettre un identifiant complet comme claude-sonnet-5, ou un alias, plus stable dans le temps : opus, sonnet, haiku, opusplan, ou default pour laisser Claude Code choisir.
• editorMode : vim pour les raccourcis Vim dans le prompt.
• theme : ici le theme clair adapte au daltonisme.
• spinnerTipsEnabled : false masque les astuces qui defilent sous le spinner.
• preferredNotifChannel : terminal_bell fait sonner le terminal quand une tache se termine ou qu'une permission attend.
• permissions.allow : les commandes lecture seule que tu fais dix fois par jour.
• permissions.deny : tes fichiers d'environnement, jamais lus.
• autoUpdatesChannel : stable prend une version d'environ une semaine, qui saute les releases a grosse regression. L'autre valeur est latest, le defaut.
• cleanupPeriodDays : supprime les transcripts de session et les donnees locales de plus de 20 jours.

Le fichier de ton equipe#

Sauvegarde dans .claude/settings.json a la racine du depot, et commite-le.

{
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(uv run pytest *)",
      "Bash(dbt compile *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./dbt/profiles.yml)",
      "Read(./secrets/**)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  },
  "env": {
    "DBT_PROFILES_DIR": "./dbt",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  },
  "plansDirectory": "./plans"
}

Trois choses a savoir avant de commiter un fichier d'equipe :

1. Les sessions cloud le lisent aussi. Une session cloud part d'un clone du depot, donc le fichier commite s'y applique.
2. Les regles allow attendent la confiance. Elles ne prennent effet qu'apres que chaque personne a accorde sa confiance au dossier. Les regles deny et ask, elles, s'appliquent dans toutes les sessions, de confiance ou non.
3. Les regles matchent le texte tel qu'ecrit. Bash(git push *) ne matche pas git -C . push. Read(./.env) arrete les outils fichiers et les commandes qui nomment le fichier, comme cat .env, mais pas un grep -r lance sur le dossier.

6. Diagnostiquer#

Voir ce qui est charge#

/status

L'onglet Status contient une ligne Setting sources qui liste chaque fichier charge pour la session : User settings, Project local settings, etc. Cette ligne dit quels fichiers ont ete lus, pas quel fichier a fourni chaque cle.

Pour la liste des entrees rejetees :

claude doctor

Trois types d'erreurs#

"Mon reglage ne s'applique pas"#

Verifie dans cet ordre :

1. Le JSON est-il valide ? Une virgule finale suffit a casser le fichier. claude doctor te le dit.
2. Un niveau superieur ecrase-t-il ta valeur ? Souviens-toi : geree > ligne de commande > projet local > projet partage > utilisateur.
3. Est-ce une des cles a restriction connue ? permissions.defaultMode avec la valeur auto ou bypassPermissions ne prend pas effet depuis .claude/settings.json ni .claude/settings.local.json. Mets-la dans ~/.claude/settings.json.
4. La cle est-elle lue une seule fois au demarrage ? C'est le cas de model, effortLevel et modelSettings. Utilise /model ou /effort.
5. Ton dossier est-il en confiance ? Les regles allow d'un .claude/settings.json commite attendent que tu accordes la confiance au dossier.

7. AVANT / APRES#

AVANT : tu mets tout dans ~/.claude/settings.json, y compris tes permissions dbt et tes variables de projet. Resultat : sur un autre projet, Claude Code autorise dbt build alors qu'il n'y a meme pas de dbt, et ton collegue n'a rien.

APRES : tu ranges par portee.

Pourquoi c'est mieux ? Chaque reglage vit a la portee ou il a du sens. Ton equipe herite des bonnes permissions en clonant le depot, et tes preferences personnelles te suivent partout sans polluer les projets.

Template pret a copier#

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "[TON_MODELE_PAR_DEFAUT]",
  "permissions": {
    "allow": ["Bash([TA_COMMANDE_QUOTIDIENNE] *)"],
    "ask": ["Bash([TA_COMMANDE_A_CONFIRMER] *)"],
    "deny": ["Read(./[TON_FICHIER_DE_SECRETS])"]
  },
  "env": {
    "[NOM_DE_TA_VARIABLE]": "[VALEUR]"
  },
  "cleanupPeriodDays": 30
}

A retenir#

• Quatre fichiers : utilisateur, projet partage, projet local, geree. Sous Windows, ~/.claude = C:\Users\<toi>\.claude.
• Priorite : geree > ligne de commande > projet local > projet partage > utilisateur.
• Les listes comme permissions.allow fusionnent entre les fichiers au lieu de s'ecraser.
• C'est du JSON strict : pas de commentaire, pas de virgule finale.
• Le bloc env definit des variables pour tes sessions, avec priorite sur ton shell.
• /status dit quels fichiers sont charges, claude doctor liste les entrees rejetees.
• model, effortLevel et modelSettings ne sont lus qu'au demarrage : utilise /model et /effort en cours de session.

Sources#

• Claude Code - Settings files and precedence
• Claude Code - Example settings files
• Claude Code - Environment variables
• Claude Code - Advanced setup
• Claude Code - Configure permissions
• Claude Code - Choose a permission mode
• Claude Code - Model configuration

Liens verifies le 26 septembre 2026.