Configurar configurações gerenciadas pelo servidor

​

Requisitos

• Plano Claude for Teams ou Claude for Enterprise
• Função de Proprietário ou Proprietário Primário em sua organização Claude, para visualizar e editar a configuração
• Acesso de rede a api.anthropic.com

​

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

​

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" }
        ]
      }
    ]
  }
}

​

Verificar entrega de configurações

• As configurações entregues foram carregadas
• Sua organização não tem configurações gerenciadas pelo servidor configuradas
• A busca falhou, com a causa e se uma política em cache ainda se aplica
• Claude Code pulou a busca, com o motivo. Veja Disponibilidade da plataforma para os provedores e configurações que a pulam

​

Controle de acesso

• Primary Owner
• Owner

​

Configurações apenas gerenciadas

​

Limitações atuais

• As configurações se aplicam uniformemente a todos os usuários da organização. Configurações por grupo ainda não são suportadas.
• Você não pode distribuir um arquivo managed-mcp.json através de configurações gerenciadas pelo servidor. Entregue as chaves de política allowedMcpServers e deniedMcpServers lá em vez disso. No Claude Code v2.1.259 ou posterior, você também pode fornecer servidores remotos com managedMcpServers, que aceita apenas servidores http e sse e não assume controle exclusivo da forma que o arquivo faz. Claude Code lê um managed-mcp.json implantado em seu caminho do sistema separadamente da camada de configurações gerenciadas, portanto, o arquivo ainda se aplica quando as configurações gerenciadas pelo servidor estão em vigor.
• 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 em vez disso. Um policyHelper implantado dessa forma é executado apenas quando sua fonte é a selecionada em precedência dentro da camada gerenciada.

​

Entrega de configurações

​

Precedência de configurações

​

Exceções por chave entre fontes gerenciadas

• Chaves de bloqueio entre fontes: um pequeno conjunto de chaves, como os bloqueios da lista de permissão de sandbox, listadas na página de configurações gerenciadas. O Claude Code as honra quando qualquer fonte gerenciada controlada por administrador as define; o nível de registro HKCU gravável pelo usuário é excluído. Quando um policyHelper fornece configurações gerenciadas, sua saída é a única fonte que essas verificações leem, exceto por forceRemoteSettingsRefresh, que o Claude Code lê das fontes de administrador diretamente na inicialização.
• O bloco env: além da unidade de telemetria e variáveis de roteamento emparelhadas com uma chave de credencial, ambas cobertas abaixo, ele se mescla por chave entre as fontes controladas por administrador. Para cada variável de ambiente, a fonte de prioridade mais alta que a define vence, e as fontes de administrador inferiores preenchem variáveis que as fontes superiores deixam não definidas. Uma entrada env gerenciada pelo endpoint, portanto, se aplica sempre que a configuração gerenciada pelo servidor deixa essa variável não definida, ou enquanto um valor de servidor em cache para ela é retido pendente de confirmação do servidor. Requer Claude Code v2.1.223 ou posterior. Antes da v2.1.223, o Claude Code aplica apenas o bloco env da fonte selecionada.
  • Unidade de telemetria: as chaves do exportador OTEL_EXPORTER_OTLP_*, os toggles de captura de conteúdo OTEL_LOG_*, OTEL_LOGS_EXPORTER e as variáveis de rastreamento beta ENABLE_BETA_TRACING_DETAILED e BETA_TRACING_ENDPOINT seguem a fonte mais alta que define qualquer uma delas como uma unidade. Uma fonte que entrega a chave de credencial otelHeadersHelper também reclama a unidade, mas coloca essas variáveis apenas quando é a fonte selecionada: uma fonte que não é selecionada mas entrega a chave não contribui com nenhuma delas e ainda bloqueia fontes inferiores de preenchê-las. De qualquer forma, um endpoint do exportador de uma fonte nunca pode ser emparelhado com credenciais de outra.
  • Roteamento emparelhado com credencial: uma fonte que emparelha variáveis de roteamento com uma chave de credencial somente de fonte selecionada, como apiKeyHelper ou otelHeadersHelper, contribui com essas variáveis de roteamento apenas quando vence o slot.
• Chaves de login do gateway: o Claude Code nunca lê forceLoginGatewayUrl ou o valor "gateway" de forceLoginMethod das configurações gerenciadas pelo servidor, portanto selecionar configurações gerenciadas pelo servidor não fornece um login do gateway nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. A entrada managedSourcesBehavior diz qual fonte de administrador na máquina as fornece.

​

Comportamento de busca e cache

• Quando um desenvolvedor se conecta na inicialização, como em uma primeira execução ou após /logout, o Claude Code aguarda até cinco segundos pela busca antes de abrir a sessão. Quando a política chega a tempo, o Claude Code a aplica desde a primeira tela e mostra seus companyAnnouncements nela. Quando o payload precisa de aprovação de segurança, o Claude Code encerra a espera e aplica o payload uma vez que o desenvolvedor aprova
• Em qualquer outra inicialização, e quando essa espera de cinco segundos se esgota, o Claude Code abre a sessão enquanto a busca continua, portanto uma breve janela passa antes das configurações carregarem e as restrições entrarem em vigor
• Se a busca falhar, o Claude Code continua sem configurações gerenciadas pelo servidor e avisa em sessões interativas que nenhuma política remota se aplica; as configurações gerenciadas pelo endpoint ainda se aplicam. Se uma fonte gerenciada define forceRemoteSettingsRefresh, o Claude Code sai em vez disso

