referência de comando da CLI GitHub Copilot

Comandos de linha de comando

copilot login opções

Em um terminal local ou em um processo local não TTY que ainda pode acessar um navegador (por exemplo, um sistema operacional da área de trabalho ou Linux com um sinal de exibição ou navegador), o modo de autenticação padrão é um fluxo da Web baseado em navegador: a CLI abre seu navegador para autorizar e captura o resultado em um retorno de chamada de loopback local. Em um terminal remoto (por exemplo, GitHub CodespacesSSH ou um contêiner de desenvolvimento) ou em CI, a CLI usa como padrão o fluxo de código do dispositivo OAuth, já que o navegador normalmente não pode acessar a porta de loopback. Use --web-flow ou --device-code para substituir o fluxo selecionado automaticamente.

Após a conclusão, um token de autenticação é armazenado com segurança no repositório de credenciais do sistema. Se um repositório de credenciais não for encontrado, o token será armazenado em um arquivo de configuração em texto simples em ~/.copilot/ (ou no diretório especificado por COPILOT_HOME, se definido).

Como alternativa, Copilot CLI usará um token de autenticação encontrado em variáveis de ambiente. Os seguintes são verificados em ordem de precedência: COPILOT_GITHUB_TOKEN, , GH_TOKEN. GITHUB_TOKEN Esse método é mais adequado para uso sem cabeça, como automação.

Os tipos de token compatíveis incluem fine-grained personal access tokens (PATs v2) com a permissão "Solicitações do Copilot", tokens OAuth do aplicativo CLI Copilot e tokens OAuth do aplicativo GitHub CLI (gh). Clássicos personal access tokens (ghp_) não são suportados.

Exemplos:

# Authenticate with github.com
copilot login

# Authenticate with GitHub Enterprise Cloud (data residency)
copilot login --host https://example.ghe.com

# Force the device code flow, for example on a remote terminal
copilot login --device-code

# Force the browser (web) flow, for example on a local terminal
copilot login --web-flow

# Read a token from standard input, bypassing the OAuth flow entirely
copilot login --with-token < mytoken.txt

# Use a fine-grained PAT via environment variable
COPILOT_GITHUB_TOKEN=github_pat_... copilot

Usando copilot completion

O comando copilot completion SHELL gera um script para o shell especificado (bash, zsh ou fish).

Ao executar este script (ou gravá-lo no diretório de autocompletar do seu shell), você pode habilitar o autocompletar com a tecla Tab no seu terminal para subcomandos copilot, opções de comando e valores conhecidos para opções de comando.

Exemplos de uso

Bash (somente sessão atual):

source <(copilot completion bash)

source <(copilot completion bash)

Bash (persistente, Linux):

copilot completion bash | sudo tee /etc/bash_completion.d/copilot

copilot completion bash | sudo tee /etc/bash_completion.d/copilot

Zsh: grave a saída em um diretório no seu $fpath. Reinicie o shell depois de executar este comando:

copilot completion zsh > "${fpath[1]}/_copilot"

copilot completion zsh > "${fpath[1]}/_copilot"

Peixe:

copilot completion fish > ~/.config/fish/completions/copilot.fish

copilot completion fish > ~/.config/fish/completions/copilot.fish

Usando copilot plugins list

Execute copilot plugins list para inspecionar cada plug-in, servidor MCP, habilidade, fonte de instrução e servidor de idioma descobertos para o diretório de trabalho atual. A saída é agrupada por categoria e, em seguida, por escopo de configuração (usuário, repositório, organização, fornecido por plug-in, integrado ou desconhecido).

# List everything for the current workspace
copilot plugins list

# Only MCP servers and skills
copilot plugins list --kind mcp --kind skill

# Only user-scoped resources, as JSON
copilot plugins list --scope user --json

Agentes personalizados e hooks restritos à sessão não são abrangidos por copilot plugins list; ambos exigem uma sessão ativa.

copilot plugins enable / copilot plugins disable

Habilite ou desabilite um plug-in, um servidor MCP ou uma habilidade por nome. A alteração persiste na configuração e se aplica a sessões futuras.

# Disable an MCP server
copilot plugins disable github --mcp

# Enable a skill
copilot plugins enable my-skill --skill

# Enable a plugin (default kind)
copilot plugins enable spark@copilot-plugins

As instruções são válidas apenas para a sessão atual e não podem ser ativadas ou desativadas com esses comandos. Servidores de linguagem, agentes e ganchos são gerenciados em outro lugar.

copilot plugins remove

Desinstale um plug-in, remova um servidor MCP ou exclua uma habilidade por nome.

# Remove an MCP server
copilot plugins remove github --mcp

# Delete a personal or project skill
copilot plugins remove my-skill --skill

# Uninstall a plugin (default kind)
copilot plugins remove spark@copilot-plugins

Com --skill, passe um nome de habilidade ou o caminho para um diretório de habilidades personalizado que você adicionou. Um nome de habilidade exclui os arquivos dessa habilidade; um caminho de diretório personalizado cancela apenas o registro do diretório e deixa seus arquivos em disco. Somente as habilidades pessoais e de projeto que você adicionou podem ser excluídas– as habilidades fornecidas por um plug-in ou pelo conjunto de buildin não podem ser removidas dessa forma (desabilitá-las em vez disso). As fontes de instrução são descobertas do disco e não podem ser removidas aqui.

Atalhos globais na interface interativa

Em sessões locais, você pode enfileirar prompts, comandos de shell e comandos de barra compatíveis para serem executados em ordem após a conclusão da tarefa atual. Pressione Ctrl+Q para enfileirar a entrada atual enquanto o agente está em execução. As entradas na fila exibem um rótulo "pendente" e podem ser canceladas individualmente antes de serem executadas.

