Configurações gerenciadas pela empresa

Use essa referência para entender as chaves atualmente compatíveis em managed-settings.json.

Para obter métodos de implantação e clientes com suporte, consulte Configurando configurações gerenciadas pela empresa.

Regras de precedência

Quando várias fontes de configurações estão presentes, as configurações anteriores nesta lista têm precedência sobre as configurações posteriormente na lista:

1. Configurações gerenciadas por MDM
2. Configurações gerenciadas pelo servidor
3. Configurações baseadas em arquivo
4. Configurações no nível do usuário

Em Copilot CLI, a sandbox chave é uma exceção a essas regras de precedência. As restrições da sandbox provenientes de configurações gerenciadas por MDM, por servidor e baseadas em arquivo se combinam entre si e com as configurações de sandbox do usuário, prevalecendo a configuração mais restritiva.

Chaves com suporte

Aplicando configurações diferentes às equipes corporativas

Para implantações gerenciadas pelo servidor, a organização pode aplicar diferentes políticas de governança a grupos de usuários com base em seu pertencimento à equipe da empresa. A empresa define todas as configurações— a associação de equipe determina apenas quais usuários recebem um determinado conjunto de valores.

Para tornar uma chave apta para valores específicos da equipe, marque-a como sobrescrevível em managed-settings.json, usando a sintaxe { "overridable": <VALUE> }. Uma chave sobreponível usa o valor da equipe quando ele está configurado ou recorre ao valor padrão da sua empresa quando a equipe não o configura. A sintaxe { "overridable": <VALUE> } se aplica às teclas permissions.model, permissions.disableBypassPermissionsMode, allowedMcpServers e deniedMcpServers. Chaves não marcadas como substituíveis permanecem uma decisão de nível empresarial que as equipes não podem modificar.

enabledPlugins e extraKnownMarketplaces funcionam de forma aditiva. A empresa managed-settings.json define uma linha de base e um arquivo de equipe empresarial pode adicionar mais plug-ins e marketplaces sobre ele. Para obter as etapas completas de instalação, consulte Configurando configurações gerenciadas pela empresa.

Configuração de exemplo

O exemplo a seguir mostra essas chaves em um arquivo de configurações gerenciadas.

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "model": "auto"
  },
  "enabledPlugins": {
    "my-plugin@agent-skills": true
  },
  "extraKnownMarketplaces": {
    "agent-skills": {
      "source": {
        "source": "github",
        "repo": "OWNER/REPO"
      }
    }
  },
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "OWNER/REPO"
    }
  ],
  "telemetry": {
    "enabled": true,
    "endpoint": "https://otel-collector.example.com",
    "protocol": "http/protobuf",
    "captureContent": false,
    "lockCaptureContent": true,
    "serviceName": "copilot",
    "resourceAttributes": {
      "deployment.environment": "production"
    },
    "headers": {
      "Authorization": "Bearer TOKEN"
    }
  },
  "remoteControl": {
    "mode": "requireSSO",
    "githubDotComOrganizations": ["ORG-NAME"]
  },
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] },
    { "serverCommand": ["cmd", "/c", "uvx", "markitdown-mcp"] }
  ],
  "deniedMcpServers": [
    {
      "serverCommand": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/"
      ]
    }
  ],
  "sandbox": {
    "enabled": true,
    "allowBypass": false,
    "sandboxMcpServers": true,
    "sandboxLspServers": true
  }
}

enabledPlugins

Define plug-ins instalados ou bloqueados automaticamente para todos os usuários corporativos. Cada entrada usa o formato PLUGIN-NAME@MARKETPLACE-NAME como a chave, com um valor booliano: true para exigir que o plug-in seja habilitado ou false para exigir que ele seja desabilitado. Consulte Sobre os padrões de plug-in gerenciados pela empresa.

extraKnownMarketplaces

Define outros marketplaces de plug-in disponíveis para os usuários. Cada entrada é um objeto de marketplace nomeado que contém a propriedade source. Há suporte para os seguintes tipos de origem:

• "github" — requer repo em OWNER/REPO formato; opcional ref (branch, tag ou SHA) e path (subdiretório)
• "git" — requer url; opcional ref e path
• "directory" — requer path

Consulte Sobre os padrões de plug-in gerenciados pela empresa.

strictKnownMarketplaces

Restringe a instalação do plug-in somente aos marketplaces definidos explicitamente pela empresa. Uma matriz vazia significa bloqueio completo. Cada entrada é um objeto do marketplace com uma source propriedade que indica o tipo de origem. Há suporte para os seguintes tipos de origem:

• "github" — requer repo no formato OWNER/REPO; opcional ref e path
• "git" — requer url; opcional ref e path
• "url"— requer url; objeto opcional headers
• "npm" — requer package
• "file" — requer path
• "directory" — requer path
• "hostPattern" — requer hostPattern (hosts do marketplace de correspondência regex)
• "pathPattern" — requer pathPattern (caminhos do marketplace na correspondência regex)

permissões

disableBypassPermissionsMode

