Pular para conteúdo
Guia

Anatomia do workspace OpenClaw: todos os arquivos que controlam seu agente

Categoria Guia

Tags
#openclaw #workspace #guia #configuracao #seguranca #skills

Você instalou o OpenClaw, conectou o WhatsApp, funciona. Aí um dia a sessão morre, você quer trocar a persona, e abre ~/.openclaw/workspace/ pela primeira vez. São 8 arquivos .md, 4 pastas, nenhum README.

Outros posts cobrem pedaços: como a memória funciona, como fazer o brain dump inicial, segurança e permissões. Este mapeia tudo junto — o workspace completo, o que cada peça faz, e quando mexer em cada uma. Atualizado para a v2026.3.22.

Arquivo/DirO que fazQuando mexer
AGENTS.mdInstruções operacionais do agenteSetup inicial + toda vez que mudar workflow
SOUL.mdPersona, tom e guardrailsSetup inicial
USER.mdQuem você é (fuso, prefs, contexto)Brain dump inicial, revisão periódica
IDENTITY.mdNome, emoji e vibe do agenteSetup inicial
MEMORY.mdMemória curada de longo prazoPeriodicamente, conforme o agente aprende
BOOT.mdChecklist executado no restart do gatewayQuando mudar rotina de startup
HEARTBEAT.mdConfiguração de polls de monitoramentoQuando configurar monitoramento ativo
skills/Habilidades locais (tier workspace)Quando adicionar automação própria
memory/Diários diários YYYY-MM-DD.mdAutomático — o agente escreve

O mapa completo

A estrutura real do workspace após uma instalação padrão:

~/.openclaw/
├── workspace/                  ← seu território
│   ├── AGENTS.md               ← instruções operacionais (carregado em todo system prompt)
│   ├── SOUL.md                 ← persona e limites do agente
│   ├── USER.md                 ← quem você é
│   ├── IDENTITY.md             ← nome, emoji, vibe do agente
│   ├── MEMORY.md               ← fatos curados de longo prazo
│   ├── BOOT.md                 ← checklist pós-restart
│   ├── HEARTBEAT.md            ← polls de monitoramento
│   ├── skills/                 ← skills locais (prioridade máxima)
│   │   └── minha-skill/
│   │       └── SKILL.md
│   └── memory/                 ← diários automáticos
│       ├── 2026-03-22.md       ← ontem (carregado automaticamente)
│       └── 2026-03-23.md       ← hoje (carregado automaticamente)
│
└── openclaw.json               ← configuração global do agente

O caminho correto é ~/.openclaw/workspace/ — não ~/clawd/. A partir da v2026.3.22, o rebrand do MoltBot para OpenClaw está completo: todas as variáveis de ambiente CLAWDBOT_* e MOLTBOT_* foram descontinuadas. Use OPENCLAW_*.

Se você precisa de um caminho diferente, o openclaw.json aceita override via agent.workspace:

// openclaw.json
{
  agent: {
    workspace: "/caminho/personalizado/workspace"
  }
}

Dois limites para ter em mente: cada arquivo é carregado até bootstrapMaxChars: 20.000 caracteres; o total de todos os arquivos de bootstrap somados não pode ultrapassar bootstrapTotalMaxChars: 150.000. Arquivos mais longos são truncados silenciosamente — escreva com economia.

Para entender o que o OpenClaw é, veja o guia completo de introdução.

Duas camadas de configuração

O workspace é a sua camada. A instalação global do OpenClaw — o binário, as skills nativas, a documentação embutida — é a camada do software.

A distinção importa na prática:

  • Workspace (~/.openclaw/workspace/): você cria, edita, versiona com git se quiser. Suas personalizações vivem aqui.
  • Instalação global (/usr/local/share/openclaw/ ou equivalente): gerenciado pelo openclaw update. Nunca edite diretamente — uma atualização sobrescreve.

A regra de ouro: workspace você customiza, global você atualiza. Skills que você escrever no workspace têm prioridade sobre qualquer skill de mesmo nome na camada gerenciada ou nativa — esse é o mecanismo de override.

