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 onde cada coisa fica, 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.

Na nossa comunidade Build With AI, vamos te ensinar a construir agentes, apps e automações personalizados para 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 guarda 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 integradas 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ê disser para 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 principais 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 API, locais 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 consomem muito contexto 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, marcar itens urgentes
12- **Agenda:** Verificar se não há conflitos antes de agendar
13- **Gerenciador de Tarefas:** Sincronizar trabalhos concluídos 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

Isso tem cerca de 20 linhas de diretrizes principais. Dá ao seu agente tudo que ele precisa para trabalhar produtivamente 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 a relação 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, solucionador de problemas persistente
6- Emoji: [Seu emoji escolhido]

USER.md define você:

1# USER.md - Perfil do Usuário
2
3- Nome: [Seu nome]
4- Tratamento preferido: [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 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 todas as etapas necessárias
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

Os heartbeats são poderosos para criar agentes proativos. Seu agente pode verificar sua agenda, escanear 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 guarda 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 raspagem web (quando sites bloqueiam requisições normais)
13- Local: ~/clawd/.venv/scraper
14- Use modo furtivo para sites protegidos

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

A pasta skills/: Fluxos de trabalho reutilizáveis

As skills são onde o OpenClaw fica poderoso. Cada skill é um fluxo de trabalho autocontido que seu agente pode invocar quando a tarefa corresponde à descrição da skill.

Cada skill vive em seu próprio subdiretório 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 reuniões.
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 CHAMADAS
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 principal 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 presente
• 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, cada 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 pode referenciar esses caminhos sem expor os valores reais.

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

O OpenClaw suporta múltiplos canais de mensagens: Discord, Telegram, Signal, WhatsApp e mais. A configuração do canal fica na configuração do seu gateway (gerenciada via comandos do gateway clawdbot).

Conceitos principais:

• Cada canal tem seu próprio comportamento de sessão
• Você pode ter múltiplos 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 quadro 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 (apague 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 (gitignorado)
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 principais casos de uso.

Passo 3. Adicione IDENTITY.md, USER.md e SOUL.md. Eles estabelecem a relação 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 começará a construir contexto com o tempo.

Passo 6. Adicione TOOLS.md conforme 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ê tem fluxos de trabalho específicos que valem a pena automatizar.

A percepção principal

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. Acertar 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 de configurado corretamente.

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

Na nossa comunidade Build With AI, vou te ensinar a construir agentes, apps e automações personalizados para usar ou vender para clientes. Lançamento em breve.

Entre na lista de espera aqui:

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