Diretório de configuração do GitHub Copilot CLI

Copilot CLI armazena sua configuração, histórico de sessão, logs e personalizações em um único diretório em seu computador. Por padrão, esse diretório é ~/.copilot (ou seja, $HOME/.copilot).

Este artigo descreve o conteúdo deste diretório e como você pode usá-los.

Visão geral do diretório

O ~/.copilot diretório contém os seguintes itens de nível superior.

Arquivos editáveis pelo usuário

Os arquivos a seguir foram projetados para serem editados diretamente por você ou gerenciados por meio de comandos da CLI.

settings.json

Este é o arquivo de configuração principal para Copilot CLI. Em uma sessão, você pode usar o comando interativo /settings para alterar valores específicos ou executar /settings KEY VALUE para definir um único valor. Consulte Alterando as configurações com o /settings comando. Como alternativa, você pode editar o settings.json arquivo diretamente em um editor de texto. O arquivo dá suporte a JSON com comentários (JSONC).

Por padrão, esse arquivo está localizado no ~/.copilot diretório, que é o diretório de configuração no nível do usuário. Ele contém padrões globais de nível de usuário para todos os repositórios. Você pode alterar o local desse diretório definindo a variável de COPILOT_HOME ambiente para um caminho diferente.

Se settings.json falhar ao ler, analisar ou validar, Copilot CLI ignorará os valores inválidos e mostrará um aviso de inicialização na linha do tempo direcionando você para a guia Problemas do comando /settings. Abra essa guia para ver o erro específico e, em seguida, corrija o problema relatado para restaurar as configurações afetadas.

Se settings.json contiver uma chave de nível superior que não seja uma configuração reconhecida (por exemplo, um erro de digitação), Copilot CLI liste-a na guia Problemas do /settings comando em vez de na linha do tempo ou no stderr. O rótulo da aba exibe uma contagem (por exemplo, Problems (2)) quando qualquer escopo de configuração apresenta um problema. $schema é tolerado e nunca relatado.

Se ~/.copilot/settings.json for um link simbólico — por exemplo, para sincronizar configurações usando um repositório de dotfiles —, as gravações do comando /settings seguem o link simbólico e atualizam seu destino, em vez de substituir o link simbólico por um arquivo comum.

Para obter a lista completa de configurações e como elas interagem com a configuração no nível do repositório, consulte configurações de arquivo mais adiante neste artigo.

Use copilot config no shell, fora de uma sessão, para ler ou alterar as configurações de forma não interativa: o equivalente em script ao comando de barra /settings. Adicionar --repo ou --local ao destino .github/copilot/settings.json ou .github/copilot/settings.local.json em vez do arquivo de configurações do usuário; somente chaves substituíveis por repositório podem ser gravadas lá. Consulte referência de comando da CLI GitHub Copilot para obter a referência de comando completa.

copilot-instructions.md

Instruções personalizadas pessoais que se aplicam a todas as suas sessões, independentemente de em qual projeto você está trabalhando. Esse arquivo funciona da mesma maneira que um nível copilot-instructions.md de repositório, mas se aplica globalmente.

Para obter mais informações, consulte Adicionando instruções personalizadas do repositório para GitHub Copilot.

instructions/

Armazene aqui arquivos de instrução pessoal adicionais como arquivos *.instructions.md. Elas são carregadas junto com copilot-instructions.md e se aplicam a todas as suas sessões. Você pode organizar instruções por tópico, por exemplo, ~/.copilot/instructions/code-style.instructions.md.

mcp-config.json

Define os servidores MCP (Protocolo de Contexto de Modelo) disponíveis no nível do usuário. Esses servidores estão disponíveis em todas as suas sessões, independentemente de qual diretório de projeto você esteja. As configurações MCP de nível de projeto (em .mcp.json ou .github/mcp.json) têm precedência sobre definições no nível do usuário quando os nomes de servidor entram em conflito.

Para obter mais informações, consulte Adicionando servidores MCP para GitHub Copilot CLI.

lsp-config.json

Define servidores LSP (Language Server Protocol) disponíveis no nível do usuário. Esses servidores fornecem inteligência de linguagem (diagnóstico, conclusões etc.) para o agente. Gerencie este arquivo usando o /lsp comando de barra, ou edite-o diretamente.

Para obter mais informações, consulte Adicionando servidores LSP para GitHub Copilot CLI.

providers.json

Define um registro de provedores e modelos BYOK (bring-your-own-key), como um objeto JSON com providers e models chaves. Quando esse arquivo declara qualquer provedor ou modelo, ele tem precedência sobre as variáveis de ambiente herdadas COPILOT_PROVIDER_* .

Por padrão, esse arquivo está localizado em ~/.copilot/providers.json. Substitua sua localização com a variável de ambiente COPILOT_PROVIDERS_CONFIG.

Os modelos neste arquivo estão disponíveis junto com os modelos fornecidos por sua Copilot assinatura. Depois de editar o arquivo manualmente, reinicie Copilot CLI para carregar suas alterações. Para obter instruções de configuração, confira Adicionando modelos LLM à CLI de GitHub Copilot.