Atalhos de linha do tempo na interface interativa

Atalhos da caixa de diálogo Tarefas

Quando a caixa de diálogo de tarefas estiver aberta (aberta via /tasks):

Subagentes que geram seus próprios subagentes aninhados aparecem como uma árvore recuada; a linha em que você é teletransportado é realçada como "atual". Ao entrar na visualização de um subagente, você pode enviar uma mensagem de orientação pelo compositor da mesma forma que faria na sessão principal.

Atalhos do seletor de sessão

Quando o seletor de sessão estiver aberto (aberto por meio /resume ou --continue):

As sessões são classificadas pelos seguintes modos:

As sessões já abertas em outra janela são movidas para o topo em todos os modos de classificação que não sejam por relevância. Quando não há contexto de diretório de trabalho disponível, o modo relevance é ignorado.

Atalhos do modo de diferimento

Quando o modo de diferimento está aberto (inserido por meio de /diff):

Atalhos de navegação na interface interativa

Comandos de barra na interface interativa

Esses são os comandos de barra que você pode usar em uma sessão interativa da CLI. Um subconjunto desses comandos com barra está disponível para clientes que usam a CLI por meio do servidor ACP. Para obter mais informações, consulte Servidor da ACP da CLI do Copilot.

Para obter uma lista completa dos comandos slash disponíveis, insira /help na interface interativa da CLI.

No gerenciador de agendamento aberto com um simples pressionamento de /every ou /after, use ↑/↓ para selecionar um item e x para removê-lo. Os agendamentos só podem ser adicionados a partir da entrada do prompt usando /every ou /after com argumentos — a própria caixa de diálogo permite apenas visualizar e remover.

/plugin sinaliza um plug-in ou marketplace instalado quando uma versão mais recente está disponível upstream e oferece uma ação de atualização do painel.

/mcp list / ls e /plugin list/ls (incluindo /plugin simples) são somente leitura e podem ser executados enquanto o agente está ocupado processando uma interação. Todos os outros subcomandos /mcp e /plugin são bloqueados até que o turno seja concluído.

Opções de linha de comando

Para obter uma lista completa de comandos e opções, execute copilot help.

Você pode usar --remote com --resume <TASK-ID> para retomar uma tarefa remota localmente. Isso funciona mesmo quando a tarefa foi criada originalmente fora de um repositório Git.

Se uma sessão ainda estava aberta quando o processo da CLI foi embora, por exemplo, devido a uma falha ou uma reinicialização do computador, na próxima vez que você iniciar copilot , será oferecida a opção de restaurá-la. Você pode ver as sessões disponíveis para restauração ou, em vez disso, iniciar uma nova sessão. Uma sessão restaurada cujo agente estava no meio do turno retoma automaticamente esse trabalho.

Planeje e depois piloto automático

O Plan-then-autopilot permite que uma sessão comece no modo de plano e continue automaticamente no modo de piloto automático quando o plano estiver pronto, sem esperar que um humano aprove a transição. Habilite-o com --plan --mode autopilot, ou com a variável de ambiente COPILOT_PLAN_THEN_AUTOPILOT para estruturas de teste que só conseguem injetar variáveis de ambiente, e não opções de linha de comando. Se ambos forem definidos, as opções explícitas têm precedência e a CLI exibe um aviso de que a variável de ambiente foi ignorada.

Nível da sandbox gerenciada pela empresa

Uma política gerenciada pela empresa pode impor o isolamento em sandbox do shell no nível do sistema operacional como nível mínimo. Em outras palavras, mesmo que você forneça --no-sandbox, a política ainda assim pode forçar a ativação do sandbox. Essa é uma substituição de política, não uma falha do sinalizador em si. Por outro lado, --sandbox não é afetado porque só ativa o sandboxing e nunca o remove.

Quando uma política gerenciada substitui sua configuração, a CLI mostra um aviso na linha do tempo interativa (ou no stderr ao usar -p) para que fique claro que o comportamento vem da imposição da política em vez da opção não funcionar. Entre em contato com o administrador se precisar que a política seja alterada. O comando /sandbox também é registrado sempre que uma política gerenciada impõe o uso de sandboxing, mesmo sem recursos experimentais ativados, para que você ainda possa inspecionar a política efetiva e o status enquanto essa imposição estiver em vigor. Disponível apenas no modo experimental.

A CLI também avisa quando uma política gerenciada habilita o sandboxing em uma sessão que você não solicitou, não apenas quando ela substitui --no-sandbox. Isso inclui sessões em que a política chega após a inicialização, pois as configurações gerenciadas pelo servidor só estão disponíveis após o logon. O aviso será omitido caso suas próprias configurações ou a opção --sandbox já tenham solicitado isolamento em sandbox, já que o estado da sessão seria então esperado.

Se um dispositivo tiver uma política gerenciada que não puder ser lida, a CLI falhará em modo fechado e aplicará o isolamento em sandbox no nível mais restritivo. O aviso explica que a política não pôde ser determinada e diz para você esperar que ela seja resolvida. O aviso de inicialização para um host sem suporte usa a mesma redação.

Restringindo as opções --allow-all

Quando permissions.disableBypassPermissionsMode é definido como "disable", todas as opções de linha de comando que permitem todas as permissões (--allow-all-tools, , --allow-all-paths, --allow-all-urls, --allow-all, --yolo) são suprimidas na inicialização e não podem ser usadas para conceder permissões elevadas. O /permissions allow-all comando barra e seus aliases /allow-all e /yolotambém são suprimidos.

