Anatomia de uma configuração perfeita do Openclaw

Um guia completo sobre arquivos do workspace, skills, canais, permissões e como configurá-los corretamente.

A maioria dos usuários do OpenClaw instala, conecta um canal e nunca mais abre a pasta do workspace.

Isso é um erro.

Seu workspace é o centro de controle de como seu assistente de IA se comporta. Ele guarda sua identidade, skills personalizadas, conexões de canais e memória. Depois que você entende o que vai onde, pode configurar o OpenClaw exatamente do seu jeito.

Este guia mostra a anatomia de uma configuração perfeita.

PS: O Openclaw é só o começo.

Dentro da nossa comunidade Build With AI, vamos te ensinar a construir agentes, aplicativos e automações personalizados que você pode usar ou vender para clientes. Lançamento em breve.

Entre na lista de espera aqui: https://return-my-time.kit.com/1bd2720397

-----------------------------------------

Duas camadas de configuração, não uma

Antes de mergulhar, uma coisa importante: o OpenClaw usa duas camadas de configuração.

A primeira é a pasta do seu workspace (geralmente ~/clawd/ ou onde você inicializou). Ela contém sua configuração pessoal, skills, memória e segredos.

A segunda é a instalação global em opt/homebrew/lib/node_modules/clawdbot/ (ou equivalente no seu sistema). Ela contém os documentos principais, skills embutidas e comportamentos padrão.

Seu workspace é onde você personaliza. A instalação global é o que você atualiza.

AGENTS.md: Suas instruções operacionais

Este é o arquivo mais importante de toda a sua configuração. Quando o OpenClaw inicia uma sessão, a primeira coisa que ele lê é o AGENTS.md. Ele carrega direto no prompt do sistema e mantém na memória durante toda a conversa.

Simplificando: tudo que você escrever no AGENTS.md, seu agente vai seguir.

Se você mandar ele sempre verificar sua agenda antes de sugerir horários de reunião, ele vai fazer. Se você disser "nunca envie e-mails sem minha aprovação explícita", ele vai respeitar isso todas as vezes.

O que realmente deve estar no AGENTS.md:

Escreva:

• Sua diretriz operacional principal (qual é o trabalho do agente?)
• Ferramentas chave e como usá-las (CLI de e-mail, fluxos de gerenciamento de tarefas)
• Regras rígidas que nunca devem ser quebradas
• Links para recursos importantes (documentação de APIs, localização de skills)
• Gatilhos de fluxo de trabalho (o que deve acontecer automaticamente)

Não escreva:

• Documentação completa que você pode linkar
• Parágrafos longos explicando teoria
• Informações que mudam com frequência

Mantenha o AGENTS.md com menos de 300 linhas. Arquivos maiores que isso consomem contexto demais e a adesão às instruções cai.

Aqui está um exemplo mínimo, mas eficaz:

1# AGENTS.md - Workspace do Clawdbot
2
3## Diretriz Operacional Principal
4Meu assistente opera como um ajudante proativo para o meu negócio.
5
6**O Mandato:**
7- Tirar o máximo possível do meu prato
8- Ser proativo — não esperar ser solicitado
9
10## Ferramentas Principais
11- **E-mail:** Verificar caixa de entrada diariamente, sinalizar itens urgentes
12- **Agenda:** Verificar se não há conflitos antes de agendar
13- **Gerenciador de Tarefas:** Sincronizar trabalho concluído ao painel
14
15## Regras Rígidas
16- NUNCA reiniciar serviços sem permissão explícita
17- Sempre verificar datas com o comando `date` antes de agendar
18- Registrar todo trabalho concluído no sistema de rastreamento

São ~20 linhas de diretrizes principais. Dá ao seu agente tudo que ele precisa para trabalhar de forma produtiva sem precisar de esclarecimentos constantes.

SOUL.md: Persona e limites

O SOUL.md define quem é seu agente e como ele deve se comunicar. É aqui que a personalidade mora.

1# SOUL.md - Persona e Limites
2
3- Mantenha as respostas concisas e diretas.
4- Faça perguntas esclarecedoras quando necessário.
5- Nunca envie respostas parciais/em streaming para superfícies de mensagens externas.

Se o AGENTS.md é o manual de instruções, o SOUL.md é o perfil de personalidade. Alguns usuários escrevem personas extensas aqui. Outros mantêm o mínimo. Ambos funcionam, depende de quanta personalização de personalidade você quer.

IDENTITY.md e USER.md: Quem é quem

Esses dois arquivos estabelecem o relacionamento entre seu agente e você.