Estrutura de configuração do provedor

Use um objeto JSON, sem comentários ou vírgulas à direita. O arquivo contém dois arrays. Cada provedor define uma conexão e cada modelo se refere a um desses provedores pelo nome. Nas tabelas abaixo, [] significa uma entrada em um array. Por exemplo, models[].capabilities.supports.vision é a vision configuração dentro supports, dentro capabilities, dentro de uma entrada de modelo.

Um arquivo ausente ou vazio, ou um arquivo sem entradas de provedor ou modelo, permite que a CLI faça fallback para COPILOT_PROVIDER_* variáveis de ambiente. Um valor null para qualquer array é tratado como um array vazio. Um arquivo com JSON inválido ou entradas de modelo ou provedor inválido produz um erro de configuração.

Para usar um modelo configurado ao iniciar a CLI, passe PROVIDER-NAME/MODEL-ID na opção --model. PROVIDER-NAME é o valor do name provedor e MODEL-ID é o valor do id modelo. Por exemplo, execute copilot --model local/qwen3:8b. Como alternativa, durante uma sessão interativa, você pode inserir /model e escolher o modelo no seletor.

Esse arquivo configura conexões, recursos de modelo e instruções de modelo para uso em Copilot CLI. O JSON neste arquivo não é um corpo de solicitação de API do provedor. As configurações não são passadas para o provedor quando você as adiciona a esse arquivo.

Configurações do provedor

Cada entrada em providers aceita os campos a seguir. Apenas name e baseUrl são sempre obrigatórios. Os requisitos de autenticação dependem do provedor.

O arquivo de provedor nomeado não dá suporte apiKeyCommand. Não coloque credenciais ou comandos de atualização de token em metadata ou localModel.args.

Configurações do servidor de modelo local

Essas configurações se aplicam somente quando providers[].type é "local_model" e baseUrl é um caminho para um arquivo .gguf. A CLI é iniciada llama-server quando o modelo é usado pela primeira vez. O executável deve ser instalado e estar disponível em PATH. Use um caminho de modelo absoluto para evitar depender do diretório do qual você inicia a CLI.

Se baseUrl for uma URL HTTP ou HTTPS, a CLI se conectará a esse servidor existente e não usará essas configurações de inicialização. Eles também não configuram o Ollama ou outros servidores compatíveis com OpenAI.

Todos os campos dentro providers[].localModel são opcionais.

A CLI gerencia o caminho do modelo do servidor, o host e a porta do servidor. Você não pode passar --model, -m, --host ou --port através de args, incluindo formas como --port=8080.

Configurações do modelo

Cada entrada em models aceita os campos a seguir. Somente id e provider são necessários.

Os três campos de limite de token aceitam números inteiros de 0 a 4294967295. Use valores positivos apropriados para sua implantação em vez de depender de 0 como uma maneira de desabilitar um limite. Essas configurações informam à CLI quais limites usar, mas não aumentam a capacidade real do modelo.

Funcionalidades do modelo

O models[].capabilities objeto descreve o modelo. Definir um recurso para true não adiciona esse recurso a um modelo que não dá suporte a ele.

Todos os campos de funcionalidade são opcionais. Os objetos são mesclados com os padrões do modelo, e os arrays substituem os arrays padrão correspondentes.

Recursos compatíveis do modelo

Os campos a seguir ficam dentro de models[].capabilities.supports.

Os adaptive_thinking valores têm os seguintes significados.

Para reasoning_effort, a CLI reconhece "none", "minimal", "low", , "medium", "high", "xhigh"e "max". Liste apenas os níveis compatíveis com seu modelo, por exemplo ["low", "medium", "high"]. Uma lista omitida ou vazia faz com que a CLI use seus padrões específicos do modelo. Selecione um nível com --reasoning-effort ou o seletor de modelo quando disponível.

Limites de capacidades do modelo

Os campos a seguir pertencem dentro de models[].capabilities.limits. Todos são opcionais.

Prefira os campos maxPromptTokens, maxContextWindowTokens e maxOutputTokens do modelo ao definir orçamentos de token manualmente. O Discovery pode salvar os limites em ambos os lugares. Mantenha valores duplicados consistentes, pois diferentes operações da CLI leem as duas representações. Para servidores locais gerenciados pela CLI, um limite de contexto medido pode ter precedência sobre um valor configurado.

Use números inteiros não negativos para contagens de tokens e tamanhos de imagem, e um número inteiro positivo para a contagem de imagens. Contagens de tokens e contagens de imagens devem caber entre 0 e 4294967295. Os tamanhos de imagem são medidos em bytes, não em tokens.

Mensagens do sistema do modelo

models[].systemMessage controla as instruções do sistema usadas quando a CLI cria um prompt padrão para esse modelo, inclusive para subagentes de uso geral. Isso tem precedência sobre a configuração de mensagens do sistema em toda a sessão nesses caminhos. Ele não substitui as instruções de um agente personalizado selecionado ou de um subagente especializado.