Defina permissions.disableBypassPermissionsMode como "allow-auto-only" para bloquear permissões irrestritas, mas permitir /permissions assisted (aprovação de permissões assistida por LLM). A aprovação assistida ainda solicita confirmação para cada solicitação, mas anexa uma recomendação de segurança da LLM para que a CLI possa aprovar automaticamente as solicitações que o modelo considerar aceitáveis.

Se permissions.disableBypassPermissionsMode estiver definido como um valor não reconhecido, a CLI não o rejeitará totalmente. Em vez disso, a CLI registra o problema e aplica "disable" como comportamento padrão de bloqueio por padrão, de modo que uma política gerenciada malformada ainda restrinja as opções de “permitir tudo”, em vez de permiti-las silenciosamente.

Três fontes podem definir essa restrição, aumentando a ordem de permanência:

Para obter detalhes de configuração do MDM, consulte Diretório de configuração do GitHub Copilot CLI.

Modelos com suporte

Use --model=MODEL ou a variável de COPILOT_MODEL ambiente para selecionar o modelo de IA. Passe auto para permitir Copilot a escolha do melhor modelo disponível automaticamente.

Você também pode alternar entre modelos durante uma sessão interativa usando o comando de barra /model.

Valores de disponibilidade da ferramenta

As opções --available-tools e --excluded-tools dão suporte a estes valores:

Ferramentas do Shell

Ferramentas de operação de arquivo

Ferramentas de delegação de agente e tarefas

Outras ferramentas

Padrões de permissão de ferramenta

As opções --allow-tool e --deny-tool aceitam padrões de permissão no formato Kind(argument). O argumento é opcional: omiti-lo corresponde a todas as ferramentas desse tipo.

Para as shell regras, o sufixo :* corresponde ao comando principal seguido por um espaço, impedindo correspondências parciais. Por exemplo, shell(git:*) corresponde git push e git pull não corresponde gitea.

As regras de negação sempre têm precedência sobre as regras de permissão, mesmo quando --allow-all estão definidas.

# Allow all git commands except git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

# Allow a specific MCP server tool
copilot --allow-tool='MyMCP(create_issue)'

# Allow all tools from a server
copilot --allow-tool='MyMCP'

# Deny writes to a specific path (exact or trailing-path-segment match; no glob support yet)
copilot --deny-tool='write(secret.txt)'

--deny-tool='write(PATH)' define o escopo da negação a esse caminho — outras gravações não são afetadas. A correspondência resolve symlinks e segmentos ./.., e não faz distinção entre maiúsculas e minúsculas no macOS e no Windows.

Variáveis de ambiente

Configurações do arquivo de configuração

Para obter informações detalhadas sobre as configurações do arquivo de configuração, incluindo a lista completa de configurações de usuário, configurações de repositório, configurações locais e como elas são em cascata, consulte Diretório de configuração do GitHub Copilot CLI.

inicialização do projeto Copilot

Quando você usa o comando copilot init ou o comando barra /init em uma sessão interativa, Copilot analisa sua base de código e grava ou atualiza um arquivo .github/copilot-instructions.md no repositório. Este arquivo de instruções personalizado contém diretrizes específicas do projeto que melhorarão as sessões futuras da CLI.

Normalmente, você usará copilot init, ou /init, quando iniciar um novo projeto ou quando começar a usar Copilot CLI em um repositório existente.

O copilot-instructions.md arquivo que é criado ou atualizado normalmente documenta:

• Comandos de compilação, teste e lint.
• Arquitetura de alto nível.
• Convenções específicas do Codebase.

Se o arquivo já existir, Copilot sugerirá melhorias que você pode optar por aplicar ou rejeitar.

A CLI procura o copilot-instructions.md arquivo na inicialização e, se ele estiver ausente, ele exibirá a mensagem:

💡 Nenhuma instrução de co-piloto foi encontrada. Execute /init para gerar um arquivo copilot-instructions.md para este projeto.

Se você não quiser criar esse arquivo, poderá ocultar permanentemente essa mensagem de inicialização para o repositório atual usando o /init suppress comando barra.

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

Use --sandbox ou --no-sandbox com copilot init para habilitar ou desabilitar o sandbox do shell no nível do sistema operacional apenas para a sessão de inicialização, sem alterar a configuração de sandbox salva. Essas opções estão sujeitas ao mesmo nível mínimo de sandbox gerenciado pela empresa que outros pontos de entrada — consulte Nível mínimo de sandbox gerenciado pela empresa.

Locais de instruções personalizadas

Copilot CLI carrega instruções personalizadas desses locais simultaneamente (todas são mescladas):

Importações de instruções personalizadas

Os arquivos de instruções oferecem suporte a @path importações. Prefixe uma linha com @ seguido por um caminho para alinhar o conteúdo de outro arquivo. Os caminhos podem ser relativos ao diretório do arquivo de instrução ou absoluto. As importações são resolvidas recursivamente, até um limite de profundidade, com proteções contra ciclos e limites de tamanho. Isso tem suporte em AGENTS.md, CLAUDE.mde .github/copilot-instructions.md.

Referência de ganchos

Para obter informações detalhadas sobre ganchos, incluindo formatos de configuração de gancho, eventos de gancho, conteúdos de entrada e controle de decisão, consulte Referência de ganchos do GitHub Copilot.

Configuração do servidor MCP

Os servidores MCP fornecem ferramentas adicionais para o agente da CLI. Configurar servidores persistentes em ~/.copilot/mcp-config.json. Use --additional-mcp-config para adicionar servidores para uma única sessão.

