# referência de comando da CLI GitHub Copilot
Encontre comandos e atalhos de teclado para ajudá-lo a usar CLI do Copilot com eficiência.
## 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-login-options). |
| `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:**
```
```shell
# 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. |
## Atalhos de navegação na interface interativa
| 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)
| |
```
Opção+←/→ (Mac) | Mova o cursor uma palavra por vez. |
```
\| ↑/↓ | Navegue pelo histórico de comandos. |
## 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](/pt/copilot/concepts/agents/copilot-cli/about-custom-agents). |
| `/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 ` | 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. |
```
\| `/compact` | Resumir o histórico de conversas para reduzir o uso da janela de contexto. Consulte [Gerenciando o contexto em CLI do GitHub Copilot](/pt/copilot/concepts/agents/copilot-cli/context-management#compaction). |
\| `/context` | Mostrar o uso e a visualização do token da janela de contexto. Consulte [Gerenciando o contexto em CLI do GitHub Copilot](/pt/copilot/concepts/agents/copilot-cli/context-management#checking-your-context-usage). |
\| `/copy` | Copie a última resposta para a área de transferência. |
\| `/cwd`, `/cd [PATH]` | Altere o diretório de trabalho ou exiba o diretório atual. |
\| `/delegate [PROMPT]` | Delegar alterações em um repositório remoto com uma solicitação de pull gerada por IA. Consulte [Delegando tarefas para CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca). |
\| `/diff` | Examine as alterações feitas no diretório atual. |
\| `/env` | Mostrar detalhes do ambiente carregado (instruções, servidores MCP, habilidades, agentes, plug-ins, LSPs, extensões). |
\| `/exit`, `/quit` | Saia da CLI. |
\| `/experimental [on\|off\|show]` | Alterne, defina ou mostre recursos experimentais. |
\| `/feedback`, `/bug` | Forneça comentários sobre a CLI. |
\| `/fleet [PROMPT]` | Habilite a execução de subagentes paralelos de partes de uma tarefa. Consulte [Executando tarefas em paralelo com o \`/fleet\` comando](/pt/copilot/concepts/agents/copilot-cli/fleet). |
\| `/help` | Mostrar a ajuda para comandos interativos. |
\| `/ide` | Conecte-se a um workspace do IDE. Consulte [Conectando CLI do GitHub Copilot a VS Code](/pt/copilot/how-tos/copilot-cli/connecting-vs-code#managing-the-connection-with-the-ide-slash-command). |
\| `/init` | Inicialize instruções personalizadas e recursos de agentes do Copilot para este repositório. Consulte [Inicialização do Projeto para Copilot](#project-initialization-for-copilot). |
\| `/instructions` | Exibir e alternar arquivos de instrução personalizados. |
\| `/keep-alive [on\|busy\|NUMBERm\|NUMBERh]` | Impedir que o computador durma: enquanto uma sessão da CLI estiver ativa, enquanto o agente estiver ocupado ou por um período de tempo definido. Disponível apenas no modo experimental. |
\| `/list-dirs` | Exiba todos os diretórios para os quais o acesso ao arquivo foi permitido. |
\| `/login` | Faça login em Copilot. |
\| `/logout` | Faça logoff do Copilot. |
\| `/lsp [show\|test\|reload\|help] [SERVER-NAME]` | Gerencie a configuração do servidor de idiomas. |
\| `/mcp [show\|add\|edit\|delete\|disable\|enable\|auth\|reload] [SERVER-NAME]` | Gerenciar a configuração do servidor MCP. Consulte [Adicionando servidores MCP para CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). |
\| `/model`, `/models [MODEL]` | Selecione o modelo de IA que você deseja usar. |
\| `/plan [PROMPT]` | Crie um plano de implementação antes da codificação. |
\| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Gerenciar plug-ins e mercados de plug-ins. Consulte [Sobre plug-ins para CLI do GitHub Copilot](/pt/copilot/concepts/agents/copilot-cli/about-cli-plugins). |
\| `/pr [view\|create\|fix\|auto]` | Gerenciar solicitações de pull para o branch atual. Consulte [Gerenciando solicitações de pull com o comando /pr](/pt/copilot/how-tos/copilot-cli/manage-pull-requests). |
\| `/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](/pt/copilot/how-tos/copilot-cli/steer-remotely). |
\| `/rename [NAME]` | Renomeie a sessão atual (gera automaticamente um nome caso a opção não seja especificada; alias para `/session rename`). |
\| `/research TOPIC` | Execute uma investigação aprofundada usando fontes de busca e web do GitHub. Consulte [Pesquisando com CLI do GitHub Copilot](/pt/copilot/concepts/agents/copilot-cli/research). |
\| `/reset-allowed-tools` | Redefina a lista de ferramentas permitidas. |
\| `/restart` | Reinicie a CLI, preservando a sessão atual. |
\| `/resume [SESSION-ID]`, `/continue [SESSION-ID]` | Alterne para uma sessão diferente escolhendo em uma lista (opcionalmente, especifique uma ID de sessão). |
\| `/review [PROMPT]` | Execute o agente de revisão de código para analisar as alterações. Consulte [Solicitando uma revisão de código com CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review). |
\| `/session [checkpoints [n]\|files\|plan\|rename NAME]`, `/sessions [checkpoints [n]\|files\|plan\|rename NAME]` | Mostrar informações de sessão e um resumo do workspace. Use os subcomandos para obter detalhes. |
\| `/share [file\|html\|gist] [session\|research] [PATH]`, `/export [file\|html\|gist] [session\|research] [PATH]` | Compartilhe a sessão em um arquivo Markdown, arquivo HTML interativo ou GitHub gist. |
\| `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Gerenciar habilidades para funcionalidades aprimoradas. Consulte [Adicionando habilidades de agente para CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli/customize-copilot/create-skills). |
\| `/statusline`, `/footer` | Configure quais itens aparecem na linha de status. |
\| `/tasks` | Exibir e gerenciar tarefas em segundo plano (subagentes e sessões de shell). |
\| `/terminal-setup` | Configure o terminal para suporte de entrada multilinha (Shift+Enter e Ctrl+Enter). |
\| `/theme [default\|dim\|high-contrast\|colorblind]` | Exibir ou definir o modo de cor. |
\| `/undo`, `/rewind` | Refaça a última ação e reverta as alterações no arquivo. |
\| `/update`, `/upgrade` | Atualize a CLI para a versão mais recente. |
\| `/usage` | Exibir estatísticas e métricas de uso de sessão. |
\| `/user [show\|list\|switch]` | Gerencie o usuário atual GitHub . |
\| `/version` | Exibir informações de versão e verificar se há atualizações. |
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](/pt/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). |
| `--agent=AGENT` | Especifique um agente personalizado a ser usado. Consulte [Sobre agentes personalizados](/pt/copilot/concepts/agents/copilot-cli/about-custom-agents). |
| `--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](/pt/copilot/how-tos/copilot-cli/allowing-tools#allowing-or-denying-permission-for-specific-tools). |
| `--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](/pt/copilot/concepts/agents/copilot-cli/autopilot). |
| `--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](/pt/copilot/how-tos/copilot-cli/allowing-tools). |
| `--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. |
| `--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](/pt/copilot/concepts/agents/copilot-cli/autopilot). |
| `--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. |
| `--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](/pt/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically). |
| `--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](/pt/copilot/how-tos/copilot-cli/steer-remotely). |
| `--resume=SESSION-ID` | Retome uma sessão interativa anterior escolhendo em uma lista (opcionalmente, especifique uma ID de sessão ou um prefixo exclusivo de mais de 7 caracteres hexadecimais). |
| `-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-.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`.
> \[!NOTE]
> 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 |
| `read_bash` / `read_powershell` | Ler a saída de uma sessão de shell |
| `write_bash` / `write_powershell` | Enviar entrada para uma sessão de shell |
| `stop_bash` / `stop_powershell` | Encerrar uma sessão de shell |
| `list_bash` / `list_powershell` | Listar sessões ativas do shell |
### Ferramentas de operação de arquivo
| Nome da ferramenta | Descrição |
| ------------------ | --------------------------------------------------------------------- |
| `view` | Ler arquivos ou diretórios |
| `create` | Criar novos arquivos |
| `edit` | Editar arquivos por meio da substituição de cadeia de caracteres |
| `apply_patch` | Aplicar patches (usados por alguns modelos em vez de `edit`/`create`) |
### Ferramentas de delegação de agente e tarefas
| Nome da ferramenta | Descrição |
| ------------------ | --------------------------------------------- |
| `task` | Executar subagentes |
| `read_agent` | Verificar o status do agente em segundo plano |
| `list_agents` | Listar agentes disponíveis |
### Outras ferramentas
| Nome da ferramenta | Descrição |
| ------------------ | ------------------------------------------------ |
| `grep`(ou `rg`) | Pesquisar texto em arquivos |
| `glob` | Localizar padrões de correspondência de arquivos |
| `web_fetch` | Buscar e analisar o conteúdo da Web |
| `skill` | Invocar habilidades personalizadas |
| `ask_user` | Faça uma pergunta ao usuário |
## 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 |
| -------- | ---------------------------- | ------------------ |
| `shell` | Execução de comando do Shell | |
```
`shell(git push)`
`shell(git:*)`
`shell`
|
```
\| `write` | Criação ou modificação de arquivo |
`write`, `write(src/*.ts)` |
\| `read` | Leituras de arquivo ou diretório |
`read`, `read(.env)` |
\| SERVER-NAME | Invocação da ferramenta de servidor MCP |
`MyMCP(create_issue)`, `MyMCP` |
\| `url` | Acesso à URL por meio de web-fetch ou shell |
`url(github.com)`, `url(https://*.api.com)` |
\| `memory` | Armazenando fatos na memória do agente | `memory` |
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.
```shell
# 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 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `COPILOT_MODEL` | Defina o modelo de IA. |
| `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_CUSTOM_INSTRUCTIONS_DIRS` | Lista separada por vírgulas de diretórios adicionais para instruções personalizadas. |
| `COPILOT_SKILLS_DIRS` | Lista separada por vírgulas de diretórios adicionais para habilidades. |
| `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_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_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](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory) para ver os padrões da plataforma. |
| `COPILOT_SUBAGENT_MAX_DEPTH` | Profundidade máxima de aninhamento de subagente. Padrão: `6`. Intervalo: `1`–`256`. |
| `COPILOT_SUBAGENT_MAX_CONCURRENT` | Máximo de subagentes simultâneos em toda a árvore de sessão. Padrão: `32`. Intervalo: `1`–`256`. |
| `GH_TOKEN` | Token de autenticação. Tem precedência sobre `GITHUB_TOKEN`. |
| `GITHUB_TOKEN` | Token de autenticação. |
| `USE_BUILTIN_RIPGREP` | Defina como `false` para usar o ripgrep do sistema em vez da versão agrupada. |
| `PLAIN_DIFF` | Definir para `true` para desativar a renderização de diferenças avançadas. |
| `COLORFGBG` | Fallback para detecção de plano de fundo do terminal escuro/claro. |
## Configurações do arquivo de configuração
As configurações são aplicadas em cascata, do usuário para o repositório e depois para o local, com níveis mais específicos substituindo os mais gerais. Sinalizadores de linha de comando e variáveis de ambiente sempre têm a precedência mais alta.
| Scope | Localidade | Propósito |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Usuário | `~/.copilot/config.json` | Padrões globais para todos os repositórios. Use a variável de `COPILOT_HOME` ambiente para especificar um caminho alternativo. |
| Repositório | `.github/copilot/settings.json` | Configuração do repositório compartilhado (confirmada no repositório). |
| Local | `.github/copilot/settings.local.json` | Substituições pessoais (adicione-as a `.gitignore`). |
### Configurações do usuário (`~/.copilot/config.json`)
| Chave | Tipo | Default | Descrição |
| ------------- | ---------- | ------- | --------------------------------------------- |
| `allowedUrls` | `string[]` | `[]` | URLs ou domínios permitidos sem solicitação. |
| `autoUpdate` | `boolean` | `true` | Baixe automaticamente as atualizações da CLI. |
| `banner` | | | |
```
`"always"`
\|
`"once"`
\|
`"never"`
| `"once"` | Frequência de exibição de banner animado. |
```
\| `bashEnv` | `boolean` | `false` | Habilitar o suporte de `BASH_ENV` para shells bash. |
\| `beep` | `boolean` | `true` | Reproduza um bipe audível quando a atenção é necessária. |
\| `compactPaste` | `boolean` | `true` | Compactar conteúdos grandes em tokens compactos. |
\| `custom_agents.default_local_only` | `boolean` | `false` | Use apenas agentes personalizados locais. |
\| `denied_urls` | `string[]` | `[]` | URLs ou domínios bloqueados (tem precedência sobre `allowed_urls`). |
\| `experimental` | `boolean` | `false` | Habilitar recursos experimentais. |
\| `includeCoAuthoredBy` | `boolean` | `true` | Adicione um trailer `Co-authored-by` às confirmações do git feitas pelo agente. |
\| `companyAnnouncements` | `string[]` | `[]` | Mensagens personalizadas mostradas aleatoriamente na inicialização. |
\| `logLevel` |
`"none"`
|
`"error"`
|
`"warning"`
|
`"info"`
|
`"debug"`
|
`"all"`
|
`"default"`
\| `"default"` | Verbosidade de registro em log. |
\| `model` | `string` | varies | Modelo de IA a ser usado (consulte o `/model` comando). Defina para `"auto"` para que Copilot selecione automaticamente o melhor modelo disponível. |
\| `powershellFlags` | `string[]` | `["-NoProfile", "-NoLogo"]` | Sinalizadores passados para o PowerShell (`pwsh`) na inicialização. Windows apenas. |
\| `effortLevel` | `string` | `"medium"` | Nível de esforço de raciocínio para o pensamento estendido (por exemplo, `"low"`, `"medium"`, `"high"`, `"xhigh"`). Níveis mais altos usam mais computação. |
\| `mergeStrategy` |
`"rebase"`
|
`"merge"`
\| — | Estratégia de resolução de conflitos para `/pr fix conflicts`. Quando definido como `"rebase"`, os conflitos são resolvidos fazendo rebase para o branch base. Quando definido como `"merge"`, o ramo base é mesclado no ramo de funcionalidade. Se não estiver configurado, uma caixa de diálogo de seleção será mostrada. |
\| `renderMarkdown` | `boolean` | `true` | Renderizar Markdown na saída do terminal. |
\| `screenReader` | `boolean` | `false` | Habilitar otimizações de leitor de tela. |
\| `stream` | `boolean` | `true` | Habilitar respostas de streaming. |
\| `storeTokenPlaintext` | `boolean` | `false` | Armazene tokens de autenticação em texto sem formatação no arquivo de configuração quando nenhum conjunto de chaves do sistema estiver disponível. |
\| `streamerMode` | `boolean` | `false` | Ocultar os nomes de modelos de versão preliminar e detalhes de cotas (é útil ao demonstrar CLI do Copilot). |
\| `theme` |
`"auto"`
|
`"dark"`
|
`"light"`
\| `"auto"` | Tema de cor do terminal. |
\| `mouse` | `boolean` | `true` | Habilite o suporte ao mouse no modo de tela alternativa. |
\| `respectGitignore` | `boolean` | `true` | Excluir os arquivos ignorados pelo git do `@` seletor de arquivos. |
\| `disableAllHooks` | `boolean` | `false` | Desabilite todos os ganchos. |
\| `hooks` | `object` | — | Definições de ganchos em linha no nível do usuário. |
\| `copyOnSelect` | `boolean` |
`true` (macOS), `false` (outros) | Copie automaticamente o texto selecionado pelo mouse para a área de transferência do sistema no modo de tela alternativa. |
\| `statusLine` | `object` | — | Exibição da linha de status personalizada.
`type`: deve ser `"command"`.
`command`: caminho para um script que recebe JSON de sessão através do stdin e imprime o conteúdo de status para o stdout.
`padding`: espaços opcionais de preenchimento esquerdo. |
\| `suppress_init_folders` | `string[]` | `[]` | Pastas em que a `/init` sugestão foi ignorada. Gerenciado automaticamente por `/init suppress`. |
\| `updateTerminalTitle` | `boolean` | `true` | Mostrar a intenção atual no título do terminal. |
### Configurações do repositório (`.github/copilot/settings.json`)
As configurações do repositório se aplicam a todos que trabalham no repositório. Somente as chaves listadas na tabela a seguir têm suporte no nível do repositório. Todas as outras chaves, incluindo chaves válidas no arquivo de configuração do usuário, são ignoradas silenciosamente.
| Chave | Tipo | Comportamento de mesclagem | Descrição |
| ------------------------ | ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `companyAnnouncements` | `string[]` | Substituído — o repositório assume precedência | Mensagens mostradas aleatoriamente na inicialização. |
| `disableAllHooks` | `boolean` | Repositório tem precedência | Desabilite todos os ganchos. |
| `enabledPlugins` | `Record` | Mesclado — o repositório tem prioridade sobre o usuário para a mesma chave | Instalação automática do plug-in declarativo. |
| `extraKnownMarketplaces` | `Record` | Mesclado — o repositório tem prioridade sobre o usuário para a mesma chave | Marketplaces de plug-in disponíveis neste repositório. |
| `hooks` | `object` | Concatenados — gatilhos do repositório são executados após os gatilhos do usuário | Definições de gancho destinadas a este repositório. Consulte a [referência de Hooks](#hooks-reference). |
| `mergeStrategy` | | | |
```
`"rebase"`
\|
`"merge"`
| Repositório tem precedência | Estratégia de resolução de conflitos para `/pr fix conflicts`. |
```
### Configurações locais (`.github/copilot/settings.local.json`)
Crie `.github/copilot/settings.local.json` no repositório para configurações pessoais que não devem ser confirmadas. Adicione este arquivo a `.gitignore`.
O arquivo de configuração local usa o mesmo esquema que o arquivo de configuração do repositório (`.github/copilot/settings.json`) e tem precedência sobre ele.
## 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 usando o `/init suppress` comando barra, que adiciona uma `suppress_init_folders` configuração para esse repositório ao arquivo Copilot de configuração.
Para obter mais informações, consulte [Adicionando instruções personalizadas do repositório para GitHub Copilot](/pt/copilot/how-tos/configure-custom-instructions/add-repository-instructions).
## Referência de ganchos
Ganchos são comandos externos que são executados em pontos de ciclo de vida específicos durante uma sessão, permitindo 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`.
#### Ganchos de comando
Os ganchos de comando executam scripts de shell e têm suporte em todos os tipos de gancho.
```json
{
"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 |
| ------------ | ----------- | -------------------------- | ---------------------------------------------------------------------------------- |
| `type` | `"command"` | Sim | Deve ser `"command"`. |
| `bash` | cadeia | Um dos `bash`/`powershell` | Comando shell para Unix. |
| `powershell` | cadeia | Um dos `bash`/`powershell` | Comando shell para Windows. |
| `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). |
| `timeoutSec` | número | No | Tempo limite em segundos. Padrão: `30`. |
#### 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.
```json
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "prompt",
"prompt": "Your prompt text or /slash-command"
}
]
}
}
```
| Campo | Tipo | Obrigatório | Descrição |
| -------- | ---------- | ----------- | ---------------------------------------------------------------------------------------- |
| `type` | `"prompt"` | Sim | Deve ser `"prompt"`. |
| `prompt` | cadeia | Sim | O texto a ser enviado pode ser uma mensagem de linguagem natural ou um comando de barra. |
### Eventos de gancho
| Acontecimento | Acionado quando | A saída foi processada |
| --------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `sessionStart` | Uma sessão nova ou retomada começa. | No |
| `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:**
```
```typescript
{
sessionId: string;
timestamp: number; // Unix timestamp in milliseconds
cwd: string;
source: "startup" | "resume" | "new";
initialPrompt?: string;
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
prompt: string;
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
hook_event_name: "UserPromptSubmit";
session_id: string;
timestamp: string; // ISO 8601 timestamp
cwd: string;
prompt: string;
}
```
#### `preToolUse` / `PreToolUse`
```
**entrada camelCase:**
```
```typescript
{
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.
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
toolName: string;
toolArgs: unknown;
toolResult: {
resultType: "success";
textResultForLlm: string;
}
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
toolName: string;
toolArgs: unknown;
error: string;
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
transcriptPath: string;
stopReason: "end_turn";
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
hook_event_name: "Stop";
session_id: string;
timestamp: string; // ISO 8601 timestamp
cwd: string;
transcript_path: string;
stop_reason: "end_turn";
}
```
#### `subagentStart`
```
**Entrada:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
transcriptPath: string;
agentName: string;
agentDisplayName?: string;
agentDescription?: string;
}
```
#### `subagentStop` / `SubagentStop`
```
**entrada camelCase:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
transcriptPath: string;
agentName: string;
agentDisplayName?: string;
stopReason: "end_turn";
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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:**
```
```typescript
{
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:**
```
```typescript
{
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:**
```
```typescript
{
sessionId: string;
timestamp: number;
cwd: string;
transcriptPath: string;
trigger: "manual" | "auto";
customInstructions: string;
}
```
```
**
VS Code entrada compatível:**
```
```typescript
{
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.
| 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. Obrigatório quando a decisão é `"deny"`. |
\| `modifiedArgs` | objeto | Substitua os argumentos da ferramenta para serem usados no lugar dos originais. |
###
```
`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. |
```
\| `message` | cadeia | Motivo para voltar à LLM ao negar. |
\| `interrupt` | boolean | Quando `true` é combinado com `"deny"`, interrompe totalmente o agente. |
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). O código `2` de saída é tratado como uma negação; se o gancho também gerar JSON no stdout, esses campos serão mesclados com a decisão de negação.
### 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:**
```
```typescript
{
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:**
```
```typescript
{
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. Para `postToolUseFailure` ganchos de comando, sair com código `2` faz com que stderr seja retornado como diretriz de recuperação para o assistente. 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 [--json]` | Mostrar configuração e ferramentas para um servidor específico. |
| `add ` | Adicione um servidor à configuração do usuário. Grava em `~/.copilot/mcp-config.json`. |
| `remove ` | 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 |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `-- [args...]` | Comandos e argumentos para servidores locais (stdio). |
| `--url ` | URL para servidores remotos. |
| `--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 ` | Filtro de ferramenta: `"*"` para todos, uma lista separada por vírgulas ou `""` para nenhum. |
| `--timeout ` | 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 ` | Caminho para o diretório de configuração. |
> \[!CAUTION]
```
`--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"`. |
```
\| `url` | Sim | URL do servidor. |
\| `tools` | Sim | Ferramentas para habilitar. |
\| `headers` | No | Cabeçalhos HTTP. Dá suporte à expansão variável. |
\| `oauthClientId` | No | ID do cliente OAuth estático (ignora o registro dinâmico). |
\| `oauthPublicClient` | No | Se o cliente OAuth é público. Padrão: `true`. |
\| `oidc` | No | Habilitar a injeção de token OIDC. Quando `true`, injeta uma `GITHUB_COPILOT_OIDC_MCP_TOKEN` variável de ambiente (servidores locais) ou um `Bearer``Authorization` cabeçalho (servidores remotos). |
\| `timeout` | No | Tempo limite de chamada de ferramenta em milissegundos. |
### 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 ` 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. |
```
\| `playwright` | Automação do navegador: navegar, clicar, digitar, captura de tela e manipulação de formulários. |
\| `fetch` | Solicitações HTTP pela ferramenta `fetch`. |
\| `time` | Utilitários de tempo: `get_current_time` e `convert_time`. |
Use `--disable-builtin-mcps` para desabilitar todos os servidores internos ou `--disable-mcp-server SERVER-NAME` desabilitar um específico.
### 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:
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 endpoint de avaliação da lista de permissão 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:
```text
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.json`CLI do GitHub Copilot. A migração mapeia novamente a `servers` chave para `mcpServers`.
```
**Conchas POSIX (bash, zsh, peixe e outros):**
```
```shell
jq '{mcpServers: .servers}' .vscode/mcp.json > .mcp.json
```
Requer [`jq`](https://jqlang.github.io/jq/).
```
**PowerShell**:
```
```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-tools`e `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. |
| `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. 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. |
| `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/` |
```
\| Usuário |
`~/.copilot/agents/` ou `~/.claude/agents/` |
\| Plug-in | `/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](#content-capture). |
| `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 |
```
\| `gen_ai.usage.input_tokens` | Total de tokens de entrada (todas as voltas) | Ambas |
\| `gen_ai.usage.output_tokens` | Total de tokens de saída (todos os turnos) | Ambas |
\| `gen_ai.usage.cache_read.input_tokens` | Leitura de tokens de entrada armazenados em cache | Ambas |
\| `gen_ai.usage.cache_creation.input_tokens` | Tokens de entrada em cache criados | Ambas |
\| `github.copilot.turn_count` | Número de viagens de ida e volta de LLM | Ambas |
\| `github.copilot.cost` | Custo monetário | Ambas |
\| `github.copilot.aiu` | Unidades de IA consumidas | Ambas |
\| `server.address` | Nome do host do servidor |
`CLIENT` somente |
\| `server.port` | Porta do servidor |
`CLIENT` somente |
\| `error.type` | Nome da classe de erro (em caso de erro) | Ambas |
\| `gen_ai.input.messages` | Mensagens de entrada completas como JSON (somente captura de conteúdo) | Ambas |
\| `gen_ai.output.messages` | Mensagens de saída completas como JSON (somente captura de conteúdo) | Ambas |
\| `gen_ai.system_instructions` | Conteúdo da solicitação do sistema como JSON (captura de conteúdo somente) | Ambas |
\| `gen_ai.tool.definitions` | Esquemas de ferramentas como JSON (somente captura de conteúdo) | 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`.
> \[!WARNING]
> 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 |
## Leitura adicional
* [CLI do GitHub Copilot](/pt/copilot/how-tos/copilot-cli)
* [referência de plugin da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-plugin-reference)
* [referência programática do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [Diretório de configuração do GitHub Copilot CLI](/pt/copilot/reference/copilot-cli-reference/cli-config-dir-reference)