Fichiers de paramètres et précédence

​

Fichiers de paramètres et qui ils affectent

​

Comparez la portée de chaque fichier de paramètres

• ~/.claude/settings.json : chaque projet sur votre machine, et rien sur celle de votre coéquipier ou dans la session cloud
• acme-app/.claude/settings.json : votre acme-app/. Il atteint le clone de votre coéquipier et la session cloud uniquement si vous faites un commit du fichier dans le contrôle de version ; jusqu’à ce que vous le fassiez, c’est un fichier sur votre disque comme n’importe quel autre et personne d’autre ne l’a
• acme-app/.claude/settings.local.json : votre acme-app/ uniquement. Claude Code l’ajoute à vos exclusions git globales la première fois qu’il écrit le fichier, donc il reste hors de vos commits ; si vous créez le fichier à la main, ajoutez-le à .gitignore vous-même
• Paramètres gérés, qu’il s’agisse d’un fichier managed-settings.json, d’une politique MDM, ou de paramètres gérés par le serveur à partir de la console claude.ai : chaque projet sur chaque machine auquel votre organisation la déploie, ou auquel vous vous connectez avec votre compte d’organisation. Seuls les paramètres gérés par le serveur atteignent la session cloud

​

Trouvez ou créez vos fichiers de paramètres

• Géré : votre organisation la déploie. Vous ne la créez ni ne l’éditez.
• Projet partagé : un projet qui utilise déjà Claude Code peut en avoir un commité. Sinon, créez-le à .claude/settings.json dans le dossier du projet.
• Utilisateur et Projet local : créez-les vous-même, ou laissez Claude Code les créer. Il écrit ~/.claude/settings.json la première fois que vous modifiez une option dans le menu /config qu’il stocke dans les paramètres utilisateur, comme le thème, et .claude/settings.local.json la première fois que vous donnez une approbation permanente sur une demande de permission, comme « Oui, et ne me demande plus » pour une commande Bash. Quelques options /config, y compris Afficher les conseils, s’enregistrent dans .claude/settings.local.json à la place du fichier utilisateur.

​

Partagez les paramètres avec votre équipe

​

Gardez les paramètres personnels hors d’un dépôt

• Claude Code l’écrit aussi. Quand Claude demande la permission d’exécuter une commande Bash et que vous choisissez « Oui, et ne me demande plus », Claude Code enregistre cette approbation de permission ici comme une règle allow.
• Vous n’avez pas besoin de le gitignorer vous-même, sauf si vous l’avez créé à la main. La première fois que Claude Code écrit le fichier dans un dépôt git qui ne l’ignore pas déjà, il ajoute **/.claude/settings.local.json à votre fichier d’exclusions git global, donc le fichier reste hors de vos commits dans chaque dépôt. Ce fichier est core.excludesFile quand votre configuration git globale le définit à un chemin absolu ou préfixé par ~ ; sinon c’est $XDG_CONFIG_HOME/git/ignore, ou ~/.config/git/ignore quand XDG_CONFIG_HOME n’est pas défini. Si vous avez créé le fichier à la main et que Claude Code ne l’a pas encore écrit, ajoutez-le à .gitignore vous-même.
• Ses règles allow n’attendent pas la confiance tant que le fichier reste non suivi. Parce que le fichier est le vôtre et non celui du dépôt, Claude Code applique ses règles allow sans l’étape de confiance de l’espace de travail qu’il exige pour le fichier commité. Si le fichier est suivi par git, l’étape de confiance s’applique aussi ; voir Quand votre fichier de paramètres locaux a besoin de confiance.

​

Où Claude Code garde le fichier local dans un dépôt git

• Quand le fichier reste avec .claude/settings.json à la place : en dehors d’un dépôt git, quand la racine du dépôt est votre répertoire personnel, sur Windows, ou quand la racine du dépôt ou son entrée .git ou .claude n’est pas possédée par votre utilisateur.
• Les chemins dans le fichier ne s’ancrent pas à la racine du dépôt : une règle de permission qui commence par / ou un chemin sandbox relatif s’ancre au répertoire de travail principal de la session à la place.

​

Vérifiez ce que votre organisation applique