Os servidores locais (stdio) que são iniciados dentro do sandbox (consulte o comando de barra /sandbox) mostram o status connected (sandboxed) em copilot mcp list e /mcp list, pois os servidores remotos (HTTP/SSE) nunca são executados em sandbox. Disponível apenas no modo experimental.

copilot mcp list e /mcp list marcam um servidor desabilitado com o sufixo (disabled) na saída em texto ou com "enabled": false por servidor na saída --json. copilot mcp get mostra uma Status: Enabled/Disabled linha.

Ao alternar /sandbox, apenas os servidores MCP locais (stdio) são reiniciados, pois são iniciados dentro do sandbox. Os servidores remotos (HTTP/SSE) permanecem conectados.

copilot mcp Subcomando

Use copilot mcp para gerenciar as configurações do servidor MCP da linha de comando sem iniciar uma sessão interativa.

Para servidores locais (stdio), forneça o comando após --:

copilot mcp add SERVER-NAME -- COMMAND [ARGS...]

copilot mcp add SERVER-NAME -- COMMAND [ARGS...]

Para servidores HTTP ou SSE remotos, especifique o transporte e forneça a URL:

copilot mcp add --transport http SERVER-NAME URL

copilot mcp add --transport http SERVER-NAME URL

** copilot mcp add Opções:**

No formulário interativo, insira o /mcp add campo como pares separados por vírgulas / ou como um objeto JSON (por exemplo, /mcp edit).env``KEY=VALUE``{"API_KEY":"secret"} $PATH é incluído por padrão e não precisa ser listado.

Tipos de transporte

Campos de configuração do servidor local

Cache de instantâneo de ferramentas

Copilot CLI salva um instantâneo da lista de ferramentas de cada servidor local para que as ferramentas fiquem disponíveis imediatamente ao iniciar, enquanto a descoberta em tempo real é concluída em segundo plano. A descoberta em tempo real sempre é executada e substitui o snapshot quando é concluída.

Defina disableToolCache: true em um servidor para forçar a descoberta em tempo real somente para esse servidor ou defina a variável de ambiente COPILOT_MCP_TOOL_CACHE=false para desabilitar o carregamento e a persistência de instantâneos para o processo inteiro. Ambas as recusas deixam os arquivos de cache existentes intocados.

Registro npm privado

Use --registry no array args para obter um pacote de um registro npm privado – por exemplo, Artifactory ou um feed de pacotes GitHub:

{
    "mcpServers": {
        "my-internal-server": {
            "command": "npx",
            "args": [
                "--registry", "https://npm.pkg.github.com",
                "@my-org/internal-mcp-server"
            ],
            "tools": ["*"]
        }
    }
}

A opção --registry e outras opções de configuração do npm (--userconfig, , --prefix``--globalconfig, --cache, --node-options, --workspace, -w) são tratadas como argumentos que consomem valor ao calcular a impressão digital de identidade do servidor. Isso garante que as verificações de lista de permissões da empresa e a verificação do registro funcionem corretamente quando essas opções aparecerem antes do nome do pacote.

Campos de configuração de servidor remoto

Autenticação nova do OAuth

Servidores MCP remotos que usam OAuth podem mostrar um needs-auth status quando um token expira ou quando uma conta diferente é necessária. Use /mcp auth <server-name> para disparar um fluxo OAuth novo. Isso abre um prompt de autenticação do navegador, permitindo que você entre ou alterne contas. Depois de concluir o fluxo, o servidor se reconecta automaticamente.

OAuth sem periféricos (concessãoclient_credentials )

Para casos de uso de CI ou cron em que nenhum navegador está disponível, defina oauthGrantType: "client_credentials". Isso requer:

• oauthClientId— a ID do cliente estático emitida pelo provedor MCP.
• oauthPublicClient: false— o cliente é confidencial.
• O client_secret armazenado no chaveiro do sistema (configurada uma vez pela interface do usuário /mcp ou por meio de gravação no OAuth Credential Store).

Quando configurada, a CLI ignora totalmente o navegador, o servidor de retorno de chamada, o PKCE e o registro dinâmico do cliente. A cada 401, ele envia grant_type=client_credentials diretamente para o ponto de extremidade de token descoberto do servidor.

{
    "mcpServers": {
        "headless-api": {
            "type": "http",
            "url": "https://api.example.com/mcp",
            "tools": ["*"],
            "oauthClientId": "YOUR-CLIENT-ID",
            "oauthPublicClient": false,
            "oauthGrantType": "client_credentials"
        }
    }
}

Mapeamento de filtro

Controlar como a saída da ferramenta MCP é processada usando o filterMapping campo na configuração de um servidor.

Servidores MCP internos

A CLI inclui servidores MCP internos que estão disponíveis sem configuração adicional.

Use --disable-builtin-mcps para desabilitar todos os servidores internos ou --disable-mcp-server SERVER-NAME desabilitar um específico.

GitHub Ferramentas do servidor MCP

github-mcp-server fornece as seguintes ferramentas.

Nomenclatura do servidor MCP

Os nomes de servidor podem conter caracteres imprimíveis, incluindo espaços, caracteres Unicode e pontuação. Caracteres de controle (U+0000–U+001F, U+007F) e a chave de fechamento (}) não são permitidos. Os nomes de servidor são usados como prefixos para nomes de ferramentas, por exemplo, um servidor nomeado my-server produz nomes de ferramentas como my-server-fetch, e um servidor nomeado My Server produz My Server-fetch.

Sanitização do nome da ferramenta MCP

