# Instruções, aprovações e configuração

Defina preferências de escrita, escolha quando o assistente pede permissão e configure regras de projeto reutilizáveis.

Dê ao assistente preferências de escrita claras e escolha como ele trata as mudanças. As instruções descrevem o trabalho que você quer; os controles de aprovação decidem quais ações de ferramentas podem prosseguir.

![Configurações → Assistente de IA → Instruções. Defina o modelo padrão, escreva suas instruções e use Salvar as instruções. A captura de páginas do PDF fica abaixo do campo de texto.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-instructions-dark-window-v2.png#view=519,89,883,724)

## Modelo padrão das conversas

Abra **Configurações → Assistente de IA → Instruções**. Escolha **Modelo padrão das conversas** para definir o modelo usado em uma nova conversa. A lista contém os modelos ativados dos seus provedores configurados. Você ainda pode trocar o modelo em uma conversa específica.

## Instruções personalizadas

Digite suas preferências em **Instruções personalizadas** e clique em **Salvar as instruções**. Um bom ponto de partida para um manuscrito de pesquisa é:

```text title="Exemplo de instruções de escrita"
Use British English and preserve the terminology already used in the paper.
Keep citation keys, labels, equations, and numerical results unchanged unless
I explicitly ask you to edit them.
When a statement needs evidence, mark it for a source check. Do not invent
references or results.
Explain substantive changes briefly so I can review them.
```

Faça estas instruções específicas o bastante para orientar uma revisão, sem repetir o briefing inteiro do projeto. Elas complementam o comportamento embutido do assistente e não alteram as permissões das ferramentas.

## Salvar as instruções

Clique em **Salvar as instruções** depois de editar. O indicador **Salvo** confirma que a alteração foi gravada. Uma edição não salva neste campo não é o seu novo padrão.

## Permitir a captura de páginas do PDF pela IA

Ative **Permitir a captura de páginas do PDF pela IA** para deixar o assistente inspecionar páginas renderizadas com um modelo que tenha suporte a visão. A ferramenta `verify_pdf_pages` converte as páginas compiladas em imagens para verificar o layout. Desative o controle quando não quiser que imagens de páginas sejam enviadas ao provedor configurado.

## Inspecione o catálogo de ferramentas

Expanda **No momento, o assistente conta com estas ferramentas** na aba Instruções. Use essa lista para ver o trabalho que o assistente pode fazer e depois peça um resultado, como compilar uma seção, inspecionar o PDF ou encontrar uma referência não resolvida.

## Personas

![Configurações → Assistente de IA → Personas. Criar persona fica acima da lista; os controles de editar e excluir ficam ao lado de cada persona.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-personas-dark-window-v2.png#view=519,89,883,902)

Uma persona é um conjunto de instruções com nome. Crie uma em **Configurações → Assistente de IA → Personas** e depois selecione-a no campo de mensagem do chat para um tipo específico de trabalho. Por exemplo, mantenha uma persona de revisão concisa e outra de revisor.

Uma persona ativa fornece o conjunto de instruções da conversa no lugar do texto das instruções personalizadas padrão. Inclua as preferências permanentes de que a persona também precisa. Uma persona muda a orientação; ela não concede permissões de ferramentas.

## Escolha um modo de aprovação

![Abra o menu de aprovação abaixo do campo de mensagem. O modo selecionado aparece com uma marca de seleção; escolha a política que você quer para o seu projeto.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-approval-menu-dark-window-v2.png#view=1448,770,465,305)

Use o seletor de aprovação no campo de mensagem do chat. A escolha é salva para o projeto atual.

| Modo | Comportamento |
|---|---|
| **Pedir aprovação** | As ferramentas classificadas como de leitura podem rodar; as demais ações perguntam antes |
| **Aprovar por mim** | As ferramentas de leitura e de rede podem rodar; alterações de arquivos e comandos de shell perguntam antes |
| **Acesso total** | As ações das ferramentas podem prosseguir sem um pedido de aprovação, exceto as ferramentas bloqueadas por uma regra `deny` |
| **Personalizado** | As regras `allow` e `deny` salvas valem, e as ferramentas sem regra usam a política de risco padrão |

**Aprovar por mim** é o padrão. Algumas ferramentas têm verificações próprias dentro de uma operação. Compilar e inspecionar um PDF são tratados de forma diferente de gravar um arquivo de código-fonte ou executar um comando de shell.

## Aprove uma ação proposta

Leia o nome da ferramenta e a operação proposta no cartão de aprovação. Aprove para executar a ação ou recuse para deixar a alteração proposta sem aplicar. Continue a conversa com uma instrução mais restrita se a ação pedida for ampla demais.

## Sempre neste projeto

No modo **Personalizado**, use **Sempre neste projeto** em um pedido de aprovação para salvar uma regra para aquela ferramenta. Confira o modo selecionado quando esperar que uma regra afete a próxima execução.

## Revise ou remova uma regra

Com o projeto aberto, vá a **Configurações → Assistente de IA → Provedores e chaves** e role até **Aprovações de ferramentas**. Cada linha mostra o nome da ferramenta e se ela é sempre permitida ou negada. Remova uma regra para devolver aquela ferramenta à política de risco padrão no modo Personalizado.

## Edite o approvals.toml

**Arquivo de regras de aprovação**, abaixo de **Aprovações de ferramentas**, edita o `~/.oleafly/approvals.toml`. Use **Recarregar** para ler o arquivo atual, **Descartar as mudanças** para abandonar as edições não salvas ou **Inserir um exemplo** para começar com uma configuração de amostra. **Como o arquivo funciona** explica o formato e mostra o ID do projeto aberto. Ao salvar, o TOML é validado antes de ser aplicado, e as regras valem a partir da próxima chamada de ferramenta.

O arquivo tem uma tabela de modos e tabelas de regras por ferramenta, identificadas pelo **ID da pasta do projeto**, não pelo título exibido:

```toml title="~/.oleafly/approvals.toml"
["$approval_modes"]
"my-project-folder-id" = "custom"

["my-project-folder-id"]
write_file = "allow"
replace_in_file = "allow"
run_command = "deny"
delete_file = "deny"
```

Troque `my-project-folder-id` pelo ID real da pasta do seu projeto. Os IDs de projeto são os nomes das pastas em `~/.oleafly/projects`. Os valores de modo são `ask-for-approval`, `approve-for-me`, `full-access` e `custom`. Um projeto que não está listado usa Aprovar por mim. Os valores das regras de ferramenta são `allow` e `deny`. Uma regra `deny` vale em todos os modos, inclusive Acesso total, então uma ferramenta negada nunca roda. Uma regra `allow` só vale no modo Personalizado. Uma ferramenta sem regra usa a política de risco normal.

Os comentários que começam com `#` sobrevivem a um salvamento feito em Configurações, mas escolher **Sempre neste projeto** em um cartão de aprovação reescreve o arquivo sem eles.

Use os nomes exatos das ferramentas do catálogo. Entre os nomes comuns estão `write_file`, `replace_in_file`, `create_file`, `rename_file`, `delete_file`, `run_command`, `compile`, `insert_figure` e `set_main_doc`.

## Qual arquivo de configuração devo usar?

| Arquivo | Finalidade |
|---|---|
| `~/.oleafly/config.json` | Configuração do aplicativo, gerenciada pelas Configurações |
| `~/.oleafly/approvals.toml` | Modos de aprovação do projeto e regras por ferramenta |
| `~/.oleafly/agent.toml` | Limites e instruções avançados de vários agentes |
| A configuração do seu agente externo, como `~/.codex/config.toml` | As configurações e as conexões MCP desse agente |

O Oleafly não usa um único `config.toml` para todas essas configurações. Use a interface de Configurações para as chaves de provedores e as preferências do aplicativo; as credenciais têm um armazenamento criptografado separado. Não substitua toda a configuração do seu aplicativo por um exemplo curto.

## Configure o agent.toml

Usuários avançados podem criar `~/.oleafly/agent.toml` para ajustar as configurações de vários agentes do assistente. Essas configurações governam o ambiente de execução de agentes do próprio Oleafly, separadamente da configuração de um agente de CLI conectado.

```toml title="~/.oleafly/agent.toml"
maxAgentDepth = 2
maxConcurrentSubagents = 8
minWaitTimeoutMs = 1000
maxWaitTimeoutMs = 300000
defaultWaitTimeoutMs = 120000
waitAgentEnabled = true

usageHintText = """
Delegate independent checks with clear scopes. Keep writing decisions with
the parent agent, and close completed agents when their work is collected.
"""

subagentDeveloperInstructions = """
Work only on the assigned task. Report the files and evidence you inspected.
Do not spawn additional agents.
"""
```

### maxAgentDepth

Limita a profundidade de aninhamento. O padrão é `2`: os filhos de uma execução não delegam mais adiante. O valor mínimo aceito é `1`.

### maxConcurrentSubagents

Limita os subagentes simultâneos em uma sessão. O padrão é `8`, e o mínimo é `1`. Mais agentes podem aumentar o uso do modelo; aumente o limite para trabalhos que realmente possam avançar de forma independente.

### minWaitTimeoutMs

Define o limite inferior da espera por um agente, em milissegundos. O padrão é `1000`.

### maxWaitTimeoutMs

Define o limite superior da espera por um agente. O padrão é `300000`, ou cinco minutos. Ele é mantido igual ou acima do mínimo.

### defaultWaitTimeoutMs

Define a duração padrão da espera. O padrão é `120000`, ou dois minutos. Os valores são limitados ao mínimo e ao máximo configurados.

### waitAgentEnabled

Controla a disponibilidade do recurso de esperar por um agente. O padrão é `true`.

### usageHintText

Fornece ao agente pai uma orientação de delegação. O exemplo acima substitui a orientação padrão pelo seu próprio texto.

### subagentDeveloperInstructions

Fornece instruções aos agentes filhos. Use-o para indicar o escopo, o que você espera no relatório e se mais delegação é apropriada.

O ambiente de execução também aceita versões em snake_case dessas chaves, como `max_agent_depth`. Os campos omitidos usam os padrões. Um arquivo ausente ou malformado volta aos padrões, então confira a sintaxe com cuidado e inicie uma nova execução depois de mudar a configuração.

## Teste uma regra com uma tarefa pequena

1. Abra um projeto de teste e escolha **Pedir aprovação**.
2. Peça: “Leia o documento principal e proponha um título mais claro. Pergunte antes de alterar o arquivo.”
3. Inspecione a alteração proposta e aprove ou recuse.
4. Revise as regras salvas em Configurações antes de passar para o modo Personalizado.
5. Use o [modo Plano](/docs/ai-chat/#plan-before-editing) quando quiser combinar várias etapas antes de as edições começarem.

Os assistentes externos que se conectam pelo MCP do Oleafly usam a [política do servidor MCP](/docs/mcp/#approvals-and-safety), que é configurada separadamente.