• Paramètres gérés par le serveur, que Claude Code récupère à partir de la console d’administration claude.ai ou d’une passerelle d’applications Claude auto-hébergée
• Politiques MDM ou au niveau du système d’exploitation, et fichiers managed-settings.json dans un répertoire système
• Un hôte d’intégration tel que Claude Desktop, via l’option SDK managedSettings ; voir Contrôler la politique à partir d’un hôte d’intégration

​

Modifiez un paramètre

​

Utilisez le menu /config

• La plupart des options : ~/.claude/settings.json
• Quelques options, comme Afficher les conseils : .claude/settings.local.json
• Les options de configuration globale : ~/.claude.json

​

Éditez un fichier de paramètres

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

​

Modifiez un paramètre pour une session

• --settings : passez une clé en JSON, en ligne ou comme chemin vers un fichier. Claude Code l’applique au-dessus de vos fichiers utilisateur, projet et locaux et en dessous des paramètres gérés. Il peut définir n’importe quelle clé que votre fichier de paramètres utilisateur peut définir ; il ne peut pas définir les clés Managed ou Global config.
• Un indicateur pour cette clé : certaines clés ont leur propre indicateur, comme --model pour model et --effort pour effortLevel et modelSettings.
• Une variable d’environnement : exportez la variable appairée de la clé avant d’exécuter claude, comme ANTHROPIC_MODEL pour model.

claude --settings '{"model": "claude-opus-5-5"}'

​

Quand les modifications prennent effet

• model : utilisez /model pour basculer en session. Chaque modèle a son propre cache d’invite, donc la première demande après un basculement relit la conversation entière sans cache ; voir Basculer les modèles
• effortLevel et modelSettings : utilisez /effort pour modifier l’effort en session

​

Confirmez ce qui a été chargé

​

Réparez un fichier de paramètres cassé

• Erreur de paramètres : un fichier utilisateur, projet ou local a du JSON invalide ou une valeur que le schéma rejette. Au début d’une session interactive, Claude Code affiche un dialogue qui vous permet de corriger le fichier avec l’aide de Claude, de quitter, ou de continuer sans les paramètres cassés.
• Avertissement de paramètres : seules les entrées individuelles échouent, comme une règle de permission mal formée ou un nom d’événement hook inconnu. Claude Code ignore ces valeurs et garde le reste du fichier en vigueur.
• Paramètres gérés : Claude Code continue d’appliquer le reste du fichier. Les entrées invalides dans les paramètres gérés dit ce qu’il supprime et quelles clés reviennent à une valeur plus stricte jusqu’à ce que vous les corrigiez. Pour un document de paramètres gérés qui n’est pas du JSON valide, voir Le document de paramètres gérés n’a pas pu être analysé.
• Erreur de configuration : ~/.claude.json ne peut pas être analysé. Claude Code copie le fichier cassé à ~/.claude/backups/.claude.json.corrupted.<timestamp> et demande si vous voulez quitter et le corriger à la main ou réinitialiser à la configuration par défaut ; une exécution -p imprime l’erreur et quitte. Pour récupérer votre état précédent, copiez l’un des cinq fichiers .claude.json.backup.<timestamp> les plus récents dans ~/.claude/backups/, que Claude Code enregistre avant d’écrire le fichier.

​

Priorité des paramètres

1. Paramètres gérés : paramètres que votre organisation déploie, par un fichier managed-settings.json, une politique MDM, ou paramètres gérés par le serveur à partir de la console claude.ai. Rien dans vos propres fichiers de paramètres ni dans --settings ne remplace une clé gérée, et un flag comme --model choisit uniquement parmi les modèles que votre organisation autorise. Un model géré est une valeur par défaut de départ, pas un verrou ; les verrous sont availableModels et deniedModels. Quand votre organisation fournit plus d’une source gérée, les règles de priorité au sein du niveau géré indiquent ce que Claude Code lit à partir de chacune.
2. Ligne de commande : le JSON que vous passez avec --settings <file-or-json> quand vous démarrez claude, pour cette session uniquement ; voir Modifiez un paramètre pour une session. Une clé que vous y définissez remplace la même clé dans vos fichiers de paramètres de projet et utilisateur, et une clé que vous omettez garde la valeur issue de ces fichiers. D’autres flags, comme --model, définissent une seule chose pour la session et ne font pas partie de cette pile ; l’entrée d’une clé dans la référence des paramètres indique quels flags la remplacent.
3. Paramètres de projet local (.claude/settings.local.json) : vos paramètres personnels pour ce projet.
4. Paramètres de projet partagés (.claude/settings.json) : paramètres que votre équipe valide dans le contrôle de source.
5. Paramètres utilisateur (~/.claude/settings.json) : vos paramètres personnels pour chaque projet.