Nomes de servidor MCP e nomes de ferramentas são sanitizados antes de serem enviados para o modelo. Caracteres inválidos em nomes de ferramentas (qualquer coisa diferente de a-z, A-Z, 0-9, -, _) são substituídos por -. Os caracteres Unicode são codificados em Punycode. O símbolo @ também é substituído por - para evitar conflitos com a codificação Punycode.

O nome combinado (serverName-toolName) é limitado a 64 caracteres. Quando o truncamento criaria uma colisão de nome, um sufixo numérico é acrescentado (por exemplo, my-server-tool2, my-server-tool3) para garantir a unicidade.

Níveis de confiança do servidor MCP

Os servidores MCP são carregados de várias fontes, cada uma com um nível de confiança diferente.

Todas as invocações da ferramenta MCP exigem permissão explícita. Isso se aplica até mesmo a operações somente leitura em serviços externos.

Prioridade de carregamento do servidor MCP

Os servidores MCP de diferentes fontes são mesclados em ordem de prioridade (primeiro mais alto). Quando os servidores compartilham um nome, a fonte de prioridade mais alta tem precedência.

1. --additional-mcp-config opção (máxima)
2. Servidores disponibilizados por plug-ins
3. Servidores de espaço de trabalho – .mcp.json e .github/mcp.json carregados do diretório de trabalho até a raiz do Git; requer que a pasta seja confiável
4. ~/.copilot/mcp-config.json (mais baixo)

Lista de permissões do MCP da Empresa

GitHub Enterprise as organizações podem impor uma lista de permissões de servidores MCP permitidos. Quando ativa, a CLI avalia cada servidor não padrão em relação à política corporativa antes de se conectar.

Quando uma política do registro GitHub Enterprise é detectada (ou o sinalizador de recurso experimental MCP_ENTERPRISE_ALLOWLIST está habilitado), a CLI:

1. Calcula uma impressão digital para cada servidor não padrão configurado com base em seu comando, argumentos e URL remota.
2. Envia as impressões digitais para o ponto de extremidade de avaliação da lista de permissões da empresa.
3. Permite apenas servidores cujas impressões digitais são aprovadas; todos os outros são bloqueados com uma mensagem nomeando a empresa.

Essa verificação é encerrada por falha: se o ponto de extremidade de avaliação não for acessível ou retornar um erro, os servidores não padrão serão bloqueados até que a política possa ser verificada.

Quando um servidor é bloqueado por uma lista de permissões da empresa, a CLI exibe:

MCP server "SERVER-NAME" was blocked by your enterprise "ENTERPRISE-NAME".
Contact your enterprise administrator to add this server to the allowlist.

Os servidores padrão internos são sempre isentos da imposição da lista de permissões.

Migrando de .vscode/mcp.json

Se o projeto usar .vscode/mcp.json (formato de configuração MCP do VS Code), migre para .mcp.jsonGitHub Copilot CLI. A migração mapeia novamente a servers chave para mcpServers.

Shells POSIX (bash, zsh, fish e outros):

jq '{mcpServers: .servers}' .vscode/mcp.json > .mcp.json

Requer jq.

PowerShell:

pwsh -NoProfile -Command "`$json = Get-Content '.vscode/mcp.json' -Raw | ConvertFrom-Json; `$content = ([pscustomobject]@{ mcpServers = `$json.servers } | ConvertTo-Json -Depth 100); [System.IO.File]::WriteAllText('.mcp.json', `$content, (New-Object System.Text.UTF8Encoding `$false))"

Em Windows, substitua pwsh por powershell se estiver usando Windows PowerShell em vez do PowerShell Core.

Saída do servidor Stdio

O transporte stdio do MCP reserva o stdout exclusivamente para mensagens JSON-RPC delimitadas por quebras de linha. A interface de linha de comando (CLI) filtra automaticamente todas as linhas que não estão em JSON — logs em texto simples, rastreamentos de pilha de exceções ou linhas contendo apenas espaços em branco — antes de encaminhar a saída ao analisador do protocolo.

Escreva toda a saída de diagnóstico em stderr, não stdout. Um servidor que grava logs ou mensagens de erro no stdout pode disparar um loop de comentários de erro de análise que trava o handshake de inicialização; o filtro impede isso soltando silenciosamente quadros não JSON.

Linhas com mais de 1 MB não passam pela verificação estrutural e são encaminhadas como estão, para evitar dividir ou descartar quadros de protocolo grandes demais, mas válidos (por exemplo, uma resposta tools/list grande).

Referência de habilidades

As habilidades são arquivos markdown que estendem o que a CLI pode fazer. Cada habilidade reside em seu próprio diretório que contém um SKILL.md arquivo. Quando invocado (via /SKILL-NAME ou automaticamente pelo agente), o conteúdo da habilidade é injetado na conversa.

Campos de frontmatter de habilidades

Localizações de habilidades

As habilidades são carregadas desses locais em ordem de prioridade (o primeiro encontrado vence para nomes duplicados).

As habilidades remotas são projetadas juntamente com as habilidades locais e seguem a mesma prioridade baseada em nome quando uma habilidade local tem o mesmo nome.

Quando dois plug-ins fornecem habilidades com o mesmo nome, ambos coexistem usando nomes de invocação qualificados para plug-in, como /my-plugin/search e /other-plugin/search. O nome simples é encaminhado para o plug-in com prioridade mais alta. Isso se aplica somente a habilidades; os comandos mantêm a eliminação de duplicação baseada em camada padrão, em que a fonte de prioridade mais alta vence.

Instalando uma habilidade de forma não interativa

Use copilot plugins install --skill para instalar uma habilidade de um arquivo, URL ou diretório sem abrir uma sessão interativa:

