SpyBara
Go Premium

managed-settings.md 2026-09-28 22:59 UTC to 2026-09-29 09:02 UTC

This page contains 101 additions and 66 deletions.

2026
Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Thu 24 22:57 Fri 25 23:58 Mon 28 22:59 Tue 29 09:02

Implantar configurações gerenciadas

Implante configurações gerenciadas na máquina de cada desenvolvedor: mecanismos de entrega por SO, como Claude Code combina fontes gerenciadas e como verificar a aplicação.

Configurações gerenciadas são as configurações que sua organização implanta na máquina de cada desenvolvedor. Claude Code as aplica acima de todos os outros níveis, portanto nenhum valor de usuário, projeto, local ou --settings as substitui, exceto por algumas exceções sensíveis à segurança onde um valor mais restritivo de um nível inferior ainda conta.

Esta página é para o administrador que implanta configurações gerenciadas ou depura por que uma não está sendo aplicada. Para decidir o que impor, comece com a tabela Decidir o que impor. Para o caminho do console claude.ai, consulte Configurações gerenciadas pelo servidor. Para saber em qual arquivo os valores próprios do desenvolvedor vão, consulte Configurações.

Implantar um arquivo de configurações gerenciadas

Esta é a forma mais rápida de colocar uma política em cada máquina: um arquivo managed-settings.json. Se você ainda não escolheu como entregar configurações gerenciadas, ou seus dispositivos estão sob MDM ou os desenvolvedores executam sessões na nuvem, leia primeiro Escolher um mecanismo de entrega.

1

Escrever managed-settings.json

Escreva um managed-settings.json que contenha as chaves que você decidiu impor, na mesma forma JSON que settings.json. A tabela Decidir o que impor lista as chaves por trás de cada controle, e cada entrada na referência de configurações diz se uma fonte gerenciada pode defini-la. Este arquivo bloqueia duas leituras de arquivo, desativa o modo de bypass e faz Claude Code ignorar regras de permissão de arquivos de usuário, projeto e local e de --allowedTools:

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

Para um exemplo mais completo que mostra a forma de mais chaves gerenciadas, incluindo o método de login, modelos, servidores MCP e marketplaces, consulte Configurações gerenciadas de uma organização.

2

Colocar o arquivo em cada máquina

Salve o arquivo como managed-settings.json no diretório do sistema para o sistema operacional, usando qualquer ferramenta que já coloque arquivos em sua frota:

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

Confirmar que a política foi aplicada

Em uma máquina, execute /status dentro de Claude Code. A linha Setting sources mostra Enterprise managed settings (file). Implante no resto da frota depois disso; Verificar que uma política está em vigor cobre o que observar quando a linha está faltando.

Escolher um mecanismo de entrega

O arquivo nas etapas acima é uma de quatro formas de colocar configurações gerenciadas em uma máquina. Cada mecanismo carrega as mesmas chaves de política que um arquivo settings.json, portanto a referência de configurações se aplica a todos eles. Algumas chaves estão vinculadas a fontes particulares, e a linha Scope de cada entrada diz qual:

Um arquivo de configurações gerenciadas, um perfil MDM ou o console claude.ai aplica uma política a todos que alcança. Para dar a um grupo de desenvolvedores uma política diferente, implante um arquivo ou perfil diferente para esse grupo; o console claude.ai ainda não pode direcionar um grupo, enquanto um gateway de aplicativos Claude auto-hospedado entrega configurações gerenciadas por grupo IdP.

Quando mais de um mecanismo entrega uma política para a mesma máquina, Claude Code por padrão usa um e ignora os outros. Como Claude Code combina fontes gerenciadas fornece a ordem e o opt-in que aplica cada fonte.

As linhas MDM e arquivo são chamadas juntas de configurações gerenciadas por endpoint, porque a política é armazenada no dispositivo do desenvolvedor, em oposição à linha gerenciada pelo servidor, onde Claude Code a busca.

Escolha um mecanismo por como você já gerencia dispositivos, usando a tabela abaixo.

Mecanismo Como você o entrega Quando Claude Code o lê Use quando
Configurações gerenciadas pelo servidor No console de administração claude.ai, ou em um gateway de aplicativos Claude auto-hospedado Buscado na inicialização e pesquisado a cada hora; consulte alterações que precisam de aprovação Você quer um lugar para alterar a política de uma organização claude.ai sem tocar em cada máquina
Política MDM ou nível do SO Como um perfil de configuração macOS ou um valor de registro HKLM do Windows, através de Jamf, Intune, Group Policy ou uma ferramenta similar; consulte onde cada mecanismo armazena a política Lido na inicialização e verificado quanto a alterações a cada 30 minutos Você já gerencia dispositivos com MDM ou Group Policy
Baseado em arquivo Como managed-settings.json em um diretório do sistema em cada máquina; consulte onde cada mecanismo armazena a política Lido na inicialização e recarregado quando um arquivo muda Máquinas sem MDM, hosts Linux ou imagens que você constrói você mesmo
Registro HKCU, Windows e WSL Como um valor de registro HKCU do Windows; consulte onde cada mecanismo armazena a política Lido na inicialização e verificado quanto a alterações a cada 30 minutos; Claude Code o usa apenas quando nenhum documento de administrador está presente acima dele e nenhuma configuração pai fornecida pelo host fornece uma chave restritiva Você não pode escrever a chave HKLM de nível de máquina

Modelos iniciais para Jamf, Iru, Intune e Group Policy estão no repositório de exemplos MDM.

Para servidores MCP gerenciados, que você implanta junto com qualquer um destes através de managed-mcp.json ou fornece através da chave managedMcpServers, consulte Configuração MCP gerenciada.

Onde e quando uma política se aplica