Prefira "mode": "append" quando você só precisa de instruções adicionais. Substituir ou remover instruções internas pode alterar o uso da ferramenta da CLI e outro comportamento esperado. Omita systemMessage para manter as instruções padrão, em vez de defini-la como null.

Somente os campos listados para um modo são aceitos. Por exemplo, adicionar sections sem definir "mode": "customize" causa um erro de configuração.

No conteúdo de reposição, {{copilot:memories}} insere as instruções de memória e o contexto da CLI quando disponível.

Seções de mensagem do sistema

No modo customize, models[].systemMessage.sections mapeia nomes de seção para objetos. Cada objeto especifica um action e, quando necessário, content. Por exemplo, models[].systemMessage.sections.tone altera a seção de tom.

As ações disponíveis são:

A ação transform não é suportada em providers.json porque requer um retorno de chamada de aplicativo, não uma configuração JSON salva.

Use os seguintes nomes de seção ou grupo como chaves em sections.

As alterações de seção individuais são aplicadas antes das alterações de grupo. Uma substituição de grupo substitui todas as seções pertencentes ao grupo, incluindo seções que você personalizou separadamente.

Blocos de conteúdo de mensagens do sistema

No modo replace, models[].systemMessage.contentBlocks fornece as instruções de substituição em vez da cadeia de caracteres simples content. Mantenha content presente porque ele é exigido pelo formato de configuração. Todos os blocos devem ter uma string content.

Metadados do modelo

models[].metadata é um objeto cujos valores podem ser qualquer valor JSON válido. São dados descritivos, não uma maneira de fornecer parâmetros de solicitação da API ou credenciais. Você não precisa adicionar metadados manualmente.

A descoberta de modelo pode salvar os campos de string a seguir. Deixe os valores de descoberta existentes intactos.

Exemplo de configuração do provedor

Este exemplo se conecta a um servidor Ollama existente e mostra como as funcionalidades do modelo e as instruções do sistema são aninhadas. Ele pressupõe que qwen3:8b está instalado. Os limites de token são orçamentos de exemplo, não uma indicação da capacidade máxima do modelo. Ajuste-os para corresponder ao contexto configurado em seu servidor.

{
  "providers": [
    {
      "name": "local",
      "type": "openai",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "modelProvider": "ollama"
    }
  ],
  "models": [
    {
      "id": "qwen3:8b",
      "provider": "local",
      "name": "Qwen 3 8B",
      "maxPromptTokens": 6144,
      "maxContextWindowTokens": 8192,
      "maxOutputTokens": 2048,
      "capabilities": {
        "supports": {
          "vision": false,
          "toolCalls": true
        }
      },
      "systemMessage": {
        "mode": "customize",
        "sections": {
          "tone": {
            "action": "append",
            "content": "\nUse concise explanations."
          }
        }
      }
    }
  ]
}

{
  "providers": [
    {
      "name": "local",
      "type": "openai",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "modelProvider": "ollama"
    }
  ],
  "models": [
    {
      "id": "qwen3:8b",
      "provider": "local",
      "name": "Qwen 3 8B",
      "maxPromptTokens": 6144,
      "maxContextWindowTokens": 8192,
      "maxOutputTokens": 2048,
      "capabilities": {
        "supports": {
          "vision": false,
          "toolCalls": true
        }
      },
      "systemMessage": {
        "mode": "customize",
        "sections": {
          "tone": {
            "action": "append",
            "content": "\nUse concise explanations."
          }
        }
      }
    }
  ]
}

Depois de reiniciar a CLI, selecione este modelo com copilot --model local/qwen3:8b ou o seletor /model. Adicione mais objetos a qualquer array para configurar outros provedores e modelos.

agents/

Armazene as definições de agente personalizado pessoal aqui como .agent.md arquivos. Os agentes colocados neste diretório estão disponíveis em todas as suas sessões. Se um agente pessoal e um agente no nível do projeto tiverem a mesma ID, por exemplo, se ambos os arquivos de nível superior forem nomeados reviewer.agent.md, o agente pessoal terá precedência. O campo opcional de frontmatter name não controla a desduplicação, portanto, agentes com o mesmo name, mas IDs diferentes, ambos são carregados.

Para obter mais informações, consulte Criando e usando agentes personalizados para GitHub Copilot CLI.

skills/

Armazene as definições de habilidades personalizadas pessoais aqui. Cada habilidade reside em um subdiretório que contém um SKILL.md arquivo, por exemplo, ~/.copilot/skills/my-skill/SKILL.md. As habilidades pessoais estão disponíveis em todas as suas sessões. Habilidades de nível de projeto têm prioridade sobre habilidades pessoais caso compartilhem o mesmo nome.

Para obter mais informações, consulte Adicionando habilidades de agente para GitHub Copilot CLI.

hooks/