AGENTS.md — o arquivo mais importante

O AGENTS.md é incluído no system prompt de toda sessão, toda vez. Se há um arquivo que define como o agente se comporta no dia a dia, é esse.

O que colocar aqui: diretivas operacionais, regras duras, referências a recursos, gatilhos de comportamento. O que não colocar: documentação completa de ferramentas (use links), teoria (va direto ao ponto), informações que mudam com frequência (o arquivo é lido do disco a cada sessão, mas conteúdo instável torna a manutenção pesada).

Limite prático: por volta de 300 linhas, a aderência do modelo ao arquivo começa a cair. Seja seletivo.

Exemplo funcional em pt-BR:

# AGENTS.md

## Diretiva principal
Assistente proativo para o meu negócio. Meu tempo é o recurso mais escasso.

**Mandato:**
- Tirar o máximo do meu prato — não esperar ser perguntado para agir
- Quando identificar algo urgente, avisar no Telegram imediatamente
- Priorizar ações que movem receita antes de qualquer outra coisa

## Ferramentas disponíveis
- **Email:** Checar inbox a cada 2h, marcar urgentes, rascunhar respostas para aprovação
- **Calendário:** Verificar conflitos antes de propor qualquer horário
- **Notion:** Registrar todo trabalho concluído com timestamp

## Regras duras
- NUNCA reiniciar serviços sem permissão explícita por escrito
- NUNCA responder em nome de clientes sem aprovação prévia
- Sempre verificar a data atual com `date` antes de qualquer agendamento
- Se não souber algo com certeza, dizer que não sabe — não inventar

## Gatilhos
- Erro 5xx em produção → avisar Telegram imediatamente, não esperar
- Fatura atrasada detectada → criar tarefa urgente no Notion + aviso

O AGENTS.md é o contrato operacional entre você e o agente. Trate-o com a seriedade de um documento de processo — não é um lugar para experimentos. Para técnicas de escrita de instruções, veja reverse prompting: delegue sem quebrar.

Arquivos de identidade — SOUL.md, USER.md, IDENTITY.md

Esses três são carregados em toda sessão, mas têm propósitos distintos.

SOUL.md define a personalidade do agente, o tom de resposta e os limites éticos que você quer impor. É onde você decide se o agente é formal ou casual, se responde em inglês ou pt-BR, se recusa determinados tipos de tarefas.

# SOUL.md

Tom: direto, sem rodeios, sem introduções longas.
Idioma: sempre pt-BR, exceto quando o usuário escrever em outro idioma.
Formato padrão: bullet points. Parágrafos só quando o contexto pede.

Não fazer:
- Fingir certeza sobre o que não sabe
- Elogiar perguntas ("ótima pergunta!")
- Usar "delve", "tapestry", "crucial", "showcase" ou equivalentes em pt-BR

USER.md é sobre você — fuso horário, ferramentas que usa, preferências de comunicação, contexto profissional. O agente usa isso para personalizar respostas sem você precisar repetir essas informações toda sessão.

# USER.md

Nome: [seu nome]
Fuso: America/Sao_Paulo
Ferramentas: Notion, Slack, Google Workspace, Meta Ads
Papel: Fundador de agência B2B

Horário de foco: 07h–12h (não agendar nada nesse bloco sem avisar)
Dias sem reunião: terça, quinta, sexta

IDENTITY.md define o agente em si — nome, emoji, vibe. Raramente muda depois do setup.

# IDENTITY.md

name: Claw
emoji: 🐾
vibe: assistente executivo sênior — eficiente, sem cerimônia, confiável

A razão de serem arquivos separados é que eles evoluem em ritmos diferentes. IDENTITY.md muda raramente. USER.md muda conforme sua vida muda. SOUL.md muda quando você quer ajustar o comportamento do agente. Arquivos separados = edições cirúrgicas, sem risco de quebrar o que estava funcionando.

Para um exemplo completo de brain dump, veja primeiro dia com OpenClaw.

BOOT.md e HEARTBEAT.md

