referência de comando da CLI GitHub Copilot

Comandos de linha de comando

Command	Propósito
`copilot`	Inicie a interface interativa do usuário.
`copilot help [TOPIC]`	Exibir informações de ajuda. Os tópicos de ajuda incluem: `config`, , `commands`, `environment`, `logging`, `monitoring`, e permissions``providers.
`copilot init`	Inicialize Copilot instruções personalizadas para este repositório.
`copilot login`	Autentique-se com Copilot por meio do fluxo do dispositivo OAuth. Aceita `--host HOST` para especificar a URL do host GitHub (padrão: `https://github.com`).
`copilot login` [OPÇÃO]	Autentique-se com Copilot por meio do fluxo do dispositivo OAuth. Veja `copilot login` as opções.
`copilot mcp`	Gerencie as configurações do servidor MCP na linha de comando.
`copilot plugin`	Gerenciar plug-ins e mercados de plug-ins.
`copilot update`	Baixe e instale a versão mais recente.
`copilot version`	Exibir informações de versão e verificar se há atualizações.

          `copilot login` opções

Opção	Propósito
`--host HOST`

          GitHub URL do host (padrão: `https://github.com`). Use isso para autenticar com uma GitHub Enterprise Cloud instância que usa residência de dados (por exemplo, `https://example.ghe.com`). |

| --config-dir PATH | Defina o diretório de configuração (padrão: ~/.copilot). |

O modo de autenticação padrão é um fluxo de navegador baseado na Web. 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 de texto sem formatação em ~/.copilot/.

Como alternativa, CLI do Copilot 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 com suporte incluem fine-grained personal access tokens (PATs v2) com a permissão "Solicitações do Copilot", tokens OAuth do aplicativo Copilot CLI 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

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

Atalhos globais na interface interativa

Atalho	Propósito
`@ FILENAME`	Inclua o conteúdo do arquivo no contexto.
`# NUMBER`	Inclua um GitHub problema ou solicitação de pull no contexto.
`! COMMAND`	Execute um comando no shell local, ignorando Copilot.
`?`	Abra ajuda rápida (em um prompt vazio).
`Esc`	Cancele a operação atual.
`Ctrl`+`C`	Cancelar a operação/limpar a entrada. Pressione duas vezes para sair.
`Ctrl`+`D`	Desligamento.
`CTRL`+`G`	Edite o prompt em um editor externo (`$EDITOR`).
`Ctrl`+`L`	Limpar a tela.
`Ctrl`+`Enter` ou `Ctrl`+`Q`	Coloca na fila uma mensagem para enviar enquanto o agente está ocupado.
`Ctrl`+`R`	Pesquisa inversa por meio do histórico de comandos.
`Ctrl`+`V`	Cole o conteúdo da área de transferência como anexo.
`Ctrl`+`X` , em seguida, `/`	Depois de começar a digitar um prompt, isso permite que você execute um comando de barra , por exemplo, se você quiser alterar o modelo sem precisar digitar novamente o prompt.
`Ctrl`+`X` , em seguida, `e`	Edite o prompt em um editor externo (`$EDITOR`).
`Ctrl`+`X` , em seguida, `o`	Abra o link mais recente da linha do tempo.
`Ctrl`+`Z`	Suspenda o processo em segundo plano (Unix).
`Shift`+`Enter` ou `Option`+`Enter` (Mac) / `Alt`+`Enter` (Windows/Linux)	Insira uma nova linha na entrada.
`Shift`+`Tab`	Ciclo entre o modo padrão, plano e piloto automático.

Atalhos de linha do tempo na interface interativa

Atalho	Propósito
`Ctrl`+`O`	Embora não haja nada na entrada do prompt, isso expande os itens recentes na linha do tempo de resposta do Copilot para mostrar mais detalhes.
`Ctrl`+`E`	Embora não haja nada na entrada do prompt, isso expande todos os itens na linha do tempo de resposta do Copilot.
`CTRL`+`T`	Expanda/recolha a exibição de raciocínio nas respostas.
`Página Para Cima`/`Página Para Baixo`	Role a linha do tempo para cima ou para baixo em uma página.

Atalho	Propósito
`Ctrl`+`A`	Ir para o início da linha (ao digitar).
`Ctrl`+`B`	Mova para o caractere anterior.
`Ctrl`+`E`	Mover para o final da linha (quando se está digitando).
`Ctrl`+`F`	Mova para o próximo caractere.
`CTRL`+`H`	Exclua o caractere anterior.
`Ctrl`+`K`	Apague desde o cursor até o final da linha. Se o cursor estiver no final da linha, exclua a quebra de linha.
`Ctrl`+`U`	Apague desde o cursor até o início da linha.
`Ctrl`+`W`	Exclua a palavra anterior.
`Início`	Vá para o início do texto.
`End`	Mova para o final do texto.
`Alt`+`←`/`→` (Windows/Linux)

          <kbd>Opção</kbd>+<kbd>←</kbd>/<kbd>→</kbd> (Mac) | Mova o cursor uma palavra por vez.             |

Comandos de barra na interface interativa

Command	Propósito
`/add-dir PATH`	Adicione um diretório à lista de permissões para acesso ao arquivo.
`/agent`	Navegue e selecione entre os agentes disponíveis (se houver). Consulte Sobre agentes personalizados.
`/ask QUESTION`	Faça uma pergunta rápida sem adicionar ao histórico da conversa. Disponível apenas no modo experimental.
`/allow-all [on\|off\|show]`, `/yolo [on\|off\|show]`	Habilite todas as permissões (ferramentas, caminhos e URLs).
`/changelog [summarize] [VERSION\|last N\|since VERSION]`, `/release-notes [summarize] [VERSION\|last N\|since VERSION]`	Exiba o registro de alterações da CLI. Opcionalmente, especifique uma versão, uma contagem de versões recentes ou uma versão inicial. Adicione a palavra-chave `summarize` para um resumo gerado por IA.
`/chronicle <standup\|tips\|improve\|reindex>`	Ferramentas e insights sobre o histórico de sessões. Disponível apenas no modo experimental.
`/clear [PROMPT]`

          `/new [PROMPT]`
          `/reset [PROMPT]`
         | Inicie uma nova conversa. |

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

Opções de linha de comando

