# Agentes de CLI

Use dentro do seu espaço de escrita um agente que você já executa no terminal.

Traga para o Oleafly o agente que você já instalou. O modo **Agente de CLI** usa o ambiente de execução e o login desse agente, para você trabalhar ao lado do manuscrito com as ferramentas que já usa.

![Configurações → Assistente de IA → Agentes de CLI. Verifique os agentes instalados no topo e depois expanda um agente para concluir a configuração dele.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-cli-agents-dark-window-v2.png#view=519,89,883,902)

## Conecte um agente

1. Abra **Configurações → Assistente de IA → Agentes de CLI** e escolha **Verificar os agentes instalados**.
2. Expanda o seu agente. A linha **Programa** mostra o programa que o Oleafly encontrou e onde ele está.
3. Escolha **Testar**. Se o cartão pedir uma ponte, escolha primeiro **Instalar a ponte**.
4. Faça login pela própria ferramenta de linha de comando do agente. O cartão mostra o **Comando de login** e, com um projeto aberto, **Abrir o terminal de login** dá a você um terminal para executá-lo.
5. Abra o assistente, mude para **Agente de CLI** e escolha o agente.
6. Comece com uma tarefa pequena, como explicar a estrutura do projeto ou revisar um parágrafo.

Se você mudar para um agente que ainda não está pronto, o assistente mostra um cartão de configuração que diz o que está faltando. O botão **Configurar** dele, como **Configurar Claude Code**, abre aquele agente em Configurações. Quando só a ponte está faltando, **Instalar a ponte** no cartão a instala.

A autenticação, o acesso aos modelos e a cobrança pertencem ao agente selecionado. Uma conta ou assinatura que ofereça suporte à CLI pode ser usada conforme os termos do respectivo provedor; o Oleafly não acrescenta uma assinatura de IA separada.

## Escolha o programa

Sob o rótulo **Programa**, o cartão mostra o arquivo que o Oleafly inicia e de onde ele veio: **Encontrado automaticamente**, **Escolhido por você** ou **Instalado pelo Oleafly**. Para alguns agentes, essa linha fica dentro dos detalhes da **Ponte ACP**.

Para usar outra cópia, escolha **Escolher…** e selecione o arquivo. Se o Oleafly não encontrou nada, a linha diz **Não encontrado neste computador** e dá a você um campo para o local. Digite ou cole o caminho e pressione Enter ou escolha **Testar**. Um arquivo que você seleciona ou digita só é salvo depois de passar no teste. **Usar a detecção automática** descarta a sua escolha.

O Oleafly procura nas pastas em que os instaladores colocam os agentes:

- No Windows, ele encontra agentes instalados com npm, pnpm, Scoop, winget e ferramentas parecidas, em qualquer unidade. Ele lê o caminho de busca do zero a cada vez, então **Verificar os agentes instalados** também encontra um agente que você instalou enquanto o Oleafly estava aberto.
- No macOS, ele encontra agentes em pastas que normalmente só o seu shell conhece, como `~/.local/bin` ou uma pasta do nvm, mesmo quando você abre o Oleafly pelo Dock ou pelo Finder.

Quando o Oleafly encontra um arquivo com o nome certo que não consegue usar, a configuração diz o que foi encontrado e por quê. Um caso comum no Windows é um script do PowerShell quando o Oleafly precisa da versão `.cmd` ou `.exe`. **Arquivos ignorados pelo Oleafly** lista cada um desses arquivos com o motivo, por exemplo uma pasta, um aplicativo de desktop, um shell ou ambiente de execução como `node`, ou uma cópia em um local de rede.

Os caminhos em Configurações ficam desfocados até você passar o mouse sobre eles ou chegar a eles com Tab, para que uma captura de tela das Configurações não mostre onde ficam os seus arquivos.

## Teste um agente

**Testar** inicia o agente em uma pasta vazia que pertence ao Oleafly, longe do seu projeto, e espera que ele responda. Não salva nada. Quando passa, você vê o nome e a versão do agente. Quando falha, recebe uma frase dizendo por quê e uma coisa para tentar:

| O que o teste informa | O que tentar |
| --- | --- |
| Não há arquivo ali, ou é uma pasta, um aplicativo de desktop ou um arquivo que o Oleafly não consegue iniciar | **Escolher…** e selecione o próprio programa |
| A ponte ainda não está instalada | **Instalar a ponte** |
| O agente precisa do Node.js ou de uma versão mais nova dele | **Obter Node.js** |
| O agente iniciou, mas não respondeu, parou antes da hora ou enviou uma resposta que o Oleafly não conseguiu ler | **Copiar detalhes** ou **Abrir terminal** para executá-lo você mesmo |

Se um arquivo que você escolheu falhar por qualquer motivo que não seja o próprio arquivo, **Usar mesmo assim** o salva de qualquer modo.

## Catálogo de agentes

| Agente | Comando da CLI |
| --- | --- |
| Claude Code | `claude` |
| Codex CLI | `codex` |
| Gemini CLI | `gemini` |
| Pi | `pi` |
| OpenCode | `opencode` |
| OpenClaw | `openclaw` |
| Cline | `cline` |
| Hermes Agent | `hermes` |
| CodeBuddy | `codebuddy` |
| Kimi Code | `kimi` |
| Grok Build | `grok` |
| Cursor | `cursor-agent` ou `agent` |
| DeepSeek Harness | `dsh` |
| Qoder | `qodercli` |

O catálogo identifica os caminhos de inicialização compatíveis. Os modelos disponíveis, os anexos, a retomada de sessão e o relatório de uso dependem do que o agente expõe. A configuração informa os requisitos ausentes antes de uma sessão começar.

O Pi roda pela ponte pi-acp, versão 0.0.34, e o Oleafly aponta a ponte para o seu programa Pi. No Windows, ele lida com pastas de projeto que têm espaços no nome.

## Trabalhe ao lado do manuscrito

Dê ao agente um pedido concreto e acompanhe as respostas, a atividade das ferramentas e os pedidos de permissão dele no painel do assistente. Abra o código-fonte resultante e compile-o no Oleafly.

> Leia a introdução e os métodos. Liste os termos que são introduzidos de forma inconsistente, com a localização nos arquivos.

Para uma cópia separada e uma revisão final, escolha um agente disponível em [Tarefas de pesquisa](/docs/research-tasks/). Essa página lista os requisitos de plataforma para o trabalho isolado.

## Pontos de partida para pesquisa

Uma nova conversa abre na página inicial do agente, que oferece pontos de partida para pesquisa. Escolher um preenche a mensagem, mas não a envia, para você poder ler e ajustar antes. Se nenhuma conversa estiver aberta ainda, ele inicia uma.

| Ponto de partida | O que ele pede |
| --- | --- |
| **Varredura da literatura** | Uma lista de leitura anotada para a pergunta de pesquisa do projeto, com a habilidade `oleafly-literature-sweep` |
| **Trabalhos relacionados** | Uma seção de trabalhos relacionados redigida a partir da lista de leitura e da bibliografia, com `oleafly-related-work` |
| **Auditoria de citações** | Uma conferência das afirmações do manuscrito com as fontes citadas, com `oleafly-verify-claims` |
| **Revisão do manuscrito** | Uma revisão do manuscrito completo, com `oleafly-review-manuscript` |
| **Auditoria de reprodutibilidade** | O que falta a cada resultado para ser reproduzido: código, dados, versões de software, sementes aleatórias e instruções de compilação |
| **Auditoria de figuras** | Uma conferência de todas as figuras e tabelas: legendas, rótulos, referências cruzadas, rótulos de eixos e unidades, legibilidade e cores que se sustentam em escala de cinza |
| **Revisão do Git** | Um resumo das alterações não commitadas e dos commits recentes que aponta edições que parecem não intencionais. Aparece só em um repositório Git |
| **Limpeza de referências** | Abre **Limpar a biblioteca de referências**, que padroniza as chaves de citação e remove duplicatas depois que você vê a prévia das alterações |

As auditorias e a revisão do manuscrito pedem ao agente que deixe os arquivos do manuscrito em paz e escreva as conclusões em um arquivo em `research/`, como `research/figure-audit.md`.

Uma habilidade que você escolhe, a partir de um ponto de partida ou da lista de habilidades da página inicial, aparece como um chip acima da mensagem. O Oleafly envia as instruções da habilidade junto com a sua mensagem, então os agentes que não recebem as ferramentas do Oleafly, como o Pi, ainda podem segui-la. Clique no chip para removê-la. Se a habilidade estiver desativada para o projeto, o ponto de partida preenche a mensagem sem ela.

## Pedidos de permissão

Quando o agente pergunta antes de agir, um cartão diz que o agente **precisa de permissão** e oferece as escolhas do próprio agente. Se o pedido alteraria arquivos, o cartão os lista. **Mostrar a alteração** abre o diff de um arquivo para você lê-lo antes de responder. Uma alteração grande demais para exibir avisa isso, e você pode revisá-la depois do turno. **Dispensar** cancela o pedido sem permitir. Um pedido que você deixa por dois minutos expira, e o agente tem de perguntar de novo.

## Revise e desfaça alterações

Depois de um turno que alterou arquivos, uma linha abaixo da resposta diz quantos. **Revisar** mostra cada alteração, e **Desfazer** e **Refazer** funcionam arquivo por arquivo ou para o turno inteiro. [Revise e desfaça um turno](/docs/ai-chat/#review-and-undo-a-turn) explica como isso funciona e no que não mexe.

## Conversas e exportação

O cabeçalho do assistente tem **Nova conversa**, **Conversas salvas** e **Configuração do agente**. Cada conversa registra o commit do Git em que o projeto estava quando ela começou.

Para guardar uma cópia fora do Oleafly, abra **Conversas salvas** e escolha **Exportar a conversa…**, depois escolha Markdown ou JSON na caixa de diálogo de salvar. O arquivo Markdown começa com o projeto, o agente, o modelo, o commit em que a conversa começou (indicando as alterações não commitadas) e quando ela começou e foi atualizada pela última vez. Em seguida vêm as mensagens, as habilidades, as chamadas de ferramentas e os arquivos alterados. O JSON guarda o registro completo.

## Agentes personalizados

Escolha **Encontrar mais agentes** para buscar no registro ACP agentes publicados por outras equipes, ou **Adicionar um agente personalizado** para colar você mesmo uma definição. Revise o executável ou o pacote, os argumentos e os requisitos de conexão antes de executá-lo. Registrar uma definição não instala nem inicia o agente.

## Use um cliente externo em vez disso

Se você prefere ficar na interface do seu próprio agente, conecte-o por MCP. O [servidor MCP do Oleafly](/docs/mcp/) dá a ele as ferramentas de projeto do aplicativo enquanto o Oleafly está aberto. O [comando `oleafly`](/docs/cli/#connect-an-agent-over-mcp) funciona também com o aplicativo fechado, e a [habilidade `oleafly-cli`](/docs/cli/#the-oleafly-cli-skill) ensina ao seu agente os comandos dele.