IDENTITY.md define seu agente:

1# IDENTITY.md - Identidade do Agente
2
3- Nome: [Nome do seu agente]
4- Criatura: [Opcional: descrição divertida]
5- Vibes: Inteligente, útil, confiável, resolvedor de problemas tenaz
6- Emoji: [Seu emoji escolhido]

USER.md define você:

1# USER.md - Perfil do Usuário
2
3- Nome: [Seu nome]
4- Como prefere ser chamado: [Apelido]
5- Fuso horário: [Seu fuso horário]
6- Telefone: [Seu número]
7- Agenda: [Plataforma de agenda e e-mail]

Por que arquivos separados? Porque eles servem a propósitos diferentes. O IDENTITY.md raramente muda depois de definido. O USER.md é atualizado conforme suas preferências evoluem. Mantê-los separados facilita a manutenção.

HEARTBEAT.md: Check-ins agendados

Este arquivo controla o que seu agente faz durante as verificações de heartbeat—momentos agendados em que o sistema verifica se algo precisa de atenção.

1# HEARTBEAT.md
2
3**Se a mensagem contiver "⚠️ EXECUTION CRON":**
4- Isso NÃO é uma verificação de heartbeat — é trabalho a ser feito
5- Leia as instruções completas na mensagem
6- Execute todos os passos necessários
7- Nunca retorne HEARTBEAT_OK
8
9**Caso contrário:**
10- Se nada precisar de atenção, retorne HEARTBEAT_OK
11- Mantenha o mínimo

Heartbeats são poderosos para criar agentes proativos. Seu agente pode verificar sua agenda, examinar sua caixa de entrada ou executar qualquer fluxo de trabalho automatizado em um cronograma, tudo acionado por verificações de heartbeat.

TOOLS.md: Documentação de ferramentas externas

Este arquivo contém suas anotações sobre ferramentas externas e convenções. Ele não define quais ferramentas existem (o OpenClaw lida com isso internamente), mas é onde você documenta como VOCÊ as usa.

1# TOOLS.md - Anotações de Ferramentas do Usuário
2
3## CLI de E-mail
4- Conta: [email protected]
5- Comum: `cli email search`, `cli calendar create`
6
7## API de Gerenciamento de Tarefas
8- Local do token: ~/.secrets/task-api-token.txt
9- Sempre use `limit=100` para evitar problemas de paginação
10- Conversão de status: [documente seu fluxo de trabalho específico]
11
12## Ferramenta de web scraping (quando sites bloqueiam requisições normais)
13- Local: ~/clawd/.venv/scraper
14- Use modo furtivo para sites protegidos

Este se torna seu guia de referência pessoal. Quando seu agente precisar usar uma ferramenta, ele verifica o TOOLS.md para suas convenções específicas.

A pasta skills/: Fluxos de trabalho reutilizáveis

Skills são onde o OpenClaw se torna poderoso. Cada skill é um fluxo de trabalho independente que seu agente pode invocar quando a tarefa corresponde à descrição da skill.

Cada skill vive em sua própria subpasta com um arquivo SKILL.md:

1skills/
2├── meeting-prep/
3│   └── SKILL.md
4├── social-post-writer/
5│   ├── SKILL.md
6│   └── references/
7│       └── templates.md
8└── podcast-show-notes/
9    └── SKILL.md

Um SKILL.md usa frontmatter YAML para descrever quando usá-lo:

1---
2name: meeting-prep
3description: Pesquisa automatizada e briefing pré-reunião. Use quando o usuário pedir para verificar reuniões futuras ou preparar uma reunião.
4---
5
6## Skill de Preparação de Reunião
7
8## Quando acionar:
9- Usuário pede para verificar reuniões futuras
10- Agendado para executar a cada 10 minutos via cron
11- Só faz briefing para PRIMEIRAS REUNIÕES
12
13## Processo:
141. Verificar agenda para reuniões nos próximos 15-45 minutos
152. Pesquisar participantes (LinkedIn, site da empresa)
163. Criar documento de briefing
174. Anexar link ao evento da agenda

A diferença chave das instruções estáticas: skills podem agrupar arquivos de suporte junto com elas. O arquivo references/templates.md pode conter exemplos de saída, formatos comprovados ou contexto adicional que só carrega quando a skill está ativa.

A pasta memory/: Contexto persistente

Esta é a memória de longo prazo do seu agente. Transcrições de sessão, preferências aprendidas e registros diários ficam aqui.

