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 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 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.
  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, exceto que um auxiliar sombreado na inicialização por configurações gerenciadas pelo servidor é 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 de classificação mais alta que entrega pelo menos uma chave de política e ignora o resto em vez de mesclá-las, exceto pelas poucas 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 de classificação mais alta se aplica, listas se unem e locks assumem o valor mais restritivo. Compor 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 que não seja as 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 não é uma.

1. Configurações remotas, entregues do claude.ai como configurações gerenciadas pelo servidor ou por um gateway de aplicativos Claude. Claude Code busca essa fonte apenas quando a sessão se autentica na API da Anthropic diretamente com um login ou chave elegível, ou se conecta a um gateway com /login. Em outros provedores, ou quando ANTHROPIC_BASE_URL aponta para algo diferente da API da Anthropic, começa na próxima fonte
2. Políticas MDM ou nível do SO: a plist 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 a chave de 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 nenhuma fonte acima dele entrega uma chave de política e nenhuma configuração pai fornecida pelo host fornece uma chave restritiva

​

Chaves lidas de cada fonte de administrador

• sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly: um true em qualquer fonte de administrador ativa o lock. Enquanto um lock está ativo, Claude Code une a lista de permissões que ele bloqueia, sandbox.network.allowedDomains junto com regras de permissão WebFetch(domain:...), ou sandbox.filesystem.allowRead, em cada fonte de administrador. Sem o lock, Claude Code trata a lista de permissões como qualquer outra chave, portanto sob "first-wins" a lista de permissões de uma fonte de administrador não selecionada é ignorada
• allowAllClaudeAiMcps
• 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 e syncClaudeAiSkills, 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 só pode 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; consulte quais valores de nível inferior ainda contam. Requer Claude Code v2.1.242 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, portanto fontes inferiores preenchem variáveis que as superiores 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

​

Compor cada fonte gerenciada

​

Calcular 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

​

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

• 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 das configurações pai que você escolheu mesclar
• Claude Code aplica o valor forceLoginOrgUUID ou allowedMcpServers nas configurações gerenciadas que aplica e bloqueia um fornecido pelo pai. Um valor em uma fonte de administrador inferior que Claude Code não aplica nem se aplica nem bloqueia o do pai. A entrada managedSourcesBehavior diz qual fonte fornece cada chave sob "merge". Antes de v2.1.223, um valor em qualquer fonte de administrador bloqueava o do pai
• Um valor availableModels segue a mesma regra que allowedMcpServers

​

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

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

​

O que um desenvolvedor pode alterar

• O modelo para uma sessão: um model gerenciado é um padrão, não um lock. --model e ANTHROPIC_MODEL ainda escolhem o modelo para essa sessão, portanto 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 a chave de registro HKLM e o domínio de preferências gerenciadas macOS existem.
• O cache gerenciado pelo servidor: as 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: as 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.

• 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

​

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