# Install for your user account (default scope)
copilot plugins install --skill ./my-skill/SKILL.md

# Install into the current project (.github/skills; file or URL skills only)
copilot plugins install --skill --scope project ./my-skill/SKILL.md

Instalar um diretório registra-o como uma fonte de habilidade personalizada em vez de copiá-lo. A instalação de um arquivo ou URL copia o conteúdo da habilidade no diretório de habilidades pessoais ou de projeto. O comando interativo equivalente é /skills add [--project] <FILE|URL|DIRECTORY>. Para obter a referência de opção completa, consulte referência de plugin da CLI GitHub Copilot.

Comandos (formato de habilidade alternativa)

Os comandos são uma alternativa às habilidades armazenadas como arquivos individuais .md em .claude/commands/. O nome do comando é derivado do nome do arquivo. Os arquivos de comando usam um formato simplificado (nenhum name campo necessário) e dão suporteargument-hint, descriptione allowed-tools``disable-model-invocation. Os comandos têm prioridade menor do que as habilidades com o mesmo nome.

Referência de agentes personalizados

Agentes personalizados são agentes de IA especializados definidos em arquivos Markdown. O nome do arquivo (extensão menos) torna-se a ID do agente. Use .agent.md ou .md como a extensão de arquivo.

Agentes integrados

code-review e security-review nunca encaminham uma revisão completa para outro agente de revisão: iniciar um deles já atende a uma solicitação para "usar" ou "chamar" um revisor, portanto eles próprios realizam a revisão, em vez de delegar toda a tarefa para um subagente code-review ou security-review aninhado, recursivamente, ao longo de toda a cadeia de delegação. code-review ainda encaminha para o especialista dedicado security-review as partes de uma solicitação voltadas à segurança, e ambos os agentes podem delegar a agentes que não fazem revisão, como explore, um trabalho pontual de levantamento de fatos com escopo independente.

Campos de frontmatter personalizados do agente

model e reasoningEffort se aplicam independentemente de o agente ser despachado pela ferramenta task ou iniciado diretamente — por exemplo, por meio do SDK session.startSubagent. Isso é resolvido com a seguinte precedência, da mais alta para a mais baixa: um valor explícito por chamada, a substituição subagents em model, o campo /reasoningEffort``~/.copilot/settings.json da definição do agente e, em seguida, o valor da sessão pai. Um modelo ou esforço declarado que não possa ser atendido recorre ao valor da sessão em vez de fazer o despacho falhar.

Locais do agente personalizado

Para agentes com escopo no projeto, a CLI percorre os diretórios ascendentes a partir do diretório de trabalho atual até a raiz do Git, carregando os diretórios .github/agents/ e .claude/agents/ em cada nível de ancestral. Isso significa que cada pacote ou subdiretório em um repositório único pode fornecer seus próprios agentes. Quando vários .github/agents/ diretórios existem no caminho, todos são carregados, com o diretório mais profundo tendo a prioridade mais alta. A convenção .github/agents/ tem precedência sobre .claude/agents/ no mesmo nível. Os agentes de nível de usuário têm prioridade menor do que os agentes no nível do projeto. Os agentes de plug-in têm a prioridade mais baixa.

Comunicação do agente

Use list_agents e write_agent dentro de agentes personalizados para inspecionar agentes próximos e coordenar o trabalho em uma sessão com vários agentes.

Rótulos de relação em list_agents

Os rótulos de relação identificam como agentes visíveis se relacionam com o agente atual. Os rótulos aparecem quando um subagente é executado em uma sessão principal com a comunicação compartilhada entre sessões irmãs habilitada.

Listagem restrita ao escopo

Use scope em list_agents para restringir a lista antes de escolher os alvos.

Em sessões com um único agente, a exibição padrão é centralizada nos agentes secundários. Em sessões de vários agentes, o modo de exibição padrão mostra o contexto local imediato em vez de toda a árvore.

list_agents(scope="siblings")
list_agents(scope="children")
list_agents(scope="all")

Mensagens com escopo

Use scope em write_agent para enviar uma mensagem a vários agentes relacionados.

Use mensagens com escopo restrito apenas a partir de um subagente em execução dentro de uma sessão principal com a comunicação compartilhada entre sessões irmãs habilitada. Em sessões de nível superior, tenha como alvo os agentes com valores explícitos de agent_id.

Se um escopo corresponder a muitos agentes, write_agent retorna um erro e, em vez disso, solicita valores explícitos de agent_id de list_agents.

write_agent(scope="children", message="Re-check your findings against the updated schema.")
write_agent(scope="siblings", message="Post status when your current check completes.")
write_agent(agent_id="explore-auth", message="Focus on token refresh flow and report only confirmed issues.")

Limites de subagente

A CLI impõe limites de profundidade e simultaneidade para impedir a geração de agente fugitivo.

A profundidade conta quantos agentes estão aninhados dentro um do outro. Quando o limite de profundidade é atingido, o agente mais interno não pode gerar subagentes adicionais. Concorrência conta quantos subagentes estão sendo executados simultaneamente em toda a árvore de sessão. Quando o limite é atingido, novas solicitações de subagente são rejeitadas até que um agente ativo finalize sua tarefa.

O limite de simultaneidade padrão depende do seu Copilot plano:

Usuários com cobrança baseada no uso podem ignorar esses limites com as configurações subagents.maxConcurrency e subagents.maxDepth:

{
    "subagents": {
        "maxConcurrency": 16,
        "maxDepth": 10
    }
}

Os valores fora do intervalo válido são limitados: maxConcurrency é limitado a 32, e maxDepth é limitado a 256. Essas configurações são ignoradas para planos que não usam cobrança baseada em uso. Consulte as configurações do arquivo de configuração.