Armazene os scripts de gancho no nível do usuário aqui. Esses ganchos se aplicam a todas as suas sessões. Você também pode definir ganchos em linha no arquivo de configuração do usuário (~/.copilot/settings.json) usando a chave hooks. Os ganchos no nível do repositório (in .github/hooks/) são carregados junto com ganchos no nível do usuário.

Para obter mais informações, consulte Usando ganchos com GitHub Copilot CLI.

extensions/

Armazene arquivos de extensão no nível do usuário aqui. As extensões neste diretório estão disponíveis entre sessões.

Você pode criar arquivos neste diretório manualmente ou criar uma extensão e editar o arquivo gerado.

Arquivos gerenciados automaticamente

Os itens a seguir são gerenciados pela CLI. Você geralmente não deve editá-los manualmente.

config.json

Armazena o estado do aplicativo interno que é gerenciado automaticamente pela CLI, incluindo dados de autenticação, metadados de plug-in instalados e outras informações de runtime. Normalmente, não é necessário editar esse arquivo.

permissions-config.json

Armazena as suas decisões de permissão de ferramenta e diretório salvas, organizadas pelo local do projeto. Quando você aprova uma ferramenta ou concede acesso a um diretório para o local atual, a CLI registra a decisão aqui para que você não seja solicitado novamente no mesmo repositório ou diretório.

Local do arquivo

Copilot CLI resolve o arquivo do diretório de configuração.

A CLI usa apenas o primeiro diretório de configuração aplicável nesta ordem. Ele também não carrega permissions-config.json dos locais de menor prioridade.

A --config-dir opção é uma opção herdada. Prefira COPILOT_HOME quando precisar alterar o diretório de configuração.

No Windows, o arquivo padrão normalmente é:

C:\Users\YOUR-USER\.copilot\permissions-config.json

Builds mais antigos usavam um arquivo sem extensão chamado permissions-config. Se permissions-config.json não existir, mas o arquivo sem extensão existir, a CLI ainda continuará usando o arquivo legado. Use permissions-config.json para novas edições.

Os locais anteriores de configuração baseados em XDG são migrados para ~/.copilot na inicialização quando COPILOT_HOME não está definido.

Chaves de localização

O objeto de nível locations superior é chaveado por um caminho absoluto.

• Para um repositório Git, use a raiz do Git como base para definir o escopo das permissões.
• As árvores de trabalho vinculadas apontam para a raiz do repositório principal; portanto compartilham permissões com a árvore de trabalho principal.
• Os submódulos usam seu próprio diretório de trabalho.
• Para um diretório que não esteja em um repositório Git, use o diretório de trabalho atual normalizado.

A chave deve corresponder ao local em que Copilot CLI está em execução. Se a chave não corresponder, as aprovações salvas não serão aplicadas.

A CLI carrega as aprovações do local correspondente quando uma sessão é iniciada e quando o diretório de trabalho ativo é alterado.

Schema

O arquivo deve conter um objeto JSON.

permissions-config.json não dá suporte a regras de negação, regras de "pergunta", modos padrão, regras de URL, filtragem de ferramentas ou política compartilhada local do repositório. Para esses comportamentos, use opções de linha de comando, como --deny-tool, --available-tools, , --excluded-toolse --allow-url``--deny-url. As regras de URL salvas são armazenadas em settings.json, não em permissions-config.json.

Campos desconhecidos não fazem parte do esquema. A CLI pode ignorá-las, e operações de gravação subsequentes podem removê-las.

Tipos de aprovação

Cada item em tool_approvals deve ser um dos seguintes objetos.

Para aprovações do MCP, serverName deve corresponder exatamente ao nome do servidor MCP configurado. Use o nome original do servidor da sua configuração do MCP, não um prefixo de nome de ferramenta sanitizado.

Correlação de comandos do Shell

permissions-config.json não oferece suporte a expressões regulares nem a padrões glob em geral. Os valores da cadeia de caracteres são comparados literalmente, exceto que um :* à direita em um valor commandIdentifiers do Shell se correlaciona ao texto antes de :*, isoladamente ou seguido por um espaço e mais texto. Um * simples não tem nenhum significado especial, portanto git* não corresponde a git status.

Correlação de diretórios

As entradas de allowed_directories permitem que a Copilot CLI acesse os caminhos dentro desses diretórios sem um prompt de caminho separado. Eles não aprovam a operação da ferramenta em si. Por exemplo, editar um arquivo em um diretório permitido ainda pode exigir uma write aprovação.

Cada allowed_directories entrada deve ser um diretório absoluto, não vazio e acessível. A CLI resolve os symlinks antes de comparar caminhos, bloqueia os caminhos de rede UNC, a menos que sejam caminhos locais de comprimento estendido, compara caminhos sem diferenciar maiúsculas de minúsculas no Windows e compara os caminhos diferenciando maiúsculas de minúsculas em outras plataformas. Se uma entrada não puder ser aplicada, a CLI registrará um aviso e ignorará essa entrada.

Examples

Permitir todos os subcomandos git e acessar um diretório local extra:

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