BOOT.md é uma lista de verificação que o agente executa automaticamente quando o gateway reinicia. Útil para garantir que o ambiente está ok antes de começar a trabalhar.

# BOOT.md — roda no restart do gateway

1. Verificar conexão com provedor: `openclaw models ping`
2. Checar cron jobs ativos: `openclaw cron status`
3. Confirmar que a integração com calendário responde: listar próximos 3 eventos
4. Enviar aviso no Telegram: "Gateway reiniciado — tudo ok"

Para o BOOT.md funcionar, ele precisa estar na raiz do workspace (~/.openclaw/workspace/BOOT.md), não em subpasta. Um arquivo em subpasta é ignorado no bootstrap.

HEARTBEAT.md configura verificações periódicas — polls que o agente roda em intervalos definidos para monitorar a saúde de serviços. É diferente do Cron (que executa prompts com saída): o heartbeat é focado em checar status e disparar alertas.

Veja mais detalhes sobre monitoramento sem custo em heartbeat: monitoramento automático e sobre problemas comuns com agendamentos em cron jobs: problemas e soluções.

Memória — MEMORY.md e memory/

O OpenClaw tem dois mecanismos de memória com propósitos diferentes.

MEMORY.md é a memória curada de longo prazo. Você escreve (ou pede ao agente para escrever) fatos importantes que precisam persistir indefinidamente — decisões estratégicas, contexto de projetos, preferências que você já explicou uma vez e não quer repetir. Esse arquivo é carregado apenas em sessões principais (não em sub-sessões), o que cria uma fronteira de segurança: contexto sensível não vaza para execuções automatizadas.

memory/YYYY-MM-DD.md são os diários diários. O agente escreve automaticamente neles — o arquivo de hoje e o de ontem são carregados automaticamente em toda sessão. Isso dá continuidade entre dias sem você precisar fazer nada.

A v2026.3.22 trouxe melhorias relevantes para quem usa memória com frequência: indexação vetorial dos diários, busca híbrida com BM25 + semântica, re-ranqueamento com diversidade MMR (evita resultados redundantes), e decaimento temporal (memórias mais antigas têm peso menor na busca automática). O agente também faz auto-flush antes de compactar o contexto — salva notas no disco antes de esvaziar a memória de trabalho, evitando perda de dados.

Para buscar memórias programaticamente, use memory_search (busca semântica) ou memory_get (recupera uma entrada específica por data/chave).

Uma regra prática simples: se você quer que algo sobreviva entre sessões, peça ao agente para escrever no disco. O que fica só na conversa, desaparece com a conversa.

Para um aprofundamento, veja por que a IA esqueceu minha conversa e o verbete de memória no glossário.

Skills — 3 tiers e ClawHub

Skills são arquivos SKILL.md que ensinam o agente a executar tarefas específicas. Toda skill carregada ocupa cerca de 97 caracteres no system prompt — irrelevante unitariamente, mas relevante se você instalar dezenas.

Existem três tiers, com ordem de precedência clara:

TierOnde ficaPrioridadeComo instalar
workspace~/.openclaw/workspace/skills/máxima — sobrescreve tudoCriar manualmente
managed~/.openclaw/skills/médiaopenclaw skills install nome
bundledInstalação globalmínimaVem com o OpenClaw

Se uma skill de workspace tiver o mesmo nome de uma skill gerenciada, a do workspace vence. Isso permite customizar ou substituir qualquer comportamento nativo sem modificar a instalação global.

A partir da v2026.3.22, o ClawHub é a fonte padrão para instalação de skills gerenciadas — o registro oficial substituiu o mecanismo anterior.

# Instalar skill do ClawHub
openclaw skills install resumo-diario

# Ver skills ativas com tier e precedência
openclaw skills list --verbose

# Criar skill local no tier workspace (prioridade máxima)
mkdir -p ~/.openclaw/workspace/skills/minha-skill
cat > ~/.openclaw/workspace/skills/minha-skill/SKILL.md << 'EOF'
---
name: minha-skill
description: Faz X quando o usuário pede Y.
bins: []
---