Agentes assistentes

Os agentes sidekick são executados automaticamente em segundo plano e publicam o contexto na caixa de entrada da sessão. Eles respondem a eventos de sessão em vez de serem invocados explicitamente.

Adicione um bloco sidekick: a qualquer definição de agente para transformá-lo em um agente auxiliar:

---
name: Context Gatherer
description: Gathers relevant context when the working directory changes
sidekick:
    triggers:
        - session.context_changed
        - event: user.message
          limit: 1
    behavior: persistent
    maxSendsPerTurn: 2
---

Gather useful context about the current repository and working directory.
Summarize recent changes and any relevant project structure.

Gatilhos de sidekick

Cada entrada em triggers é uma string simples com o nome do evento, que é disparada um número ilimitado de vezes, ou um objeto com event e um limit opcional.

Campos de configuração do sidekick

O comportamento de "restart" é indicado para agentes de coleta de contexto sem estado. O comportamento de "persistent" é adequado para agentes que acumulam estado ao longo dos turnos.

Respostas de aprovação de permissão

Quando a CLI solicita permissão para executar uma operação, você pode responder com as seguintes chaves.

Quando a caixa de diálogo completa é mostrada, você também pode escolher entre estas opções:

Essa opção de local é exibida quando a CLI pode determinar uma chave de local (raiz do Git ou diretório atual). A permissão é salva no disco, de modo que a mesma permissão é concedida automaticamente na próxima vez que você trabalhar nesse diretório, sem que seja necessário confirmar novamente.

Use /permissions reset para limpar as aprovações na memória da sessão atual.

Segurança

Modo planejamento

/plan inicia uma sessão de planejamento em que Copilot CLI pode explorar e analisar sua base de código, mas é impedida de editar seus arquivos de projeto. Specifically:

• Os arquivos do projeto estão protegidos. Qualquer tentativa de editar, corrigir ou executar um comando de shell que alteraria um arquivo em seu workspace é bloqueada automaticamente. Isso não é apenas uma sugestão para o modelo, ele é imposto diretamente, portanto, não depende do modelo optar por se comportar.
• O plano em si ainda pode ser escrito. Copilot precisa de um lugar para manter anotações e elaborar o plano, para que ele possa criar e editar arquivos em seu próprio workspace de planejamento privado (incluindo o arquivo de plano que você examinará e aprovará).
• Subtarefas delegadas também são protegidas. Se Copilot criar uma sessão auxiliar para pesquisar parte da sua pergunta, esse auxiliar herdará as mesmas restrições e também não poderá editar seu projeto.
• É uma rede de segurança, não uma garantia. Essa proteção foi projetada para capturar tentativas claras e diretas de alterar seus arquivos, não é um bloqueio hermético. Algumas coisas são permitidas intencionalmente para que a pesquisa não seja excessivamente restrita: por exemplo, comandos de shell cujo efeito não pode ser claramente determinado com antecedência e chamadas para ferramentas externas/MCP que você conectou. Na prática, isso raramente é um problema, mas o modo de plano deve ser considerado como "as alterações exigem sua revisão antes de aplicar", não uma garantia absoluta de que nada no disco pode mudar.

Quando estiver satisfeito com o plano, aprove-o para sair do modo de planejamento e permitir que Copilot faça as alterações efetivas.

Análise de segurança de comando

Os comandos do Shell são analisados antes da execução para identificar padrões potencialmente perigosos:

• Exclusão de arquivo (rm -rf)
• Modificações do sistema (sudo, chmod 777)
• Exfiltração de rede (curl com caminhos confidenciais)
• Acesso a credenciais (leitura de .env, chaves SSH)
• Atribuições de variáveis de ambiente embutidas que substituem variáveis perigosas (por exemplo, PATH=..., ) LD_PRELOAD=...

Os comandos de alto risco exibem avisos adicionais e exigem confirmação explícita.

Quando o sandboxing está habilitado e a configuração Permitir bypass de área restrita está ativada (o padrão), um comando de shell síncrono bloqueado pelo sistema de arquivos da área restrita ou pela política de rede solicita que você a execute novamente fora da área restrita— nenhum modelo de ida e volta é necessário. Ao aprovar o prompt, o comando é executado novamente e sua saída é retornada. O declínio mantém o resultado em área restrita (bloqueado).

Para obter mais informações, consulte Configurando as configurações locais da sandbox.

Lista de negação de variável de ambiente

A interface de linha de comando (CLI) bloqueia a atribuição em linha de variáveis de ambiente, que pode ser explorada para executar código arbitrário, mesmo em comandos somente de leitura. As categorias bloqueadas incluem:

web_fetch Proteção SSRF

A ferramenta web_fetch aplica proteções contra falsificação de solicitações do lado do servidor (SSRF) antes de realizar qualquer solicitação HTTP:

• Lista de permissões de protocolo: somente http:// e https:// URLs são permitidas. file:// e outros esquemas são rejeitados.
• Lista de bloqueio de IP: solicitações para endereços de loopback (127.x.x.x, ::1), intervalos privados RFC-1918 (10.x, 172.16–31.x, 192.168.x) e endpoints de metadados da nuvem (por exemplo, 169.254.169.254) são bloqueadas pela verificação de IP literal e pela pré-resolução de DNS.
• Redirecionamentos validados: web_fetch segue 3xx redirecionamentos (até 10 saltos, dentro de um orçamento de rede de 60 segundos), validando novamente o destino de cada salto na mesma lista de bloqueios de IP antes de segui-lo. Um redirecionamento para uma origem diferente da URL original requer aprovação de permissão, o mesmo que qualquer outra busca entre origens; Os redirecionamentos de mesma origem são seguidos sem um prompt extra. O resultado final anota quando o conteúdo era (redirected from <original URL>).