​

Les listes fusionnent au lieu de remplacer

• fallbackModel est une chaîne ordonnée où la position porte du sens, donc Claude Code prend la valeur entière du fichier de priorité la plus élevée qui la définit.
• modelPicker contient une liste ordonnée de lignes plus un flag de remplacement, donc Claude Code ne fusionne jamais les lignes de deux sources. Il prend la valeur entière du plus élevé des paramètres gérés, --settings, et des paramètres utilisateur qui la définit, et ignore la clé dans les paramètres de projet et locaux. Nécessite Claude Code v2.1.242 ou ultérieur.
• availableModels : quand les paramètres gérés que Claude Code applique la définissent, Claude Code applique cette liste telle quelle et ignore les entrées que vous ajoutez dans les paramètres utilisateur, projet ou locaux, sauf si une application qui intègre Claude Code fournit sa propre liste de modèles ; voir Exceptions à la priorité des paramètres gérés. Entre les sources gérées, la liste ne fusionne jamais non plus ; comment Claude Code combine les sources gérées dit quelle liste de source s’applique. Entre les portées non gérées, Claude Code fusionne les tableaux comme d’habitude.
• modelSettings : Claude Code la résout un modèle à la fois, avec effortLevel. L’entrée modelSettings indique de quel fichier provient la valeur qui s’applique à un modèle.

​

Exemples de priorité

​

Les paramètres d’équipe remplacent les paramètres personnels

​

Les paramètres de l’organisation remplacent tout

​

La ligne de commande remplace vos fichiers pour une session

​

Un flag ou une variable d’environnement définit la même chose

​

Dépannez un paramètre qui ne s’applique pas

​

Une valeur que vous avez définie est ignorée

• Un niveau plus élevé la définit. Un autre fichier de paramètres, un flag --settings, ou une source gérée définit la clé au-dessus de la vôtre ; la pile dit lequel. Un flag ou une variable d’environnement peut aussi remplacer la clé de son propre chef, décidé clé par clé ; l’entrée de la clé sur la référence des paramètres dit lequel Claude Code utilise, et l’entrée env couvre une valeur env gérée par rapport à une exportation shell.
• Une clé de sécurité garde sa valeur stricte. Pour quelques clés, Claude Code honore la valeur restrictive à partir de n’importe quel fichier, donc un true de projet pour disableClaudeAiConnectors reste activé ; voir Exceptions à la priorité des paramètres gérés.
• Le fichier ne peut pas définir cette valeur. Les valeurs permissions.defaultMode auto et bypassPermissions ne prennent pas effet à partir des paramètres de projet ou locaux ; définissez-les dans les paramètres utilisateur ou gérés à la place, ou passez --permission-mode pour une session. Avant v2.1.257, bypassPermissions prenait effet à partir de n’importe quel fichier. Une variable d’exportation de télémétrie dans un bloc env ne prend pas effet à partir des paramètres de projet ou locaux non plus, à part quelques valeurs off. Variables que Claude Code ignore dans env énumère les variables et ces valeurs.
• Le fichier est cassé. Du JSON invalide ou une valeur rejetée fait que Claude Code ignore le fichier ou l’entrée ; voir Réparez un fichier de paramètres cassé.

​

Un changement que vous avez fait dans Claude Code est perdu dans les nouvelles sessions

​

Un changement géré ne vous a pas atteint

​

Une clé validée n’atteint pas les coéquipiers