Opção	Propósito
`--add-dir=PATH`	Adicione um diretório à lista de permissões para acesso a arquivos (pode ser usado várias vezes).
`--add-github-mcp-tool=TOOL`	Adicione uma ferramenta para habilitar para o GitHub servidor MCP, em vez do subconjunto padrão da CLI (pode ser usado várias vezes). Use `*` para todas as ferramentas.
`--add-github-mcp-toolset=TOOLSET`	Adicione um conjunto de ferramentas para habilitar para o GitHub servidor MCP, em vez do subconjunto padrão da CLI (pode ser usado várias vezes). Use `all` para todos os conjuntos de ferramentas.
`--additional-mcp-config=JSON`	Adicione apenas um servidor MCP para esta sessão. A configuração do servidor pode ser fornecida como uma cadeia de caracteres JSON ou um caminho de arquivo (prefixo com `@`). Amplia a configuração de `~/.copilot/mcp-config.json`. Substitui qualquer configuração de servidor MCP instalada com o mesmo nome. Consulte Adicionando servidores MCP para CLI do GitHub Copilot.
`--agent=AGENT`	Especifique um agente personalizado a ser usado. Consulte Sobre agentes personalizados.
`--allow-all`	Habilitar todas as permissões (equivalente a `--allow-all-tools --allow-all-paths --allow-all-urls`).
`--allow-all-paths`	Desabilite a verificação do caminho do arquivo e permita o acesso a qualquer caminho.
`--allow-all-tools`	Permitir que todas as ferramentas sejam executadas automaticamente sem confirmação. Necessário ao usar a CLI programaticamente (env: `COPILOT_ALLOW_ALL`).
`--allow-all-urls`	Permitir acesso a todas as URLs sem confirmação.
`--allow-tool=TOOL ...`	Ferramentas que a CLI tem permissão para usar. Não solicitará permissão. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas. Consulte Permitir e negar o uso da ferramenta.
`--allow-url=URL ...`	Permitir o acesso a URLs ou domínios específicos. Para várias URLs, use uma lista entre aspas e separada por vírgulas.
`--autopilot`	Habilite a continuação do piloto automático no modo de prompt. Consulte Permitindo que GitHub Copilot CLI funcione de forma autônoma.
`--available-tools=TOOL ...`	Somente essas ferramentas estarão disponíveis para o modelo. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas. Consulte Permitir e negar o uso da ferramenta.
`--banner`, `--no-banner`	Mostrar ou ocultar o banner de inicialização.
`--bash-env`	Habilitar o suporte de `BASH_ENV` para shells bash.
`--config-dir=PATH`	Defina o diretório de configuração (padrão: `~/.copilot`).
`--connect[=SESSION-ID]`	Conecte-se diretamente a uma sessão remota (opcionalmente, especifique uma ID de sessão ou ID da tarefa). Conflitos com `--resume` e `--continue`.
`--continue`	Retome a sessão mais recente no diretório de trabalho atual, voltando à sessão globalmente mais recente.
`--deny-tool=TOOL ...`	Ferramentas que a CLI não tem permissão para usar. Não solicitará permissão. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas.
`--deny-url=URL ...`	Negar acesso a URLs ou domínios específicos, tem precedência sobre `--allow-url`. Para várias URLs, use uma lista entre aspas e separada por vírgulas.
`--disable-builtin-mcps`	Desabilitar todos os servidores MCP internos (atualmente: `github-mcp-server`).
`--disable-mcp-server=SERVER-NAME`	Desabilite um servidor MCP específico (pode ser usado várias vezes).
`--disallow-temp-dir`	Impedir o acesso automático ao diretório temporário do sistema.
`--effort=LEVEL`, `--reasoning-effort=LEVEL`	Definir o nível de esforço de raciocínio (`low`, `medium`, ). `high`
`--enable-all-github-mcp-tools`	Habilite todas as GitHub ferramentas do servidor MCP, em vez do subconjunto padrão da CLI. Substitui as opções `--add-github-mcp-toolset` e `--add-github-mcp-tool`.
`--enable-reasoning-summaries`	Solicite resumos de raciocínio para modelos OpenAI que dão suporte a ele.
`--excluded-tools=TOOL ...`	Essas ferramentas não estarão disponíveis para o modelo. Para várias ferramentas, use uma lista entre aspas e separada por vírgulas.
`--experimental`	Habilitar recursos experimentais (use `--no-experimental` para desabilitar).
`-h`, `--help`	Exibir ajuda.
`-i PROMPT`, `--interactive=PROMPT`	Inicie uma sessão interativa e execute esse prompt automaticamente.
`--log-dir=DIRECTORY`	Defina o diretório do arquivo de log (padrão: `~/.copilot/logs/`).
`--log-level=LEVEL`	Defina o nível de log (opções: `none`, , , `error`, `warning`, `info`, , `debug`). all``default
`--max-autopilot-continues=COUNT`	Número máximo de mensagens de continuação no modo de piloto automático (padrão: ilimitado). Consulte Permitindo que GitHub Copilot CLI funcione de forma autônoma.
`--mode=MODE`	Defina o modo de agente inicial (opções: `interactive`, `plan`, ). `autopilot` Não é possível combinar com `--autopilot` ou `--plan`.
`--model=MODEL`	Defina o modelo de IA que você deseja usar. Passe `auto` para permitir Copilot a escolha do melhor modelo disponível automaticamente.
`--mouse[=VALUE]`	Habilite o suporte ao mouse no modo de tela alternativa. VALUE pode ser `on` (padrão) ou `off`. Quando habilitada, a CLI captura eventos do mouse no modo de tela alt — roda de rolagem, cliques etc. Quando desabilitado, o comportamento do mouse nativo do terminal é preservado. Depois de definir a configuração, ela será salva no arquivo de configuração.
`-n NAME`, `--name=NAME`	Defina um nome para a nova sessão. Usado por `--resume` e `/resume` para localizar sessões por nome.
`--no-ask-user`	Desabilite a `ask_user` ferramenta (o agente funciona de forma autônoma sem fazer perguntas).
`--no-auto-update`	Desabilite o download de atualizações da CLI automaticamente.
`--no-bash-env`	Desative o suporte de `BASH_ENV` para shells bash.
`--no-color`	Desative toda a saída de cor.
`--no-custom-instructions`	Desabilite o carregamento de instruções personalizadas de `AGENTS.md` e arquivos relacionados.
`--no-experimental`	Desabilitar recursos experimentais.
`--no-mouse`	Desabilite o suporte ao mouse.
`--no-remote`	Desabilite o acesso remoto para esta sessão.
`--output-format=FORMAT`	FORMAT pode ser `text` (padrão) ou `json` (saídas JSONL: um objeto JSON por linha).
`-p PROMPT`, `--prompt=PROMPT`	Execute um prompt programaticamente (sai após a conclusão). Consulte Executando CLI do GitHub Copilot programaticamente.
`--plan`	Inicie no modo plano. Abreviação de `--mode plan`. Não é possível combinar com `--mode` ou `--autopilot`.
`--plain-diff`	Desative a renderização de diferenças avançadas (realce de sintaxe através da ferramenta de diff especificada na sua configuração do Git).
`--plugin-dir=DIRECTORY`	Carregue um plug-in de um diretório local (pode ser usado várias vezes).
`--remote`	Habilite o acesso remoto a esta sessão a partir de GitHub.com e GitHub Mobile. Consulte Controlando uma CLI do GitHub Copilot sessão de outro dispositivo.
`--resume[=VALUE]`	Retome uma sessão interativa anterior escolhendo em uma lista. Opcionalmente, especifique uma ID de sessão, um prefixo de ID ou um nome de sessão. A correspondência de nomes é exata e não diferencia maiúsculas de minúsculas; volta para o resumo gerado automaticamente quando nenhum nome explícito corresponde.
`-s`, `--silent`	Gerar somente a resposta do agente (sem estatísticas de uso), útil para scripts com `-p`.
`--screen-reader`	Habilitar otimizações de leitor de tela.
`--secret-env-vars=VAR ...`	Redigir uma variável de ambiente do shell e do servidor MCP (pode ser usada várias vezes). Para várias variáveis, use uma lista entre aspas e separada por vírgulas. Os valores nas variáveis de ambiente `GITHUB_TOKEN` e `COPILOT_GITHUB_TOKEN` são omitidos do resultado por padrão.
`--share=PATH`	Compartilhe uma sessão em um arquivo Markdown após a conclusão de uma sessão programática (caminho padrão: `./copilot-session-<ID>.md`).
`--share-gist`	Compartilhe uma sessão em um gist secreto do GitHub após a conclusão de uma sessão programática.
`--stream=MODE`	Habilitar ou desabilitar o modo de streaming (opções de modo: `on` ou `off`).
`-v`, `--version`	Mostrar informações de versão.
`--yolo`	Habilitar todas as permissões (equivalente a `--allow-all`).

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

