Paramètres Claude Code

​

Portées de configuration

​

Portées disponibles

​

Quand utiliser chaque portée

• Les politiques de sécurité qui doivent être appliquées à l’échelle de l’organisation
• Les exigences de conformité qui ne peuvent pas être contournées
• Les configurations standardisées déployées par l’IT/DevOps

• Les préférences personnelles que vous voulez partout (thèmes, paramètres d’éditeur)
• Les outils et plugins que vous utilisez dans tous les projets
• Les clés API et l’authentification (stockées de manière sécurisée)

• Les paramètres partagés par l’équipe (permissions, hooks, MCP servers)
• Les plugins que toute l’équipe devrait avoir
• La standardisation des outils entre collaborateurs

• Les remplacements personnels pour un projet spécifique
• Tester les configurations avant de les partager avec l’équipe
• Les paramètres spécifiques à la machine qui ne fonctionneront pas pour les autres

​

Comment les portées interagissent

1. Managed (la plus élevée) : ne peut pas être contournée par quoi que ce soit
2. Arguments de ligne de commande : remplacements de session temporaires
3. Local : remplace les paramètres de projet et d’utilisateur
4. Project : remplace les paramètres d’utilisateur
5. User (la plus basse) : s’applique quand rien d’autre ne spécifie le paramètre

​

Ce qui utilise les portées

​

Fichiers de paramètres

• Les paramètres utilisateur sont définis dans ~/.claude/settings.json et s’appliquent à tous les projets.
• Les paramètres de projet sont enregistrés dans votre répertoire de projet :
  • .claude/settings.json pour les paramètres qui sont vérifiés dans le contrôle de source et partagés avec votre équipe
  • .claude/settings.local.json pour les paramètres qui ne sont pas vérifiés, utiles pour les préférences personnelles et l’expérimentation. Quand Claude Code crée .claude/settings.local.json, il configure git pour ignorer le fichier. Si vous créez le fichier vous-même, ajoutez-le à votre gitignore manuellement. Parce que ce fichier est le vôtre plutôt que celui du référentiel, ses règles de permission allow prennent effet sans l’étape de confiance de l’espace de travail que les règles allow de .claude/settings.json nécessitent. Si le référentiel fournit le fichier, par exemple en le validant, la confiance de l’espace de travail s’applique toujours.
• Paramètres gérés : Pour les organisations qui ont besoin d’un contrôle centralisé, Claude Code supporte plusieurs mécanismes de livraison pour les paramètres gérés. Tous utilisent le même format JSON et ne peuvent pas être contournés par les paramètres utilisateur ou de projet :
  • Paramètres gérés par le serveur : livrés à distance au moment de la connexion, soit à partir des serveurs d’Anthropic via la console d’administration claude.ai, soit à partir d’une passerelle d’applications Claude auto-hébergée. Voir paramètres gérés par le serveur.
  • Politiques MDM/au niveau du système d’exploitation : livrées via la gestion native des appareils sur macOS et Windows :
    • macOS : domaine de préférences gérées com.anthropic.claudecode. Les clés de niveau supérieur du plist reflètent managed-settings.json, avec les paramètres imbriqués comme dictionnaires et les tableaux comme tableaux plist. Déployez via des profils de configuration dans Jamf, Iru (Kandji), ou d’autres outils MDM similaires.
    • Windows : clé de registre HKLM\SOFTWARE\Policies\ClaudeCode avec une valeur Settings (REG_SZ ou REG_EXPAND_SZ) contenant du JSON (déployé via Group Policy ou Intune)
    • Windows (au niveau utilisateur) : HKCU\SOFTWARE\Policies\ClaudeCode (priorité de politique la plus basse, utilisée uniquement quand aucune source au niveau administrateur n’existe)
  • Basé sur fichier : managed-settings.json et managed-mcp.json déployés dans les répertoires système :
    • macOS : /Library/Application Support/ClaudeCode/
    • Linux et WSL : /etc/claude-code/
    • Windows : C:\Program Files\ClaudeCode\
    Le chemin Windows hérité C:\ProgramData\ClaudeCode\managed-settings.json n’est plus supporté à partir de v2.1.75. Les administrateurs qui ont déployé des paramètres à cet emplacement doivent migrer les fichiers vers C:\Program Files\ClaudeCode\managed-settings.json.
    Les paramètres gérés basés sur fichier supportent également un répertoire drop-in à managed-settings.d/ dans le même répertoire système à côté de managed-settings.json. Cela permet à des équipes séparées de déployer des fragments de politique indépendants sans coordonner les modifications d’un seul fichier. Suivant la convention systemd, managed-settings.json est fusionné en premier comme base, puis tous les fichiers *.json dans le répertoire drop-in sont triés alphabétiquement et fusionnés par-dessus. Les fichiers ultérieurs remplacent les fichiers antérieurs pour les valeurs scalaires ; les tableaux sont concaténés et dédupliqués ; les objets sont fusionnés en profondeur. Les fichiers cachés commençant par . sont ignorés. Utilisez des préfixes numériques pour contrôler l’ordre de fusion, par exemple 10-telemetry.json et 20-security.json.
  Voir paramètres gérés et Configuration MCP gérée pour plus de détails. Ce référentiel inclut des modèles de déploiement de démarrage pour Jamf, Iru (Kandji), Intune, et Group Policy. Utilisez-les comme points de départ et ajustez-les selon vos besoins.
  Les déploiements gérés peuvent également restreindre les ajouts de marketplace de plugins en utilisant strictKnownMarketplaces. Pour plus d’informations, voir Restrictions de marketplace gérées.