Permita comandos selecionados enquanto ainda pede a confirmação antes de gravações de arquivos:

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

Aprove as gravações de arquivo e um servidor MCP para um repositório:

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

Aprove uma ferramenta MCP, gravações de memória e acesso às permissões da extensão:

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

session-state/

Contém dados de histórico de sessão, organizados por ID de sessão em subdiretórios. Cada diretório de sessão armazena um log de eventos (events.jsonl) e artefatos de workspace (planos, pontos de verificação, arquivos rastreados). Esses dados permitem que a sessão seja retomada (--resume ou --continue).

Excluir arquivos desse diretório remove apenas cópias locais. Se você tiver sincronizado sessões com sua GitHub conta, os dados sincronizados serão armazenados separadamente e não serão afetados pela exclusão de arquivo local. Você pode excluir ou ocultar sessões sincronizadas de GitHub.com. Para obter mais informações, consulte Sobre os dados da sessão do GitHub Copilot.

command-history-state/

Contém dados de histórico de comandos usados para pesquisa reversa (Ctrl+R) e navegação de histórico na interface interativa. Esse diretório é gerenciado automaticamente e não deve ser editado.

session-store.db

Um banco de dados SQLite usado pela CLI para armazenamento de dados entre sessões, como indexação e buscas de checkpoints. Esse arquivo é gerenciado automaticamente e não deve ser editado.

Se você excluir esse arquivo, poderá recompilá-lo usando o /chronicle reindex comando. A reindexação também sincroniza seus dados de sessão com sua conta.

logs/

Contém arquivos de log para sessões da CLI. Cada sessão cria um arquivo de log chamado process-{timestamp}-{pid}.log. Esses arquivos são úteis na depuração de problemas.

A CLI também pode criar logs específicos de extensão em logs/extensions/.

Isso é separado do ~/.copilot/extensions/, que armazena o código de extensão criado pelo usuário.

installed-plugins/

Contém os arquivos para plug-ins instalados. Os plug-ins instalados de um marketplace são armazenados em installed-plugins/{marketplace-name}/{plugin-name}/. Os plug-ins instalados diretamente são armazenados em installed-plugins/_direct/. Gerencie plug-ins usando os copilot plugin comandos em vez de editar esse diretório diretamente.

Para obter mais informações, consulte referência de plugin da CLI GitHub Copilot.

plugin-data/

Contém dados persistentes para plug-ins instalados, organizados pelo marketplace e pelo nome do plug-in. Esses dados são gerenciados pelos próprios plug-ins e não devem ser editados manualmente.

ide/

Contém arquivos de bloqueio e estado para integrações de IDE (por exemplo, quando Copilot CLI se conecta a Visual Studio Code). Esse diretório é gerenciado automaticamente.

mcp-oauth-config/

Contém arquivos de fallback do token OAuth do MCP, de registro e de PKCE quando o armazenamento com suporte do keychain não está disponível. Esse diretório é gerenciado automaticamente.

mcp-secrets/

Inclui armazenamento de arquivos de fallback e um índice para espaços reservados de segredos do MCP quando o armazenamento baseado em keychain não está disponível. Esse diretório é gerenciado automaticamente.

Alterando o local do diretório de configuração

Para substituir o local padrão ~/.copilot , defina a COPILOT_HOME variável de ambiente para o caminho do diretório que você deseja usar.

export COPILOT_HOME=/path/to/my/copilot-config

export COPILOT_HOME=/path/to/my/copilot-config

Coisas que devem ser observadas

• COPILOT_HOME substitui todo o caminho ~/.copilot. O valor definido deve ser o caminho completo para o diretório que você deseja usar para os arquivos de configuração e subdiretórios.

• Alterar o diretório significa que a configuração existente, o histórico de sessão, os plug-ins instalados e as permissões salvas não serão encontrados no novo local. Copie ou mova o conteúdo de ~/.copilot para o novo local, para preservá-los.

• O diretório de cache (usado para caches do marketplace, pacotes de atualização automática e outros dados efêmeros) segue as convenções da plataforma e não é afetado por COPILOT_HOME. Ele está localizado em:

  • macOS: ~/Library/Caches/copilot
  • Linux: $XDG_CACHE_HOME/copilot ou ~/.cache/copilot
  • Windows:%LOCALAPPDATA%/copilot

  Para substituir o diretório de cache separadamente, defina COPILOT_CACHE_HOME.

O que você pode excluir com segurança

Configurações do arquivo de configuração

As configurações são aplicadas nesta ordem (as posteriores substituem as anteriores):

1. Padrões internos
2. Configurações gerenciadas por MDM (gerenciamento de dispositivos móveis)
3. Configurações do usuário (~/.copilot/settings.json)
4. Configurações do repositório (.github/copilot/settings.json)
5. Configurações locais (.github/copilot/settings.local.json)
6. Variáveis de ambiente
7. Sinalizadores de linha de comando