Uma política implantada alcança as sessões do desenvolvedor da seguinte forma:

  • Superfícies: na máquina do desenvolvedor, o terminal, as extensões VS Code e JetBrains, a aba Code do aplicativo desktop e as sessões Agent SDK leem todas essas fontes. As sessões Agent SDK carregam configurações gerenciadas mesmo quando settingSources exclui os arquivos de usuário, projeto e local.

  • Sessões na nuvem: uma sessão em um ambiente hospedado pela Anthropic não lê um perfil MDM ou arquivo de dispositivo, portanto a política para ela deve vir de configurações gerenciadas pelo servidor. Uma sessão em um ambiente auto-hospedado também lê o arquivo de configurações gerenciadas em sua imagem de executor, por padrão apenas quando as configurações gerenciadas pelo servidor não entregam nenhuma chave de política, exceto pelas chaves que Claude Code lê de cada fonte de administrador. Como Claude Code combina fontes gerenciadas cobre o opt-in que aplica ambas.

  • Sessões Cowork: Cowork no aplicativo Claude Desktop executa suas sessões em Claude Code. Em uma sessão Cowork, Claude Code nunca busca configurações gerenciadas pelo servidor do console de administração claude.ai, mesmo quando o usuário se conecta com uma conta Team ou Enterprise, portanto qual política se aplica depende de onde a sessão é executada:

    • Na máquina do usuário: por padrão, Claude Code em uma sessão Cowork lê a política MDM ou nível do SO e o arquivo de configurações gerenciadas nesse dispositivo, portanto implante a política lá.
    • Em um sandbox de VM completa: quando sua configuração gerenciada do Claude Desktop define requireCoworkFullVmSandbox, Claude Code é executado dentro de uma máquina virtual onde a política MDM do dispositivo e o arquivo de configurações gerenciadas não estão presentes.
    • Sessões Cowork remotas: estas são executadas em VMs gerenciadas pela Anthropic, onde Claude Code não tem política de dispositivo para ler.

    Onde quer que a sessão seja executada, claude.ai aplica as listas strictKnownMarketplaces e blockedMarketplaces do console de administração quando alguém adiciona um marketplace de um repositório git em claude.ai ou de Customize na aba Cowork. Como as restrições funcionam descreve essa verificação. A tabela cobertura de superfície compara Cowork com as outras superfícies.

  • Sessões em execução: a maioria das alterações alcança uma sessão em execução no cronograma na tabela de mecanismo de entrega, sem uma reinicialização.

  • Alterações que precisam de aprovação: além das atualizações que aguardam o próximo lançamento, uma alteração gerenciada pelo servidor em uma configuração que precisa de aprovação, como um hook ou uma variável env, aguarda o desenvolvedor aceitar o diálogo em uma sessão interativa e se aplica para a execução atual em uma sessão que uma extensão IDE ou o Agent SDK hospeda. Outras alterações gerenciadas pelo servidor se aplicam na próxima pesquisa.

  • Sessões de longa duração: uma sessão deixada aberta por semanas ainda pode ficar para trás em um lançamento. requiredMinimumVersion bloqueia um binário desatualizado de iniciar e não encerra uma sessão que já está em execução.

Onde cada mecanismo armazena a política

As chaves são as mesmas em todos os lugares, mas cada mecanismo as armazena em um lugar e forma diferentes:

  • Gerenciado pelo servidor: os servidores da Anthropic, ou seu gateway, mantêm a política. Claude Code mantém um cache local que aplica na inicialização e substitui em cada busca bem-sucedida.
  • Perfil de configuração macOS: o domínio de preferências gerenciadas com.anthropic.claudecode. Use as mesmas chaves de nível superior que managed-settings.json, com configurações aninhadas como dicionários e listas como arrays plist.
  • Registro HKLM do Windows: o JSON como um valor REG_SZ ou REG_EXPAND_SZ nomeado Settings sob HKLM\SOFTWARE\Policies\ClaudeCode.
  • Baseado em arquivo: managed-settings.json, um diretório opcional managed-settings.d/ e managed-mcp.json no diretório do sistema: /Library/Application Support/ClaudeCode/ no macOS, /etc/claude-code/ no Linux e WSL, e C:\Program Files\ClaudeCode\ no Windows. Claude Code não lê o caminho legado do Windows C:\ProgramData\ClaudeCode\managed-settings.json.
  • Registro HKCU do Windows: o mesmo valor Settings sob HKCU\SOFTWARE\Policies\ClaudeCode.

Dividir uma política baseada em arquivo entre equipes

Se várias equipes possuem partes de uma política, coloque cada parte em seu próprio arquivo em managed-settings.d/, ao lado de managed-settings.json no mesmo diretório do sistema, em vez de editar um arquivo compartilhado.

Claude Code mescla managed-settings.json primeiro, depois cada arquivo *.json no diretório em ordem alfabética. Nomeie os arquivos com prefixos numéricos para controlar a ordem, como 10-telemetry.json e 20-security.json. Claude Code ignora arquivos ocultos e arquivos que não terminam em .json.

Quando dois arquivos definem a mesma chave, Claude Code os combina por estas regras:

  • Valores únicos, como "model": "opus" ou "cleanupPeriodDays": 7: o valor do arquivo posterior substitui o anterior
  • Listas, como permissions.deny ou sandbox.network.allowedDomains: as duas listas se combinam, com duplicatas removidas
  • Blocos aninhados, como env ou sandbox: os dois blocos se mesclam chave por chave, e cada chave dentro segue essas mesmas regras
  • fallbackModel: a cadeia posterior substitui a anterior inteira
  • extraKnownMarketplaces e managedMcpServers: uma entrada posterior com o mesmo nome substitui a anterior inteira
  • modelPicker: o lineup posterior substitui o anterior inteiro

Como Claude Code combina fontes gerenciadas

Quando sua organização entrega mais de uma fonte gerenciada para a mesma máquina, a chave managedSourcesBehavior decide o que Claude Code faz com as outras:

  • "first-wins", o padrão: Claude Code usa a fonte com classificação mais alta que entrega pelo menos uma chave de política e ignora o resto em vez de mesclá-las, exceto pelas chaves em Chaves lidas de cada fonte de administrador. Claude Code não mostra aviso para as fontes que pula; /status nomeia a fonte que usou e as que pulou.
  • "merge": Claude Code aplica cada fonte de administrador que entrega uma chave de política e as combina por tipo de chave: na maioria das chaves o valor da fonte com classificação mais alta se aplica, listas se unem, e bloqueios assumem o valor mais restritivo. Componha cada fonte gerenciada diz onde definir a chave e como cada tipo de chave se combina. Requer Claude Code v2.1.242 ou posterior.