• As configurações em cache se aplicam imediatamente na inicialização, exceto pelos valores em cache modelPricing e managedMcpServers e as variáveis de ambiente que o Claude Code retém até que o servidor confirme o payload
• Um modelPricing em cache não se aplica até que a busca da sessão confirme o payload. Até então, os valores de custo que os desenvolvedores veem em /usage e na linha de status estão no preço de lista
• Um bloco managedMcpServers em cache não se aplica até que a busca da sessão confirme o payload. O Claude Code aguarda até 30 segundos por essa busca antes de conectar servidores MCP. Se a busca falhar ou expirar, a sessão inicia sem os servidores da organização, /status diz isso, e eles se conectam uma vez que uma busca posterior os confirma. Veja Quando servidores fornecidos se conectam para o comportamento completo, incluindo primeiro lançamento. Requer Claude Code v2.1.259 ou posterior
• O Claude Code busca configurações atualizadas em segundo plano
• As configurações em cache persistem através de falhas de rede. Se a busca de inicialização falhar, o Claude Code avisa em sessões interativas que a política em cache está em vigor
• Até que uma busca seja bem-sucedida, os valores retidos na inicialização permanecem retidos

• Configuração de proxy e TLS, como HTTPS_PROXY, NODE_EXTRA_CA_CERTS e as variáveis de certificado de cliente mTLS CLAUDE_CODE_CLIENT_CERT e CLAUDE_CODE_CLIENT_KEY
• Roteamento de API e seleção de provedor, incluindo ANTHROPIC_BASE_URL, as variáveis de seleção de provedor como CLAUDE_CODE_USE_BEDROCK e CLAUDE_CODE_USE_VERTEX, e as URLs de endpoint do provedor como ANTHROPIC_BEDROCK_BASE_URL
• Credenciais de autenticação, como ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e CLAUDE_CODE_OAUTH_TOKEN
• O seletor de diretório de configuração CLAUDE_CONFIG_DIR
• Seletores de fonte de credencial e diretório de configuração, no Claude Code v2.1.223 ou posterior: as variáveis de Workload Identity Federation como ANTHROPIC_FEDERATION_RULE_ID e ANTHROPIC_IDENTITY_TOKEN, os seletores de perfil e diretório de configuração ANTHROPIC_PROFILE e ANTHROPIC_CONFIG_DIR, e as variáveis de diretório do sistema operacional HOME, XDG_CONFIG_HOME, APPDATA e USERPROFILE

​

Entradas inválidas em configurações entregues

• O cache em ~/.claude/remote-settings.json armazena o payload salvo com entradas inválidas removidas, exceto por valores inválidos de cleanupPeriodDays e desktopSessionCleanupPeriodDays, que permanecem na cópia em cache e nunca são aplicados.
• Quando nenhum campo no payload pode ser salvo e o payload não é apenas essas chaves de retenção, o Claude Code rejeita o payload, mantém as últimas configurações em cache aceitas e escreve Remote settings: Settings validation failed - no fields could be salvaged no log de depuração. Com forceRemoteSettingsRefresh definido, a CLI sai em vez disso.
• A caixa de diálogo de aprovação de segurança avalia o payload salvo, portanto uma entrada inválida removida nunca é apresentada para aprovação e nunca é executada.

​

Impor inicialização com falha fechada

• Se o gateway responde um lançamento interativo assistido com um 401 e essa configuração está desativada, o gateway encerrou esse login. O Claude Code imprime Cloud gateway session expired — run /login to reconnect. e abre a sessão desconectada do gateway até que o usuário execute /login.
• Quando a busca falha de qualquer outra forma, ou em qualquer outro tipo de lançamento exceto um subcomando claude auth, o cliente sai com um erro.

{
  "forceRemoteSettingsRefresh": true
}

​

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

• Configurações de comando shell: configurações que executam comandos shell, como apiKeyHelper, statusLine e otelHeadersHelper
• Configurações de binário de sandbox: sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep. Cada uma dessas configurações aponta para um executável, e o Claude Code executa esse executável
• Configurações de rede e isolamento de sandbox: configurações de sandbox que deixam o proxy de sandbox ler, redirecionar ou autenticar tráfego, ou que enfraquecem o isolamento do sandbox: sandbox.network.tlsTerminate, sandbox.network.httpProxyPort, sandbox.network.socksProxyPort, sandbox.credentials, sandbox.allowAppleEvents, sandbox.enableWeakerNestedSandbox, sandbox.enableWeakerNetworkIsolation, sandbox.filesystem.disabled, sandbox.network.allowAllUnixSockets, sandbox.network.allowUnixSockets e sandbox.network.allowMachLookup. Um bloco sandbox.credentials que contém apenas regras deny não precisa de aprovação, pois restringe o sandbox sem dar ao proxy uma credencial. Antes da v2.1.251, o Claude Code aplicava essas configurações sem aprovação
• Variáveis de ambiente personalizadas: variáveis env entregues que exigem aprovação do usuário, como variáveis de proxy e URL base; veja Variáveis de ambiente e a caixa de diálogo de aprovação
• Configurações de hook: qualquer definição de hook

