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

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. Abrir captura de tela completa

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 é:

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. Abrir captura de tela completa

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. Abrir captura de tela completa

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:

~/.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.

~/.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 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, que é configurada separadamente.