Ambas as configurações classificam as fontes da mesma forma. Estes termos recorrem nesta seção:

  • Chave de política: qualquer chave de configurações diferente das duas chaves de controle, wslInheritsWindowsSettings e managedSourcesBehavior. Um arquivo de configurações gerenciadas ou política MDM que contém apenas aquelas não conta, e Claude Code passa para a próxima fonte.
  • Fonte de administrador: uma das três primeiras fontes abaixo. O registro HKCU é gravável pelo usuário e não é uma.

Claude Code verifica as fontes nesta ordem, prioridade mais alta primeiro:

  1. Configurações remotas, entregues de claude.ai como configurações gerenciadas pelo servidor ou por um gateway de aplicativos Claude. Claude Code busca esta fonte apenas quando a sessão se autentica na API da Anthropic diretamente com um login ou chave elegível, ou faz login em um gateway com /login. Em outros provedores, ou quando ANTHROPIC_BASE_URL aponta para algum lugar diferente da API da Anthropic, começa na próxima fonte
  2. Políticas MDM ou de nível do SO: a plist do macOS ou a chave de registro HKLM
  3. Arquivos de configurações gerenciadas, managed-settings.d/*.json e managed-settings.json mesclados juntos
  4. O registro HKCU, no Windows, e no WSL uma vez que o registro HKLM ou o arquivo de configurações gerenciadas do Windows ativa wslInheritsWindowsSettings e o valor HKCU também o define. Claude Code o lê apenas quando nenhum documento de administrador está presente acima dele e nenhuma configuração pai fornecida pelo host fornece uma chave restritiva

Claude Code nunca aplica o registro HKCU gravável pelo usuário sob um documento de administrador que está presente. Um documento está presente quando define qualquer chave de política para um valor diferente de null, mesmo um valor que Claude Code não consegue ler. Um valor HKLM, arquivo de configurações gerenciadas, ou diretório managed-settings.d que existe mas não consegue ser lido também está presente. No WSL, /etc/claude-code também é gravável pelo usuário, e a entrada wslInheritsWindowsSettings diz quando os documentos do Windows estão acima dele.

Este diagrama mostra a classificação, com exemplos das chaves entre fontes que Claude Code lê das três primeiras fontes sob qualquer configuração:

Diagrama mostrando as quatro fontes de configurações gerenciadas classificadas de configurações remotas no topo através de MDM, arquivos de configurações gerenciadas, e o registro HKCU na parte inferior. Por padrão, a primeira fonte com uma chave de política fornece a política e o resto é pulado; com managedSourcesBehavior definido como merge, cada fonte de administrador com uma chave de política contribui, combinada por tipo de chave, e o registro HKCU fica de fora. Um painel lateral mostra que chaves entre fontes como os bloqueios de sandbox, forceRemoteSettingsRefresh, e o merge env por variável são lidos de cada fonte de administrador, que exclui o registro HKCU. Diagrama mostrando as quatro fontes de configurações gerenciadas classificadas de configurações remotas no topo através de MDM, arquivos de configurações gerenciadas, e o registro HKCU na parte inferior. Por padrão, a primeira fonte com uma chave de política fornece a política e o resto é pulado; com managedSourcesBehavior definido como merge, cada fonte de administrador com uma chave de política contribui, combinada por tipo de chave, e o registro HKCU fica de fora. Um painel lateral mostra que chaves entre fontes como os bloqueios de sandbox, forceRemoteSettingsRefresh, e o merge env por variável são lidos de cada fonte de administrador, que exclui o registro HKCU.

Chaves lidas de cada fonte de administrador

Sob a configuração padrão "first-wins", Claude Code lê a maioria das chaves apenas da fonte que selecionou, e ignora um valor em uma fonte com classificação mais baixa mesmo quando a fonte selecionada deixa essa chave indefinida.

Algumas chaves funcionam diferentemente. Claude Code as lê de cada fonte de administrador, então uma política MDM com classificação mais baixa ou arquivo de configurações gerenciadas ainda pode defini-las quando a fonte selecionada não o faz. Claude Code deixa o registro HKCU gravável pelo usuário de fora dessa verificação; quando HKCU é a única fonte e nenhum host fornece configurações pai, HKCU se aplica como qualquer fonte selecionada.

As chaves entre fontes incluem:

  • sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly: um true em qualquer fonte de administrador ativa o bloqueio. Enquanto um bloqueio está ativo, Claude Code une a lista de permissões que bloqueia, sandbox.network.allowedDomains junto com regras de permissão WebFetch(domain:...), ou sandbox.filesystem.allowRead, em cada fonte de administrador. Sem o bloqueio, Claude Code trata a lista de permissões como qualquer outra chave, então sob "first-wins" a lista de permissões de uma fonte de administrador não selecionada é ignorada

  • allowAllClaudeAiMcps

  • allowManagedMcpServersOnly: um true em qualquer fonte de administrador ativa o bloqueio de lista de permissões MCP. Enquanto o bloqueio está ativo, a lista allowedMcpServers gerenciada vem da fonte de administrador com classificação mais alta que define uma. Uma lista gerenciada pelo servidor substitui a lista de uma fonte mais baixa em vez de se combinar com ela.

    Se nenhuma fonte de administrador define uma lista, cada servidor que passa a lista de negação é carregado, a menos que configurações pai forneçam uma lista.

    Sem o bloqueio, Claude Code lê allowedMcpServers da fonte gerenciada que aplica, então sob "first-wins" a lista de uma fonte de administrador não selecionada é ignorada. Requer Claude Code v2.1.273 ou posterior

  • deniedMcpServers e disableClaudeAiConnectors: uma entrada ou um true em qualquer fonte de administrador se aplica. Requer Claude Code v2.1.273 ou posterior

  • Os caminhos binários de sandbox sandbox.bwrapPath e sandbox.socatPath

  • O binário ripgrep de sandbox, sandbox.ripgrep

  • sandbox.filesystem.disabled e sandbox.network.strictAllowlist

  • useAutoModeDuringPlan, syncClaudeAiSkills, e syncClaudeAiPlugins, onde um false de qualquer fonte de administrador desativa o comportamento. Um false nas configurações de usuário ou local do desenvolvedor também o desativa; cada chave pode apenas negar

  • enableArtifact, onde um false de qualquer fonte de administrador desativa a ferramenta Artifact. Um false nas configurações de usuário, projeto ou local do desenvolvedor também o desativa, e nenhuma fonte o ativa novamente; veja quais valores de nível mais baixo ainda contam. Requer Claude Code v2.1.242 ou posterior

  • maxEffortLevel, onde o limite mais baixo em qualquer fonte de administrador se aplica. Se um desenvolvedor define um limite mais baixo em suas próprias configurações ou com --settings, Claude Code aplica aquele; nenhuma fonte pode aumentar o limite. Requer Claude Code v2.1.267 ou posterior

  • Um opt-out de trailer de commit em attribution, ou no includeCoAuthoredBy descontinuado, de qualquer nível

  • forceRemoteSettingsRefresh

  • env, mesclado por variável em fontes de administrador: cada variável vem da fonte de prioridade mais alta que a define, então fontes mais baixas preenchem variáveis que as mais altas deixam indefinidas. Algumas variáveis seguem suas próprias regras; Exceções por chave em fontes gerenciadas nomeia cada uma. Requer Claude Code v2.1.223 ou posterior. Antes de v2.1.223, Claude Code aplicava apenas o bloco env inteiro da fonte selecionada

As chaves de login do gateway seguem uma regra separada. Claude Code nunca as lê de configurações gerenciadas pelo servidor, então enquanto configurações gerenciadas pelo servidor são a fonte selecionada, a fonte de administrador com classificação mais alta na máquina que carrega uma chave de política ainda as fornece. Um valor em uma fonte de administrador classificada abaixo daquela, ou no registro HKCU, é ignorado.

Quando uma fonte de administrador define allowManagedMcpServersOnly ou uma lista allowedMcpServers e esse valor não é o que está em vigor, /status e claude doctor nomeiam essa fonte e chave.

Componha cada fonte gerenciada

Para ter Claude Code aplicar cada fonte de administrador que sua organização entrega, defina managedSourcesBehavior como "merge" na fonte com classificação mais alta que você implanta. Claude Code lê a chave apenas da fonte com classificação mais alta que carrega a chave ou uma chave de política, então uma fonte mais baixa não pode se optar para mesclar com a fonte acima dela, e uma máquina que nunca recebe configurações gerenciadas pelo servidor precisa da chave em seu perfil MDM também. O registro HKCU gravável pelo usuário nunca se mescla com outra fonte. Requer Claude Code v2.1.242 ou posterior.

Sob "merge", Claude Code adiciona entradas de lista de uma fonte mais baixa, como regras permissions.allow e hooks, à política, então ative-o apenas quando cada fonte classificada abaixo da sua mais alta estiver sob controle de um administrador.

Esta tabela mostra como Claude Code combina cada tipo de chave sob "merge". A entrada managedSourcesBehavior nomeia cada chave em três das linhas: listas de permissões de restrição, valores tomados inteiros, e chaves lidas apenas da fonte com classificação mais alta.

Tipo de chave Como Claude Code a combina Exemplos
Listas Combina as entradas de cada fonte permissions.allow, hooks, sandbox.network.allowedDomains, deniedMcpServers, deniedModels
Bloqueios Aplica o valor mais restritivo que qualquer fonte define; um valor mais solto se aplica apenas da fonte com classificação mais alta allowManagedHooksOnly, permissions.disableBypassPermissionsMode, crossSessionInbound, availableModelsMatch
Listas de permissões de restrição Toma a lista inteira da fonte com classificação mais alta que a define, sem adicionar entradas de fontes mais baixas availableModels, allowedMcpServers, strictKnownMarketplaces, allowedChannelPlugins, e a cadeia fallbackModel
Valores tomados inteiros Toma o valor inteiro da fonte com classificação mais alta que o define, sem combinar entradas ou campos de fontes mais baixas sandbox.credentials.awsPairs, sandbox.ripgrep
Servidores MCP fornecidos Combina os nomes de servidor de cada fonte; quando duas fontes definem o mesmo nome, aplica a entrada inteira da fonte com classificação mais alta managedMcpServers
Chaves lidas apenas da fonte com classificação mais alta Ignora a chave em cada fonte mais baixa, mesmo quando a fonte com classificação mais alta a deixa indefinida Auxiliares de credencial como apiKeyHelper, pins de login como forceLoginOrgUUID, modelPicker, permissions.defaultMode
env Mescla por variável em fontes de administrador sob qualquer configuração, como Chaves lidas de cada fonte de administrador descreve
Qualquer outra chave Toma o valor da fonte com classificação mais alta que o define model, cleanupPeriodDays

Para confirmar quais fontes se combinaram em uma máquina, leia a linha Setting sources em /status; essa seção diz o que cada rótulo significa.

Calcule a política com um programa auxiliar

Um policyHelper é um executável que sua política MDM ou arquivo de configurações gerenciadas nomeia, e Claude Code o executa para calcular configurações gerenciadas na inicialização. Quando a fonte selecionada configura um e o auxiliar emite um objeto managedSettings, essa saída muda o que Claude Code lê:

Para quais execuções de auxiliar falham, e o que Claude Code faz quando uma falha, veja Falhas de auxiliar.

Deixe um host de incorporação adicionar política

Quando outro aplicativo inicia Claude Code, como Claude Desktop, uma extensão IDE, ou um aplicativo Agent SDK, esse host pode passar suas próprias configurações gerenciadas através da opção SDK managedSettings. Claude Code chama essas configurações pai.

Por padrão, Claude Code ignora configurações pai sempre que uma fonte de administrador está presente: configurações gerenciadas pelo servidor, uma política MDM ou de nível do SO, ou um arquivo de configurações gerenciadas.

Para ter Claude Code mesclar configurações pai junto com uma fonte de administrador, defina parentSettingsBehavior como "merge" na fonte gerenciada de prioridade mais alta; Claude Code lê a chave apenas dessa fonte.

Claude Code então mantém apenas os valores do host que restringem o que Claude pode fazer, com uma lacuna a saber: a menos que você também defina os bloqueios allowManaged*Only, as regras de permissão de permissão do host e listas de permissões de sandbox ainda se aplicam. Veja Restrinja configurações pai para os bloqueios.

Um policyHelper pode desativar a mesclagem pai independentemente dessa chave; sua entrada diz quando.

Claude Code também aplica essas verificações a valores fornecidos pelo pai por conta própria:

  • Quando qualquer fonte de administrador define allowManagedPermissionRulesOnly, Claude Code descarta regras de permissão de permissão fornecidas pelo pai e additionalDirectories conforme as lê, mesmo quando uma fonte de prioridade mais alta deixa a chave indefinida. O efeito da chave em suas próprias regras de permissão vem das configurações gerenciadas que Claude Code aplica, ou de configurações pai que você escolheu mesclar

  • Claude Code impõe o valor forceLoginOrgUUID ou allowedMcpServers nas configurações gerenciadas que aplica e bloqueia um fornecido pelo pai. Fora do bloqueio de lista de permissões MCP, um valor em uma fonte de administrador mais baixa que Claude Code não aplica nem se aplica nem bloqueia o do pai.

    No Claude Code v2.1.273 ou posterior, enquanto allowManagedMcpServersOnly está ativo, a lista allowedMcpServers da fonte de administrador com classificação mais alta que define uma se aplica e bloqueia a do pai, como uma chave entre fontes. A lista do pai se aplica apenas quando nenhuma fonte de administrador define uma. A entrada managedSourcesBehavior diz qual fonte fornece cada chave sob "merge". Antes de v2.1.223, um valor em qualquer fonte de administrador bloqueava a do pai

  • Para availableModels, Claude Code impõe o valor nas configurações gerenciadas que aplica e bloqueia uma lista fornecida pelo pai

  • Para strictKnownMarketplaces, Claude Code igualmente impõe a lista nas configurações gerenciadas que aplica e bloqueia uma fornecida pelo pai. A lista do pai se aplica apenas quando nenhuma fonte gerenciada aplicada define uma. Requer Claude Code v2.1.282 ou posterior

  • Um blockedMarketplaces fornecido pelo pai se aplica além de qualquer lista de negação que uma fonte gerenciada define. Requer Claude Code v2.1.282 ou posterior

Mantenha o acesso à pasta Cowork quando apenas regras gerenciadas se aplicam

Cowork no aplicativo Claude Desktop executa suas sessões no Claude Code e concede a cada sessão acesso às suas pastas de trabalho, como a pasta que o usuário conecta, através de regras de permissão que fornece quando inicia a sessão. Quando sua política gerenciada define allowManagedPermissionRulesOnly, Claude Code mantém apenas as regras de permissão na política gerenciada: descarta regras de permissão que um host fornece como configurações pai, como --allowedTools, ou em um arquivo de configurações, então gravações nessas pastas perdem sua pré-aprovação. Em uma sessão Cowork que pede antes de edições, Cowork não consegue mostrar o prompt, e Claude relata cada gravação como bloqueada porque o caminho se resolve para um local protegido ou um caminho fora da pasta conectada.

Para restaurar as gravações, adicione regras de permissão para essas pastas à fonte gerenciada que Claude Code seleciona nessas máquinas: em uma frota gerenciada por MDM, essa é a política MDM em vez de um arquivo de configurações gerenciadas separado. Este exemplo usa a forma de arquivo, e uma política MDM toma as mesmas chaves. Mantém allowManagedPermissionRulesOnly definido e permite edições sob uma pasta CoworkProjects no diretório inicial de cada usuário; substitua o caminho pelas pastas que seus usuários conectam:

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

Depois de implantar a política, Claude pode salvar arquivos sob essa pasta em uma nova sessão Cowork. Regras de leitura e edição cobrem a sintaxe de caminho, incluindo a forma // para caminhos absolutos.

O que um desenvolvedor pode mudar

Os próprios arquivos de configurações de um desenvolvedor, valores --settings, e arquivos de projeto nunca substituem um valor gerenciado; as exceções apenas deixam um valor de nível mais baixo mais restritivo contar. Estes casos ficam fora dessa regra:

  • O modelo para uma sessão: um model gerenciado é um padrão, não um bloqueio. --model e ANTHROPIC_MODEL ainda escolhem o modelo para essa sessão, então implante availableModels para restringir a escolha.
  • Direitos de administrador local: um desenvolvedor que é um administrador na máquina pode editar a própria fonte gerenciada, é por isso que a ferramenta MDM pode reimplantar o perfil ou arquivo em um cronograma e por que o registro HKLM e o domínio de preferências gerenciadas do macOS existem.
  • O cache gerenciado pelo servidor: configurações gerenciadas pelo servidor vêm dos servidores da Anthropic, e uma edição no cache local dura apenas até a próxima busca bem-sucedida.
  • Outras ferramentas: configurações gerenciadas vinculam apenas Claude Code. Um desenvolvedor que chama a API de outra ferramenta não está sob elas.

Verificar que uma política está em vigor

Um desenvolvedor relata que uma política não está sendo aplicada, ou você quer confirmar que um lançamento chegou antes de empurrá-lo para a frota. Dois comandos nessa máquina respondem: /status mostra qual fonte gerenciada Claude Code selecionou, e claude doctor lista o que descartou.

Ler a fonte em /status

Na máquina do desenvolvedor, execute /status dentro de Claude Code e leia a linha Setting sources. Quando uma fonte gerenciada está em vigor, a linha lista Enterprise managed settings com a fonte que Claude Code selecionou entre parênteses:

  • (remote): configurações gerenciadas pelo servidor do claude.ai ou um gateway
  • (plist) ou (HKLM): uma política MDM ou nível do SO
  • (file), (drop-ins) ou (file + drop-ins): managed-settings.json, o diretório drop-in ou ambos
  • (remote + file, merged) ou outra lista terminando em , merged: sua organização compõe cada fonte gerenciada e Claude Code mesclou as fontes listadas na política. Uma fonte inferior ainda pode fornecer variáveis env sem aparecer na lista. Requer Claude Code v2.1.242 ou posterior
  • (HKCU): o fallback de registro gravável pelo usuário
  • (parent process): um host de incorporação forneceu configurações restritivas
  • (helper): um policyHelper configurado pela fonte MDM ou arquivo selecionada

Quando Claude Code encontrou uma fonte gerenciada na máquina e não a selecionou, uma segunda linha, Skipped sources, nomeia cada tal fonte. Leia-a para distinguir uma política que nunca alcançou a máquina de uma que alcançou e que uma fonte de prioridade mais alta substituiu. Requer Claude Code v2.1.242 ou posterior.

Quando a política não está sendo aplicada, a linha Setting sources diz qual de dois problemas você tem:

  • A linha está faltando: Claude Code não encontrou nenhuma fonte gerenciada que entregue uma chave de política.

    Se você implantou um arquivo de configurações gerenciadas, verifique se ele fica no caminho para o SO e se contém uma chave de política em vez de apenas as chaves de controle. Um arquivo que não é JSON válido não produz este estado; Claude Code recusa iniciar em vez disso.

    Quando você implantou através de configurações gerenciadas pelo servidor em vez disso, execute claude doctor, que relata o resultado da busca.

  • A linha nomeia uma fonte diferente da que você implantou: uma fonte de prioridade mais alta está presente e Claude Code ignorou a sua, e Skipped sources a lista. Como Claude Code combina fontes gerenciadas fornece a ordem.

Encontrar entradas que Claude Code descartou

Se seu arquivo de configurações gerenciadas, perfil MDM, valor de registro ou payload gerenciado pelo servidor falhar na validação de esquema, Claude Code primeiro pula as entradas individuais que pode reparar, como uma regra de permissão inválida, e avisa sobre cada uma. Claude Code então descarta qualquer valor que ainda falha, a menos que o valor pertença a uma das chaves que falham fechadas em vez disso.

Claude Code é mais rigoroso com o managedSettings que um policyHelper emite: faz os mesmos reparos de entrada, mas qualquer violação de esquema que sobreviva falha a execução inteira do auxiliar, e na inicialização Claude Code recusa iniciar, o mesmo que para um auxiliar que sai com código diferente de zero.

Quando um arquivo de configurações gerenciadas, arquivo drop-in, plist MDM ou valor de registro HKLM está presente mas não pode ser analisado como um objeto JSON, Claude Code recusa iniciar e imprime um erro nomeando a fonte, mesmo quando outra fonte de administrador entrega uma política válida. Cada fonte falha desta forma quando:

  • Arquivo de configurações gerenciadas ou arquivo drop-in: o arquivo não é JSON válido, ou seu nível superior não é um objeto
  • Plist MDM: o plutil do macOS relata o plist malformado, ou seu conteúdo convertido não é um objeto JSON
  • Valor de registro HKLM: o valor Settings não é uma string, está vazio ou não contém um objeto JSON

Três estados de fonte não causam essa recusa:

  • Um arquivo, perfil ou valor de registro ausente não é uma falha; Claude Code é executado sem essa fonte.
  • Um arquivo de configurações gerenciadas vazio conta como {}.
  • Um valor malformado na chave de registro HKCU gravável pelo usuário nunca bloqueia o lançamento. Claude Code o relata como um aviso em /status e claude doctor em vez disso.

Se um arquivo de configurações gerenciadas, arquivo drop-in ou diretório managed-settings.d/ não puder ser lido e nenhuma fonte de administrador fornecer uma política, sessões conectadas com credenciais claude.ai ou Claude Console saem na inicialização com uma mensagem para contatar um administrador.

Para encontrar uma entrada descartada, procure em um de três lugares:

  • Sessões interativas mostram um diálogo na inicialização listando as entradas inválidas.
  • Execuções não interativas com -p imprimem um resumo para stderr.
  • claude doctor lista cada entrada inválida com sua fonte e campo.

Chaves que falham fechadas

Quando uma fonte gerenciada define uma chave de nível superior que tem um único valor restritivo, como allowManagedPermissionRulesOnly, disableAutoMode ou skipDangerousModePermissionPrompt, para algo que Claude Code não consegue ler, a chave lê como esse valor até você corrigi-la. O relatório diz que a chave was present but invalid e nomeia o valor que Claude Code trata como. Para uma chave dentro de sandbox, consulte Valores inválidos dentro de sandbox.

Estes casos não falham fechados:

  • Um null remove a chave.
  • Um disableAllHooks inválido, mesmo um booleano entre aspas, é descartado com um aviso, porque aplicar true também descarregaria os hooks que suas próprias configurações gerenciadas implantam.
  • Para cada outra chave booleana que a regra cobre, a string "true" ou "false" lê como esse booleano, com um aviso em /status pedindo que você remova as aspas.

Claude Code repara os blocos permissions, autoMode, worktree e attribution por campo em vez de descartá-los inteiros:

  • Um lock dentro de um, como permissions.disableBypassPermissionsMode, lê como seu valor restritivo.
  • Um permissions.defaultMode inválido lê como default.
  • Enquanto uma lista deny ou ask em permissions não puder ser lida, Claude Code retém allow e additionalDirectories, portanto as concessões nunca se aplicam sem as restrições escritas ao lado delas. O relatório nomeia cada concessão retida e a lista que não pôde ser lida.
  • Em autoMode, uma lista soft_deny ou hard_deny que não puder ser lida, ou que perdeu uma entrada inválida, retém allow e environment da mesma forma.

A regra de falha fechada para chaves com um único valor restritivo e os reparos por campo requerem Claude Code v2.1.282 ou posterior.

Estas chaves têm seu próprio fallback:

Campo Comportamento quando presente mas inválido
allowedMcpServers Aplicado como uma lista de permissões vazia até que o valor seja corrigido, portanto nenhum servidor MCP que os usuários adicionem é admitido. Servidores que sua organização entrega através de managedMcpServers ainda carregam, e servidores managed-mcp.json carregam por Como um servidor é avaliado. Uma entrada individual inválida é removida e o subconjunto válido é aplicado.
allowedHttpHookUrls Claude Code aplica uma lista de permissões gerenciada vazia até que você corrija o valor, portanto um hook HTTP é executado apenas se outro arquivo de configurações listar sua URL. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto.
httpHookAllowedEnvVars Claude Code aplica uma lista de permissões gerenciada vazia até que você corrija o valor, portanto uma variável de cabeçalho é interpolada apenas se outro arquivo de configurações a nomear. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto.
allowedChannelPlugins Claude Code aplica uma lista de permissões vazia até que você corrija o valor, portanto nenhum plugin de canal passado para --channels é admitido. Se apenas uma entrada individual for inválida, ele remove essa entrada e aplica o resto.
strictKnownMarketplaces Aplicado como uma lista de permissões vazia até que o valor seja corrigido, portanto nenhuma fonte de marketplace é admitida. Uma entrada individual que é inválida ou não pode ser aplicada, como um regex hostPattern que não compila, é removida e o subconjunto válido é aplicado.
availableModels Aplicado como uma lista de permissões vazia até ser corrigido, portanto apenas o modelo Padrão está disponível; uma entrada não-string é removida e o subconjunto válido é aplicado.
availableModelsMatch Tratado como exact até que o valor seja corrigido.
forceLoginOrgUUID Nenhuma organização é permitida fazer login até que o valor seja corrigido.
gatewayInternalNetworks Quando o valor inválido vem da fonte gerenciada mais alta na máquina, /login recusa cada novo gateway de nuvem login na máquina até que o valor seja corrigido.
crossSessionInbound Tratado como refuse, o valor mais restritivo, portanto mensagens entre sessões de entrada são recusadas até que o valor seja corrigido. O desenvolvedor vê um aviso.
deniedMcpServers Uma entrada individual inválida é removida e o subconjunto válido é aplicado. Um valor totalmente inválido é descartado com um aviso, já que negar cada servidor bloquearia servidores que a política nunca nomeou.
deniedModels Uma entrada não-string é removida e o resto da lista é aplicado. Um valor totalmente inválido é descartado com um aviso e bloqueia nenhum modelo até ser corrigido.
blockedMarketplaces Uma entrada individual inválida é removida e o subconjunto válido é aplicado. Uma entrada que analisa mas nunca pode corresponder, como um regex hostPattern que não compila, é mantida com um aviso. Ela bloqueia nada até ser corrigida, mas restrições de marketplace permanecem ativas. Um valor totalmente inválido é descartado com um aviso, já que bloquear cada marketplace bloquearia fontes que a política nunca nomeou.
sandbox Quando um valor dentro do bloco é inválido, Claude Code não descarta o bloco inteiro. Para o que acontece com cada tipo de campo inválido, consulte Valores inválidos dentro de sandbox.
sandbox.credentials Uma entrada inválida recuperável é degradada para mode: "deny" com um aviso; uma irrecuperável é removida; entradas válidas permanecem aplicadas. Consulte entradas de credencial inválidas.
strictPluginOnlyCustomization Tratado como true, bloqueando todas as quatro superfícies, quando o valor não é nem um booleano nem um array. Uma entrada de array que esta versão não reconhece como uma superfície bloqueia nada; uma nota de status conta tais entradas para que você possa verificá-las quanto a erros de digitação.
enabledPlugins Uma entrada inválida é descartada com um aviso e as outras entradas permanecem aplicadas. Um valor que não é um mapa de IDs de plugin, ou cujas entradas são todas inválidas, é descartado inteiro com um aviso.

allowedHttpHookUrls e httpHookAllowedEnvVars mesclam entre arquivos de configurações, portanto entradas em suas configurações de usuário, projeto ou local ainda se aplicam enquanto a lista gerenciada está vazia.

Os fallbacks para essas duas chaves e para allowedChannelPlugins requerem Claude Code v2.1.267 ou posterior; versões anteriores descartam a chave inteira quando seu valor ou qualquer entrada é inválida. Os fallbacks para strictKnownMarketplaces e blockedMarketplaces requerem Claude Code v2.1.277 ou posterior; versões anteriores descartam a chave inteira quando seu valor ou qualquer entrada é inválida. Os fallbacks para strictPluginOnlyCustomization e enabledPlugins requerem Claude Code v2.1.282 ou posterior.

requiredMinimumVersion e requiredMaximumVersion falham abertos por design: um valor inválido é descartado em vez de ser aplicado.

Esta tolerância se aplica apenas a configurações gerenciadas. Arquivos de configurações de usuário, projeto e local permanecem rigorosos: um arquivo cuja JSON ou forma de nível superior falha na validação é rejeitado como um todo e relatado, e uma entrada individual que falha, como uma regra de permissão malformada, é pulada com um aviso enquanto o resto do arquivo se aplica.

Valores inválidos dentro de `sandbox`

Quando um valor em seu bloco sandbox gerenciado é inválido, Claude Code não descarta o bloco inteiro, porque valida cada campo por conta própria. Este tratamento por campo requer Claude Code v2.1.283 ou posterior. Em versões anteriores a v2.1.283, Claude Code descarta cada campo sandbox exceto credentials quando um valor fora de credentials é inválido.

O aviso que você recebe para um campo inválido nomeia o campo e diz o que acontece com ele. O que acontece depende do que o campo controla:

  • Se você definir uma chave booleana para uma "true" ou "false" entre aspas, o valor conta como esse booleano. Em vez de um aviso, /status mostra um aviso pedindo que você remova as aspas.
  • Se failIfUnavailable for inválido, Claude Code descarta o valor em vez de tratá-lo como true, portanto um valor ilegível nunca interrompe sessões de inicialização em toda sua frota.
  • Claude Code trata cada outro booleano inválido como o valor que mantém o sandbox mais rigoroso até você corrigi-lo. Uma chave que ativa o sandbox ou uma de suas restrições, como enabled ou network.allowManagedDomainsOnly, conta como true. Uma chave que o afrouxe, como allowUnsandboxedCommands, conta como false.
  • Em uma lista fora de credentials, como excludedCommands ou network.allowedDomains, Claude Code descarta uma entrada inválida e mantém o resto da lista. Uma lista que não é um array, ou que não tem entrada válida, não se aplica.
  • Enquanto network.deniedDomains ou qualquer entrada nela for inválida, Claude Code também retém network.allowedDomains, portanto a lista de permissões gerenciada não concede nada até você corrigir a lista de negação.
  • Enquanto filesystem.denyRead, filesystem.denyWrite ou qualquer entrada em qualquer uma delas for inválida, Claude Code também retém filesystem.allowRead e filesystem.allowWrite até você corrigir a lista de negação.

Chaves que apenas uma fonte gerenciada pode definir

Claude Code lê as seguintes chaves apenas de uma fonte gerenciada; colocá-las em arquivos de configurações de usuário ou projeto não tem efeito.

A maioria delas são bloqueios: o valor que um bloqueio governa, como regras de permissão ou sandbox.network.allowedDomains, é uma chave ordinária que qualquer nível pode definir, e o bloqueio diz ao Claude Code para honrar apenas o valor gerenciado.

A tabela cobre os controles de permissão, plugin e entrega. Para qualquer chave não listada aqui, a coluna Escopo da referência de configurações diz se é apenas gerenciada; as chaves apenas gerenciadas restantes lá incluem a URL de login do gateway, versão, navegador, simulador móvel, host SSH, sessão local do Desktop, caminho binário da sandbox, preço do modelo, restrição de modelo e controles CLAUDE.md.

Configuração Descrição
allowAllClaudeAiMcps Carregue os conectores claude.ai que Claude Code busca por si mesmo junto com um managed-mcp.json implantado em vez de suprimi-los
allowedChannelPlugins Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definida. Requer channelsEnabled: true. Veja Restringir quais plugins de canal podem ser executados
allowManagedHooksOnly Quando true, restringe quais hooks são executados; veja o que é executado sob allowManagedHooksOnly para a lista completa de efeitos
allowManagedMcpServersOnly Quando true, apenas allowedMcpServers das configurações gerenciadas são respeitados. deniedMcpServers ainda é mesclado de todas as fontes. Veja Chaves lidas de todas as fontes de administrador para quais fontes gerenciadas podem defini-la, e Configuração MCP gerenciada
allowManagedPermissionRulesOnly Torna as configurações gerenciadas a única fonte de configurações de regras de permissão. A entrada lista todas as fontes que ignora
blockedMarketplaces Lista de bloqueio de fontes de marketplace. As fontes bloqueadas são verificadas antes do download, portanto nunca tocam o sistema de arquivos. Veja restrições de marketplace gerenciadas
channelsEnabled Permitir canais para a organização. Veja controles empresariais para o padrão em cada plano
disableCommandPluginSources Quando true, bloqueia fontes de plugin command inteiramente, portanto o comando declarado no marketplace nunca é executado. Também bloqueia comandos headersHelper do marketplace, exceto para um marketplace que as próprias configurações gerenciadas declaram. Quando não definido, segue allowManagedHooksOnly. Requer Claude Code v2.1.229 ou posterior, e o bloqueio headersHelper requer v2.1.238 ou posterior
disableSideloadFlags Rejeite os sinalizadores --plugin-dir, --plugin-url, --agents e --mcp-config na inicialização. Em sessões na nuvem, Claude Code descarta os servidores MCP que o servidor entregou através de --mcp-config, exceto entradas type: "sdk" em processo, e inicia a sessão. Requer Claude Code v2.1.193 ou posterior
forceRemoteSettingsRefresh Quando true, bloqueia a inicialização da CLI até que as configurações gerenciadas remotas sejam buscadas recentemente e sai se a busca falhar. Veja aplicação de falha fechada
managedMcpServers Servidores MCP remotos fornecidos a cada usuário junto com os seus próprios. Fornece servidores em vez de bloquear qualquer coisa. Veja Fornecer servidores através de configurações gerenciadas. Requer Claude Code v2.1.259 ou posterior
managedSourcesBehavior Se Claude Code aplica apenas a fonte gerenciada de prioridade mais alta ou compõe cada uma delas
parentSettingsBehavior Se as configurações pai fornecidas pelo host são mescladas sob a política gerenciada
pluginSuggestionMarketplaces Marketplaces cujos plugins Claude Code pode sugerir aos usuários
pluginTrustMessage Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação
policyHelper Executável que calcula configurações gerenciadas na inicialização; veja Calcular configurações gerenciadas com um auxiliar de política
sandbox.filesystem.allowManagedReadPathsOnly Quando true, apenas caminhos filesystem.allowRead das configurações gerenciadas são respeitados. denyRead ainda é mesclado de todas as fontes
sandbox.network.allowManagedDomainsOnly Honre apenas regras de permissão allowedDomains e WebFetch(domain:...) gerenciadas; bloqueie outros domínios sem solicitar
strictKnownMarketplaces Controla de quais fontes de marketplace de plugins os usuários podem adicionar e instalar plugins. Veja restrições de marketplace gerenciadas
strictPluginOnlyCustomization Bloqueie skills, agentes, hooks e servidores MCP de fontes de usuário e projeto; true bloqueia todos os quatro, uma matriz nomeia qual
wslInheritsWindowsSettings Quando definido no registro HKLM ou em um arquivo sob C:\Program Files\ClaudeCode, faça o WSL ler a cadeia de política do Windows e ler /etc/claude-code apenas quando nenhum documento de administrador do Windows está presente; a entrada fornece a ordem

Desativar telemetria para sua organização

Claude Code envia telemetria operacional da Anthropic por padrão em sessões que usam a API da Anthropic, seja diretamente, através de um gateway LLM ou através de um ANTHROPIC_BASE_URL personalizado; Comportamentos padrão por provedor de API diz quais provedores a enviam. Para desativá-la para cada desenvolvedor sem depender da shell de cada pessoa, entregue DISABLE_TELEMETRY através do bloco env de suas configurações gerenciadas. Este exemplo define DISABLE_TELEMETRY para todos que a política alcança:

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

Claude Code aplica um valor de 1 sem mostrar ao usuário o diálogo de aprovação.

Se você desativar a telemetria, Claude Code para de enviar os dados de uso que alimentam o painel de análise de sua organização para os desenvolvedores que a política alcança. A variável também desativa a busca de sinalizadores de recurso para esses desenvolvedores. Para Remote Control, consulte os requisitos do Remote Control.

Onde e quando uma política se aplica diz qual mecanismo de entrega alcança cada superfície, e Disponibilidade de plataforma diz quais sessões pulam a busca de configurações gerenciadas pelo servidor.

Se sua organização usa chaves de criptografia gerenciadas pelo cliente e roteia Claude Code através de um gateway, Configurar proxies e gateways diz por que essas sessões precisam dessa variável.

Veja também