1memory/
2├── 2026-03-22.md
3├── 2026-03-21.md
4├── email-style.md
5├── business-context-2026-02.md
6└── workflow-playbook.md

Boas práticas:

• Mantenha registros diários em memory/YYYY-MM-DD.md
• No início da sessão, seu agente lê hoje + ontem se presentes
• Capture fatos duráveis, preferências e decisões
• Evite armazenar segredos

Arquivos de memória são o que dão contexto ao seu agente entre sessões. Sem eles, toda conversa começa do zero.

A pasta .secrets/: Credenciais

Tokens de API, senhas e configurações sensíveis ficam aqui. Esta pasta deve estar no gitignore e nunca ser commitada.

1.secrets/
2├── task-api-token.txt
3├── openai-api-key.txt
4├── anthropic-api-key.txt
5└── service-credentials.txt

Seu AGENTS.md ou TOOLS.md podem referenciar esses caminhos sem expor os valores reais.

Configuração de canal: Onde você conversa com seu agente

O OpenClaw suporta vários canais de mensagens: Discord, Telegram, Signal, WhatsApp e mais. A configuração do canal fica na sua configuração de gateway (gerenciada via comandos clawdbot gateway).

Conceitos chave:

• Cada canal tem seu próprio comportamento de sessão
• Você pode ter vários canais ativos simultaneamente
• Regras específicas de canal (como "não responda a menos que seja @mencionado no Discord") vão no AGENTS.md

O panorama completo

Aqui está como tudo se junta:

1~/clawd/
2├── AGENTS.md           # Instruções operacionais (uso diário)
3├── SOUL.md             # Persona e limites
4├── IDENTITY.md         # Identidade do agente
5├── USER.md             # Seu perfil
6├── HEARTBEAT.md        # Comportamento de check-in agendado
7├── TOOLS.md            # Documentação de ferramentas externas
8├── BOOTSTRAP.md        # Ritual de primeira execução (delete depois)
9│
10├── skills/             # Fluxos de trabalho personalizados
11│   ├── meeting-prep/
12│   ├── podcast-show-notes/
13│   └── social-post-writer/
14│
15├── memory/             # Contexto persistente
16│   ├── 2026-03-22.md
17│   └── key-context.md
18│
19├── .secrets/           # Chaves de API e credenciais (gitignored)
20│   ├── task-api-token.txt
21│   └── anthropic-api-key.txt
22│
23└── output/             # Arquivos gerados e exportações

Uma configuração prática para começar

Se você está começando do zero, aqui está uma progressão que funciona bem.

Passo 1. Execute openclaw onboard e complete a configuração inicial. Escolha seu provedor de modelo e conecte pelo menos um canal.

Passo 2. Crie sua pasta de workspace e adicione AGENTS.md com suas diretrizes principais. Comece com 10-20 linhas cobrindo seus casos de uso principais.

Passo 3. Adicione IDENTITY.md, USER.md e SOUL.md. Eles estabelecem o relacionamento e a personalidade.

Passo 4. Crie sua primeira skill para um fluxo de trabalho que você repete. Preparação de reunião, rascunhos de e-mail ou criação de conteúdo são bons pontos de partida.

Passo 5. Configure memory/ com um modelo de registro diário. Seu agente vai começar a construir contexto com o tempo.

Passo 6. Adicione TOOLS.md conforme você descobrir padrões específicos de ferramentas que valem a pena documentar.

Isso é realmente tudo que você precisa para 95% dos casos de uso. Funcionalidades avançadas como cron jobs, configurações multi-agente e plugins de canal personalizados entram quando você tiver fluxos de trabalho específicos que valem a pena automatizar.

A percepção chave

Seu workspace do OpenClaw é, na verdade, um protocolo para dizer ao seu assistente de IA quem você é, o que precisa ser feito e quais regras ele deve seguir. Quanto mais claramente você definir isso, menos tempo gasta corrigindo seu agente e mais tempo ele gasta fazendo trabalho útil.

O AGENTS.md é seu arquivo de maior alavancagem. Acerta ele primeiro. Todo o resto é otimização.

Comece pequeno, refine conforme avança e trate como qualquer outra peça de infraestrutura no seu fluxo de trabalho: algo que rende dividendos todos os dias depois que está configurado corretamente.

PS: O Openclaw é só o começo.

Dentro da nossa comunidade Build With AI, vou te ensinar a construir agentes, aplicativos e automações personalizados que você pode usar ou vender para clientes. Lançamento em breve.

Entre na lista de espera aqui:

https://return-my-time.kit.com/1bd2720397