Observação

As opções --remote, --no-remote e --connect exigem que o recurso de sessões remotas esteja disponível em sua conta.

Valores de disponibilidade da ferramenta

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

Ferramentas do Shell

Nome da ferramenta	Descrição
`bash` / `powershell`	Executar comandos
`list_bash` / `list_powershell`	Listar sessões ativas do shell
`read_bash` / `read_powershell`	Ler a saída de uma sessão de shell
`stop_bash` / `stop_powershell`	Encerrar uma sessão de shell
`write_bash` / `write_powershell`	Enviar entrada para uma sessão de shell

Ferramentas de operação de arquivo

Nome da ferramenta	Descrição
`apply_patch`	Aplicar patches (usados por alguns modelos em vez de `edit`/`create`)
`create`	Criar novos arquivos
`edit`	Editar arquivos por meio da substituição de cadeia de caracteres
`view`	Ler arquivos ou diretórios

Ferramentas de delegação de agente e tarefas

Nome da ferramenta	Descrição
`list_agents`	Listar agentes disponíveis
`read_agent`	Verificar o status do agente em segundo plano
`task`	Executar subagentes

Outras ferramentas

Nome da ferramenta	Descrição
`ask_user`	Faça uma pergunta ao usuário
`glob`	Localizar padrões de correspondência de arquivos
`grep`(ou `rg`)	Pesquisar texto em arquivos
`show_file`	Apresentar snippets de código embutidos na linha do tempo. Disponível apenas no modo experimental.
`skill`	Invocar habilidades personalizadas
`web_fetch`	Buscar e analisar o conteúdo da Web

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.

Variante	Descrição	Padrões de exemplo
`memory`	Armazenando fatos na memória do agente	`memory`
`read`	Leituras de arquivo ou diretório

          `read`, `read(.env)` |