• Claude Code ignore la clé dans un fichier de dépôt. Cherchez User, local, or managed, User or managed, User, Managed, ou Global config dans la colonne Scope de l’index des paramètres. Ces clés ne s’appliquent jamais à partir du fichier partagé, à part quelques-unes qu’un fichier de dépôt peut toujours désactiver. Chacune de ces entrées le dit sur sa ligne Scope. Les clés Global config s’appliquent uniquement à partir de ~/.claude.json. À l’intérieur de la clé env, les variables d’exportation de télémétrie ne s’appliquent jamais à partir du fichier partagé non plus, à part quelques valeurs off ; voir Variables que Claude Code ignore dans env.
• La clé attend la confiance. Les règles permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces, et la plupart des valeurs env s’appliquent uniquement après que chaque coéquipier fasse confiance au dossier. Jusqu’à ce qu’ils le fassent, ils voient toujours des demandes de permission et n’obtiennent pas les plugins d’une marketplace que le fichier déclare. Les règles deny et ask s’appliquent immédiatement.

​

Les règles de permission se combinent différemment que vous ne l’attendiez

• Vous avez choisi « Oui, et ne plus me demander » sur une demande de permission mais on vous demande toujours la permission pour le même outil. Ce choix a enregistré une règle allow dans votre fichier local, et une règle allow là ne surclasse pas une règle ask à partir d’un fichier de projet ou géré ; comment les règles de permission se combinent explique l’ordre. Dans l’extension VS Code, la carte d’approbation vous permet de choisir le fichier de destination, y compris le fichier partagé du projet, ce qui change la règle pour tout le monde ; dans la CLI, Claude Code écrit uniquement dans votre fichier local.
• Les règles allow de votre organisation s’appliquent toujours à côté des vôtres. C’est attendu : Claude Code fusionne permissions.allow entre les portées, sauf si votre organisation définit allowManagedPermissionRulesOnly.

​

Exceptions à la priorité des paramètres gérés

​

Paramètres dans les sessions cloud

• Threads cloud dans un projet : dans un thread cloud d’un projet, aucune des règles de permission, aucun des hooks ni aucune des valeurs env du .claude/settings.json d’un dépôt ne s’applique, quel que soit le nombre de dépôts du projet. Ce que les threads récupèrent de vos dépôts énumère ce qu’il faut utiliser à la place.
• Paramètres de projet partagés (.claude/settings.json) : lus dans une session avec un seul dépôt en dehors d’un projet, car le fichier fait partie du clone et la session démarre à l’intérieur. Commitez un paramètre à cet endroit pour l’appliquer dans ces sessions.
• Paramètres de projet partagés avec plusieurs dépôts : dans un environnement hébergé par Anthropic, une session avec plusieurs dépôts démarre au-dessus des clones et lit uniquement les clés enabledPlugins et extraKnownMarketplaces du .claude/settings.json de chaque dépôt, pas les règles de permission, les hooks, env, ou d’autres clés. Les marketplaces et les plugins que ces deux clés déclarent ne se chargent toujours pas dans une session cloud. Pour un environnement auto-hébergé, consultez les paramètres de quel dépôt s’appliquent.
• Paramètres utilisateur et projet local (~/.claude/settings.json et .claude/settings.local.json) : non lus. Les deux restent sur votre machine, et le fichier local n’est pas dans le clone.
• Paramètres gérés : un fichier managed-settings.json ou un profil MDM sur votre appareil ne parvient pas à une session cloud. Les paramètres gérés par le serveur de votre organisation le font ; la couverture de surface énumère quelles sessions cloud les reçoivent. Un environnement auto-hébergé lit aussi le fichier de paramètres gérés dans son image de runner. Comment Claude Code combine les sources gérées indique quand ce fichier s’applique.
• /config : dans votre navigateur sur claude.ai/code, ouvre la section Claude Code de vos paramètres claude.ai à la place de modifier une valeur. Pour modifier un paramètre pour une session cloud, définissez une variable d’environnement sur l’environnement. Dans une session avec un seul dépôt en dehors d’un projet, vous pouvez à la place commiter la clé dans le .claude/settings.json de ce dépôt.

​

Quoi de neuf

• Tous les paramètres : chaque clé, avec où vous la définissez et un exemple
• Fichiers de paramètres d’exemple : un fichier personnel, un fichier d’équipe, et un fichier géré d’une organisation
• Configurer les permissions : règles allow, ask, et deny, et ce que Claude Code exécute sans demander
• Variables d’environnement : les variables que Claude Code lit et le bloc env
• Déboguer votre configuration : quand un paramètre ne s’applique pas
• Référence du répertoire Claude : chaque fichier que Claude Code lit, y compris les subagents, serveurs MCP, plugins, et CLAUDE.md