As configurações gerenciadas por MDM são carregadas durante a inicialização e mescladas com as configurações do usuário como linha de base da política. Para a maioria das chaves, as configurações do usuário podem substituir essa linha de base. Para permissions.disableBypassPermissionsMode, um valor MDM de "disable" sempre prevalece. As configurações gerenciadas sandbox são outra exceção. Em vez de ser substituível, cada valor gerenciado de sandbox define um limite mínimo que você não pode flexibilizar. Se sua própria configuração for mais permissiva, o valor gerenciado ganhará. A sandbox.failIfUnavailable configuração só pode ser definida por um administrador. Para obter mais informações, consulte as configurações gerenciadas do MDM.

A interface de linha de comando também lê .claude/settings.json e .claude/settings.local.json para o subconjunto compartilhado entre ferramentas das configurações do repositório (como companyAnnouncements, disableAllHooks, enabledPlugins, extraKnownMarketplaces e hooks).

Os padrões do repositório são opcionais: defina as entradas enabledPlugins como false nas configurações locais do repositório para substituir os padrões do repositório. As entradas de plug-in necessárias ou bloqueadas gerenciadas sempre têm prioridade. Consulte Localizando e instalando plug-ins para GitHub Copilot CLI.

Configurações do usuário (~/.copilot/settings.json)

Essas configurações se aplicam em todas as suas sessões e repositórios. Você pode usar o /settings comando barra para executar uma caixa de diálogo interativa ou usar comandos de barra específicos para atualizar valores individuais ou editar esse arquivo diretamente.

A /sandbox caixa de diálogo agrupa a autenticação do Git, gh a autenticação e as variáveis de ambiente mascaradas em uma guia Credenciais dedicadas e mostra o settings.json caminho em que a configuração atual do sandbox é armazenada. Na guia Sistema de Arquivos, a lista de caminhos configurada é resumida por permissão (por exemplo, 2 read/write, 1 read-only) em uma linha Caminhos configurados pelo usuário. Pressione Enter nessa linha para abrir a lista completa, que assume o cursor e a barra de tabulação até pressionar Esc. Os caminhos configurados são exibidos como caminhos absolutos em vez de ./formulários relativos ou ~abreviados. Digitar ~/path ao adicionar um caminho ainda o expande para o diretório pessoal. Pressione Ctrl+E na /sandbox caixa de diálogo para salvar as alterações pendentes e abrir settings.json no editor (COPILOT_EDITOR``VISUALouEDITOR), correspondendo ao mesmo atalho em /settings. A caixa de diálogo recarrega seu estado a partir do disco após editar e salvar o arquivo.

Regras de host e sandbox.userPolicy.network.proxy usam um proxy local interno. Quando ambos são configurados, o proxy local aplica as regras de host antes de encaminhar o tráfego para o proxy upstream. As credenciais upstream permanecem fora do processo filho em área restrita. As regras de host e as configurações de proxy ficam inativas quando o acesso de saída está desativado.

Quando nenhum proxy é definido nas configurações de área restrita, o proxy local seleciona seu proxy upstream a partir da primeira variável de ambiente não vazia no host nesta ordem: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY. Somente http:// e https:// proxies têm suporte, não socks5.

Destinos que correspondem ao host NO_PROXY ignoram apenas este proxy upstream herdado. O proxy local da sandbox ainda manipula essas conexões e aplica suas regras de host. Um proxy configurado nas configurações de sandbox ignora NO_PROXY.

No macOS e no Linux, o sandbox restringe as conexões diretas para que os programas não possam evitar o proxy. No Windows, o sandbox depende de programas que respeitam as configurações de proxy. Como resultado, os programas que ignoram as configurações de proxy no Windows podem se conectar diretamente e contornar suas regras de host. As regras de proxy e host do Windows também exigem um host com suporte e allowLocalNetwork: true, o que permite acesso à rede privada. No Linux, as configurações de proxy rejeitam literais de endereço IPv6 diferentes do [::] curinga de pilha dupla. Use um ponto de extremidade IPv4 ou um nome de host com suporte para IPv4.

As configurações de sandbox são de nível de usuário ou gerenciadas pela empresa. Eles não podem ser sobrescritos no nível do repositório. Para obter as etapas de configuração e as limitações de rede, consulte Configurando as configurações locais da sandbox.

O sandboxing é viabilizado por Microsoft eXecution Container (MXC), que fornece mecanismos de isolamento específicos da plataforma. Copilot CLIusa o Seatbelt no macOS, o Bubblewrap no Linux e o ProcessContainer no Windows.

Configurações do repositório (.github/copilot/settings.json)

As configurações do repositório se aplicam a todos que trabalham no repositório. Eles são comprometidos com o repositório e compartilhados com colaboradores.

Somente as chaves listadas na tabela a seguir têm suporte no nível do repositório. Todas as outras chaves, incluindo chaves válidas no arquivo de configuração do usuário, são ignoradas silenciosamente. Cada chave compatível tem uma política de mesclagem direcional que mantém a substituição fechada em caso de falha e segura.