| shell | Execução de comando do Shell | shell(git push) shell(git:*) shell | | url | Acesso à URL por meio de web-fetch ou shell | url(github.com), url(https://*.api.com) | | write | Criação ou modificação de arquivo | write, write(src/*.ts) | | SERVER-NAME | Invocação da ferramenta de servidor MCP | MyMCP(create_issue), MyMCP |

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'

Variáveis de ambiente

Variable	Descrição
`COLORFGBG`	Fallback para detecção de plano de fundo do terminal escuro/claro.
`COPILOT_ALLOW_ALL`	Configure para `true` permitir todas as permissões automaticamente (equivalente a `--allow-all`).
`COPILOT_AUTO_UPDATE`	Defina como `false` para desabilitar atualizações automáticas.
`COPILOT_CACHE_HOME`	Substitua o diretório de cache (usado para caches do marketplace, pacotes de atualização automática e outros dados efêmeros). Consulte Diretório de configuração do GitHub Copilot CLI para ver os padrões da plataforma.
`COPILOT_CUSTOM_INSTRUCTIONS_DIRS`	Lista separada por vírgulas de diretórios adicionais para instruções personalizadas.
`COPILOT_EDITOR`	Comando do editor para edição interativa (checado após `$VISUAL` e `$EDITOR`). Assume o valor padrão de `vi` se nenhum for definido.
`COPILOT_GH_HOST`

          GitHub nome do host apenas para CLI do Copilot, substituindo `GH_HOST`. Use quando `GH_HOST` alvos GitHub Enterprise Server , mas Copilot precisa se autenticar no GitHub.com ou no GitHub Enterprise Cloud nome de host. |

| COPILOT_GITHUB_TOKEN | Token de autenticação. Tem precedência sobre GH_TOKEN e GITHUB_TOKEN. | | COPILOT_HOME | Sobrescreva a configuração e o diretório de estado. Padrão: $HOME/.copilot. | | COPILOT_MODEL | Defina o modelo de IA. | | COPILOT_PROMPT_FRAME | Defina como 1 para habilitar o quadro decorativo da IU ao redor do prompt de entrada ou como 0 para desabilitá-lo. Substitui o PROMPT_FRAME sinalizador de recurso experimental para a sessão atual. | | COPILOT_SKILLS_DIRS | Lista separada por vírgulas de diretórios adicionais para habilidades. | | COPILOT_SUBAGENT_MAX_CONCURRENT | Máximo de subagentes simultâneos em toda a árvore de sessão. Padrão: 32. Intervalo: 1–256. | | COPILOT_SUBAGENT_MAX_DEPTH | Profundidade máxima de aninhamento de subagente. Padrão: 6. Intervalo: 1–256. | | GH_HOST | GitHub nome do host para ambos GitHub CLI e CLI do Copilot (padrão: github.com). Defina como seu GitHub Enterprise Cloud nome de host com residência de dados. Substitua com COPILOT_GH_HOST somente para CLI do Copilot. | | GH_TOKEN | Token de autenticação. Tem precedência sobre GITHUB_TOKEN. | | GITHUB_TOKEN | Token de autenticação. | | PLAIN_DIFF | Definir para true para desativar a renderização de diferenças avançadas. | | USE_BUILTIN_RIPGREP | Defina como false para usar o ripgrep do sistema em vez da versão agrupada. |

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.

Observação

As configurações do usuário foram armazenadas anteriormente em ~/.copilot/config.json. As configurações existentes nesse local são migradas automaticamente para ~/.copilot/settings.json na inicialização.

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 CLI do Copilot 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.

Referência de ganchos

Os ganchos são comandos externos, webhooks HTTP ou cadeias de caracteres de prompt ( sessionStart somente) que são executadas em pontos de ciclo de vida específicos durante uma sessão, habilitando automação personalizada, controles de segurança e integrações. Os arquivos de configuração de gancho são carregados automaticamente a partir do .github/hooks/*.json em seu repositório.

Formato de configuração do gancho

Os arquivos de configuração do gancho usam o formato JSON com a versão 1. Cada entrada de gancho é um gancho de comando, um gancho HTTP ou (somente no sessionStart) um gancho de prompt.

Ganchos de comando

Os ganchos de comando executam scripts de shell e têm suporte em todos os tipos de gancho.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

Campo	Tipo	Obrigatório	Descrição
`bash`	cadeia	Um dos `bash`/`powershell`	Comando shell para Unix.
`cwd`	cadeia	No	Diretório de trabalho para o comando (relativo à raiz do repositório ou absoluto).
`env`	objeto	No	Variáveis de ambiente a serem definidas (dá suporte à expansão variável).
`powershell`	cadeia	Um dos `bash`/`powershell`	Comando shell para Windows.
`timeoutSec`	número	No	Tempo limite em segundos. Padrão: `30`.
`type`	`"command"`	Sim	Deve ser `"command"`.

Ganchos de prompt

Prompt hooks enviam automaticamente o texto como se o usuário tivesse digitado. Eles têm suporte apenas em sessionStart e são executados antes que qualquer prompt inicial seja passado via --prompt. O texto pode ser uma solicitação em linguagem natural ou um comando de barra.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Campo	Tipo	Obrigatório	Descrição
`prompt`	cadeia	Sim	O texto a ser enviado pode ser uma mensagem de linguagem natural ou um comando de barra.
`type`	`"prompt"`	Sim	Deve ser `"prompt"`.

Ganchos HTTP

HTTP faz POST do conteúdo do evento como JSON em uma URL configurada e analisa o corpo da resposta JSON. Eles têm suporte em todos os tipos de evento de hook e são úteis para integrações no estilo webhook, como serviços de políticas remotas, endpoints de auditoria e fluxos de trabalho de aprovação, sem necessidade de um executável local.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "http",
        "url": "https://policy.example.com/preToolUse"
      }
    ]
  }
}

Campo	Tipo	Obrigatório	Descrição
`type`	`"http"`	Sim	Deve ser `"http"`.
`url`	cadeia	Sim	URL do ponto de extremidade. Deve usar `http:` ou `https:`. Nenhuma substituição env var na url em si.
`headers`	objeto	No	Cabeçalhos de solicitação. Os valores oferecem suporte à substituição por `$VAR` / `${VAR}`, limitada a nomes listados em `allowedEnvVars`.
`allowedEnvVars`	cadeia de caracteres[]	No	Lista de permissões para modelagem de valor de cabeçalho. A configuração para uma matriz não vazia requer HTTPS.
`timeoutSec`	número	No	Tempo limite para cada solicitação em segundos. Padrão: `30`.

          `timeout` é aceito como um alias; `timeoutSec` tem precedência. |

O corpo da resposta usa o mesmo esquema JSON que o stdout do gancho de comando para cada evento. Responda 204 No Content ou qualquer 2xx com corpo vazio quando nenhuma ação for necessária.

Aviso

Os ganchos HTTP não têm semântica de código de saída. Uma resposta não 2xx é uma falha de gancho, não uma decisão de negação. Para negar uma chamada de ferramenta de um gancho HTTP preToolUse , retorne 200 OK com {"permissionDecision":"deny","permissionDecisionReason":"..."}. Para negar a partir de um gancho HTTP permissionRequest, retorne 200 OK com {"behavior":"deny","message":"..."}.

Uma entrada de gancho com os campos bash e url é processada conforme a primeira variante que corresponder; o campo não utilizado é descartado sem aviso. Sempre defina type explicitamente e remova campos de gancho de comando ao usar ganchos HTTP.

Segurança do hook HTTP

O HTTPS é necessário nos seguintes casos:

Quando allowedEnvVars é uma matriz não vazia, para impedir que as credenciais sejam enviadas por texto sem formatação.
Por padrão, para preToolUse e permissionRequest ganchos, para proteger o canal de decisão de permissão.

A CLI impõe uma política SSRF de negação padrão: qualquer URL cujo nome de host é resolvido para um endereço de loopback, privado, link-local ou endereço de metadados de nuvem é rejeitado antes da conexão. O DNS é resolvido antecipadamente e todos os endereços retornados são validados (defesa de revinculação de DNS).

As variáveis de ambiente a seguir relaxam esses padrões somente para desenvolvimento e teste.

Variable	Efeito	Utilização pretendida
`COPILOT_HOOK_ALLOW_LOCALHOST=1`

          `http://` Permite literal`localhost`, `127.*`ou `[::1]` (regras HTTPS) e qualquer nome de host que resolva inteiramente como loopback (regra SSRF). | Somente desenvolvimento local |

| COPILOT_HOOK_ALLOW_HTTP_AUTH_HOOKS=1 | Permite http:// para ganchos preToolUse e permissionRequest em qualquer lugar. | Somente teste |

Ambas as variáveis devem ser definidas antes de iniciar copilot. Não os defina globalmente, em CI ou em ambientes compartilhados.

Semântica de falha de gancho HTTP

Condição	Comportamento
2xx + corpo JSON válido	Corpo analisado de acordo com o esquema de saída do evento.
2xx + corpo vazio ou não JSON	Nenhuma ação.
Resposta com código diferente de 2xx	O gancho falha. Erro registrado. O agente continua.
Redirecionamento 3xx	O gancho falha ("redirecionamento retornado"). O agente continua.
Intervalo	O gancho falha. Erro foi registrado. O agente continua.
Erro de rede, DNS ou TLS	O gancho falha. Erro registrado. O agente continua.
Erro de validação de configuração no carregamento	Arquivo de configuração inteiro rejeitado; nenhum gancho foi registrado a partir desse arquivo.

Para preToolUse e permissionRequest, uma falha de hook HTTP é tratada como fail-open: o agente recai no fluxo de permissão padrão.

Eventos de gancho

Acontecimento	Acionado quando	A saída foi processada
`sessionStart`	Uma sessão nova ou retomada começa.	Opcional – pode retornar `additionalContext` para injetar o contexto de toda a sessão a cada vez.
`sessionEnd`	A sessão é encerrada.	No
`userPromptSubmitted`	O usuário envia um prompt.	No
`preToolUse`	Antes de executar cada ferramenta.	Sim — pode permitir, negar ou modificar.
`postToolUse`	Depois que cada ferramenta for executada com sucesso.	Sim, pode substituir o resultado bem-sucedido (somente ganchos programáticos do SDK).
`postToolUseFailure`	Depois que uma ferramenta termina com falha.	Sim – pode fornecer diretrizes de recuperação por meio de `additionalContext` (código de saída `2` para hooks de comando).
`agentStop`	O agente principal conclui um turno.	Sim – pode bloquear e forçar a continuação.
`subagentStop`	Um subagente completa.	Sim – pode bloquear e forçar a continuação.
`subagentStart`	Um subagente é gerado (antes de ser executado). Retorna `additionalContext` prefixado ao prompt do subagente.

          `matcher` Dá suporte para filtrar pelo nome do agente. | Não — não é possível bloquear a criação. |

| preCompact | A compactação de contexto está prestes a começar (manual ou automática). matcher Dá suporte para filtrar por gatilho ("manual" ou "auto"). | Não — somente notificação. | | permissionRequest | Antes de mostrar uma caixa de diálogo de permissão para o usuário, após verificações baseadas em regra, não encontre nenhuma regra de permissão ou negação correspondente. matcher Dá suporte ao regex em toolName. | Sim – pode permitir ou negar programaticamente. | | errorOccurred | Ocorre um erro durante a execução. | No | | notification | É acionado de forma assíncrona quando a CLI emite uma notificação do sistema (conclusão do shell, conclusão do agente ou estado ocioso, prompts de permissão, caixas de diálogo para elicitação). Disparar e esquecer: nunca bloqueia a sessão. matcher Dá suporte ao regex em notification_type. | Opcional – pode injetar additionalContext na sessão. |

Cargas de entrada de evento do gancho

Cada evento de gancho fornece uma carga JSON para o manipulador de gancho. Há suporte para dois formatos de conteúdo, selecionados pelo nome do evento usado na configuração do gancho:

formato camelCase — Configure o nome do evento em camelCase (por exemplo, sessionStart). Os campos usam camelCase.

          VS Code Formato compatível** — configure o nome do evento em PascalCase (por exemplo, `SessionStart`). Os campos usam snake_case para corresponder ao formato de extensão VS CodeCopilot.

`sessionStart` / `SessionStart`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

`sessionEnd` / `SessionEnd`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

`userPromptSubmitted` / `UserPromptSubmit`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

`preToolUse` / `PreToolUse`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

          **
          VS Code entrada compatível:**

Quando configurado com o nome do evento PreToolUse PascalCase, o conteúdo usa nomes de campo em snake_case para corresponder ao formato de extensão VS CodeCopilot.

{
    hook_event_name: "PreToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)
}

`postToolUse` / `PostToolUse`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "PostToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    tool_result: {
        result_type: "success" | "failure" | "denied" | "error";
        text_result_for_llm: string;
    }
}

`postToolUseFailure` / `PostToolUseFailure`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "PostToolUseFailure";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    error: string;
}

`agentStop` / `Stop`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

`subagentStart`

          **Entrada:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

`subagentStop` / `SubagentStop`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "SubagentStop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    agent_name: string;
    agent_display_name?: string;
    stop_reason: "end_turn";
}

`errorOccurred` / `ErrorOccurred`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "ErrorOccurred";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    error_context: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

`preCompact` / `PreCompact`

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "PreCompact";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    trigger: "manual" | "auto";
    custom_instructions: string;
}

          `preToolUse` controle de decisão

O preToolUse gancho pode controlar a execução da ferramenta escrevendo um objeto JSON para stdout (ganchos de comando) ou retornando-o no corpo da resposta (ganchos HTTP).

Campo	Valores	Descrição
`permissionDecision`

          `"allow"`
          `"deny"`
          `"ask"`
         | Se a ferramenta é executada. A saída vazia usa o comportamento padrão. |

| permissionDecisionReason | cadeia | Motivo mostrado ao agente. Recomendado quando a decisão é "deny" ou "ask". | | modifiedArgs | desconhecido | Substitui toda a entrada da ferramenta antes da execução. Somente válido quando permissionDecision não for "deny" ou "ask". | | additionalContext | cadeia | Enfileirado como contexto para a próxima interação do modelo. Somente válido quando permissionDecision não for "deny" nem "ask". |

Observação

O pseudônimo VS Code (PreToolUse) também aceita hookSpecificOutput.{permissionDecision, permissionDecisionReason, updatedInput, additionalContext} aninhados. updatedInput é normalizado para modifiedArgs. Os campos de nível superior são aceitos como um fallback.

          `agentStop`
           / 
          `subagentStop` controle de decisão

Campo	Valores	Descrição
`decision`

          `"block"`, `"allow"` | 
          `"block"` obriga outro agente a fazer um turno usando `reason` como prompt. |

| reason | cadeia | Solicite a próxima rodada quando decision for "block". |

          `permissionRequest` controle de decisão

O permissionRequest gancho é acionado quando uma caixa de diálogo de permissão no nível da ferramenta está prestes a ser mostrada. Ele é acionado após verificações de permissão baseadas em regras não encontrarem nenhuma regra correspondente de "permitir" ou "negar". Use-o para aprovar ou negar chamadas de ferramentas de forma programática, especialmente útil no modo de pipe (-p) e em ambientes de CI onde nenhum prompt interativo está disponível.

          **Matcher:** Regex opcional testado contra `toolName`. Quando definido, o gancho é acionado apenas para nomes de ferramentas correspondentes.

Para controlar a decisão de permissão, exibir JSON no stdout:

Campo	Valores	Descrição
`behavior`

          `"allow"`, `"deny"` | Aprovar ou negar a chamada da ferramenta. |

Retornar saída vazia ou {} para cair no comportamento padrão (mostrar a caixa de diálogo do usuário ou negar no modo pipe). Para ganchos de comando, o código 2 de saída é tratado como uma negação; stdout JSON (se houver) é mesclado com {"behavior":"deny"}, e stderr é ignorado.

Gancho `notification`

O notification gancho é acionado de forma assíncrona quando a CLI emite uma notificação do sistema. Esses ganchos são fire-and-forget: eles nunca bloqueiam a sessão, e quaisquer erros são registrados no log e ignorados.

          **Entrada:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    hook_event_name: "Notification";
    message: string;           // Human-readable notification text
    title?: string;            // Short title (e.g., "Permission needed", "Shell completed")
    notification_type: string; // One of the types listed below
}

          **Tipos de notificação:**

Tipo	Quando é acionado
`shell_completed`	Um comando de shell em segundo plano (assíncrono) termina
`shell_detached_completed`	Uma sessão de shell desconectada é concluída
`agent_completed`	Um subagente em execução em segundo plano é finalizado (completo ou com falha)
`agent_idle`	Um agente em segundo plano conclui um ciclo e entra em modo inativo (aguardando `write_agent`)
`permission_prompt`	O agente solicita permissão para executar uma ferramenta
`elicitation_dialog`	O agente solicita informações adicionais do usuário

          **Saída:**

{
    additionalContext?: string; // Injected into the session as a user message
}

Se additionalContext for retornado, o texto será injetado na sessão como uma mensagem de usuário prefixada. Isso pode disparar um processamento adicional do agente se a sessão estiver ociosa. Retornar {} ou esvaziar a saída para não executar nenhuma ação.

          **Matcher:** Regex opcional em `notification_type`. O padrão é ancorado como `^(?:pattern)$`. Omita `matcher` para receber todos os tipos de notificação.

Nomes de ferramentas para correspondência de ganchos

Nome da ferramenta	Descrição
`bash`	Execute comandos de shell (Unix).
`powershell`	Execute comandos de shell (Windows).
`view`	Ler o conteúdo do arquivo.
`edit`	Modificar o conteúdo do arquivo.
`create`	Crie novos arquivos.
`glob`	Localizar arquivos por padrão.
`grep`	Pesquisar conteúdo do arquivo.
`web_fetch`	Recuperar páginas da Web.
`task`	Executar tarefas de subagente.

Se vários ganchos do mesmo tipo forem configurados, eles serão executados em ordem. Para preToolUse, se algum gancho retornar "deny", a ferramenta será bloqueada. Códigos de saída se aplicam somente a ganchos de comando— para ganchos HTTP, consulte a semântica de falha do gancho HTTP. Para postToolUseFailure ganchos de comando, sair com código 2 faz com que stderr seja retornado como diretriz de recuperação para o assistente. Para permissionRequest ganchos de comando, o código de saída 2 é tratado como uma negação; stdout JSON (se houver) é mesclado com {"behavior":"deny"}, e stderr é ignorado. As falhas de gancho (códigos de saída ou tempos limite diferentes de zero) são registradas e ignoradas, elas nunca bloqueiam a execução do agente.

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.

          `copilot mcp` Subcomando

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

Subcommand	Descrição
`list [--json]`	Listar todos os servidores MCP configurados agrupados por origem.
`get <name> [--json]`	Mostrar configuração e ferramentas para um servidor específico.
`add <name>`	Adicione um servidor à configuração do usuário. Grava em `~/.copilot/mcp-config.json`.
`remove <name>`	Remova um servidor no nível do usuário. Os servidores de espaço de trabalho devem ser editados diretamente em seus arquivos de configuração.

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

Opção	Descrição
`-- <command> [args...]`	Comandos e argumentos para servidores locais (stdio).
`--url <url>`	URL para servidores remotos.
`--type <type>`	Tipo de transporte: `local`, , `stdio`, `http`ou `sse`.
`--env KEY=VALUE`	Variável de ambiente (repetível).
`--header KEY=VALUE`	Cabeçalho HTTP para servidores remotos (repetível).
`--tools <tools>`	Filtro de ferramenta: `"*"` para todos, uma lista separada por vírgulas ou `""` para nenhum.
`--timeout <ms>`	Tempo limite em milissegundos.
`--json`	A saída adicionou a configuração como JSON.
`--show-secrets`	Mostrar valores completos de variável de ambiente e cabeçalho.
`--config-dir <path>`	Caminho para o diretório de configuração.

Cuidado

          `--show-secrets` é capaz de imprimir valores confidenciais de variáveis de ambiente e de cabeçalho no seu terminal ou nos arquivos de log. Use essa opção apenas em ambientes confiáveis e evite copiar, colar ou capturar a saída em logs ou histórico compartilhados.

Tipos de transporte

Tipo	Descrição	Campos obrigatórios
`local` / `stdio`	Processo local comunicando-se por meio de stdin/stdout.

          `command`, `args` |

| http | Servidor remoto utilizando transporte HTTP transmissível. | url | | sse | Servidor remoto usando o transporte de eventos Server-Sent. | url |

Campos de configuração do servidor local

Campo	Obrigatório	Descrição
`command`	Sim	Comando para iniciar o servidor.
`args`	Sim	Argumentos de comando (matriz).
`tools`	Sim	Ferramentas para habilitar: `["*"]` para todos ou uma lista de nomes de ferramentas específicos.
`env`	No	Variáveis de ambiente. Dá suporte a `$VAR`, `${VAR}` e `${VAR:-default}` expansão.
`cwd`	No	Diretório de trabalho para o servidor.
`timeout`	No	Tempo limite de chamada de ferramenta em milissegundos.
`type`	No

          `"local"` ou `"stdio"`. Padrão: `"local"`. |

Campos de configuração de servidor remoto

Campo	Obrigatório	Descrição
`type`	Sim

          `"http"` ou `"sse"`. |

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.

Mapeamento de filtro

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

Modo	Descrição
`none`	Sem filtragem.
`markdown`	Formatar saída como Markdown.
`hidden_characters`	Remova caracteres ocultos ou de controle. Padrão.

Servidores MCP internos

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

Servidor	Descrição
`github-mcp-server`

          GitHub Integração de API: problemas, solicitações de pull, confirmações, pesquisa de código e GitHub Actions. |

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

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.

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.

Fonte	Nível de confiança	Revisão necessária
Interna	Alto	No
Repositório (`.github/mcp.json`)	Medium	Recomendado
Espaço de Trabalho (`.mcp.json`)	Medium	Recomendado
Configuração do usuário (`~/.copilot/mcp-config.json`)	User-defined	Responsabilidade do usuário
Servidores remotos	Baixo	Sempre

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.

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 GitHub Enterprise política do Registro é detectada (ou o MCP_ENTERPRISE_ALLOWLIST sinalizador de recurso experimental está habilitado), a CLI:

Calcula uma impressão digital para cada servidor não padrão configurado com base em seu comando, argumentos e URL remota.
Envia as impressões digitais para o endpoint de avaliação da lista de permissão da empresa.
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.jsonCLI do GitHub Copilot. A migração mapeia novamente a servers chave para mcpServers.

          **Conchas POSIX (bash, zsh, peixe 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.

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

Campo	Tipo	Obrigatório	Descrição
`name`	cadeia	Sim	Identificador exclusivo para a habilidade. Somente letras, números e hifens. Máximo de 64 caracteres.
`description`	cadeia	Sim	O que a habilidade faz e quando usá-la. Máximo de 1024 caracteres.
`allowed-tools`	cadeia de caracteres ou string[]	No	Lista separada por vírgulas ou matriz yaml de ferramentas que são automaticamente permitidas quando a habilidade está ativa. Use `"*"` para todas as ferramentas.
`user-invocable`	boolean	No	Se os usuários podem invocar a habilidade com `/SKILL-NAME`. Padrão: `true`.
`disable-model-invocation`	boolean	No	Impedir que o agente invoque automaticamente essa habilidade. Padrão: `false`.

Localizações de habilidades

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

Localidade	Scope	Descrição
`.github/skills/`	Projeto	Habilidades específicas de projeto.
`.agents/skills/`	Projeto	Local alternativo do projeto.
`.claude/skills/`	Projeto	Local compatível com Claude.
Pai `.github/skills/`	Herdado	Suporte para diretório raiz do Monorepo.
`~/.copilot/skills/`	Pessoal	Habilidades pessoais para todos os projetos.
`~/.agents/skills/`	Pessoal	Habilidades de agente compartilhadas em todos os projetos.
`~/.claude/skills/`	Pessoal	Localização pessoal compatível com o sistema Claude.
Diretórios de plug-in	Plug-in	Habilidades de complementos instalados.
`COPILOT_SKILLS_DIRS`	Personalizado	Diretórios adicionais (separados por vírgula).
(agrupado com a CLI)	Interna	Habilidades enviadas com a CLI. Prioridade mais baixa , substituível por qualquer outra fonte.

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 suporte description, allowed-toolse 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

Agente	Modelo padrão	Descrição
`code-review`	claude-sonnet-4.5	Revisão de código com alta relação sinal/ruído. Analisa as diferenças em busca de bugs, problemas de segurança e erros lógicos.
`configure-copilot`	varies	Subagente interno para o gerenciamento da configuração do CLI do Copilot por meio da linguagem natural — adicionando servidores MCP, instalando agentes e gerenciando competências. Disponível apenas no modo experimental.
`explore`	claude-haiku-4.5	Exploração rápida da base de código. Pesquisa arquivos, lê código e responde a perguntas. Retorna respostas focadas em menos de 300 palavras. Seguro para ser executado em paralelo.
`general-purpose`	claude-sonnet-4.5	Agente de funcionalidade completa para tarefas complexas de várias etapas. É executado em uma janela de contexto separada.
`research`	claude-sonnet-4.6	Agente de pesquisa profunda. Gera um relatório com base em informações em sua base de código, em repositórios relevantes e na Web.
`rubber-duck`	modelo complementar	Use um modelo complementar para fornecer uma crítica construtiva de propostas, designs, implementações ou testes. Identifica pontos fracos e sugere melhorias. Ao usar Claude, ele usa um modelo gpt; ao usar GPT, ele usa Claude Opus 4.7. Nunca faz alterações diretas de código. Disponível apenas no modo experimental.
`task`	claude-haiku-4.5	Execução de comandos (testes, compilações, lints). Retorna um breve resumo em caso de sucesso, saída completa em caso de falha.

Campos de frontmatter personalizados do agente

Campo	Tipo	Obrigatório	Descrição
`description`	cadeia	Sim	Descrição mostrada na lista de agentes e na ferramenta `task`.
`infer`	boolean	No	Permitir a delegação automática pelo agente principal. Padrão: `true`.
`mcp-servers`	objeto	No	Servidores MCP para conectar. Usa o mesmo esquema que `~/.copilot/mcp-config.json`.
`model`	cadeia	No	Modelo de IA para este agente. Quando não definido, herda o modelo do agente externo. Quando o modelo de sessão é definido `Auto` como (selecionado pelo servidor), os subagentes sempre herdam o modelo de sessão resolvido, independentemente desse campo.
`name`	cadeia	No	Nome de exibição. O padrão é o nome do arquivo.
`tools`	cadeia de caracteres[]	No	Ferramentas disponíveis para o agente. Padrão: `["*"]` (todas as ferramentas).

Locais do agente personalizado

Scope	Localidade
Projeto

          `.github/agents/` ou `.claude/agents/` |

Agentes em nível de projeto têm precedência sobre agentes em nível de usuário. Os agentes de plug-in têm a prioridade mais baixa.

Limites de subagente

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

Limit	Default	Variável de ambiente
Profundidade máxima	`6`	`COPILOT_SUBAGENT_MAX_DEPTH`
Máximo simultâneo	`32`	`COPILOT_SUBAGENT_MAX_CONCURRENT`

          **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. Os valores são limitados entre `1` e `256`.

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.

Chave	Efeito
`y`	Permitir essa solicitação específica uma vez.
`n`	Negar essa solicitação específica uma vez.
`!`	Permitir todas as solicitações semelhantes para o restante da sessão.
`#`	Negar todas as solicitações semelhantes para o restante da sessão.
`?`	Mostrar informações detalhadas sobre a solicitação.

As aprovações de sessão são redefinidas quando você executa /clear ou inicia uma nova sessão.

Monitoramento do OpenTelemetry

          CLI do Copilot pode exportar rastreamentos e métricas por meio do [OpenTelemetry](https://opentelemetry.io/) (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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/).

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

Variáveis de ambiente OTel

Variable	Default	Descrição
`COPILOT_OTEL_ENABLED`	`false`	Habilite explicitamente o OTel. Não é necessário se `OTEL_EXPORTER_OTLP_ENDPOINT` estiver definido.
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	URL do ponto de extremidade OTLP. Definir isso habilita automaticamente o OTel.
`COPILOT_OTEL_EXPORTER_TYPE`	`otlp-http`	Tipo de exportador: `otlp-http` ou `file`. Seleciona automaticamente `file` quando `COPILOT_OTEL_FILE_EXPORTER_PATH` está definido.
`OTEL_SERVICE_NAME`	`github-copilot`	Nome do serviço em atributos de recurso.
`OTEL_RESOURCE_ATTRIBUTES`	—	Atributos de recursos extras como pares separados por vírgula `key=value` . Use a codificação por porcentagem para caracteres especiais.
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	`false`	Capture o conteúdo completo do prompt e da resposta. Consulte a captura de conteúdo.
`OTEL_LOG_LEVEL`	—	Nível do log de diagnóstico OTel: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`, `ALL`.
`COPILOT_OTEL_FILE_EXPORTER_PATH`	—	Escreva todos os sinais neste arquivo como linhas JSON. Definir isso habilita automaticamente o OTel.
`COPILOT_OTEL_SOURCE_NAME`	`github.copilot`	Nome do escopo de instrumentação para rastreador e medidor.
`OTEL_EXPORTER_OTLP_HEADERS`	—	Cabeçalhos de autenticação para o exportador OTLP (por exemplo, `Authorization=Bearer token`).

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.

As sessões de nível superior usam o tipo de abrangência CLIENT (invocação de serviço remoto) com server.address e server.port.
Invocação de subagente (por exemplo, explorar, tarefa) usa o tipo de span INTERNAL (em processo) sem atributos de servidor.

Attribute	Descrição	Tipo de intervalo
`gen_ai.operation.name`	`invoke_agent`	Ambas
`gen_ai.provider.name`	Provedor (por exemplo, `github`, `anthropic`)	Ambas
`gen_ai.agent.id`	Identificador de sessão	Ambas
`gen_ai.agent.name`	Nome do agente (quando disponível)	Ambas
`gen_ai.agent.description`	Descrição do agente (quando disponível)	Ambas
`gen_ai.agent.version`	Versão de execução	Ambas
`gen_ai.conversation.id`	Identificador de sessão	Ambas
`gen_ai.request.model`	Modelo solicitado	Ambas
`gen_ai.response.finish_reasons`

          `["stop"]` ou `["error"]` | Ambas |

          `chat` atributos de 'span'

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

Attribute	Descrição
`gen_ai.operation.name`	`chat`
`gen_ai.provider.name`	Nome do provedor
`gen_ai.request.model`	Modelo solicitado
`gen_ai.conversation.id`	Identificador de sessão
`gen_ai.response.id`	ID de resposta
`gen_ai.response.model`	Modelo resolvido
`gen_ai.response.finish_reasons`	Razões de parada
`gen_ai.usage.input_tokens`	Tokens de entrada desta vez
`gen_ai.usage.output_tokens`	Tokens de saída neste turno
`gen_ai.usage.cache_read.input_tokens`	Leitura de tokens armazenados em cache
`gen_ai.usage.cache_creation.input_tokens`	Tokens em cache criados
`github.copilot.cost`	Custo de turno
`github.copilot.aiu`	As unidades de IA foram consumidas neste turno
`github.copilot.server_duration`	Duração no lado do servidor
`github.copilot.initiator`	Iniciador de solicitação
`github.copilot.turn_id`	Identificador de turno
`github.copilot.interaction_id`	Identificador de interação
`github.copilot.time_to_first_chunk`	Tempo para a primeira parte de transmissão, em segundos (somente transmissão)
`server.address`	Nome do host do servidor
`server.port`	Porta do servidor
`error.type`	Nome da classe de erro (em caso de erro)
`gen_ai.input.messages`	Mensagens completas de prompt como JSON (captura de conteúdo apenas)
`gen_ai.output.messages`	Mensagens de resposta completas como JSON (somente captura de conteúdo)
`gen_ai.system_instructions`	Conteúdo da solicitação do sistema como JSON (captura de conteúdo somente)

          `execute_tool` atributos de 'span'

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

Attribute	Descrição
`gen_ai.operation.name`	`execute_tool`
`gen_ai.provider.name`	Nome do provedor (quando disponível)
`gen_ai.tool.name`	Nome da ferramenta (por exemplo, `readFile`)
`gen_ai.tool.type`	`function`
`gen_ai.tool.call.id`	Identificador de chamada de ferramenta
`gen_ai.tool.description`	Descrição da ferramenta
`error.type`	Nome da classe de erro (em caso de erro)
`gen_ai.tool.call.arguments`	Argumentos de entrada da ferramenta como JSON (apenas captura de conteúdo)
`gen_ai.tool.call.result`	Saída da ferramenta como JSON (somente captura de conteúdo)

Métricas

Métricas de convenção do GenAI

Métrica	Tipo	Unidade	Descrição
`gen_ai.client.operation.duration`	Histograma	s	Duração da chamada à API LLM e da invocação do agente
`gen_ai.client.token.usage`	Histograma	tokens	Contagens de token por tipo (`input`/`output`)
`gen_ai.client.operation.time_to_first_chunk`	Histograma	s	Hora de receber a primeira parte de streaming
`gen_ai.client.operation.time_per_output_chunk`	Histograma	s	Latência entre partes após a primeira parte

Métricas específicas do fornecedor

Métrica	Tipo	Unidade	Descrição
`github.copilot.tool.call.count`	Contador	chamadas	Invocações de ferramenta por `gen_ai.tool.name` e `success`
`github.copilot.tool.call.duration`	Histograma	s	Latência de execução da ferramenta por `gen_ai.tool.name`
`github.copilot.agent.turn.count`	Histograma	turnos	Ciclos de ida e volta de LLM por chamada de agente

Eventos com intervalo

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

Acontecimento	Descrição	Atributos de chave
`github.copilot.hook.start`	Um gancho começou a ser executado

          `github.copilot.hook.type`, `github.copilot.hook.invocation_id` |

| github.copilot.hook.end | O hook foi concluído com êxito | github.copilot.hook.type, github.copilot.hook.invocation_id | | github.copilot.hook.error | Falha em um gancho | github.copilot.hook.type github.copilot.hook.invocation_id github.copilot.hook.error_message | | github.copilot.session.truncation | O histórico de conversas foi truncado | github.copilot.token_limit, github.copilot.pre_tokens, github.copilot.post_tokens, github.copilot.pre_messages, github.copilot.post_messages, github.copilot.tokens_removed, , github.copilot.messages_removed, , github.copilot.performed_by | | github.copilot.session.compaction_start | Compactação de histórico iniciada | Nenhum | | github.copilot.session.compaction_complete | Compactação de histórico concluída | github.copilot.success, github.copilot.pre_tokens, github.copilot.post_tokens, github.copilot.tokens_removed, , github.copilot.messages_removed``github.copilot.message(somente captura de conteúdo) | | github.copilot.skill.invoked | Uma habilidade foi invocada | github.copilot.skill.name, github.copilot.skill.path, , github.copilot.skill.plugin_name``github.copilot.skill.plugin_version | | github.copilot.session.shutdown | A sessão está sendo fechada | github.copilot.shutdown_type, github.copilot.total_premium_requests, github.copilot.lines_added, , github.copilot.lines_removed``github.copilot.files_modified_count | | github.copilot.session.abort | O usuário cancelou a operação atual | github.copilot.abort_reason | | exception | Erro de sessão | github.copilot.error_type github.copilot.error_status_code github.copilot.error_provider_call_id |

Atributos de recursos

Todos os sinais carregam esses atributos de recurso.

Attribute	Valor
`service.name`

          `github-copilot` (configurável via `OTEL_SERVICE_NAME`) |

| service.version | Versão de execução |

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.

Aviso

A captura de conteúdo pode incluir informações confidenciais, como código, conteúdo de arquivo e prompts do usuário. Habilite isso apenas em ambientes confiáveis.

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

Attribute	Conteúdo
`gen_ai.input.messages`	Mensagens de prompt completo (JSON)
`gen_ai.output.messages`	Mensagens de resposta completas (JSON)
`gen_ai.system_instructions`	Conteúdo do prompt do sistema (JSON)
`gen_ai.tool.definitions`	Esquemas de ferramentas (JSON)
`gen_ai.tool.call.arguments`	Argumentos de entrada da ferramenta
`gen_ai.tool.call.result`	Saída da ferramenta

Neste artigo