Impede que os usuários habilitem o modo de bypass (também conhecido como "modo YOLO"). O modo de bypass permite que um agente execute comandos, acesse arquivos e busque URLs sem solicitar aprovação.

Quando você define disableBypassPermissionsMode como "disable", os usuários não podem ativar o modo de bypass:

• Em Copilot CLI, todas as opções de linha de comando que permitem todas as permissões (--yolo, --allow-all e as opções individuais --allow-all-tools, --allow-all-paths e --allow-all-urls) são suprimidas na inicialização e não podem conceder permissões elevadas. Os comandos de barra /yolo e /allow-all também estão bloqueados.
• Em VS Code, a configuração de aprovação automática global (chat.tools.global.autoApprove) está desativada e não pode ser habilitada novamente.
• Em GitHub Copilot app, a configuração "Permitir tudo" de "Permissões de ferramentas" está bloqueada nas configurações da sessão.
• Essa chave é substituível pelo mapeamento de equipe empresarial. Em sua managed-settings.json, use a sintaxe { "overridable": "disable" } para personalizar a configuração da chave para cada equipe. Em seguida, você pode definir "disableBypassPermissionsMode": "unmanaged" em um arquivo de configurações da equipe, fornecendo uma especialização que tem precedência sobre managed-settings.json para os membros da equipe em questão.

modelo

Define a seleção de modelo automático como o padrão para novas conversas. Consulte Sobre Copilotauto model selection.

• Quando você define permissions.model como "auto", novas sessões usam o modelo Automático, a menos que o usuário especifique um modelo diferente por conversa.
• Essa chave é substituível pelo mapeamento de equipe empresarial. Em sua managed-settings.json, use a sintaxe { "overridable": "auto" } para personalizar a configuração da chave para cada equipe. Em seguida, você pode definir "model": "unmanaged" em um arquivo de configurações da equipe, fornecendo uma especialização que tem precedência sobre managed-settings.json para os membros da equipe em questão.

telemetria

Configura a exportação do OpenTelemetry, encaminhando os dados de uso Copilot para um coletor à sua escolha.

Essa propriedade tem suporte para Copilot CLI e VS Code.

Quando você define a propriedade telemetry, a telemetria de Copilot é enviada para o endpoint que você especificar. Há suporte para as seguintes sub-propriedades:

