Montando um assistente pessoal com o OpenClaw

O OpenClaw é um gateway de WhatsApp + Telegram + Discord + iMessage para agentes Pi. Plugins adicionam suporte ao Mattermost. Este guia cobre o setup de “assistente pessoal”: um número de WhatsApp dedicado que funciona como seu agente sempre disponível.

⚠️ Segurança em primeiro lugar

Você está colocando um agente numa posição de:

  • executar comandos na sua máquina (dependendo da configuração de ferramentas Pi)
  • ler/escrever arquivos no seu workspace
  • enviar mensagens via WhatsApp/Telegram/Discord/Mattermost (plugin)

Comece de forma conservadora:

  • Sempre configure channels.whatsapp.allowFrom (nunca rode aberto para o mundo no seu Mac pessoal).
  • Use um número de WhatsApp dedicado para o assistente.
  • Heartbeats agora vêm configurados para cada 30 minutos. Desabilite até confiar no setup definindo agents.defaults.heartbeat.every: "0m".

Pré-requisitos

  • OpenClaw instalado e com onboarding concluído — veja Primeiros Passos se ainda não fez isso
  • Um segundo número de telefone (SIM/eSIM/pré-pago) para o assistente

O setup de dois telefones (recomendado)

O que você quer é isso:

flowchart TB
    A["<b>Seu Telefone (pessoal)<br></b><br>Seu WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Segundo Telefone (assistente)<br></b><br>WA do Assistente<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Seu Mac (openclaw)<br></b><br>Agente Pi"]

Se você vincular seu WhatsApp pessoal ao OpenClaw, toda mensagem que você receber vira “input do agente”. Isso raramente é o que você quer.

Quick start em 5 minutos

  1. Pareie o WhatsApp Web (mostra QR; escaneie com o telefone do assistente):
openclaw channels login
  1. Inicie o Gateway (deixe rodando):
openclaw gateway --port 18789
  1. Coloque uma configuração mínima em ~/.openclaw/openclaw.json:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Agora mande uma mensagem para o número do assistente a partir do telefone na allowlist.

Quando o onboarding terminar, o dashboard abre automaticamente e exibe um link limpo (sem token). Se pedir autenticação, cole o token de gateway.auth.token nas configurações da Control UI. Para reabrir depois: openclaw dashboard.

Dê um workspace ao agente (AGENTS)

O OpenClaw lê instruções operacionais e “memória” do diretório de workspace.

Por padrão, o OpenClaw usa ~/.openclaw/workspace como workspace do agente e o cria automaticamente (junto com AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) no setup/primeira execução. O BOOTSTRAP.md só é criado quando o workspace é novinho (não deve reaparecer depois de deletado). O MEMORY.md é opcional (não é criado automaticamente); quando presente, é carregado em sessões normais. Sessões de sub-agente injetam apenas AGENTS.md e TOOLS.md.

Dica: trate essa pasta como a “memória” do OpenClaw e transforme-a num repositório git (de preferência privado) para ter backup dos seus AGENTS.md e arquivos de memória. Se o git estiver instalado, workspaces novos são inicializados automaticamente.

openclaw setup

Layout completo do workspace e guia de backup: Workspace do agente Workflow de memória: Memória

Opcional: escolha um workspace diferente com agents.defaults.workspace (suporta ~).

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Se você já distribui seus próprios arquivos de workspace a partir de um repositório, pode desabilitar a criação dos arquivos de bootstrap completamente:

{
  agent: {
    skipBootstrap: true,
  },
}

A configuração que transforma num “assistente”

O OpenClaw já vem com padrões bons para um assistente, mas normalmente você vai querer ajustar:

  • persona/instruções no SOUL.md
  • padrões de thinking (se desejar)
  • heartbeats (quando você confiar no setup)

Exemplo:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Comece com 0; habilite depois.
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

Sessões e memória

  • Arquivos de sessão: ~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Metadados de sessão (uso de tokens, última rota, etc): ~/.openclaw/agents/<agentId>/sessions/sessions.json (legado: ~/.openclaw/sessions/sessions.json)
  • /new ou /reset inicia uma sessão nova para aquele chat (configurável via resetTriggers). Se enviado sozinho, o agente responde com um breve hello para confirmar o reset.
  • /compact [instructions] compacta o contexto da sessão e informa o orçamento restante de contexto.

Heartbeats (modo proativo)

Por padrão, o OpenClaw roda um heartbeat a cada 30 minutos com o prompt: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. Defina agents.defaults.heartbeat.every: "0m" para desabilitar.

  • Se o HEARTBEAT.md existir mas estiver efetivamente vazio (apenas linhas em branco e cabeçalhos markdown como # Heading), o OpenClaw pula a execução do heartbeat para economizar chamadas de API.
  • Se o arquivo não existir, o heartbeat roda normalmente e o modelo decide o que fazer.
  • Se o agente responder com HEARTBEAT_OK (opcionalmente com preenchimento curto; veja agents.defaults.heartbeat.ackMaxChars), o OpenClaw suprime a entrega de saída daquele heartbeat.
  • Por padrão, a entrega de heartbeat para alvos DM user:<id> é permitida. Defina agents.defaults.heartbeat.directPolicy: "block" para suprimir a entrega direta mantendo as execuções de heartbeat ativas.
  • Heartbeats executam turnos completos do agente — intervalos menores consomem mais tokens.
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

Mídia de entrada e saída

Anexos de entrada (imagens/áudio/documentos) podem ser expostos ao seu comando via templates:

  • {{MediaPath}} (caminho do arquivo temporário local)
  • {{MediaUrl}} (pseudo-URL)
  • {{Transcript}} (se a transcrição de áudio estiver habilitada)

Anexos de saída do agente: inclua MEDIA:<caminho-ou-url> numa linha própria (sem espaços). Exemplo:

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

O OpenClaw extrai esses marcadores e os envia como mídia junto com o texto.

Checklist de operações

openclaw status          # status local (credenciais, sessões, eventos na fila)
openclaw status --all    # diagnóstico completo (somente leitura, pode colar em qualquer lugar)
openclaw status --deep   # adiciona probes de health do gateway (Telegram + Discord)
openclaw health --json   # snapshot de health do gateway (WS)

Logs ficam em /tmp/openclaw/ (padrão: openclaw-YYYY-MM-DD.log).

Próximos passos

arrow_back
Anterior
Onboarding
Próximo
Wizard CLI Reference
arrow_forward