Para permitir que web_fetch alcance localhost durante o desenvolvimento — por exemplo, para um servidor local de documentação — defina a seguinte variável de ambiente:

export COPILOT_WEB_FETCH_ALLOW_LOCALHOST=1

Permissões do diretório de ferramentas de sandbox

Quando o sandboxing local está habilitado, Copilot CLI descobre os diretórios de ferramentas que um comando em área restrita provavelmente precisará e concede a cada um acesso somente leitura, para que um comando possa executar uma cadeia de ferramentas instalada sem poder modificá-la . A detecção é executada para cada comando, antes que o processo seja iniciado, e lê dois tipos de fontes no ambiente do comando.

• PATH(Path em Windows). Cada diretório listado é uma concessão de candidato.
• Variáveis nomeadas da toolchain. A CLI inspeciona as variáveis na tabela abaixo em cada sistema operacional. Uma variável que contém um único diretório concede acesso a esse diretório; uma variável que contém uma lista de caminhos é separada usando o separador de caminhos do sistema operacional (; no Windows, : nos demais sistemas), e cada entrada se torna uma candidata a concessão de acesso.

Um candidato só é aceito quando é um caminho absoluto existente e resolve para um diretório. Os candidatos são descartados — e o motivo registrado no destino de log sandbox_spawn — quando são relativos, não existem, resolvem para a raiz de um sistema de arquivos (como / ou C:\) ou ficam em um local crítico do sistema (%WINDIR% no Windows; /bin, /sbin, /usr/bin, /usr/sbin, /boot, /proc, /sys e /dev no Linux e no macOS). Links simbólicos são resolvidos antes dessas verificações e diretórios duplicados são removidos (sem diferenciar maiúsculas de minúsculas em Windows).

Cada variável é lida em todas as plataformas; a coluna Normalmente definido em mostra onde cada variável é normalmente definida, não uma restrição imposta pela CLI. Uma variável não configurada simplesmente não contribui em nada.

Essas não são as únicas permissões de somente leitura. Copilot CLI também concede acesso aos diretórios de aplicativos do perfil do usuário (~/.local/bin e ~/.local/lib no Linux e macOS; os subdiretórios imediatos de %LOCALAPPDATA%\Programs no Windows), aos locais padrão do sistema e do perfil do usuário e aos caches e registros usados por gerenciadores de pacotes e cadeias de ferramentas comuns (mostrados como acesso a ferramentas de desenvolvimento no relatório /sandbox policy). Para ver a política completamente resolvida para o diretório atual — caminhos com leitura/gravação, somente leitura e negados — execute /sandbox policy em uma sessão. Para obter os conceitos por trás de como a política é montada, consulte Noções básicas sobre políticas de sistema de arquivos para área restrita local em GitHub Copilot CLI.

Monitoramento do OpenTelemetry

Copilot CLI pode exportar rastreamentos e métricas por meio do OpenTelemetry (OTel), proporcionando visibilidade das interações do agente, chamadas LLM, execuções de ferramentas e uso de token. Todos os nomes de sinal e atributos seguem as Convenções Semânticas do OTel GenAI.

O OTel está desativado por padrão sem sobrecarga. Ele é ativado quando qualquer uma das seguintes condições é atendida:

• COPILOT_OTEL_ENABLED=true
• OTEL_EXPORTER_OTLP_ENDPOINT está definido
• COPILOT_OTEL_FILE_EXPORTER_PATH está definido

A configuração do OTel também pode ser definida em VS Code, ou em um arquivo managed-settings.json de toda a empresa. Consulte Habilitar o monitoramento OTel na documentação VS Code e Configurações gerenciadas pela empresa.

Variáveis de ambiente OTel

Vestígios

O runtime emite uma árvore de intervalo hierárquica para cada interação do agente. Cada árvore contém um invoke_agent intervalo raiz, com chat e execute_tool intervalos filho.

invoke_agent atributos de 'span'

Encapsula toda a invocação do agente: todas as chamadas LLM e execuções de ferramentas para uma mensagem de usuário.

• Tanto as sessões de nível superior quanto as invocações de subagentes (por exemplo, explore, task) usam o tipo de span INTERNAL (no processo); a inferência relacionada ao provedor é representada por spans filhos CLIENT``chat.
• Sessões de nível superior também incluem server.address e server.port; invocações de subagentes não.

chat atributos de 'span'

Um intervalo por solicitação LLM. Tipo de intervalo: CLIENT.

execute_tool atributos de 'span'

Um intervalo por chamada de ferramenta. Tipo de intervalo: INTERNAL.

Métricas

Métricas de convenção do GenAI

Métricas específicas do fornecedor

Eventos com intervalo

Eventos de ciclo de vida registrados no intervalo ativo entre chat e invoke_agent.

Atributos de recursos

Todos os sinais carregam esses atributos de recurso.

Captura de conteúdo

Por padrão, nenhum conteúdo de prompt, respostas ou argumentos de ferramenta são capturados– somente metadados como nomes de modelo, contagens de token e durações. Para capturar o conteúdo completo, defina OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true.

Quando a captura de conteúdo é habilitada, os atributos a seguir são preenchidos.

Leitura adicional

• GitHub Copilot CLI
• Referência de ganchos do GitHub Copilot
• referência de plugin da CLI GitHub Copilot
• referência programática do GitHub Copilot CLI
• Diretório de configuração do GitHub Copilot CLI