• Autre configuration est stockée dans ~/.claude.json. Ce fichier contient votre session OAuth, les configurations de MCP server pour les portées utilisateur et locale, l’état par projet (outils autorisés, paramètres de confiance), et divers caches. Les MCP servers au niveau du projet sont stockés séparément dans .mcp.json.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

Quand les modifications prennent effet

• model : utilisez /model pour basculer en session
• outputStyle : fait partie de l’invite système, qui est reconstruite sur /clear ou redémarrage

​

Entrées invalides dans les paramètres gérés

• Les sessions interactives affichent une boîte de dialogue au démarrage énumérant les entrées invalides.
• Les exécutions sans tête avec -p impriment un résumé sur stderr.
• claude doctor énumère chaque entrée invalide avec sa source et son champ.

​

Paramètres disponibles

​

Paramètres de configuration globale

​

Paramètres de worktree

​

Paramètres de permission

​

Syntaxe de règle de permission

​

Paramètres de sandbox

​

Préfixes de chemin sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• Paramètres sandbox.filesystem (affichés ci-dessus) : Contrôlez les chemins à la limite du sandbox au niveau du système d’exploitation. Ces restrictions s’appliquent à toutes les commandes de sous-processus (par exemple, kubectl, terraform, npm), pas seulement aux outils de fichier de Claude.
• Règles de permission : Utilisez les règles allow/deny Edit pour contrôler l’accès à l’outil de fichier de Claude, les règles deny Read pour bloquer les lectures (une règle deny Read bloque également l’outil Edit sur les chemins correspondants), et les règles allow/deny WebFetch pour contrôler les domaines réseau. Les chemins de ces règles sont également fusionnés dans la configuration du sandbox.

​

Paramètres d’attribution

• Les commits utilisent les trailers git (comme Co-Authored-By) par défaut, qui peuvent être personnalisés ou désactivés
• Les descriptions de pull request sont du texte brut

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

​

Paramètres de suggestion de fichier

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

{"query": "src/comp"}

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

​

Badges de lien de pied de page

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

Configuration des hooks

• Les hooks gérés et les hooks SDK sont chargés
• Les hooks des plugins force-activés dans les paramètres gérés enabledPlugins sont chargés. Cela permet aux administrateurs de distribuer des hooks vérifiés via une marketplace organisationnelle tout en bloquant tout le reste. La confiance est accordée par l’ID complet plugin@marketplace, donc un plugin avec le même nom d’une marketplace différente reste bloqué
• Les hooks utilisateur, projet et tous les autres hooks de plugin sont bloqués

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

Calculer les paramètres gérés avec un assistant de politique

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

Précédence des paramètres