​

Memória de aprovação

• Um login claude.ai salvo por /login ou claude auth login, ou o login do Console sem chave: uma aprovação por organização, mantida pela conta que aprovou mais recentemente.
• Um login de gateway de aplicativos Claude: uma aprovação por gateway. Se você se desconectar e reconectar ao mesmo gateway, o Claude Code não mostra a caixa de diálogo novamente enquanto as configurações que exigem aprovação não forem alteradas. O Claude Code a mostra novamente quando essas configurações mudam, quando você se conecta a um gateway diferente e quando você aceita um novo certificado para o mesmo gateway. O Claude Code não salva aprovação para um gateway de desenvolvimento de loopback alcançado por HTTP simples, portanto a caixa de diálogo aparece novamente após cada login.
• Qualquer outra credencial, como uma chave de API ou CLAUDE_CODE_OAUTH_TOKEN: uma aprovação para as configurações entregues, mantida com a cópia em cache das configurações nesse diretório de configuração. O Claude Code mostra a caixa de diálogo novamente quando as configurações que exigem aprovação mudam, e após você executar /logout ou claude auth logout, qualquer um dos quais exclui a cópia em cache.

• Se você se desconectar e reconectar, ou mudar para outra organização e depois retornar, o Claude Code não mostra a caixa de diálogo novamente enquanto essas configurações não forem alteradas, a menos que outra conta as tenha aprovado para essa organização no mesmo diretório de configuração no meio tempo.
• Se você se conectar à mesma organização com uma conta diferente, o Claude Code mostra a caixa de diálogo novamente mesmo quando as configurações não forem alteradas. A aprovação dessa conta substitui a anterior, portanto quando você muda de volta, o Claude Code mostra a caixa de diálogo mais uma vez.

• Uma sessão interativa que não pode mostrar a caixa de diálogo: o Claude Code não aplica as configurações entregues e mantém as últimas configurações aprovadas. A caixa de diálogo aparece na próxima sessão que pode mostrá-la. Requer Claude Code v2.1.211 ou posterior.
• claude install ou claude update: o Claude Code não mostra a caixa de diálogo durante nenhum dos comandos. O comando é executado com as últimas configurações aprovadas, e a caixa de diálogo aparece em sua próxima sessão interativa. Se o Claude Code aguardar a busca de configurações na inicialização, como com forceRemoteSettingsRefresh definido ou em uma implantação de gateway de aplicativos Claude, ele mostra a caixa de diálogo durante o comando em vez disso, e uma execução de instalação de um pipe falha; veja Raw mode is not supported durante install. Antes da v2.1.246, o Claude Code tentava mostrar a caixa de diálogo durante esses comandos também.
• Um erro fecha a caixa de diálogo antes de você responder: o Claude Code não aplica as configurações entregues e mantém as últimas configurações aprovadas. Ele mostra a caixa de diálogo novamente na próxima sessão que pode mostrá-la.
• Uma execução não interativa, como claude -p ou uma sessão do Agent SDK: o Claude Code não pode mostrar a caixa de diálogo, portanto quando as configurações entregues exigiriam aprovação, ele as aplica apenas para essa execução. Ele não as registra como aprovadas ou as escreve no cache local, e a próxima sessão interativa mostra a caixa de diálogo. Até que um usuário aprove em uma sessão interativa, cada execução não interativa busca as configurações novamente na inicialização. Antes da v2.1.207, uma execução não interativa salvava as configurações como aprovadas, portanto as sessões interativas posteriores nunca mostravam a caixa de diálogo para elas.

​

Variáveis de ambiente e a caixa de diálogo de aprovação

• Toggles de recurso e comando
• Seleção de modelo e configurações de comportamento, como ANTHROPIC_MODEL, DISABLE_PROMPT_CACHING e CLAUDE_CODE_EFFORT_LEVEL
• Contexto de janela e configurações de compactação, como DISABLE_AUTO_COMPACT
• Opções de UI de terminal e acessibilidade
• Limites numéricos, orçamentos e timeouts

​

Disponibilidade de plataforma

• Um login OAuth de Equipe ou Empresa
• Um token OAuth fornecido através de CLAUDE_CODE_OAUTH_TOKEN
• Uma chave de API configurada diretamente
• Um perfil Anthropic user_oauth, a menos que o perfil defina um base_url diferente da API Anthropic. Requer Claude Code v2.1.257 ou posterior.

​

Auditoria de logs

​

Considerações de segurança

​

Veja também

• Todas as configurações: todas as chaves de configuração
• 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