Déployer les paramètres gérés

​

Déployer un fichier de paramètres gérés

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

​

Choisir un mécanisme de livraison

• Contrôles de livraison : policyHelper, wslInheritsWindowsSettings, et managedSourcesBehavior
• Clés de connexion à la passerelle : forceLoginGatewayUrl, gatewayInternalNetworks, et la valeur "gateway" de forceLoginMethod

​

Où et quand une politique s’applique

• Surfaces : sur la machine du développeur, le terminal, les extensions VS Code et JetBrains, l’onglet Code de l’application de bureau, et les sessions Agent SDK lisent toutes ces sources. Les sessions Agent SDK chargent les paramètres gérés même quand settingSources exclut les fichiers utilisateur, projet et local.
• Sessions cloud : une session dans un environnement hébergé par Anthropic ne lit pas un profil MDM ou un fichier d’appareil, donc la politique pour cela doit provenir des paramètres gérés par le serveur. Une session dans un environnement auto-hébergé lit également le fichier de paramètres gérés dans son image de runner, par défaut uniquement quand les paramètres gérés par le serveur ne livrent aucune clé de politique, à l’exception des clés que Claude Code lit de chaque source d’administration. Comment Claude Code combine les sources gérées couvre l’opt-in qui s’applique aux deux.
• Sessions Claude Tag : les sessions Claude Tag s’exécutent dans des environnements cloud mais ne reçoivent pas les paramètres gérés par le serveur. Dans un environnement auto-hébergé, elles lisent toujours le fichier de paramètres gérés dans l’image du runner. Configurez Claude Tag lui-même dans les paramètres d’administration Claude Tag.
• Sessions Cowork : Cowork dans l’application Claude Desktop exécute ses sessions sur Claude Code. Dans une session Cowork, Claude Code ne récupère jamais les paramètres gérés par le serveur de la console d’administration claude.ai, même quand l’utilisateur se connecte avec un compte Team ou Enterprise, donc la politique qui s’applique dépend de l’endroit où la session s’exécute :
  • Sur la machine de l’utilisateur : par défaut, Claude Code dans une session Cowork lit la politique MDM ou au niveau du système d’exploitation et le fichier de paramètres gérés sur cet appareil, donc déployez la politique là.
  • Dans un sandbox VM complet : quand votre configuration gérée Claude Desktop définit requireCoworkFullVmSandbox, Claude Code s’exécute à l’intérieur d’une machine virtuelle où la politique MDM de l’appareil et le fichier de paramètres gérés ne sont pas présents.
  • Sessions Cowork distantes : celles-ci s’exécutent sur des machines virtuelles gérées par Anthropic, où Claude Code n’a pas de politique d’appareil à lire.
  Où que la session s’exécute, claude.ai applique les listes strictKnownMarketplaces et blockedMarketplaces de la console d’administration elle-même quand quelqu’un ajoute une marketplace à partir d’un dépôt git sur claude.ai ou à partir de Personnaliser dans Cowork. Comment fonctionnent les restrictions décrit cette vérification. Le tableau couverture de surface compare Cowork avec les autres surfaces.
• Sessions en cours d’exécution : la plupart des modifications atteignent une session en cours d’exécution selon le calendrier du tableau de mécanisme de livraison, sans redémarrage.
  • Les modifications apportées à forceRemoteSettingsRefresh, requiredMinimumVersion, et certaines clés modifiables par l’utilisateur prennent effet au prochain démarrage de session.
  • Une entrée policyHelper nouvelle ou modifiée prend effet au prochain lancement. Si les paramètres gérés par le serveur masquent l’assistant à ce lancement, l’assistant s’exécute dès qu’une récupération signale que ces paramètres ont été supprimés.
• Modifications qui nécessitent une approbation : à part les mises à jour qui attendent le prochain lancement, une modification gérée par le serveur d’un paramètre qui nécessite une approbation, comme un hook ou une variable env, attend que le développeur accepte la boîte de dialogue dans une session interactive, et s’applique pour l’exécution actuelle dans une session qu’une extension IDE ou l’Agent SDK héberge. Les autres modifications gérées par le serveur s’appliquent au prochain sondage.
• Sessions longue durée : une session laissée ouverte pendant des semaines peut toujours être en retard sur un déploiement. requiredMinimumVersion bloque un binaire obsolète de démarrer et ne termine pas une session qui s’exécute déjà.

​

Où chaque mécanisme stocke la politique

