AGENTS.md

O que é o AGENTS.md?

Pense no AGENTS.md como um runbook (manual de operação) do seu agente:

• Regras de execução (o que pode fazer / o que não pode)

• Política de confirmação (quando ele deve parar e pedir “ok”)

• Preferências de trabalho (como ele planeja, como reporta, como registra)

• Restrições de segurança (como tratar credenciais, arquivos sensíveis, etc.)

• Memória operacional (coisas que você quer que ele “lembre” para agir melhor)

Ele existe dentro de um conjunto de “bootstrap files” que o OpenClaw espera no workspace. Entre eles, você costuma ver também: SOUL.md (persona e tom), TOOLS.md (anotações de ferramentas), USER.md (perfil do usuário), IDENTITY.md, BOOTSTRAP.md, etc.

Por que esse arquivo é tão relevante?

Porque agentes desse tipo não são só chatbots: eles podem executar ações reais no seu ambiente (sistema, integrações, ferramentas). Isso é poderoso — e arriscado.

Nas últimas semanas, houve relatos de:

• Skills maliciosas publicadas em registry público (ClawHub) que exploram o fato de o agente ter acesso a sistema/arquivos/rede.

• Extensão falsa de VS Code “ClawBot Agent” distribuindo trojan ao se passar por ferramenta “oficial”.

• Análises de segurança apontando que “skills” em Markdown podem virar superfície de ataque porque frequentemente incluem passos do tipo “rode este comando” (que usuários/agents tendem a seguir).

Então, o AGENTS.md vira o lugar certo para você escrever, com clareza, quais ações são aceitáveis e sob quais condições.

AGENTS.md vs SOUL.md vs TOOLS.md (diferença prática)

Uma forma simples de separar responsabilidades:

• AGENTS.md → como o agente opera e decide (processos, limites, confirmações, padrões de execução).

• SOUL.md → quem o agente “é” (tom, persona, estilo, limites de comunicação).

• TOOLS.md → catálogo e convenções de ferramentas (comandos permitidos, notas, shortcuts, boas práticas).

Se você mistura tudo, seu agente fica inconsistente: ele até “fala bonito”, mas age mal.

Estrutura recomendada shows (template pronto)

Abaixo vai um modelo seguro e pragmático (você pode colar no seu blog e no seu projeto). A ideia é ser explícito e auditável.

# AGENTS.md — Operação e Segurança do Agente

## 1) Missão - Objetivo principal: ajudar com tarefas de produtividade e desenvolvimento sem causar risco ao ambiente. - Prioridades: (1) segurança, (2) reversibilidade, (3) clareza, (4) velocidade.

## 2) Permissões e Confirmações

### Pode fazer sem confirmar - Ler arquivos dentro do workspace do projeto. - Fazer buscas locais em pastas não sensíveis. - Propor planos e rascunhos (sem executar ações externas).

### Deve confirmar antes de executar - Rodar comandos no terminal - Instalar dependências/pacotes - Criar/alterar arquivos fora do workspace - Enviar mensagens/e-mails/postagens - Acessar credenciais/segredos, tokens, chaves

### Nunca fazer (bloqueio duro) - Executar scripts baixados via “curl | bash” ou equivalentes - Desativar antivírus/segurança do sistema - Exfiltrar dados (copiar/mandar arquivos, dumps, bases, senhas) - Ações financeiras (trade, transferências, pagamentos)

## 3) Política de Segredos - Nunca registrar chaves, tokens, senhas em texto plano. - Preferir variáveis de ambiente e vault. - Se detectar segredo em output/log, mascarar imediatamente.

## 4) Padrão de Execução (Runbook) 1) Entender tarefa e restrições 2) Propor plano curto (checklist) 3) Identificar riscos e necessidade de confirmação 4) Executar passos reversíveis primeiro 5) Reportar resultado + mudanças feitas + próximos passos

## 5) Log e Auditoria - Sempre listar arquivos alterados e por quê. - Sempre fornecer comandos executados (se houver), com contexto. - Preferir mudanças pequenas e versionáveis (Git).

## 6) Preferências do Usuário - Linguagem: PT-BR - Estilo: direto, sem enrolação - Código: pronto para copiar/colar

Esse tipo de estrutura conversa diretamente com a forma como o ecossistema organiza “contexto persistente em Markdown” no workspace.

Boas práticas que evitam dor de cabeça (e incidentes)

1) Trate “skills” como código executável

Mesmo quando a “skill” parece só documentação, ela pode induzir execução de comandos ou baixar scripts. Isso já foi destacado em análises de segurança do ecossistema.

Regra de ouro para colocar no AGENTS.md:

“Nenhum comando baixado/obfuscado roda sem revisão e confirmação.”

2) Crie uma política explícita de confirmação

O maior erro é deixar o agente “autônomo” em ações destrutivas (instalar coisas, mexer fora do workspace, enviar mensagens). O AGENTS.md é o lugar certo para cravar isso.

3) Defina limites por categoria de risco

Ex.: terminal, instalação, rede, mensageria, arquivos fora do workspace. Quanto mais claro, menos surpresa.

4) Versione seu workspace

Como grande parte do “estado” fica em arquivos Markdown, versionar com Git te dá “rollback” de memória/instruções do agente (um dos motivos que a comunidade gosta desse approach).