Implantar configurações gerenciadas

​

Implantar um arquivo de configurações gerenciadas

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

​

Escolher um mecanismo de entrega

• Controles de entrega: policyHelper, wslInheritsWindowsSettings e managedSourcesBehavior
• Chaves de login do gateway: forceLoginGatewayUrl, gatewayInternalNetworks e o valor "gateway" de forceLoginMethod

​

Onde e quando uma política se aplica

• 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 Claude Tag: as sessões Claude Tag são executadas em ambientes na nuvem, mas não recebem configurações gerenciadas pelo servidor. Em um ambiente auto-hospedado, elas ainda leem o arquivo de configurações gerenciadas na imagem do executor. Configure o Claude Tag em si nas configurações de administrador do Claude Tag.
• 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 em forceRemoteSettingsRefresh, requiredMinimumVersion e algumas chaves editáveis pelo usuário entram em vigor na próxima inicialização de sessão.
  • Uma entrada policyHelper nova ou alterada entra em vigor no próximo lançamento. Se configurações gerenciadas pelo servidor sombrearem o auxiliar nesse lançamento, o auxiliar é executado assim que uma busca relata que essas configurações foram removidas.
• 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

• 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

• 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

• "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.

• 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.

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 uma credencial elegível, faz login em um gateway com /login, ou é executada na aba Code do Claude Desktop por trás de um gateway que fornece configurações a essa sessão. 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

​

Quando um documento de administrador conta como presente

• 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 pode ser lido

​

Chaves lidas de cada fonte de administrador

• 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 allowlist que bloqueia, sandbox.network.allowedDomains junto com regras allow WebFetch(domain:...), ou sandbox.filesystem.allowRead, em cada fonte de administrador. Sem o bloqueio, Claude Code trata a allowlist como qualquer outra chave, então sob "first-wins" a allowlist de uma fonte de administrador não selecionada é ignorada
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly: um true em qualquer fonte de administrador ativa o bloqueio da allowlist 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 pela denylist é 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

​

Componha cada fonte gerenciada

​

Calcule a política com um programa auxiliar

• O objeto managedSettings emitido é a única configuração gerenciada para a sessão, incluindo para as chaves que de outra forma lê de cada fonte de administrador, exceto por forceRemoteSettingsRefresh, que tem sua própria regra de inicialização

​

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

• Quando qualquer fonte de administrador define allowManagedPermissionRulesOnly, Claude Code descarta regras allow 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 da allowlist 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
• Para allowedProviders, uma lista na fonte gerenciada selecionada bloqueia uma fornecida pelo pai, e sob a opção "merge" de managedSourcesBehavior uma lista em qualquer fonte de administrador também bloqueia. Requer Claude Code v2.1.285 ou posterior
• Um blockedMarketplaces fornecido pelo pai se aplica além de qualquer lista de bloqueio que uma fonte gerenciada define. Requer Claude Code v2.1.282 ou posterior

​

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

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

​

O que um desenvolvedor pode mudar

• 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.
• A janela de compactação automática para uma sessão: um autoCompactWindow gerenciado também é um padrão. A flag --autocompact e a variável CLAUDE_CODE_AUTO_COMPACT_WINDOW ainda definem a janela de compactação automática para essa sessão.
• 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

​

Ler a fonte em /status

• (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

• 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

• 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

• 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 o sistema operacional negou a leitura, por exemplo em um arquivo somente raiz, cada sessão inicia sem as políticas dessa fonte. /status e claude doctor registram a falha, e uma execução com -p também a imprime para stderr.
• Para qualquer outra falha de leitura, como um erro de E/S, cada sessão sai na inicialização com uma mensagem para contatar um administrador.

• 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

• 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.

• 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.

​

Valores inválidos dentro de sandbox

• 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 allowlist 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

​

Desativar telemetria para sua organização

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

​

Veja também

• Configurar Claude Code para sua organização: decidir o que impor e como
• Configurações gerenciadas pelo servidor: entregar política do console claude.ai ou um gateway
• Configuração MCP gerenciada: controlar quais servidores MCP os desenvolvedores podem usar
• Todas as configurações: cada chave, com se uma fonte gerenciada pode defini-la
• Arquivos de configurações de exemplo: um managed-settings.json completo mostrando a forma das chaves gerenciadas