• Gérée par le serveur : les serveurs d’Anthropic, ou votre passerelle, détiennent la politique. Claude Code conserve un cache local qu’il applique au démarrage et remplace à chaque récupération réussie.
• Profil de configuration macOS : le domaine des préférences gérées com.anthropic.claudecode. Utilisez les mêmes clés de niveau supérieur que managed-settings.json, avec les paramètres imbriqués comme dictionnaires et les listes comme tableaux plist.
• Registre Windows HKLM : le JSON comme valeur REG_SZ ou REG_EXPAND_SZ nommée Settings sous HKLM\SOFTWARE\Policies\ClaudeCode.
• Basé sur fichier : managed-settings.json, un répertoire optionnel managed-settings.d/, et managed-mcp.json dans le répertoire système : /Library/Application Support/ClaudeCode/ sur macOS, /etc/claude-code/ sur Linux et WSL, et C:\Program Files\ClaudeCode\ sur Windows. Claude Code ne lit pas le chemin Windows hérité C:\ProgramData\ClaudeCode\managed-settings.json. Vous pouvez déployer n’importe lequel de ces fichiers sous forme de lien symbolique, et Claude Code lit le fichier vers lequel pointe le lien. La politique s’applique toujours lorsque le lien pointe en dehors du répertoire système ou que Claude Code ne peut pas confirmer qu’il reste à l’intérieur. Un avertissement nommant le fichier apparaît alors dans /status et claude doctor. Pour supprimer l’avertissement, faites pointer le lien vers une cible à l’intérieur du répertoire système.
• Registre Windows HKCU : la même valeur Settings sous HKCU\SOFTWARE\Policies\ClaudeCode.

​

Diviser une politique basée sur fichier entre les équipes

• Valeurs uniques, comme "model": "opus" ou "cleanupPeriodDays": 7 : la valeur du fichier ultérieur remplace celle du fichier antérieur
• Listes, comme permissions.deny ou sandbox.network.allowedDomains : les deux listes se combinent, avec les doublons supprimés
• Blocs imbriqués, comme env ou sandbox : les deux blocs fusionnent clé par clé, et chaque clé à l’intérieur suit ces mêmes règles
• fallbackModel : la chaîne ultérieure remplace entièrement la chaîne antérieure
• extraKnownMarketplaces et managedMcpServers : une entrée ultérieure avec le même nom remplace entièrement celle antérieure
• modelPicker : la lineup ultérieure remplace entièrement la lineup antérieure

​

Comment Claude Code combine les sources gérées

• "first-wins", la valeur par défaut : Claude Code utilise la source la mieux classée qui livre au moins une clé de politique et ignore le reste plutôt que de les fusionner, à l’exception des clés dans Clés lues de chaque source d’administration. Claude Code n’affiche aucun avertissement pour les sources qu’il ignore ; /status nomme la source qu’il a utilisée et celles qu’il a ignorées.
• "merge" : Claude Code applique chaque source d’administration qui livre une clé de politique et les combine par type de clé : sur la plupart des clés, la valeur de la source la mieux classée s’applique, les listes s’unissent, et les verrous prennent la valeur la plus stricte. Composer chaque source gérée dit où définir la clé et comment chaque type de clé se combine. Nécessite Claude Code v2.1.242 ou ultérieur.

• Clé de politique : toute clé de paramètres autre que les deux clés de contrôle, wslInheritsWindowsSettings et managedSourcesBehavior. Un fichier de paramètres gérés ou une politique MDM qui contient uniquement ceux-ci ne compte pas, et Claude Code passe à la source suivante.
• Source d’administration : l’une des trois premières sources ci-dessous. Le registre HKCU modifiable par l’utilisateur n’en est pas une.

