Configurar configurações gerenciadas pelo servidor

Configure centralmente o Claude Code para sua organização através de configurações entregues pelo servidor, sem exigir infraestrutura de gerenciamento de dispositivos.

As configurações gerenciadas pelo servidor permitem que administradores configurem centralmente o Claude Code através de uma interface baseada na web no Claude.ai. Os clientes do Claude Code recebem automaticamente essas configurações quando os usuários se autenticam com suas credenciais organizacionais.

Essa abordagem foi projetada para organizações que não possuem infraestrutura de gerenciamento de dispositivos ou precisam gerenciar configurações para usuários em dispositivos não gerenciados.

Requisitos

Para usar configurações gerenciadas pelo servidor, você precisa de:

• Plano Claude for Teams ou Claude for Enterprise
• Claude Code versão 2.1.38 ou posterior para Claude for Teams, ou versão 2.1.30 ou posterior para Claude for Enterprise
• Acesso de rede a api.anthropic.com

Escolha entre configurações gerenciadas pelo servidor e gerenciadas pelo endpoint

O Claude Code suporta duas abordagens para configuração centralizada. As configurações gerenciadas pelo servidor entregam a configuração dos servidores da Anthropic. As configurações gerenciadas pelo endpoint são implantadas diretamente em dispositivos através de políticas nativas do SO (preferências gerenciadas do macOS, registro do Windows) ou arquivos de configurações gerenciadas.

Se seus dispositivos estão inscritos em uma solução MDM ou gerenciamento de endpoint, as configurações gerenciadas pelo endpoint fornecem garantias de segurança mais fortes porque o arquivo de configurações pode ser protegido contra modificação do usuário no nível do SO.

Configurar configurações gerenciadas pelo servidor

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

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
]
}
]
}
}

{
"autoMode": {
"environment": [
"Source control: github.example.com/acme-corp and all repos under it",
"Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
"Trusted internal domains: *.corp.example.com"
]
}
}

Verificar entrega de configurações

Para confirmar que as configurações estão sendo aplicadas, peça a um usuário para reiniciar o Claude Code. Se a configuração incluir configurações que acionem a caixa de diálogo de aprovação de segurança, o usuário vê um prompt descrevendo as configurações gerenciadas na inicialização. Você também pode verificar que as regras de permissão gerenciadas estão ativas pedindo a um usuário para executar /permissions para visualizar suas regras de permissão efetivas.

Controle de acesso

Os seguintes papéis podem gerenciar configurações gerenciadas pelo servidor:

• Primary Owner
• Owner

Restrinja o acesso a pessoal confiável, pois as alterações de configurações se aplicam a todos os usuários da organização.

Configurações apenas gerenciadas

A maioria das chaves de configurações funciona em qualquer escopo. Um punhado de chaves são lidas apenas de configurações gerenciadas e não têm efeito quando colocadas em arquivos de configurações de usuário ou projeto. Veja configurações apenas gerenciadas para a lista completa. Qualquer configuração não nessa lista ainda pode ser colocada em configurações gerenciadas e tem a precedência mais alta.

Limitações atuais

As configurações gerenciadas pelo servidor têm as seguintes limitações:

• As configurações se aplicam uniformemente a todos os usuários da organização. Configurações por grupo ainda não são suportadas.
• Configurações de servidor MCP não podem ser distribuídas através de configurações gerenciadas pelo servidor.
• Configurações restritas a fontes de política em nível do SO, como policyHelper e wslInheritsWindowsSettings, não são honradas. Implante-as através de MDM ou um arquivo managed-settings.json do sistema.

Entrega de configurações

Precedência de configurações

As configurações gerenciadas pelo servidor e as configurações gerenciadas pelo endpoint ocupam o nível mais alto na hierarquia de configurações do Claude Code. Nenhum outro nível de configurações pode substituí-las, incluindo argumentos de linha de comando.

Dentro do nível gerenciado, a primeira fonte que entrega uma configuração não vazia vence. As configurações gerenciadas pelo servidor são verificadas primeiro, depois as configurações gerenciadas pelo endpoint. As fontes não se mesclam: se as configurações gerenciadas pelo servidor entregarem qualquer chave, as configurações gerenciadas pelo endpoint são ignoradas completamente. Se as configurações gerenciadas pelo servidor não entregarem nada, as configurações gerenciadas pelo endpoint se aplicam.