• enabled: Defina como true para ativar a exportação de telemetria ou como false para desativá-la.
• endpoint: a URL do coletor OTLP (por exemplo, https://otel-collector.example.com).
• protocol: o protocolo de transporte para exportação de telemetria. Os valores aceitos são "http/json" e "http/protobuf".
• captureContent: defina como true para incluir o conteúdo do prompt e da resposta na carga de telemetria, ou false para excluí-lo.
• lockCaptureContent: definido como true para impedir que os usuários alterem a configuração captureContent.
• serviceName: um rótulo para o nome do serviço de telemetria (por exemplo, "copilot").
• resourceAttributes: um objeto de atributos de recurso OpenTelemetry a ser anexado a toda a telemetria exportada (por exemplo, {"deployment.environment": "production"}).
• headers: um objeto de cabeçalhos HTTP a ser incluído com cada solicitação de telemetria (por exemplo, um Authorization cabeçalho para o coletor).

remoteControl

Restringe se as Copilot sessões hospedadas em um dispositivo podem ser controladas remotamente. Isso não afeta a capacidade de um usuário de controlar remotamente suas sessões hospedadas em outros dispositivos.

• mode: Defina como "disabled" para impedir o controle remoto de sessões no dispositivo, "requireSSO" para permitir o controle remoto apenas a partir de um cliente autorizado por SSO para as organizações listadas em githubDotComOrganizations, ou "enabled" para permiti-lo sem restrições.
• githubDotComOrganizations: uma matriz de logons da organização. Necessário quando mode é "requireSSO".

allowedMcpServers

Define uma lista de permissões de servidores MCP permitidos para execução. Quando definido, somente servidores correspondentes a pelo menos uma entrada são permitidos. Qualquer servidor que não seja correspondido é bloqueado.

Omita completamente esta chave para permitir todos os servidores, desde que respeitadas quaisquer entradas em deniedMcpServers. Defina-a como uma matriz vazia para bloquear todos os servidores, exceto servidores padrão internos.

Quando várias fontes de configurações definem allowedMcpServers, a lista de permissões efetiva é a interseção de todas as fontes. Um servidor deve ser autorizado por cada origem para ser executado.

Cada entrada deve conter exatamente uma propriedade correspondente.

Essa chave é substituível para equipes empresariais. Encapsule os objetos de correspondência em overridable no nível da empresa e, em seguida, use a sintaxe regular para definir listas de permissões e listas de bloqueio no arquivo de cada equipe.

Canonização de URL

Antes de comparar um serverUrl padrão com uma URL do servidor, o cliente normaliza os dois valores:

• Converte o esquema e o host em letras minúsculas.
• Converte nomes de host internacionalizados ou Unicode em Punycode.
• Remove a porta padrão, :80 para HTTP ou :443 para HTTPS.
• Decodifica octetos de host codificados por porcentagem. Por exemplo, %65vil se tornará evil.
• Remove fragmentos de URL e pontos à direita de nomes DNS.
• Impede que curingas no componente de autoridade correspondam ao / limite no caminho.

deniedMcpServers

Define servidores MCP bloqueados incondicionalmente. Um servidor que corresponde a qualquer entrada é bloqueado mesmo que ele também corresponda a uma entrada em allowedMcpServers. As regras de negação sempre têm precedência sobre as regras de permissão.

Servidores de primeira parte Copilot , como o servidor MCP interno GitHub , são isentos de regras de negação e não podem ser bloqueados.

Quando várias fontes de configuração definem deniedMcpServers, a lista de bloqueio efetiva é a união de todas as fontes. Um servidor bloqueado por qualquer origem é bloqueado para todos.

Cada entrada usa a mesma serverName, serverUrlou serverCommand propriedades descritas em allowedMcpServers.

sandbox

Impõe restrições mínimas de sandbox local para Copilot CLI. As configurações de área restrita gerenciada impõem restrições em vez de padrões:

• Para configurações de ativação forçada, um valor gerenciado de true aplica a configuração. false ou a omissão deixa a configuração do usuário inalterada.
• Para configurações de funcionalidade, um valor gerenciado de false proíbe a funcionalidade. true ou a omissão deixa a configuração do usuário inalterada.
• Listas de caminhos de leitura/gravação e somente leitura gerenciadas restringem as concessões configuradas pelo usuário, enquanto os caminhos negados gerenciados adicionam negações configuradas pelo usuário.

Há suporte para as seguintes sub-propriedades:

• enabled: true requer isolamento em sandbox e impede que os usuários o desativem.
• allowBypass: false impede que o modelo solicite que um comando individual seja executado fora da área restrita.
• addCurrentWorkingDirectory: false impede que Copilot CLI adicione automaticamente o diretório de trabalho atual aos caminhos de leitura e gravação da sandbox.
• sandboxMcpServers: true exige que os servidores MCP locais iniciados por Copilot CLI sejam executados na área restrita. Os servidores MCP remotos não são executados na área restrita local.
• sandboxLspServers: true exige que os servidores de linguagem iniciados por Copilot CLI sejam executados no sandbox.
• gitAuth: false impede que Copilot CLI injete um token GitHub para operações Git HTTPS autenticadas no ambiente restrito.
• ghAuth: false impede Copilot CLI de injetar um token GitHub para GitHub CLI no sandbox.
• allowDevToolAccess: false impede o acesso automático à configuração da ferramenta de desenvolvimento, caches, registros e carrinhos de ferramentas. Esses locais podem conter credenciais ou tokens de registro de pacotes. Desabilitar o acesso pode fazer com que a restauração de pacotes, as operações autenticadas no registro ou as compilações que usam caches compartilhados falhem, a menos que você conceda explicitamente acesso aos caminhos necessários.
• userPolicy: Um objeto que configura restrições do sistema de arquivos, de rede e específicas do Seatbelt no macOS. As propriedades compatíveis são descritas nas seções a seguir.

sandbox.userPolicy.filesystem

Configura o acesso ao sistema de arquivos para processos em sandbox. Os caminhos devem ser absolutos. As listas gerenciadas de permissões são comparadas com as listas configuradas pelo usuário pela string exata do caminho, e não pela abrangência de caminhos pai ou filho.

• readwritePaths: uma matriz de caminhos que os processos em área restrita podem ler e gravar. Um caminho configurado pelo usuário permanecerá disponível somente se sua cadeia de caracteres exata também aparecer em todas as fontes gerenciadas que especificam essa propriedade. Uma matriz gerenciada vazia remove todas as concessões de caminho de leitura/gravação configuradas pelo usuário, mas não remove o acesso montado separadamente, como diretórios temporários ou o diretório de trabalho atual.
• readonlyPaths: uma matriz de caminhos que os processos em área restrita podem ler, mas não gravar. Um caminho configurado pelo usuário permanecerá disponível somente se sua cadeia de caracteres exata também aparecer em todas as fontes gerenciadas que especificam essa propriedade. Uma matriz gerenciada vazia remove todas as concessões de caminho somente leitura configuradas pelo usuário, mas não remove o acesso montado separadamente.
• deniedPaths: uma matriz de caminhos que os processos em área restrita não podem acessar. Um valor gerenciado é adicionado aos caminhos bloqueados de um usuário, em vez de substituí-los.

sandbox.userPolicy.network

Configura o acesso à rede para processos em área restrita.

• allowOutbound: false bloqueia o acesso à rede de saída.
• allowLocalNetwork: false impede o acesso à rede local.

O comportamento da rede varia de acordo com o sistema operacional. Em particular, um proxy não é um limite de controle de saída completo porque alguns aplicativos podem ignorar as configurações de proxy.

sandbox.userPolicy.seatbelt

Configura opções de Cinto de Segurança específicas do macOS.

• keychainAccess: false impede que processos em área restrita acessem o conjunto de chaves do macOS.