As substituições model, effortLevel econtextTier só se aplicam quando o diretório de trabalho é confiável.

Um plug-in habilitado somente por meio do enabledPlugins de um repositório fica restrito a esse repositório: ele é instalado e ativado automaticamente no repositório em que é declarado, mas permanece desabilitado globalmente, de modo que nunca é ativado em projetos não relacionados. Sair do repositório ou o repositório desativar o plugin encerra seu servidor MCP e desativa seus agentes e habilidades para a sessão.

Lista de permissões de modelos no nível do repositório (.github/allowed_models.txt)

Restrinja quais modelos integrados um repositório pode usar com uma lista de permissões em texto simples em .github/allowed_models.txt, resolvida a partir da raiz do repositório no diretório de trabalho atual (ou do próprio diretório de trabalho fora de um repositório).

Cada linha é um padrão glob comparado com IDs de modelo ou uma diretiva fallback: que nomeia o modelo a ser usado quando o modelo configurado ou solicitado não for permitido:

# .github/allowed_models.txt
fallback: gpt-6-astra
gpt-6-astra
gpt-6-sol
claude-sonnet-*

Padrões negados (!pattern) não são suportados; o modelo de fallback deve ser um ID exato (não um padrão glob) e o próprio modelo de fallback deve corresponder a um dos padrões glob configurados. Copilot CLI reavalia a política /cd e rejeita um arquivo inválido com um erro antes de executar.

A lista de permissões se aplica apenas aos modelos integrados de Copilot. Ele não pode filtrar modelos personalizados adicionados usando o método BYOK (traga suas próprias chaves de API). Os modelos BYOK permanecem listados e selecionáveis independentemente dos padrões configurados e a fallback: diretiva nunca se aplica a eles. Para obter mais informações, consulte Habilitar modelos personalizados para GitHub Copilot em sua empresa e Habilitar modelos personalizados para GitHub Copilot em sua organização.

Configurações locais (.github/copilot/settings.local.json)

Crie .github/copilot/settings.local.json no repositório para configurações pessoais que não devem ser confirmadas. Adicione este arquivo a .gitignore.

O arquivo de configuração local usa o mesmo esquema que o arquivo de configuração do repositório (.github/copilot/settings.json) e tem precedência sobre ele.

Configurações gerenciadas de MDM

Os administradores de TI podem implantar a política de base por meio de configurações gerenciadas por MDM (Mobile Gerenciamento de Dispositivos), em vez de exigir configuração individual por usuário. Essas configurações aplicam padrões no nível do dispositivo para chaves compatíveis e são carregadas antes das configurações do usuário.

As configurações gerenciadas se aplicam uniformemente a todos os modos de hospedagem de sessão — interativo, -p, --acp, --ahp-host e --server —, de modo que as políticas corporativas de MCP, permissões e plug-ins não possam ser contornadas ao iniciar uma sessão por um ponto de entrada diferente.

Copilot CLI também carrega configurações gerenciadas pelo servidor na inicialização, além do MDM. As configurações gerenciadas pelo dispositivo (MDM) e pelo servidor são resolvidas por chave: o valor do MDM prevalece para qualquer chave que ele defina, e o valor do servidor preenche as chaves que o MDM deixa não definidas. Isso permite que uma organização defina alguma política por meio do MDM (por exemplo, permissions) enquanto ainda recebe outros padrões gerenciados (por exemplo, model) do servidor.

Sessões de longa duração buscam e reaplicam as configurações gerenciadas a cada hora, portanto, as alterações de política — por exemplo, uma organização habilitando permissions.disableBypassPermissionsMode — entram em vigor sem reiniciar a sessão.

Fontes de configurações gerenciadas do MDM

A Copilot CLI lê as configurações gerenciadas de localizações específicas de plataforma baseadas em arquivo ou MDM.

Formato de arquivo

Escreva configurações gerenciadas baseadas em arquivo como JSON.

{
    "model": "auto",
    "permissions": {
        "disableBypassPermissionsMode": "disable"
    }
}

Chaves com suporte

Somente as chaves a seguir têm suporte nas configurações gerenciadas do MDM.

sandbox.learningMode é exclusivo do Windows e só pode ser definido por meio do MDM nativo (por exemplo, por meio do Intune ou do Registro) — um valor do arquivo managed-settings.json é ignorado. Em um host com captura de negação, defina-o para "allow" iniciar comandos de shell em área restrita no modo de registro e permissão em vez do modo padrão de registro e negação, gravando cada acesso ao sistema de arquivos ou ao processo e permitindo-o em vez de recusá-lo (a política de rede ainda é imposta). Isso permite que um administrador observe o que os comandos de uma coorte precisam antes de bloqueá-los; não é um modo de contenção. A linha de status mostra sandbox relaxed e as chamadas de shell mostram (sandbox relaxed) enquanto é aplicado. deny valor (o padrão), ou a remoção da chave, retorna a coorte para o sandbox padrão aplicado, e deny de qualquer canal gerenciado sempre tem precedência sobre allow. As configurações do usuário e os hosts do SDK não podem definir essa chave.