Se você limpar sua configuração gerenciada pelo servidor no console de administração com a intenção de voltar a uma plist gerenciada pelo endpoint ou política de registro, esteja ciente de que configurações em cache persistem em máquinas cliente até a próxima busca bem-sucedida. Execute /status para ver qual fonte gerenciada está ativa.

Comportamento de busca e cache

O Claude Code busca configurações dos servidores da Anthropic na inicialização e faz polling para atualizações a cada hora durante sessões ativas.

Primeiro lançamento sem configurações em cache:

• O Claude Code busca configurações de forma assíncrona
• Se a busca falhar, o Claude Code continua sem configurações gerenciadas
• Há uma breve janela antes das configurações carregarem onde as restrições ainda não são aplicadas

Lançamentos subsequentes com configurações em cache:

• As configurações em cache se aplicam imediatamente na inicialização
• O Claude Code busca configurações atualizadas em segundo plano
• As configurações em cache persistem através de falhas de rede

O Claude Code aplica atualizações de configurações automaticamente sem reinicialização, exceto para configurações avançadas como configuração OpenTelemetry, que exigem uma reinicialização completa para entrar em vigor.

Impor inicialização com falha fechada

Por padrão, se a busca de configurações remotas falhar na inicialização, a CLI continua sem configurações gerenciadas. Para ambientes onde essa breve janela não aplicada é inaceitável, defina forceRemoteSettingsRefresh: true em suas configurações gerenciadas.

Quando essa configuração está ativa, a CLI bloqueia na inicialização até que as configurações remotas sejam buscadas recentemente. Se a busca falhar, a CLI sai em vez de prosseguir sem a política. Essa configuração se auto-perpetua: uma vez entregue do servidor, ela também é armazenada em cache localmente para que as inicializações subsequentes imponham o mesmo comportamento mesmo antes da primeira busca bem-sucedida de uma nova sessão.

Para ativar isso, adicione a chave à sua configuração de configurações gerenciadas:

{
  "forceRemoteSettingsRefresh": true
}

Antes de ativar essa configuração, certifique-se de que suas políticas de rede permitem conectividade a api.anthropic.com. Se esse endpoint estiver inacessível, a CLI sai na inicialização e os usuários não podem iniciar o Claude Code.

Caixas de diálogo de aprovação de segurança

Certas configurações que podem representar riscos de segurança exigem aprovação explícita do usuário antes de serem aplicadas:

• Configurações de comando shell: configurações que executam comandos shell
• Variáveis de ambiente personalizadas: variáveis não na lista de permissão segura conhecida
• Configurações de hooks: qualquer definição de hook

Quando essas configurações estão presentes, os usuários veem uma caixa de diálogo de segurança explicando o que está sendo configurado. Os usuários devem aprovar para prosseguir. Se um usuário rejeitar as configurações, o Claude Code sai.

Disponibilidade de plataforma

As configurações gerenciadas pelo servidor exigem uma conexão direta a api.anthropic.com e não estão disponíveis ao usar provedores de modelo de terceiros:

• Amazon Bedrock
• Google Vertex AI
• Microsoft Foundry
• Endpoints de API personalizados via ANTHROPIC_BASE_URL ou gateways LLM

Auditoria de logs

Os eventos de log de auditoria para alterações de configurações estão disponíveis através da API de conformidade ou exportação de log de auditoria. Entre em contato com sua equipe de conta da Anthropic para obter acesso.

Os eventos de auditoria incluem o tipo de ação executada, a conta e o dispositivo que executaram a ação, e referências aos valores anteriores e novos.

Considerações de segurança

As configurações gerenciadas pelo servidor fornecem aplicação de política centralizada, mas funcionam como um controle do lado do cliente. Em dispositivos não gerenciados, usuários com acesso de administrador ou sudo podem modificar o binário do Claude Code, sistema de arquivos ou configuração de rede.

Para detectar alterações de configuração em tempo de execução, use hooks ConfigChange para registrar modificações ou bloquear alterações não autorizadas antes que entrem em vigor.

Para garantias de aplicação mais fortes, use configurações gerenciadas pelo endpoint em dispositivos inscritos em uma solução MDM.

Veja também

Páginas relacionadas para gerenciar a configuração do Claude Code:

• Settings: referência de configuração completa incluindo todas as configurações disponíveis
• Configurações gerenciadas pelo endpoint: configurações gerenciadas implantadas em dispositivos por TI
• Authentication: configure o acesso do usuário ao Claude Code
• Security: salvaguardas de segurança e melhores práticas