1. Paramètres distants, livrés de claude.ai comme paramètres gérés par le serveur ou par une passerelle d’applications Claude. Claude Code récupère cette source uniquement quand la session s’authentifie à l’API d’Anthropic directement avec des identifiants éligibles, se connecte à une passerelle avec /login, ou s’exécute dans l’onglet Code de Claude Desktop derrière une passerelle qui fournit des paramètres à cette session. Sur d’autres fournisseurs, ou quand ANTHROPIC_BASE_URL pointe ailleurs que l’API d’Anthropic, il commence à la source suivante
2. Politiques MDM ou au niveau du système d’exploitation : le plist macOS ou la clé de registre HKLM
3. Fichiers de paramètres gérés, managed-settings.d/*.json et managed-settings.json fusionnés ensemble
4. Le registre HKCU, sur Windows, et sur WSL une fois que le registre HKLM ou le fichier de paramètres gérés Windows active wslInheritsWindowsSettings et la valeur HKCU le définit également. Claude Code ne le lit que quand aucun document d’administration n’est présent au-dessus et aucun paramètre parent fourni par l’hôte ne fournit une clé restrictive

​

Quand un document d’administration est considéré comme présent

• Il définit une clé de politique à une valeur autre que null, même une valeur que Claude Code ne peut pas lire
• Il s’agit d’une valeur HKLM, d’un fichier de paramètres gérés ou d’un répertoire managed-settings.d qui existe mais ne peut pas être lu

​

Clés lues de chaque source d’administration

• sandbox.network.allowManagedDomainsOnly et sandbox.filesystem.allowManagedReadPathsOnly : un true dans n’importe quelle source d’administration active le verrou. Pendant qu’un verrou est actif, Claude Code unit la liste d’autorisation qu’il verrouille, sandbox.network.allowedDomains ensemble avec les règles d’autorisation WebFetch(domain:...), ou sandbox.filesystem.allowRead, de chaque source d’administration. Sans le verrou, Claude Code traite la liste d’autorisation comme n’importe quelle autre clé, donc sous "first-wins" la liste d’autorisation d’une source d’administration non sélectionnée est ignorée
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly : un true dans n’importe quelle source d’administration active le verrou de liste d’autorisation MCP. Pendant que le verrou est actif, la liste allowedMcpServers gérée provient de la source d’administration la mieux classée qui en définit une. Une liste gérée par le serveur remplace la liste d’une source inférieure plutôt que de se combiner avec elle. Si aucune source d’administration ne définit une liste, chaque serveur qui passe la liste de refus se charge, à moins que les paramètres parent ne fournissent une liste. Sans le verrou, Claude Code lit allowedMcpServers de la source gérée qu’il applique, donc sous "first-wins" la liste d’une source d’administration non sélectionnée est ignorée. Nécessite Claude Code v2.1.273 ou ultérieur
• deniedMcpServers et disableClaudeAiConnectors : une entrée ou un true dans n’importe quelle source d’administration s’applique. Nécessite Claude Code v2.1.273 ou ultérieur
• Les chemins binaires sandbox sandbox.bwrapPath et sandbox.socatPath
• Le binaire sandbox ripgrep, sandbox.ripgrep
• sandbox.filesystem.disabled et sandbox.network.strictAllowlist
• useAutoModeDuringPlan, syncClaudeAiSkills, et syncClaudeAiPlugins, où un false de n’importe quelle source d’administration désactive le comportement. Un false dans les paramètres utilisateur ou local du développeur le désactive également ; chaque clé ne peut que refuser
• enableArtifact, où un false de n’importe quelle source d’administration désactive l’outil Artifact. Un false dans les paramètres utilisateur, projet ou local du développeur le désactive également, et aucune source ne le réactive ; consultez quelles valeurs de niveau inférieur comptent toujours. Nécessite Claude Code v2.1.242 ou ultérieur
• maxEffortLevel, où le plafond le plus bas dans n’importe quelle source d’administration s’applique. Si un développeur définit un plafond plus bas dans ses propres paramètres ou avec --settings, Claude Code applique celui-ci ; aucune source ne peut augmenter le plafond. Nécessite Claude Code v2.1.267 ou ultérieur
• Une opt-out de commit-trailer dans attribution, ou dans le includeCoAuthoredBy déprécié, de n’importe quel niveau
• forceRemoteSettingsRefresh
• env, fusionné par variable de chaque source d’administration : chaque variable provient de la source de priorité la plus élevée qui la définit, donc les sources inférieures remplissent les variables que les sources supérieures laissent non définies. Quelques variables suivent leurs propres règles ; Exceptions par clé de chaque source gérée nomme chacune. Nécessite Claude Code v2.1.223 ou ultérieur. Avant v2.1.223, Claude Code appliquait uniquement le bloc env entier de la source sélectionnée

​

Composer chaque source gérée

​

Calculer la politique avec un programme d’aide

• L’objet managedSettings émis est le seul paramètre géré pour la session, y compris pour les clés qu’il lit autrement de chaque source d’administration, à l’exception de forceRemoteSettingsRefresh, qui a sa propre règle de démarrage

​

Laisser un hôte d’intégration ajouter une politique

• Quand n’importe quelle source d’administration définit allowManagedPermissionRulesOnly, Claude Code supprime les règles d’autorisation de permission fournies par le parent et additionalDirectories au fur et à mesure qu’il les lit, même quand une source de priorité plus élevée laisse la clé non définie. L’effet de la clé sur vos propres règles de permission provient des paramètres gérés que Claude Code applique, ou des paramètres parent que vous avez choisi de fusionner
• Claude Code applique la valeur forceLoginOrgUUID ou allowedMcpServers dans les paramètres gérés qu’il applique et bloque une valeur fournie par le parent. En dehors du verrou de liste d’autorisation MCP, une valeur dans une source d’administration inférieure que Claude Code n’applique pas ne s’applique ni ne bloque celle du parent. Sur Claude Code v2.1.273 ou ultérieur, pendant que allowManagedMcpServersOnly est actif, la liste allowedMcpServers de la source d’administration la mieux classée qui en définit une s’applique et bloque celle du parent, comme une clé inter-source. La liste du parent s’applique uniquement quand aucune source d’administration n’en définit une. L’entrée managedSourcesBehavior dit quelle source fournit chaque clé sous "merge". Avant v2.1.223, une valeur dans n’importe quelle source d’administration bloquait celle du parent
• Pour availableModels, Claude Code applique la valeur dans les paramètres gérés qu’il applique et bloque une liste fournie par le parent
• Pour strictKnownMarketplaces, Claude Code applique de la même manière la liste dans les paramètres gérés qu’il applique et bloque une liste fournie par le parent. La liste du parent s’applique uniquement quand aucune source gérée appliquée ne la définit. Nécessite Claude Code v2.1.282 ou ultérieur
• Pour allowedProviders, une liste dans la source gérée sélectionnée bloque une liste fournie par le parent, et avec l’activation de "merge" de managedSourcesBehavior, une liste dans n’importe quelle source d’administration la bloque. Nécessite Claude Code v2.1.285 ou ultérieur
• Un blockedMarketplaces fourni par le parent s’applique en plus de toute liste de blocage qu’une source gérée définit. Nécessite Claude Code v2.1.282 ou ultérieur

​

Garder l’accès au dossier Cowork quand seules les règles gérées s’appliquent

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

​

Ce qu’un développeur peut changer

• Le modèle pour une session : un model géré est une valeur par défaut, pas un verrou. --model et ANTHROPIC_MODEL choisissent toujours le modèle pour cette session, donc déployez availableModels pour restreindre le choix.
• La fenêtre de compaction automatique pour une session : un autoCompactWindow géré est également une valeur par défaut. Le flag --autocompact et la variable CLAUDE_CODE_AUTO_COMPACT_WINDOW définissent toujours la fenêtre de compaction automatique pour cette session.
• Droits d’administrateur local : un développeur qui est administrateur sur la machine peut modifier la source gérée elle-même, c’est pourquoi les outils MDM peuvent redéployer le profil ou le fichier selon un calendrier et pourquoi le registre HKLM et le domaine des préférences gérées macOS existent.
• Le cache géré par le serveur : les paramètres gérés par le serveur proviennent des serveurs d’Anthropic, et une modification du cache local dure uniquement jusqu’à la prochaine récupération réussie.
• Autres outils : les paramètres gérés lient uniquement Claude Code. Un développeur qui appelle l’API à partir d’un autre outil n’est pas sous eux.

​

Vérifier qu’une politique est en vigueur

​

Lire la source dans /status

• (remote) : paramètres gérés par le serveur de claude.ai ou une passerelle
• (plist) ou (HKLM) : une politique MDM ou au niveau du système d’exploitation
• (file), (drop-ins), ou (file + drop-ins) : managed-settings.json, le répertoire drop-in, ou les deux
• (remote + file, merged), ou une autre liste se terminant par , merged : votre organisation compose chaque source gérée, et Claude Code a fusionné les sources énumérées dans la politique. Une source inférieure peut toujours fournir des variables env sans apparaître dans la liste. Nécessite Claude Code v2.1.242 ou ultérieur
• (HKCU) : le registre de secours modifiable par l’utilisateur
• (parent process) : un hôte d’intégration a fourni des paramètres restrictifs
• (helper) : un policyHelper configuré par la source MDM ou fichier sélectionnée

• La ligne est manquante : Claude Code n’a trouvé aucune source gérée qui livre une clé de politique. Si vous avez déployé un fichier de paramètres gérés, vérifiez qu’il se trouve au chemin du système d’exploitation et qu’il contient une clé de politique plutôt que uniquement les clés de contrôle. Un fichier qui n’est pas un JSON valide ne produit pas cet état ; Claude Code refuse de démarrer à la place. Quand vous avez déployé via les paramètres gérés par le serveur à la place, exécutez claude doctor, qui signale le résultat de la récupération.
• La ligne nomme une source autre que celle que vous avez déployée : une source de priorité plus élevée est présente et Claude Code a ignoré la vôtre, et Skipped sources l’énumère. Comment Claude Code combine les sources gérées donne l’ordre.

​

Trouver les entrées que Claude Code a supprimées

• Fichier de paramètres gérés ou fichier drop-in : le fichier n’est pas un JSON valide, ou son niveau supérieur n’est pas un objet
• Plist MDM : le plutil de macOS signale le plist malformé, ou son contenu converti n’est pas un objet JSON
• Valeur de registre HKLM : la valeur Settings n’est pas une chaîne, est vide, ou ne contient pas un objet JSON

• Un fichier, profil, ou valeur de registre absent n’est pas une défaillance ; Claude Code s’exécute sans cette source.
• Un fichier de paramètres gérés vide compte comme {}.
• Une valeur malformée dans la clé de registre HKCU modifiable par l’utilisateur ne bloque jamais le lancement. Claude Code la signale comme un avis dans /status et claude doctor à la place.

• Si le système d’exploitation a refusé la lecture, par exemple sur un fichier réservé à root, chaque session démarre sans les politiques de cette source. /status et claude doctor enregistrent l’échec, et une exécution avec -p l’imprime également sur stderr.
• Pour tout autre échec de lecture, comme une erreur d’E/S, chaque session se termine au démarrage avec un message pour contacter un administrateur.

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

​

Clés qui échouent fermées

• Un null supprime la clé.
• Un disableAllHooks invalide, même un booléen entre guillemets, est supprimé avec un avertissement, car appliquer true déchargerait également les hooks que vos propres paramètres gérés déploient.
• Pour chaque autre clé booléenne que la règle couvre, la chaîne "true" ou "false" se lit comme ce booléen, avec un avis dans /status vous demandant de supprimer les guillemets.

• Un verrou à l’intérieur d’un, comme permissions.disableBypassPermissionsMode, se lit comme sa valeur restrictive.
• Un permissions.defaultMode invalide se lit comme default.
• Tandis qu’une liste deny ou ask dans permissions ne peut pas être lue du tout, Claude Code retient allow et additionalDirectories, donc les subventions ne s’appliquent jamais sans les restrictions écrites à côté. Le rapport nomme chaque subvention retenue et la liste qui ne pouvait pas être lue.
• Dans autoMode, une liste soft_deny ou hard_deny qui ne peut pas être lue, ou qui a perdu une entrée invalide, retient allow et environment de la même manière.

​

Valeurs invalides à l’intérieur de sandbox

• Si vous définissez une clé booléenne sur une "true" ou "false" entre guillemets, la valeur compte comme ce booléen. Au lieu d’un avertissement, /status affiche un avis vous demandant de supprimer les guillemets.
• Si failIfUnavailable est invalide, Claude Code supprime la valeur plutôt que de la traiter comme true, donc une valeur illisible ne bloque jamais les sessions de démarrage sur votre flotte.
• Claude Code traite chaque autre booléen invalide comme la valeur qui garde le sandbox le plus strict jusqu’à ce que vous la corrigiez. Une clé qui active le sandbox ou l’une de ses restrictions, comme enabled ou network.allowManagedDomainsOnly, compte comme true. Une clé qui l’assouplit, comme allowUnsandboxedCommands, compte comme false.
• Dans une liste en dehors de credentials, comme excludedCommands ou network.allowedDomains, Claude Code supprime une entrée invalide et garde le reste de la liste. Une liste qui n’est pas un tableau, ou qui n’a aucune entrée valide, ne s’applique pas du tout.
• Tandis que network.deniedDomains ou une entrée quelconque en elle est invalide, Claude Code retient également network.allowedDomains, donc la liste d’autorisation gérée n’accorde rien jusqu’à ce que vous corrigiez la liste de refus.
• Tandis que filesystem.denyRead, filesystem.denyWrite, ou une entrée quelconque dans l’une ou l’autre est invalide, Claude Code retient également filesystem.allowRead et filesystem.allowWrite jusqu’à ce que vous corrigiez la liste de refus.

​

Clés que seule une source gérée peut définir

​

Désactiver la télémétrie pour votre organisation

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

​

Voir aussi

• Configurer Claude Code pour votre organisation : décider ce qu’il faut appliquer et comment
• Paramètres gérés par le serveur : livrer la politique de la console claude.ai ou une passerelle
• Configuration MCP gérée : contrôler quels serveurs MCP les développeurs peuvent utiliser
• Tous les paramètres : chaque clé, avec si une source gérée peut la définir
• Fichiers de paramètres d’exemple : un managed-settings.json complet montrant la forme des clés gérées