Regras de permissão gerenciada

Adicionar deny, aske allow listas de regras sob a chave gerenciada permissions para impor uma política de permissão para todos. Isso funciona se está ou não permissions.disableBypassPermissionsMode definido.

{
    "permissions": {
        "deny": ["Shell(rm -rf *)", "Domain(*.evil.example)"],
        "ask": ["Shell(git push *)"],
        "allow": ["Read(**)"]
    }
}

As regras são combinadas entre as fontes gerenciadas com uma precedência fixa: negar sempre vence, depois perguntar e, por fim, permitir — a correspondência com uma regra deny bloqueia a solicitação, mesmo que uma regra allow também corresponda. deny e ask são combinados entre todas as fontes gerenciadas (servidor, MDM). allow requer que todas as fontes que declaram uma lista allow admitam a operação — uma interseção, não uma união. Quando qualquer um de deny, ask ou allow é definido, uma operação que não corresponde a nenhum deles assume ask como padrão, em vez de prosseguir silenciosamente.

As regras Edit(...) e Write(...) se aplicam a mais do que apenas as ferramentas de arquivo integradas. Eles também abrangem arquivos gravados diretamente por um comando de shell. Copilot CLI reconhece um conjunto fixo dessas operações de escrita. Ele aborda redirecionamentos de saída do Bash (>, >>, >|, &>, &>>), redirecionamentos de saída do PowerShell (>, >>, *>, *>>) e um pequeno conjunto de edições no local com sed (sed -i ou --in-place, e as formas BSD -i '' e -I ''). Quando Copilot CLI consegue determinar o arquivo de destino a partir do comando, uma regra deny correspondente bloqueia a escrita, e uma regra ask correspondente solicita sua confirmação primeiro. Isso se aplica mesmo quando uma regra ampla, como Shell(*) de outra forma, permitiria o comando. Às vezes, o arquivo de destino não pode ser trabalhado antecipadamente, por exemplo, quando o caminho vem de uma variável. Nesse caso, essas regras de caminho não se aplicam e o comando é verificado pelas regras de comando do shell normais.

Limite de domínio (limitTo)

Adicione um limitTo array junto com deny, ask e allow sob a chave gerenciada permissions para impor uma lista de permissões de domínio de mundo fechado:

{
    "permissions": {
        "limitTo": ["github.com", "*.github.com"]
    }
}

Somente entradas Domain(...) são compatíveis em limitTo. Qualquer solicitação de rede de agente para um domínio fora da lista é negada sem pedir confirmação, e as regras de usuário, aprovações salvas e modos de permitir tudo não podem ampliá-la. As URLs detectadas em solicitações de shell são tratadas como solicitações Domain e também devem atender à fronteira. limitTo não restringe as operações shell, read ou write por si só.

Uma lista vazia limitTo nega todas as solicitações de domínio. Uma lista inválida ou uma entrada inválida é imposta como uma lista vazia (e relatada como um erro de configuração) em vez de descartar o restante da política gerenciada.

deny ainda tem precedência sobre limitTo. ask e allow refinam apenas as solicitações que já estão dentro do limite. Por allowexemplo, limitTo é uma interseção entre fontes gerenciadas— todas as fontes gerenciadas que declaram uma lista limitTo devem admitir a solicitação.

Lista de permissões/negações do servidor MCP gerenciado

Os administradores podem controlar servidores MCP diretamente por meio de configurações gerenciadas de MDM, independentemente da lista de permissões do MCP corporativo.

Definir allowedMcpServers e/ou deniedMcpServers em uma fonte de configurações gerenciadas:

{
    "allowedMcpServers": [
        { "serverUrl": "https://mcp.example.com/*" },
        { "serverCommand": ["npx", "-y", "@example/mcp-server"] }
    ],
    "deniedMcpServers": [
        { "serverName": "untrusted-server" }
    ]
}

Cada entrada identifica um servidor por exatamente um dos seguintes critérios de correspondência.

Réguas:

• Servidores de primeira parte confiáveis (por exemplo, o servidor MCP interno GitHub ) são sempre isentos de ambas as listas.
• Unset allowedMcpServers permite todos os servidores não padrão; uma matriz vazia bloqueia todos eles (negar-tudo).
• Não definido ou vazio deniedMcpServers não bloqueia nada.
• A negação sempre prevalece—um servidor que corresponde a deniedMcpServers é bloqueado mesmo que também corresponda a allowedMcpServers.
• Para servidores remotos, uma correspondência deve vir de uma entrada serverUrl; serverName só conta quando não existem entradas serverUrl. Para servidores stdio, uma correspondência deve vir de uma entrada serverCommand; serverName só conta quando não existem entradas serverCommand.

Leitura adicional

• GitHub Copilot CLI
• referência de comando da CLI GitHub Copilot
• referência programática do GitHub Copilot CLI
• referência de plugin da CLI GitHub Copilot
• Referência de ganchos do GitHub Copilot