1. Paramètres gérés (gérés par le serveur, politiques MDM/au niveau du système d’exploitation, ou paramètres gérés)
   • Politiques déployées par l’IT via la livraison par serveur, les profils de configuration MDM, les politiques de registre, ou les fichiers de paramètres gérés
   • Ne peuvent pas être contournés par aucun autre niveau, y compris les arguments de ligne de commande
   • Au sein du niveau géré, une seule source est utilisée et les autres sont ignorées plutôt que fusionnées. Précédence, du plus élevé au plus bas :
     • Sortie policyHelper : quand configuré, c’est la seule source gérée utilisée
     • Distant (paramètres gérés par le serveur claude.ai ou passerelle d’applications Claude-livrés)
     • Politiques MDM/au niveau du système d’exploitation
     • Basé sur fichier (managed-settings.d/*.json et managed-settings.json, fusionnés ensemble)
     • Registre HKCU (Windows uniquement)
   • Quelques clés sont des exceptions, honorées quand n’importe quelle source gérée contrôlée par l’administrateur les définit plutôt que seulement la source gagnante. La source de registre HKCU inscriptible par l’utilisateur est exclue. Les clés d’exception sont :
     • les clés de verrouillage sandbox sandbox.network.allowManagedDomainsOnly et sandbox.filesystem.allowManagedReadPathsOnly, avec leurs listes blanches associées
     • allowAllClaudeAiMcps
     • les chemins binaires sandbox sandbox.bwrapPath et sandbox.socatPath
     • forceRemoteSettingsRefresh
   • Les hôtes d’intégration tels que Claude Desktop peuvent fournir une politique via l’option SDK managedSettings. Par défaut, ceci est ignoré quand une source gérée déployée par l’administrateur est présente : paramètres gérés par le serveur, une politique MDM ou au niveau du système d’exploitation, ou un fichier de paramètres gérés. Le fallback de registre HKCU inscriptible par l’utilisateur ne compte pas comme une source déployée par l’administrateur. Les administrateurs peuvent opter en définissant parentSettingsBehavior à "merge". Les valeurs de l’intégrateur sont filtrées pour qu’elles puissent resserrer la politique gérée mais pas l’assouplir.
2. Arguments de ligne de commande
   • Remplacements temporaires pour une session spécifique. JSON passé via --settings <file-or-json> fusionne avec les paramètres basés sur fichier en utilisant les mêmes règles que les autres couches : une clé définie ici remplace la même clé dans les paramètres locaux, de projet ou utilisateur, et omettre une clé laisse la valeur de couche inférieure en place
3. Paramètres de projet local (.claude/settings.local.json)
   • Paramètres personnels spécifiques au projet
4. Paramètres de projet partagés (.claude/settings.json)
   • Paramètres de projet partagés par l’équipe dans le contrôle de source
5. Paramètres utilisateur (~/.claude/settings.json)
   • Paramètres globaux personnels

​

Vérifier les paramètres actifs

​

Points clés du système de configuration

• Fichiers de mémoire (CLAUDE.md) : Contiennent les instructions et le contexte que Claude charge au démarrage
• Fichiers de paramètres (JSON) : Configurez les permissions, les variables d’environnement, et le comportement des outils
• Skills : Invites personnalisées qui peuvent être invoquées avec /skill-name ou chargées automatiquement par Claude
• MCP servers : Étendez Claude Code avec des outils et des intégrations supplémentaires
• Précédence : Les configurations de niveau supérieur (Managed) remplacent celles de niveau inférieur (User/Project)
• Héritage : Les paramètres fusionnent entre les portées ; les valeurs scalaires des portées de priorité supérieure remplacent, et les tableaux se concatènent, avec deux exceptions décrites dans la Note de fusion de tableau

​

Invite système

​

Exclure les fichiers sensibles

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

​

Configuration des subagents

• Subagents utilisateur : ~/.claude/agents/, disponibles dans tous vos projets
• Subagents de projet : .claude/agents/, spécifiques à votre projet et partageables avec votre équipe

​

Configuration des plugins

​

Paramètres des plugins

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

​

enabledPlugins

• Paramètres utilisateur (~/.claude/settings.json) : Préférences personnelles de plugin
• Paramètres de projet (.claude/settings.json) : Plugins spécifiques au projet partagés avec l’équipe
• Paramètres locaux (.claude/settings.local.json) : Remplacements par machine, ignorés par git quand Claude Code les crée
• Paramètres gérés (managed-settings.json) : Remplacements de politique au niveau de l’organisation qui bloquent l’installation à toutes les portées et masquent le plugin de la marketplace

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

extraKnownMarketplaces

1. Les membres de l’équipe sont invités à installer la marketplace quand ils font confiance au dossier
2. Les membres de l’équipe sont ensuite invités à installer les plugins de cette marketplace
3. Les utilisateurs peuvent ignorer les marketplaces ou plugins indésirables (stockés dans les paramètres utilisateur)
4. L’installation respecte les limites de confiance et nécessite un consentement explicite

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• github : Référentiel GitHub (utilise repo)
• git : N’importe quelle URL git (utilise url)
• directory : Chemin du système de fichiers local (utilise path, pour le développement uniquement)
• hostPattern : Modèle regex pour correspondre aux hôtes de marketplace (utilise hostPattern)
• settings : marketplace en ligne déclarée directement dans settings.json sans référentiel hébergé séparé (utilise name et plugins)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• macOS : /Library/Application Support/ClaudeCode/managed-settings.json
• Linux et WSL : /etc/claude-code/managed-settings.json
• Windows : C:\Program Files\ClaudeCode\managed-settings.json

• Disponible uniquement dans les paramètres gérés (managed-settings.json)
• Ne peut pas être contourné par les paramètres utilisateur ou projet (précédence la plus élevée)
• Appliqué avant les opérations de réseau et système de fichiers, donc les sources bloquées ne s’exécutent jamais
• Utilise la correspondance exacte pour les spécifications de source (y compris ref, path pour les sources git), sauf hostPattern et pathPattern, qui utilisent la correspondance regex

• undefined (par défaut) : pas de restrictions, donc les utilisateurs peuvent ajouter n’importe quelle marketplace
• Tableau vide [] : verrouillage complet, donc les utilisateurs ne peuvent pas ajouter de nouvelles marketplaces
• Liste de sources : les utilisateurs ne peuvent ajouter que les marketplaces qui correspondent exactement

1. Référentiels GitHub :

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Référentiels Git :

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. Marketplaces basées sur URL :

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. Packages NPM :

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. Chemins de fichier :

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. Chemins de répertoire :

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. Correspondance de modèle d’hôte :

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github : correspond toujours à github.com
• git : extrait le nom d’hôte de l’URL (supporte les formats HTTPS et SSH)
• url : extrait le nom d’hôte de l’URL
• npm, file, directory : non supporté pour la correspondance de modèle d’hôte

8. Correspondance de modèle de chemin :

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• Le repo ou url doit correspondre exactement
• Le champ ref doit correspondre exactement (ou les deux être non définis)
• Le champ path doit correspondre exactement (ou les deux être non définis)

// Ce sont des sources DIFFÉRENTES :
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// Ce sont aussi DIFFÉRENTES :
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• Les restrictions sont vérifiées avant toute demande réseau ou opération de système de fichiers
• Quand bloquée, les utilisateurs voient des messages d’erreur clairs indiquant que la source est bloquée par la politique gérée
• La restriction s’applique à l’ajout de marketplace et à l’installation, la mise à jour, l’actualisation et la mise à jour automatique de plugins. Une marketplace ajoutée avant que la politique soit définie ne peut pas être utilisée pour installer ou mettre à jour des plugins une fois que sa source ne correspond plus à la liste blanche
• Les paramètres gérés ont la précédence la plus élevée et ne peuvent pas être contournés

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

Gérer les plugins

• Parcourir les plugins disponibles à partir des marketplaces
• Installer/désinstaller les plugins
• Activer/désactiver les plugins
• Afficher les détails du plugin (skills, agents, hooks fournis)
• Ajouter/supprimer les marketplaces

​

Variables d’environnement

​

Outils disponibles pour Claude

​

Voir aussi

• Permissions : système de permissions, syntaxe des règles, modèles spécifiques aux outils, et politiques gérées
• Authentification : configurer l’accès utilisateur à Claude Code
• Déboguer votre configuration : diagnostiquer pourquoi un paramètre, un hook, ou un serveur MCP ne prend pas effet
• Dépannage de l’installation et de la connexion : problèmes d’installation, d’authentification, et de plateforme