## Processo
1. Identificar o contexto da solicitação
2. Executar as etapas relevantes
3. Reportar resultado com timestamp
EOF

Skills também aceitam gating por metadados: bins (binários necessários no PATH), env (variáveis de ambiente obrigatórias), config (chaves no openclaw.json), e os (sistema operacional). O agente só ativa a skill se todos os requisitos forem atendidos.

Veja exemplos práticos em 5 automações que economizam 2h/dia e o verbete de skill no glossário.

Canais e segurança

O OpenClaw suporta 30+ canais de mensagem: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, Nostr, entre outros. Cada canal tem uma política de DM configurável:

  • pairing (padrão): só aceita comandos de números/contas pareadas explicitamente
  • allowlist: aceita apenas identificadores numa lista branca
  • open: aceita comandos de qualquer origem — nunca use em canais públicos
  • disabled: canal conectado para envio, mas não processa comandos recebidos

Para sessões isoladas por contexto, dmScope: "per-channel-peer" garante que a conversa com a pessoa A no WhatsApp não vaza para a conversa com a pessoa B no Telegram.

O modelo de permissões tem quatro perfis de ferramentas, em escala de acesso:

  • minimal: só leitura, sem ações destrutivas
  • messaging: envio de mensagens, sem acesso a sistema de arquivos
  • coding: acesso a terminal e arquivos, sem chamadas de rede externas
  • full: acesso completo (requer aprovação humana para ops destrutivas)

Operações destrutivas — apagar arquivos, reiniciar serviços, executar scripts com efeitos colaterais — passam pelo mecanismo de exec approvals: o agente para, descreve a ação, e espera confirmação explícita.

O sandbox de execução usa Docker com --cap-drop ALL por padrão. A v2026.3.22 adicionou dois novos backends: OpenShell (para ambientes sem Docker) e SSH (para execução remota em VPS).

Para aprofundar, veja segurança: 5 regras para não vazar suas chaves.

O que mudou na v2026.3.22

Timeout de sessão: o padrão agora é 48 horas de inatividade antes da sessão expirar. Era 10 minutos. Se sua sessão ainda expira rápido, verifique o openclaw.json:

// openclaw.json
{
  session: {
    idleMinutes: 2880  // 48h — padrão v2026.3.22 (era 10 min)
  },
  sandbox: {
    backend: "docker"  // ou "openshell", "ssh" (novos backends)
  }
}

ClawHub-first: o ClawHub virou a fonte padrão para plugins e skills gerenciadas. openclaw skills install agora aponta para o registro oficial por padrão.

Rebrand completo: variáveis de ambiente CLAWDBOT_* e MOLTBOT_* foram descontinuadas. Se você migrou de uma instalação antiga, renomeie para OPENCLAW_*. O comando openclaw doctor detecta variáveis desatualizadas.

Para configurar provedores de IA e OAuth, veja configurar OpenAI, Claude e OAuth. Para roteamento entre modelos, veja multi-model routing com OpenRouter.

Troubleshooting

“Atualizei e meus paths sumiram”

A migração de ~/clawd/ para ~/.openclaw/workspace/ não é automática. Mova os arquivos manualmente:

mv ~/clawd/* ~/.openclaw/workspace/

Ou rode openclaw doctor --fix para que o agente detecte e corrija a estrutura automaticamente.

“Skill instalada não aparece”

Verifique a precedência: openclaw skills list --verbose. Se uma skill de workspace tiver o mesmo nome, ela sobrescreve. Também confirme que os bins e env necessários estão presentes — skill com requisito não atendido é simplesmente ignorada na ativação.

“Sessão expira rápido demais”

Desde a v2026.3.22 o padrão é idleMinutes: 2880 (48h). Se a sua ainda expira antes, provavelmente há um valor explícito mais baixo no openclaw.json. Procure pela chave session.idleMinutes e atualize.

“BOOT.md não executa no restart”

O arquivo precisa estar exatamente em ~/.openclaw/workspace/BOOT.md. Subpastas não são verificadas no bootstrap. Confirme o caminho e reinicie o gateway.

Próximo passo

Esc