Curso OpenClaw Docker

O OpenClaw nasceu em novembro de 2025 como "Clawdbot", renomeado para "Moltbot" e depois para "OpenClaw" em apenas 3 dias. É o repositório mais estrelado da história do GitHub, com 365.000 estrelas em abril de 2026.

Entender a origem ajuda a compreender as escolhas de design e por que a comunidade cresceu tão rápido — são decisões que afetam como você vai usar o projeto.

Clawdbot → Moltbot → OpenClaw. Criado por Peter Steinberger. Open source. Tema de lagosta (claw = garra). Comunidade no Discord "Friends of the Crustacean".

Self-hosted significa que o OpenClaw roda na sua própria máquina ou servidor, sem depender de nuvem de terceiros. Você controla tudo: dados, modelos, configurações.

Com self-hosted, seus arquivos, conversas e memórias nunca saem da sua máquina. Você pode usar modelos gratuitos, não tem limite de uso e pode personalizar completamente.

Privacidade total. Sem mensalidade SaaS. Sem limites de uso impostos por terceiros. Você escolhe o modelo. Dados ficam nos seus volumes Docker.

O Gateway é o processo central do OpenClaw — um servidor WebSocket na porta 18789 que recebe mensagens dos canais, gerencia sessões, executa ferramentas e devolve respostas.

Toda interação passa pelo gateway. Quando algo não funciona, é aqui que você vai procurar nos logs. Entender o gateway é entender o OpenClaw.

Porta 18789. Comando openclaw gateway. Bind em 0.0.0.0 dentro do Docker (mas exposto só em 127.0.0.1 no host). WebSocket + HTTP.

OpenClaw não é um modelo de IA — é um orquestrador local que usa qualquer modelo como "cérebro" e adiciona corpo (ferramentas, memória, canais, agendamento). ChatGPT e Claude são interfaces SaaS na nuvem.

Essa distinção muda tudo: você pode usar o Claude via OpenClaw sem pagar assinatura Claude.ai, e ainda ter o agente no WhatsApp, com memória persistente e execução autônoma.

OpenClaw = orquestrador. Claude/GPT/Gemini = cérebro alugado via API. Você paga só pela API do modelo, não pelo SaaS. Autonomia via Heartbeat. 15+ canais de mensagem.

Para rodar o docker-openclaw você precisa de: Docker Engine 24+ ou Docker Desktop, 2GB RAM mínimo (4GB recomendado), 5GB de espaço em disco, e acesso à internet para APIs.

Checar requisitos antes de começar evita frustrações. Um computador velho com 2GB RAM funciona para uso básico via OpenRouter — você não precisa de GPU potente.

Windows 10+ / macOS 13+ / Ubuntu 22.04+. Docker obrigatório. GPU opcional (só para modelos locais via Ollama). API key do OpenRouter (gratuita para começar).

O ecossistema inclui: GitHub (github.com/openclaw/openclaw), docs oficiais (docs.openclaw.ai), Discord com 169k membros (discord.gg/clawd) e ClawHub com 13.700+ skills públicas.

A comunidade é o maior recurso. Problemas são resolvidos em minutos no Discord. O ClawHub tem skills prontas para quase tudo que você imaginar.

docs.openclaw.ai = documentação oficial. discord.gg/clawd = suporte da comunidade. github.com/openclaw/clawhub = marketplace de skills. Issues no GitHub para bugs.

O OpenClaw tem 4 pilares: (1) Gateway — o servidor central, (2) Canais — como você se comunica (Telegram, WhatsApp...), (3) Workspace — os arquivos que definem o agente, (4) Skills — extensões de capacidade.

Conhecer os pilares ajuda a diagnosticar problemas: se o Telegram não funciona, é problema de Canal. Se o agente responde errado, é problema de Workspace.

Gateway = processo central. Canal = interface de mensagem. Workspace = pasta de arquivos .md. Skills = extensões de capacidade. Todos se integram via openclaw.json.

O Gateway escuta na porta 18789, aceita conexões WebSocket de canais, roteia mensagens para os agentes corretos, executa ferramentas (busca web, shell, arquivos) e retorna respostas.

Você acessa o webchat via porta 18789. Os logs do gateway mostram tudo que acontece. Saber isso ajuda a configurar túneis SSH, firewalls e portas corretamente.

Porta padrão 18789. Bind "lan" dentro do Docker. Host expõe só em 127.0.0.1. Autenticação via token. Webchat em /chat. API em /api.

Canais são as interfaces de mensagem: Telegram, WhatsApp, Discord, Slack, Signal, iMessage, Teams, Matrix, Webchat e mais de 15 opções. Cada canal tem sua própria configuração no openclaw.json.

Você pode usar o agente pelo app que já usa no dia a dia. Configure Telegram para acesso rápido, Discord para um servidor compartilhado, Webchat para uso via browser.

Cada canal requer credenciais específicas (bot token, QR code, OAuth). Todos passam pelo gateway central. Pairing controla quem pode usar cada canal.

O workspace é uma pasta de arquivos Markdown que define quem é seu agente. Inclui SOUL.md (personalidade), AGENTS.md (regras), MEMORY.md (memória), skills/ (extensões) e muito mais.

É editando o workspace que você personaliza completamente seu agente. Quer um assistente formal? Edite o SOUL.md. Quer que ele evite certos comandos? Edite o AGENTS.md.

Workspace = pasta de arquivos .md. Volume Docker openclaw-workspace. Arquivos em linguagem natural (não código). Pode ser versionado com Git.

Skills são extensões de capacidade empacotadas como pasta com SKILL.md. O ClawHub tem 13.700+ skills prontas: review de PR, monitoring de email, newsletter automática, integrações com APIs externas.

Com skills você não precisa programar nada. Instala uma skill de geração de newsletter e seu agente passa a redigir relatórios semanais automaticamente, sem nenhuma linha de código.

Skills = pasta + SKILL.md. Hierarquia: workspace > project > personal > managed > bundled. ClawHub = marketplace. Skills em linguagem natural no corpo do arquivo.

Você manda mensagem no Telegram → canal recebe e envia ao gateway → gateway carrega SOUL.md + AGENTS.md + memória → monta o prompt → envia ao modelo via OpenRouter → recebe resposta → devolve no Telegram.

Visualizar o fluxo completo explica por que certas coisas levam mais tempo (context window grande), por que o agente "lembra" coisas (memória carregada no prompt) e onde debugar erros.

Canal → Gateway → Workspace → Modelo → Resposta. Cada passo pode ser monitorado nos logs. Tokens são consumidos a cada round-trip com o modelo.

OpenRouter é um agregador de APIs de modelos de IA. Ele expõe uma API compatível com OpenAI e roteia suas requisições para o provedor correto — seja Anthropic, Google, Meta ou qualquer outro.

Sem o OpenRouter você precisaria de uma conta e API key em cada provedor separadamente. Com ele, uma conta = acesso a todos, incluindo modelos gratuitos.

openrouter.ai. API compatível com OpenAI. 200+ modelos. Billing unificado. Modelos gratuitos disponíveis. Endpoint: https://openrouter.ai/api/v1.

Acesse openrouter.ai → faça login com Google ou GitHub → vá em "Keys" → crie uma nova API key → copie (começa com sk-or-v1-...). Você pode adicionar créditos ou usar modelos gratuitos sem gastar nada.

A API key é o requisito principal para qualquer uso do OpenClaw via OpenRouter. Sem ela, o agente não consegue chamar nenhum modelo de IA.

Formato: sk-or-v1-... Cole no .env como OPENROUTER_API_KEY. Nunca commite no git. Pode criar múltiplas keys com limites diferentes. Conta gratuita dá acesso aos modelos :free.

Modelos com sufixo :free no OpenRouter são totalmente gratuitos. Os melhores testados: Qwen3 Coder 480B (⭐ melhor para código), Llama 3.3 70B (ótimo geral), DeepSeek R1 (raciocínio).

Para aprender e testar, modelos gratuitos são mais que suficientes. O Qwen3 Coder 480B tem 480 bilhões de parâmetros e é gratuito — melhor que muitos modelos pagos.

qwen/qwen3-coder:free — melhor gratuito. meta-llama/llama-3.3-70b-instruct:free — bom geral. Limite: ~20 req/min. Logs podem ser armazenados pelo provider. Use para testes.

Para uso intenso ou qualidade máxima: Claude Sonnet 4 ($3/M input, $15/M output), GPT-4o (~$5/M), Gemini 2.0 Flash (muito barato). Você paga só pelo que usa — sem mensalidade.

O modelo pago vai responder melhor, mais rápido e em português perfeito. Para uso diário, o custo é muito menor do que uma assinatura SaaS equivalente.

anthropic/claude-sonnet-4 — melhor qualidade testada. openai/gpt-4o — excelente para código. Preços em openrouter.ai/models. Pay-per-token, não por assinatura.

O formato correto é sempre openrouter/provider/modelo. Exemplo: openrouter/anthropic/claude-sonnet-4. Sem o prefixo "openrouter/" o modelo não é reconhecido.

O erro mais comum de configuração é esquecer o prefixo openrouter/. O container vai subir, mas o agente responderá "Unknown model" em cada mensagem.

✅ openrouter/anthropic/claude-sonnet-4. ❌ anthropic/claude-sonnet-4. ❌ claude-sonnet-4. Define no DEFAULT_MODEL no .env. Pode mudar a qualquer momento.

Para começar grátis: qwen/qwen3-coder:free. Para qualidade máxima em português: openrouter/anthropic/claude-sonnet-4. Para código: qwen3-coder. Para raciocínio: deepseek-r1 (atenção às tags <think>).

Cada modelo tem pontos fortes diferentes. Escolher o certo para seu caso de uso melhora muito a experiência e pode reduzir custo.

Português bom: claude-sonnet-4, llama-3.3-70b. Gratuito: qwen3-coder:free, llama-3.3-70b:free. Código: qwen3-coder. Evitar: deepseek-r1 (incompatível com tags think no OpenClaw).

Pairing é o sistema de segurança para canais de mensagem. Quando alguém desconhecido fala com seu bot, ele retorna um código de emparelhamento. Só após aprovação explícita o usuário pode usar o agente.

Sem pairing, qualquer pessoa que souber o número do seu bot no WhatsApp poderia executar comandos, acessar seus arquivos e consumir sua cota de API.

Código expira em 1h. Aprovação: openclaw pairing approve telegram <code>. dmPolicy controla comportamento. Tokens rotacionam a cada novo pairing.

Cada conversa é uma sessão. O histórico da sessão é mantido em memória e usado como contexto para as próximas respostas do agente. Sessões podem ser resetadas com /new ou /reset.

Quando o agente "esquece" algo que você disse 10 mensagens atrás, provavelmente o contexto ficou grande demais e foi comprimido. Use /compact para comprimir sem perder contexto importante.

/new ou /reset = nova sessão. /compact = comprime contexto. /status = vê tokens usados. Sessões persistem no volume openclaw-data entre reinícios do container.

SOUL.md define quem é o agente — personalidade, valores, tom, especialidades. AGENTS.md define como ele age — regras operacionais, quais ferramentas usar, como gerenciar memória. "Personalidade no SOUL, procedimentos no AGENTS."

Sem SOUL.md o agente é "sem graça" — responde de forma genérica. Com um bom SOUL.md você tem um assistente com identidade consistente que parece feito especificamente para você.

Ambos em linguagem natural (português funciona). Carregados a cada sessão. SOUL.md = quem. AGENTS.md = como. Ficam no volume openclaw-workspace.

Três volumes Docker guardam seus dados: openclaw-data (config, sessões, tokens de auth), openclaw-workspace (SOUL.md, AGENTS.md, skills, memória) e openclaw-logs (logs persistentes).

Volumes persistem entre reinícios do container. Se você rodar docker compose down -v TUDO é apagado — incluindo sessões, tokens de pairing e workspace. Faça backup antes!

down = para e remove container (dados preservados). down -v = apaga tudo ⚠️. restart = reinicia sem perder dados. backup = docker run com volume montado.

Dentro das conversas você pode usar: /status (modelo, tokens, custo), /new ou /reset (nova sessão), /compact (comprimir contexto), /think <level> (off/low/medium/high), /verbose on|off, /usage.

Esses comandos dão controle total sobre o comportamento do agente sem precisar reiniciar o container ou editar arquivos de configuração.

/status — diagnóstico rápido. /new — nova conversa. /compact — economiza tokens. /think high — raciocínio avançado (mais lento). /restart — reinicia gateway (owner only).

O openclaw.json em ~/.openclaw/ é o arquivo central de configuração. Neste setup Docker, ele é gerado automaticamente pelo entrypoint.sh a partir das variáveis de ambiente do .env — você raramente precisa editar manualmente.

Configurações avançadas (múltiplos modelos, ajustes de gateway, opções de segurança) exigem editar este arquivo diretamente. Saber que ele existe e onde fica é fundamental.

Gerado pelo entrypoint.sh. Permissão 600 (protegido). Não commitar no git. Para editar: entre no container com bash. openclaw doctor valida o arquivo.

Docker é uma ferramenta que empacota um programa com tudo que ele precisa (sistema, dependências, configurações) em um "container". É como uma caixa isolada — o programa dentro não interfere no seu sistema.

Com Docker você não precisa instalar Node.js, Python, FFmpeg ou qualquer dependência do OpenClaw. Um único comando sobe tudo. E para remover, basta apagar o container.

Container = ambiente isolado. Image = molde do container. docker compose = orquestrador de múltiplos containers. Volume = pasta persistente fora do container.

No Windows instale o Docker Desktop (docker.com/products/docker-desktop). Ele inclui o WSL2 automaticamente. Após instalar, abra o Docker Desktop, espere o ícone 🐳 aparecer na bandeja e confirme com docker --version no CMD.

WSL2 é obrigatório — sem ele o Docker Desktop não funciona no Windows. O instalador cuida disso, mas você precisa reiniciar o PC e ativar a virtualização na BIOS se necessário.

Docker Desktop = interface gráfica + engine. WSL2 = subsistema Linux no Windows (obrigatório). Erro "pipe/dockerDesktopLinuxEngine" = Docker Desktop não está aberto. Mínimo 4GB RAM recomendado.

No Ubuntu/Debian: curl -fsSL https://get.docker.com | sh. Depois habilite o serviço, adicione seu usuário ao grupo docker e faça logout/login. Verify: docker ps sem sudo.

No Linux o Docker roda nativamente sem WSL2 — é mais rápido e eficiente que no Windows. É a plataforma ideal para rodar o OpenClaw 24/7 em um servidor.

Script oficial instala tudo automaticamente. sudo usermod -aG docker $USER = usar sem sudo. systemctl enable docker = inicia no boot. docker compose (sem hífen) no Docker moderno.

No Mac baixe o Docker Desktop em docker.com e escolha a versão correta para seu chip (Intel ou Apple Silicon/M1/M2/M3). Arraste para Applications, abra e aguarde inicializar.

Macs com Apple Silicon (M1/M2/M3) precisam da versão ARM do Docker Desktop. Instalar a versão errada pode causar erros de arquitetura nos containers.

Apple Silicon = ARM64. Intel = AMD64. Docker Desktop detecta automaticamente na nova versão. Verificar chip: menu Apple → Sobre este Mac. docker --version deve funcionar no Terminal.

Execute: docker --version (deve mostrar versão 24+), docker compose version (versão 2+), e docker ps (lista vazia sem erro). Se tudo funcionar, está pronto.

Verificar antes de clonar o projeto evita descobrir problemas só no meio da configuração. Dois minutos de teste agora economizam horas de debug depois.

docker --version mínimo 24. docker compose version mínimo 2. docker ps sem sudo = grupo docker configurado. docker run hello-world = teste completo do engine.

Problemas frequentes: "permission denied" no Linux (solução: adicionar ao grupo docker + logout/login), "cannot connect to Docker daemon" (solução: abrir Docker Desktop no Windows/Mac), "WSL Stopped" (solução: abrir Docker Desktop).

Esses erros aparecem frequentemente em primeiras instalações. Conhecer as soluções antes de encontrá-los reduz muito a frustração inicial.

permission denied → sudo usermod -aG docker $USER + logout. WSL Stopped → abrir Docker Desktop. Build lento → aumentar RAM em Settings → Resources. CRLF → git config core.autocrlf input.

Execute git clone https://github.com/inematds/docker-openclaw.git e depois cd docker-openclaw. No Windows, use Git Bash, CMD ou PowerShell — todos funcionam.

O clone traz o Dockerfile, docker-compose.yml, entrypoint.sh e o .env.example que são a base de tudo. Sem eles você não tem como subir o container.

git clone = copia o repositório. cd = entra na pasta. ls (Linux/Mac) ou dir (Windows) = vê os arquivos. Precisa ter Git instalado. No Windows: git-scm.com.

Copie o .env.example para .env (cp .env.example .env no Linux/Mac ou copy .env.example .env no Windows). Abra com qualquer editor e substitua os placeholders pelas suas chaves reais.

O .env é a forma segura de passar secrets para o container sem escrever chaves no código. O .gitignore já exclui o .env do git — suas chaves nunca vão para o GitHub.

NUNCA commitar o .env. Variáveis no formato CHAVE=valor. Sem espaços ao redor do =. Linhas com # são comentários. O container lê as variáveis na inicialização.

O GATEWAY_AUTH_TOKEN protege o acesso à API e ao webchat. Gere com openssl rand -hex 24 (Linux/Mac) ou use qualquer senha longa (24+ caracteres). Cole no .env.

Sem um token forte, qualquer pessoa na sua rede local que descobrir a porta 18789 pode acessar seu agente. O token é a primeira linha de defesa do gateway.

Mínimo 24 caracteres aleatórios. openssl rand -hex 24 gera 48 chars hex. Use no webchat: http://localhost:18789/?token=SEU_TOKEN. Guarde em um gerenciador de senhas.

Crie a key em openrouter.ai/keys. Começa com sk-or-v1-. Cole no .env como OPENROUTER_API_KEY=sk-or-v1-sua-key-aqui. Sem essa key o agente não consegue chamar nenhum modelo de IA.

Esta é a variável mais importante. Sem ela o container sobe, mas o agente vai responder erro em cada mensagem. Confirme que a key está correta antes de subir.

sk-or-v1-... Não tem espaços. Não usar aspas no .env. Pode criar múltiplas keys para isolamento. openrouter.ai/activity para ver o uso. Keys podem ter limites configuráveis.

Define qual modelo será usado por padrão. Exemplo: DEFAULT_MODEL=openrouter/qwen/qwen3-coder:free (grátis) ou openrouter/anthropic/claude-sonnet-4 (pago). SEMPRE inclua o prefixo openrouter/.

O erro mais comum é esquecer o prefixo openrouter/. O container sobe normalmente, mas cada mensagem retorna "Unknown model". Confirme o formato antes de iniciar.

Formato: openrouter/provider/modelo. Para mudar: edite .env e execute docker compose down && docker compose up -d. Restart simples não recarrega variáveis de ambiente.

Além das variáveis obrigatórias, você pode adicionar: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN + SLACK_APP_TOKEN, BRAVE_API_KEY (busca web). Todos são opcionais — adicione só os que for usar.

Configure os canais que você usa. Começar só com o webchat é válido — adicione Telegram quando quiser acessar de qualquer lugar. Cada canal adicionado expande o alcance do agente.

Variáveis sem valor são ignoradas automaticamente. Adicionar nova variável requer docker compose down && up (não só restart). LOG_LEVEL=info é útil para debug. GATEWAY_PORT=18789 é o padrão.

docker compose up -d constrói a imagem (na primeira vez demora ~5 minutos baixando Node.js, FFmpeg, etc.) e sobe o container em background. Nas próximas vezes inicia em segundos.

O -d (detached) roda o container em segundo plano — você continua usando o terminal normalmente. Sem o -d o container fica preso no terminal e para quando você fechar.

up -d = sobe em background. Primeira vez = download e build (5-10min). Próximas vezes = segundos. --no-cache = força rebuild completo. up --build = rebuild + up.

Execute docker compose logs -f para ver os logs em tempo real. Você deve ver: "🦞 First run — creating config", "🔑 Setting gateway auth token", "🦞 Starting OpenClaw". Se aparecer erro, há algo errado no .env.

Os logs são o principal recurso de diagnóstico. Se o agente não responde, os logs mostram exatamente o que está errado — modelo inválido, token incorreto, canal não configurado.

logs -f = acompanha em tempo real (Ctrl+C para parar). logs --tail 50 = últimas 50 linhas. logs openclaw = só do container openclaw. Erro em vermelho = algo para corrigir.

O entrypoint.sh roda antes do OpenClaw iniciar. Ele: cria a pasta de config se não existir, gera o openclaw.json a partir do template, injeta as variáveis de ambiente nas configs JSON, e executa openclaw gateway.

Entender o entrypoint explica por que "mudar o .env e só reiniciar" não funciona — o entrypoint só regenera config na primeira vez ou quando o volume é apagado.

Roda uma vez por inicialização do container. Gera config apenas se não existir. Para forçar regeneração: docker compose down -v (apaga tudo) + up. Deteta provider automaticamente.

Execute docker exec openclaw openclaw doctor para checar automaticamente: permissões do arquivo de config, bind do gateway, política de DM, token configurado e outros itens de segurança.

O doctor é o primeiro comando a rodar quando algo não funciona. Ele identifica problemas de configuração em segundos, sem precisar ler logs manualmente.

docker exec openclaw openclaw doctor. Checa config permissions, gateway bind, dmPolicy, logging. Retorna lista de ✅ e ❌. Corrija os ❌ antes de continuar.

restart = reinicia o container sem rebuild (preserva volumes, não recarrega .env). down + up = para e sobe novamente (recarrega .env e variáveis). build --no-cache + up = rebuild completo (puxa nova versão do OpenClaw).

Usar restart quando mudou o .env não funciona — as variáveis não são relidas. É preciso fazer down && up. Isso confunde muito iniciantes que mudam a API key e acham que o restart aplicou.

restart = rápido, não relê .env. down + up = relê .env. build --no-cache = nova imagem. down -v = apaga dados ⚠️. Regra geral: mudou .env → down + up.

stop = para o container sem remover (pode subir com start). down = para e remove o container (precisa de up para voltar). down -v = remove container E volumes (apaga todos os dados). stop não perde dados.

Muita gente usa down quando queria stop, e vice-versa. A diferença entre stop e down é pequena, mas down -v é devastador — apaga sessões, pairing tokens, workspace.

stop = para (seguro). down = para + remove container (seguro, dados preservados nos volumes). down -v = apaga tudo ⚠️. Para recuperar: só um novo up (mas dados perdidos ficam perdidos).

Abra o browser e acesse http://localhost:18789/chat. Se o container está rodando, você verá a interface do webchat pedindo seu token de autenticação. É a forma mais direta de conversar com o agente.

O webchat funciona sem configurar nenhum canal externo (Telegram, WhatsApp, etc.). É o ponto de partida ideal para testar se tudo está funcionando antes de configurar outros canais.

localhost = só acessível na sua máquina. Porta 18789. /chat = interface. /api = endpoints REST. Se aparecer "connection refused" o container não está rodando. Só funciona com container ativo.

O webchat pede o GATEWAY_AUTH_TOKEN que você definiu no .env. Digite o token quando solicitado, ou acesse direto com: http://localhost:18789/chat?token=SEU_TOKEN para pular a tela de login.

Sem autenticação, o webchat não funciona — qualquer pessoa na sua rede poderia usar seu agente. O token garante que só você (ou quem você autorizar) tem acesso.

Token no .env = GATEWAY_AUTH_TOKEN. URL com token: ?token=SEU_TOKEN. Sessão fica salva no browser. Para sair: limpar cookies ou abrir aba anônima. Token não tem prazo de expiração.

Comece com mensagens simples: "Olá! Você está funcionando?" para verificar resposta. "Qual modelo você está usando?" para confirmar o modelo. "/status" para ver informações técnicas da sessão.

A primeira mensagem confirma que a cadeia completa funciona: container → gateway → OpenRouter → modelo → resposta. Se não responder, é hora de checar os logs.

Resposta lenta = modelo ocupado ou contexto grande. Sem resposta = checar logs. Resposta em inglês = modelo com suporte a português fraco (trocar modelo). /status = diagnóstico rápido.

O comando /status mostra: modelo em uso, tokens consumidos na sessão, custo estimado, tempo de resposta e outras métricas. É seu painel de controle para entender o consumo.

Monitorar tokens evita surpresas na fatura. Com modelos gratuitos o custo é zero, mas context windows grandes podem deixar o agente mais lento — /compact resolve isso.

Tokens = unidades de texto processadas. 1000 tokens ≈ 750 palavras. Custo depende do modelo. Context window = limite de tokens que o modelo "lembra". /compact comprime quando fica grande.

/new ou /reset = começa uma nova conversa apagando o histórico. /compact = comprime o contexto mantendo os pontos importantes. /verbose on|off = ativa/desativa detalhes extras nas respostas.

Use /new quando quiser mudar completamente de assunto. Use /compact quando as respostas ficarem lentas (contexto grande). Ambos são mais rápidos que reiniciar o container.

/new = sessão limpa. /compact = comprime sem apagar. /think high = raciocínio mais profundo (mais lento). /activation always = responde em grupos sem menção. /usage = relatório de consumo.

Para acessar o webchat de outra máquina: túnel SSH — ssh -L 18789:localhost:18789 usuario@servidor e acesse http://127.0.0.1:18789/chat. Ou use Tailscale para acesso permanente sem abrir portas.

O gateway está vinculado ao loopback (127.0.0.1) por segurança. Para acessar de outros dispositivos NUNCA exponha a porta diretamente — use SSH tunnel ou Tailscale.

Túnel SSH = seguro, temporário (fecha com o terminal). Tailscale = VPN permanente, mais conveniente. NUNCA: ports: "0.0.0.0:18789:18789" no docker-compose.yml (expõe para internet).

Telegram é o canal mais simples de configurar: você cria um bot pelo @BotFather, copia o token e adiciona no .env. Sem OAuth, sem QR code, sem aprovação de app. Token → funciona.

Telegram dá acesso ao seu agente de qualquer dispositivo (celular, tablet, PC) sem precisar abrir o webchat. É o canal mais prático para uso diário.

@BotFather no Telegram. /newbot = cria novo bot. Token formato: 123456:ABC-DEF... TELEGRAM_BOT_TOKEN no .env. Bot é privado por padrão (pairing obrigatório).

No Telegram: 1) Procure @BotFather e inicie conversa. 2) Envie /newbot. 3) Escolha um nome (ex: "Meu Assistente"). 4) Escolha um username (deve terminar em "bot", ex: "meuassistente_bot"). 5) Copie o token gerado.

O processo leva 2 minutos e o bot fica permanentemente disponível. O @BotFather também permite personalizar foto, descrição e comandos do bot.

Nome = qualquer texto. Username = único globalmente, termina em "bot". Token = credencial do bot (proteja como senha). /mybots = vê seus bots existentes. /token = regenera token expirado.

Abra o .env e adicione/edite a linha: TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Depois faça docker compose down && docker compose up -d para aplicar.

O restart simples não recarrega o .env. Você precisa do ciclo down + up. Nos logs deve aparecer "📱 Enabling Telegram..." confirmando que o canal foi ativado.

Token 401 no log = token inválido ou expirado (regere no BotFather). Sem linha no log do Telegram = variável não foi lida (verificar ciclo down+up). Token nunca vai no git.

Procure seu bot no Telegram pelo username criado e envie qualquer mensagem (ex: "Oi"). O bot responde com um código de pairing tipo "DJX5TL6K". Você precisa aprovar esse código para liberar o acesso.

O pairing é a barreira de segurança. Sem aprovação o bot ignora as mensagens. Isso é intencional — garante que só você (ou quem você aprovar) pode usar o agente.

Código expira em 1h. Bot não responde até aprovação. Um código por dispositivo/usuário. Se expirar: envie nova mensagem para gerar novo código. Cada aprovação cria um token de acesso.

Execute no terminal: docker exec openclaw openclaw pairing approve telegram DJX5TL6K (substitua pelo seu código). O bot então começa a responder normalmente suas mensagens.

A aprovação via linha de comando garante que só o dono do servidor pode autorizar novos usuários. Não há forma de auto-aprovação — é uma decisão de segurança deliberada.

docker exec openclaw = executa comando dentro do container. openclaw pairing approve = comando CLI. Após aprovação o bot responde imediatamente. Para revogar: openclaw pairing revoke.

Adicione o bot a um grupo do Telegram. Por padrão ele responde quando mencionado (@username). Use /activation always para responder todas as mensagens, ou /activation mention para só quando mencionado.

Em grupos você pode ter um assistente compartilhado com família, equipe ou amigos. Cada membro precisa ser aprovado individualmente pelo pairing.

/activation mention = padrão (menção). /activation always = responde tudo. Grupos compartilham o mesmo agente. Cada membro precisa de pairing. /restart só funciona para o owner.

Telegram: setup em 2 min, bot dedicado, não usa seu número pessoal. WhatsApp: usa seu número real, todo mundo tem, mas setup mais complexo (QR code) e requer número dedicado para segurança.

Escolher o canal certo evita problemas. WhatsApp com número pessoal tem riscos — contatos podem receber código de pairing acidentalmente. Telegram é mais seguro por ser um bot separado.

Telegram = bot independente (recomendado). WhatsApp = seu número real conectado. Para WhatsApp seguro: chip pré-pago ou Google Voice dedicado. Ambos suportam pairing.

Execute docker exec -it openclaw openclaw channels login whatsapp. Um QR code aparece no terminal. Escaneie com WhatsApp → Configurações → Aparelhos Conectados → Conectar um Aparelho.

O -it no docker exec é obrigatório — sem ele o QR code não aparece corretamente no terminal. O QR expira rapidamente, tenha o WhatsApp pronto para escanear.

QR code expira em ~20 segundos. docker exec -it = modo interativo. Após scan o terminal mostra "Connected". A sessão do WhatsApp fica salva no volume openclaw-data.

Com número pessoal: o bot vê todas as mensagens recebidas. Contatos desconhecidos podem tentar usar o agente (receberão código de pairing). Número dedicado = separação limpa, maior segurança.

Usar número pessoal sem configurar dmPolicy corretamente pode expor o agente a contatos indesejados. Um chip pré-pago barato resolve elegantemente o problema.

dmPolicy: pairing = padrão seguro. dmPolicy: allowlist = só usuários específicos. Número dedicado recomendado. Chip pré-pago = opção econômica. Google Voice = alternativa digital.

dmPolicy controla como o agente trata DMs de desconhecidos. Opções: "pairing" (pede aprovação), "allowlist" (só usuários pré-aprovados), "block" (ignora todos), "open" (aceita qualquer um — não recomendado).

O padrão "pairing" é seguro mas pode incomodar se você receber muitas mensagens. "Allowlist" é mais rígido. "Open" é conveniente mas perigoso — qualquer pessoa usa seus créditos de API.

Padrão = pairing. Mais seguro = allowlist. Nunca use open em servidor público. Configure em openclaw.json ou via variável de ambiente. Afeta todos os canais configurados.

Problemas frequentes: QR expirado (solução: rodar o comando de login novamente), desconexão após restart do container (solução: sessão salva no volume, reconecta automaticamente na maioria dos casos).

Desconexões do WhatsApp são comuns — o WhatsApp tem limites para aparelhos conectados e pode desconectar se o dispositivo ficar inativo por tempo longo.

QR expira rápido → tenha WhatsApp pronto. Sessão no volume openclaw-data reconecta automaticamente. Se não reconectar: rodar login novamente. Máximo ~3 aparelhos conectados no WhatsApp.

Use número dedicado, configure dmPolicy para allowlist, não conecte o mesmo número em outros aparelhos simultaneamente, mantenha o container sempre ativo com restart: unless-stopped.

WhatsApp não é uma API oficial — a conexão é via reverse engineering. Seguir boas práticas reduz o risco de banimento do número pelo WhatsApp.

Número dedicado = menos risco. restart: unless-stopped no docker-compose.yml = auto-reinicia. Não use o mesmo número em WhatsApp Web e no bot simultaneamente. Volume preserva sessão entre reinícios.

Acesse discord.com/developers/applications. Crie uma nova Application com um nome qualquer. Depois vá em "Bot" → "Add Bot". É aqui que nasce o bot do Discord — o bot é um sub-recurso da Application.

Diferente do Telegram (só token), o Discord exige criar uma "Application" antes do bot. Entender essa separação evita confusão na hora de configurar permissões e gerar o token.

Application = container. Bot = sub-recurso. Guarde o Client ID (Application). Token do bot: Bot → Token → Reset/Copy. Application e Bot têm IDs diferentes. Não confunda os dois.

Em "Bot" → "Privileged Gateway Intents" ative: MESSAGE CONTENT INTENT. Sem isso o bot recebe eventos mas não vê o conteúdo das mensagens — ele ignora tudo que as pessoas escrevem.

O Discord introduziu Privileged Intents em 2022 por privacidade. Sem MESSAGE CONTENT INTENT o bot simplesmente não enxerga o texto das mensagens. É o erro mais comum em novos bots Discord.

MESSAGE CONTENT INTENT = obrigatório para OpenClaw. SERVER MEMBERS INTENT = opcional. PRESENCE INTENT = não necessário. Bots em 100+ servidores precisam de aprovação manual do Discord para usar Privileged Intents.

Em "Bot" → "Token" → "Reset Token" (ou "Copy" se já gerado). Copie e adicione no .env: DISCORD_BOT_TOKEN=seu_token. Faça docker compose down && docker compose up -d para aplicar.

O token não é mostrado duas vezes. Se fechar sem copiar, precisa resetar (gerar um novo, invalidando o anterior). Nos logs: "🎮 Enabling Discord..." confirma que o canal foi ativado com sucesso.

Token começa com MTM... ou similar. Reset = invalida o token anterior. NUNCA commite no git. 401 no log = token inválido ou resetado. Restart simples não recarrega .env — precisa de down + up.

Em "OAuth2" → "URL Generator" → marque "bot" em SCOPES → marque permissões: Send Messages, Read Message History, View Channels, Use Slash Commands. Copie a URL gerada e abra no browser para adicionar o bot ao servidor.

O bot precisa ser explicitamente convidado para cada servidor. A URL de convite embute as permissões necessárias. Permissões insuficientes = bot não consegue enviar mensagens no canal.

Permissões mínimas: Send Messages + Read Messages + View Channels. Slash Commands = boa prática adicionar. O dono do servidor precisa autorizar. Um bot pode estar em múltiplos servidores simultaneamente.

Por padrão o OpenClaw responde quando você menciona o bot (@nome_do_bot). Use /activation always para responder todas as mensagens do canal, ou /activation mention para só quando mencionado. Em DM o bot sempre responde (se aprovado no pairing).

Em servidores movimentados, /activation mention é mais educado e evita que o bot responda a tudo. Em canais dedicados ao bot, /activation always é mais conveniente — não precisa mencionar a cada mensagem.

@bot = menção direta. /activation always = responde tudo no canal. /activation mention = padrão (só com @). DM = sempre responde (se pairing aprovado). Pode usar tanto menção em servidores quanto DM para conversa privada.

Crie um canal #ai-assistant no Discord dedicado ao bot. Nas permissões do canal, dê ao bot: View Channel, Send Messages, Read Message History. Restrinja o canal para que só membros aprovados tenham acesso.

Um canal dedicado mantém o uso do bot organizado, evita que ele responda onde não é bem-vindo e facilita gerenciar quem pode usar o agente — dê acesso ao canal só para quem foi aprovado no pairing.

Channel overrides = permissões por canal específico. Category override = afeta todos os canais da categoria. @everyone sem View Channel = canal privado. Bot precisa de permissão específica no canal para aparecer e responder nele.

No Slack você cria uma "Slack App" (não um "bot" diretamente). A App contém o Bot User. Acesse api.slack.com/apps → "Create New App" → "From Scratch" → nome + workspace. A App gerencia permissões e os dois tokens necessários.

A terminologia Slack é confusa. Você cria uma App que tem um Bot User. A App gerencia permissões e tokens. Sem entender essa estrutura é fácil perder no portal e não saber onde encontrar o token certo.

App = container principal. Bot User = identidade visível no workspace. Dois tokens necessários: xoxb (bot token) e xapp (app-level token). Socket Mode = conexão WebSocket que o OpenClaw usa (necessário para xapp).

api.slack.com/apps → "Create New App" → "From Scratch" → defina nome (ex: "Meu Assistente") → selecione o workspace onde instalar. A app fica em rascunho até você instalar no workspace e configurar os tokens.

Você precisa criar a app no workspace onde vai usar. Se tiver múltiplos workspaces, precisa criar uma app para cada. A criação leva 2 minutos mas configurar scopes e tokens corretamente exige atenção.

Uma App = um workspace (versão básica). Nome da app = nome visível do bot no workspace. Foto pode ser customizada depois. Ative Socket Mode em "Socket Mode" tab antes de gerar o xapp token — esse passo é frequentemente esquecido.

Em "OAuth & Permissions" → "Bot Token Scopes" adicione: chat:write, channels:history, channels:read, im:history, im:write, app_mentions:read. Esses são os scopes mínimos para o OpenClaw funcionar no Slack.

O Slack é muito restritivo — sem o scope certo o bot não consegue fazer nada. Scopes insuficientes causam "missing_scope" nos logs. Adicionar um scope depois requer reinstalar a app no workspace.

Scopes obrigatórios: chat:write, channels:history, im:history, im:write, app_mentions:read. Adicionar scope = reinstalar app (gera novo xoxb). Menos scopes = mais seguro. User Token Scopes = raramente necessário para OpenClaw.

Bot Token (xoxb): "OAuth & Permissions" → "Install to Workspace" → copie o "Bot User OAuth Token" (começa xoxb-). App Token (xapp): "Basic Information" → "App-Level Tokens" → "Generate Token" → scope connections:write → copie (começa xapp-).

O OpenClaw precisa de DOIS tokens para o Slack. O xoxb é para enviar/ler mensagens. O xapp é para o Socket Mode (conexão WebSocket bidirecional). Sem ambos configurados o Slack simplesmente não funciona.

SLACK_BOT_TOKEN = xoxb-... SLACK_APP_TOKEN = xapp-... Socket Mode ativo = necessário antes de gerar xapp. xapp scope: connections:write. Ambos vão no .env. Ative Socket Mode em configurações antes de gerar o token xapp.

"OAuth & Permissions" → "Install to Workspace" → "Allow". O bot aparece no workspace na seção "Apps". Convide para canais com /invite @nome_do_bot. Nos logs do OpenClaw deve aparecer "💼 Enabling Slack..." confirmando ativação.

A instalação é necessária e precisa ser repetida a cada vez que você muda os scopes. É uma etapa separada da criação da app — muita gente cria tudo mas esquece de clicar em "Install to Workspace".

Install = gera o xoxb token. Reinstall = necessário após mudar scopes. /invite @bot = adiciona ao canal. Direct message ao bot = funciona após pairing. Apps section na sidebar do Slack = onde o bot aparece para DM.

Em ambientes corporativos: use canal #ai-assistant dedicado, informe a equipe que é um bot pessoal, configure dmPolicy para allowlist (só usuários aprovados), e não ative em canais com dados confidenciais da empresa.

Bots em workspaces corporativos podem gerar preocupações de segurança. Se os admins do Slack virem um app instalado sem comunicação prévia, pode ser removido. Transparência com a equipe é sempre melhor.

dmPolicy: allowlist = mais seguro em corporativo. Canal dedicado = menos intrusivo. Admin pode revogar a instalação a qualquer momento. Dados enviados ao agente passam pelo modelo de IA — informe a equipe. Tokens expiram se app não usada por muito tempo.

SOUL.md é um arquivo Markdown no workspace que define a identidade permanente do agente. Cada sessão começa com o conteúdo do SOUL.md injetado como contexto. Sem ele, o agente é genérico; com ele, é seu.

A personalidade, linguagem, especialidades e valores do agente vêm do SOUL.md. É a diferença entre um assistente genérico e um que fala do seu jeito, entende seu contexto e sabe o que você prioriza.

Localização: workspace/SOUL.md. Injetado em cada sessão automaticamente. Markdown simples — sem sintaxe especial. Pode ser editado a qualquer hora com efeito imediato na próxima sessão. Afeta consumo de tokens (mais longo = mais caro).

Não há estrutura obrigatória. O que funciona melhor: (1) Quem você é e o que faz, (2) Como o agente deve se comportar, (3) Áreas de conhecimento especializadas, (4) Tom e estilo de comunicação, (5) O que nunca fazer.

O agente interpreta o SOUL.md literalmente. "Responda em PT-BR sempre" funciona melhor que "fale português". Listas com bullets funcionam melhor que parágrafos longos para instruções claras.

Tamanho ideal: ~500–2000 tokens. Headers ## ajudam a organizar. Instruções em bullets = mais claro que prosa. Teste mudanças conversando com o agente após editar. Iterate até o comportamento ser o que você quer.

Defina explicitamente: idioma (sempre PT-BR), formalidade (formal/informal), verbosidade (curto/detalhado), uso de emojis (sim/não), humor (sim/não), estilo técnico ou didático. O agente segue essas diretrizes rigorosamente.

Sem instruções de tom, o agente usa o padrão do modelo — geralmente formal em inglês. "Responda sempre em português, de forma direta e sem enrolação" transforma completamente a experiência de uso diário.

"Responda em PT-BR" = instrução essencial. Verboso vs conciso: defina sua preferência. "Evite repetir perguntas" = elimina comportamento irritante padrão. Tom informal = mais natural para uso pessoal. Teste com uma conversa após mudar.

Liste explicitamente as áreas onde o agente deve ser especialista: "Sou desenvolvedor Python, foco em data science. Tenho conhecimento em SQL, pandas, sklearn. Quando houver dúvida sobre abordagem técnica, prefira soluções idiomáticas Python."

Com especialidades definidas, o agente não pergunta nível básico, usa terminologia correta e dá exemplos relevantes para seu contexto. Sem isso, ele trata você como iniciante em tudo.

Seja específico: "Python" > "programação". Inclua ferramentas e stack que usa. Mencione nível (sênior, júnior). Inclua domínio de negócio (fintech, saúde, e-commerce). Stack tech atual → respostas mais relevantes.

Defina o que o agente NÃO deve fazer: "Não me pergunte para confirmar ações óbvias", "Não resuma o que acabou de dizer", "Não use linguagem corporativa", "Não sugira consultar um profissional para questões técnicas que você sabe responder".

Esses "proibidos" eliminam os comportamentos mais irritantes dos modelos: over-caution, repetição, summarização do óbvio. São as regras que mais mudam a experiência diária — valem mais que qualquer instrução positiva.

Proibidos comuns: "não diga que precisa de mais contexto se puder inferir", "não repita o que acabei de dizer", "não use disclaimers excessivos", "não pergunte se quer continuar". Use linguagem imperativa direta: "Nunca X", "Não faça Y".

Exemplo mínimo eficaz: "Você é meu assistente pessoal. Responda sempre em PT-BR. Seja direto e conciso. Sou desenvolvedor backend sênior — não explique conceitos básicos. Use Python 3.12+ idiomático. Não resuma o que acabou de fazer."

Um SOUL.md de 5 linhas bem escritas é mais eficaz que 200 linhas genéricas. O foco deve ser no que vai MUDAR o comportamento — não em descrever o óbvio ou listar capacidades que o modelo já tem.

Minimum viable SOUL: idioma + tom + especialidade + 2-3 proibidos. Iterate: escreva → converse → ajuste. Commite no git para ter histórico. Não precisa ser perfeito de primeira — melhora com o uso.

SOUL.md = quem o agente É (identidade, personalidade, valores). AGENTS.md = como o agente AGE (regras operacionais, workflow, como usa ferramentas, o que bloquear). SOUL é o "ser", AGENTS é o "fazer".

A separação evita um arquivo gigante e confuso. SOUL muda quando você quer mudar a personalidade. AGENTS muda quando quer mudar comportamento operacional — ferrramentas, memória, segurança.

SOUL = system prompt de identidade. AGENTS = system prompt de operação. Ambos são injetados em cada sessão. AGENTS.md fica em workspace/agents/main/AGENTS.md. Pode ter AGENTS.md específico por agente.

Defina como o agente toma decisões: "Antes de executar ação destrutiva, confirme comigo", "Se não souber a resposta, diga 'não sei' ao invés de inventar", "Priorize soluções simples sobre complexas".

Sem regras de comportamento, o agente segue os padrões do modelo — que podem incluir comportamentos indesejados como inventar respostas (alucinação) ou executar ações sem confirmação.

Regras imperativas funcionam melhor: "Faça X", "Nunca Y". Regras de confirmação para ações irreversíveis = boa prática de segurança. "Prefira soluções simples" = evita over-engineering. Exemplos concretos > abstrações.

Instrua o agente sobre ferramentas: "Use busca web para informações após 2024", "Prefira criar arquivos em workspace/", "Quando pesquisar, use 3 fontes diferentes antes de concluir", "Use code execution para validar código antes de entregar".

Sem preferências definidas, o agente escolhe ferramentas arbitrariamente. Definir preferências economiza tokens (menos tentativas) e melhora qualidade — o agente usa o conjunto certo de ferramentas para cada tipo de tarefa.

Liste ferramentas disponíveis. Defina ordem de preferência. Especifique quando NÃO usar uma ferramenta. workspace/ = diretório padrão para arquivos criados. Limite de buscas por resposta evita loops de pesquisa excessivos.

Instrua como o agente deve usar memória: "Salve preferências importantes descobertas em MEMORY.md", "Ao fim de tarefas longas, resuma em memory/YYYY-MM-DD.md", "Leia MEMORY.md no início de sessões importantes antes de responder".

Memória sem regras resulta em MEMORY.md gigante com tudo e nada. Com regras claras, o agente mantém uma memória curta e relevante — sabe o que vale lembrar e o que descartar após cada sessão.

MEMORY.md = fatos permanentes sobre você. Daily = log de sessão por data. "Lembre-se de X" = instrução para salvar imediatamente. Sem regras, memória cresce infinitamente e vira ruído. Revise mensalmente.

Para trade-offs, defina prioridades: "Segurança primeiro, conveniência depois", "Quando houver conflito entre velocidade e correção, prefira correção", "Em caso de dúvida sobre ação irreversível, pergunte ao invés de assumir".

Quando o agente enfrenta trade-offs, ele precisa de um framework de decisão. Sem ele, cada modelo tem seu viés — alguns são excessivamente cautelosos, outros impulsivos demais. Você define o equilíbrio.

Framework sugerido: segurança > correção > performance > conveniência. Defina o que é "reversível" vs "irreversível" — ajuda o agente a calibrar autonomia. Exemplos concretos funcionam melhor que abstrações.

Liste ações que NUNCA devem ser executadas sem aprovação explícita: "Nunca execute rm -rf, git push --force, DROP TABLE sem aprovação escrita", "Nunca envie mensagens em meu nome sem confirmação", "Nunca delete arquivos fora do workspace/".

Mesmo com pairing e autenticação, o agente age no seu nome. Uma instrução ambígua pode resultar em ação destrutiva. Bloqueios explícitos no AGENTS.md são a última linha de defesa antes da execução.

Blocklist essencial: rm -rf, git force push, DROP TABLE, format, DELETE sem WHERE. Ações de comunicação (email, post público). Acesso fora do workspace/. "Nunca" + descrição específica = mais eficaz que categorias genéricas.

Uma skill é um arquivo SKILL.md com frontmatter YAML no início. O frontmatter define: name, description, trigger (palavra que ativa) e tools. O corpo do arquivo é o system prompt da skill, injetado quando ela é ativada pelo trigger.

Skills são modulares — você ativa quando precisa e desativa quando não precisa. É diferente do SOUL.md (sempre ativo). Uma skill de "analisa código" só é injetada quando você usa o trigger /code.

Frontmatter: ---\nname: minha-skill\ndescription: ...\ntrigger: /analisa\n---. Trigger = palavra ou frase de ativação. Skills ficam em workspace/skills/. Podem ser compartilhadas via ClawHub. Inativas até o trigger ser usado.

ClawHub (github.com/openclaw/clawhub) é o repositório público de skills da comunidade com mais de 13.700 skills. Você navega, escolhe e instala copiando o arquivo SKILL.md para workspace/skills/.

Antes de criar uma skill do zero, verifique o ClawHub — provavelmente já existe uma skill para o que você precisa, testada pela comunidade. Skills de clima, busca, calendário, código, finanças, já estão prontas.

github.com/openclaw/clawhub. Instalação: copiar SKILL.md para workspace/skills/. Categorias: productivity, coding, research, communication. Skills mais populares: daily-brief, code-review, web-researcher. Fork e customize para seu uso.

Skills podem ser instaladas em 3 níveis: (1) workspace/skills/ = para um agente específico, (2) ~/.openclaw/skills/ = para todos os agentes do usuário, (3) Diretório global = para toda a instalação. O nível mais específico tem prioridade em conflitos de nome.

A hierarquia permite ter skills globais (busca na web) e skills específicas por agente (análise jurídica só para o agente de trabalho). Skills do mesmo nome: o mais específico ganha — útil para customizar skills da comunidade.

workspace/skills/ > user skills > global skills. Instalar: copie o SKILL.md para o nível desejado. Desativar: mova para fora da pasta ou adicione enabled: false no frontmatter. Reinicie o gateway após instalar skills novas.

Crie workspace/skills/minha-skill.md com: ---\nname: analisa-pr\ndescription: Analisa pull requests\ntrigger: /pr\n---. No corpo: "Quando ativado com /pr, você é um revisor de código experiente. Analise focando em segurança, performance e manutenibilidade."

Skills personalizadas são o superpoder do OpenClaw. Você codifica seu processo de trabalho em Markdown e o agente segue. Uma skill bem escrita é como ter um especialista on-demand disponível com um comando.

Trigger único (não colida com outros). Description clara. Prompt específico no corpo. Tamanho ideal: 100-500 palavras no corpo. Teste: use o trigger na conversa e veja se o agente muda de modo. Debug: logs do gateway mostram carregamento de skills.

O frontmatter completo suporta: name (string), description (string), trigger (string ou lista), tools (lista de ferramentas), enabled (boolean, padrão true), priority (number — maior = mais prioritário em conflitos de nome).

O frontmatter correto é o que faz o OpenClaw detectar e registrar a skill. Um erro de YAML e a skill simplesmente não é carregada — sem erro visível na interface. Verifique os logs se uma skill não aparecer.

YAML estrito: indentação com espaços (não tabs). Strings com espaço entre aspas. Tools: [web_search, code_execution]. Trigger pode ser lista: [/pr, /review]. enabled: false = desativa sem deletar. Verificar carregamento: docker compose logs | grep skill.

As skills mais populares no ClawHub incluem: daily-brief (resumo diário de notícias), code-review (revisão de código), meeting-notes (resumo de reunião), web-researcher (pesquisa com múltiplas fontes), expense-tracker (controle de gastos), language-tutor (prática de idiomas).

Conhecer as skills populares dá inspiração para criar as suas e mostra o que a comunidade considera mais valioso. Muitas são ponto de partida — você instala e customiza para seu uso específico.

Explore por categoria no ClawHub. Fork = copie e adapte livremente. Contribuir: abra PR no repositório clawhub. Ranking indica qualidade validada pela comunidade. Categorias mais populares: produtividade > coding > research > comunicação.

3 tipos: Sessão (contexto da conversa atual, limpo no /new), Diária (arquivo memory/YYYY-MM-DD.md criado automaticamente), Longo prazo (MEMORY.md — fatos permanentes que o agente sempre sabe sobre você).

Entender os tipos evita confusão. "O agente esqueceu o que disse ontem" = era memória de sessão. Para persistir informação entre sessões, ela precisa ir para MEMORY.md ou para um arquivo daily explicitamente.

Sessão = context window (limite de tokens). Daily = memory/AAAA-MM-DD.md. MEMORY.md = curado manualmente ou pelo agente. USER.md = perfil permanente seu. Hierarquia: MEMORY.md > daily > sessão.

workspace/MEMORY.md contém fatos que o agente deve sempre saber: preferências, projetos em andamento, pessoas importantes, contexto de trabalho. É injetado automaticamente em cada sessão junto com o SOUL.md.

MEMORY.md elimina a necessidade de repetir contexto a cada conversa. "Meu projeto principal é X, minha stack é Y, meu prazo é Z" — sem ele, você explica de novo todo dia. Com ele, o agente já sabe.

Tamanho ideal: 500–2000 tokens (afeta custo por sessão). Seções sugeridas: Eu (quem você é), Projetos (o que está fazendo), Preferências (como quer que o agente aja), Contexto (informações recentes importantes). Revise e atualize regularmente.

O agente cria automaticamente arquivos como workspace/memory/2026-04-28.md com um log da sessão do dia. Você pode pedir: "O que trabalhamos ontem?" ou "Que decisão tomamos semana passada?" — o agente consulta esses arquivos.

Os diários são o "histórico de trabalho" do agente. Com eles, você tem continuidade entre sessões — o agente recupera decisões, tarefas e contexto de conversas anteriores sem você precisar reexplicar.

Formato: memory/AAAA-MM-DD.md. Criado automaticamente ao fim de sessões longas. O agente lê quando instruído. Pode ser editado manualmente. Limpe periodicamente (memória antiga = tokens gastos à toa + informação desatualizada).

workspace/USER.md é onde você descreve seu perfil: nome, profissão, empresa, timezone, idioma preferido, habilidades técnicas, contexto familiar, hobbies relevantes. O agente usa isso para personalizar as respostas automaticamente.

Com USER.md, o agente sabe quem você é sem precisar de contexto a cada sessão. "Sou João, engenheiro sênior em SP, work em fintech, GMT-3" — torna cada interação mais relevante e personalizada para sua realidade.

Arquivo opcional mas recomendado. Complementa SOUL.md (SOUL = como o agente age, USER = quem você é). Atualize quando seu contexto muda. Dados sensíveis: pense antes de incluir — quem mais tem acesso ao seu workspace?

Duas formas: Automático (MEMORY.md e USER.md injetados no início de cada sessão) e Sob demanda ("Lembre-se de X" instrui o agente a salvar; "O que sabe sobre Y?" faz ele buscar nos arquivos do workspace). O comando /memory mostra o estado atual.

Memória automática = sempre presente mas consome tokens. Memória sob demanda = não consome tokens até ser solicitada. Para informações críticas: automático. Para histórico detalhado: sob demanda conforme necessário.

/memory = mostra o que está na memória ativa. "Salve isso em MEMORY.md" = instrução direta para o agente. "Lembre-se de..." = mesmo efeito. Busca em arquivos = ferramenta file search. Contexto automático: SOUL + MEMORY + USER a cada sessão.

Vale memorizar: preferências de trabalho, contexto de projetos longos, pessoas e papéis, decisões importantes, padrões que se repetem. Não vale memorizar: informações que você acha fácil em outro lugar, dados temporários, contexto de conversa única.

MEMORY.md muito grande = custo alto por sessão (mais tokens consumidos) + agente distraído com informação irrelevante. A chave é curar bem: mantenha o que muda como o agente age, descarte o que é circunstancial.

Regra geral: se vai precisar explicar em mais de 3 conversas, memorize. Se é one-off, não memorize. Revise MEMORY.md mensalmente e remova o que não é mais relevante. Prefira itens curtos a parágrafos longos — mais fácil de manter.

Heartbeat é a funcionalidade que permite ao agente agir de forma proativa e autônoma sem precisar de uma mensagem sua para iniciar. Com Heartbeat, o agente executa tarefas em horários programados — newsletter diária, verificação de status, resumo de emails, etc.

A maioria dos assistentes de IA só age quando você fala com eles. Heartbeat inverte isso — o agente monitora, age e te notifica quando algo acontece. É a diferença entre um chatbot e um assistente genuinamente proativo.

Heartbeat = execução autônoma agendada. Requer HEARTBEAT.md no workspace. Usa cron syntax para agendamento. Envia resultados por canal configurado (Telegram, etc.). Distinto de BOOT.md (executa uma vez ao iniciar o gateway).

Crie workspace/agents/main/HEARTBEAT.md com as tarefas autônomas. Cada bloco define uma tarefa com schedule (cron), canal de notificação e a instrução em linguagem natural. Ex: "Todo dia às 8h, busque as principais notícias de tech e me mande no Telegram".

O HEARTBEAT.md é o "agendador" do seu agente. Sem ele, o agente só age quando você inicia a conversa. Com ele, o agente toma iniciativa nos horários que você definir — sem nenhuma interação sua.

Localização: workspace/agents/main/HEARTBEAT.md. Formato YAML + Markdown. schedule: "0 8 * * *" = todo dia às 8h. channel: telegram = onde notificar. A instrução é em linguagem natural — não precisa saber programar.

O schedule usa sintaxe cron: "minuto hora dia-do-mês mês dia-da-semana". Exemplos: "0 8 * * *" (todo dia às 8h), "0 8 * * 1-5" (seg-sex às 8h), "0 9 * * 1" (toda segunda às 9h), "*/30 * * * *" (a cada 30 min).

Cron é o padrão universal de agendamento Unix. Uma vez aprendido, vale para qualquer sistema. Para iniciantes: use crontab.guru para gerar e testar expressões cron sem precisar decorar a sintaxe.

crontab.guru = gerador visual gratuito. 5 campos: min hora dia mês weekday. * = qualquer valor. */n = a cada n. 1-5 = de 1 a 5. Problema comum: o container usa UTC — ajuste o horário conforme seu timezone (ex: GMT-3 = adicionar 3h ao cron).

Exemplos reais: (1) Newsletter diária: busca notícias de tech/finanças, resume os 5 mais importantes, envia para Telegram às 8h. (2) Monitor de site: verifica se URL está acessível a cada hora, notifica se cair. (3) Resumo de tarefas: lista todo dia às 9h o que está aberto.

Esses casos mostram o poder do Heartbeat na prática. Um agente que te manda newsletter personalizada de graça (usando modelo free) é mais valioso que muitas assinaturas pagas de serviços de curadoria.

Newsletter: busca web + summarize + send via canal. Monitor: check URL + condicional + notify. Resumo: lê MEMORY.md + formata + send. Combinar com Skills = ainda mais poderoso. Limite: depende das ferramentas disponíveis no modelo.

workspace/BOOT.md é executado automaticamente CADA VEZ que o gateway inicia. Diferente do Heartbeat (agendado por hora/dia), o BOOT.md roda uma única vez na inicialização. Use para: atualizar MEMORY.md, verificar status de serviços, preparar contexto do dia.

BOOT.md é como o "startup script" do agente. Executado sem interação humana logo que o container sobe. Útil para tarefas de setup diário que precisam estar prontas antes da primeira conversa.

workspace/BOOT.md. Executa uma vez por inicialização do gateway. Não envia notificações por padrão (diferente do Heartbeat). Pode usar ferramentas. Se falhar, o gateway ainda sobe — erro aparece nos logs. Diferença: BOOT = inicialização, HEARTBEAT = agenda recorrente.

Heartbeat consome tokens do modelo. Para otimizar: (1) Use modelos menores para tarefas simples de monitoramento, (2) Mantenha o contexto do Heartbeat pequeno, (3) Agende com frequência adequada — monitorar a cada hora ≠ monitorar a cada minuto, (4) Use modelos gratuitos sempre que possível.

Heartbeats rodando frequentemente com modelos caros podem gerar conta significativa de API. Com modelos gratuitos (Llama 3.3 70B free) o custo é zero, mas o rate limit (20 req/min) limita frequências muito altas.

Custo = tokens × preço do modelo. Llama 3.3 free = sem custo. Claude Sonnet = $3/M tokens. Heartbeat a cada hora = 24 chamadas/dia. Monitore com /usage. Prefira modelos free para monitoramento simples e modelos premium para tarefas complexas.

Voice Wake permite ativar o agente com uma palavra-chave falada, sem precisar digitar. O agente fica em modo de "escuta passiva" e responde quando ouve a wake word configurada — como um Alexa, mas rodando localmente com seu modelo.

Voice Wake transforma o OpenClaw em algo próximo a um Alexa/Siri pessoal, mas sem enviar áudio para a nuvem (usando Whisper local), sem mensalidade, com seu modelo de preferência e com suas regras de privacidade.

Wake word = palavra-chave de ativação. Requer microfone configurado. Suporte nativo: macOS app desktop. Talk Mode = conversa contínua após ativação. Whisper = transcrição local. ElevenLabs = resposta em voz. Funciona sem internet com modelos locais.

Voice Mode tem suporte diferente por plataforma: macOS (total — wake word + Talk Mode no app desktop), iOS (parcial — Talk Mode via app nativo), Android (Talk Mode via webchat no Chrome), Linux/Windows (Talk Mode via webchat com permissão de microfone).

Se você está no macOS com o app desktop do OpenClaw, tem a experiência mais completa. Nos outros sistemas o Talk Mode ainda funciona bem via webchat, mas a wake word passiva não está disponível nativamente.

App desktop macOS = experiência completa (wake word + Talk Mode). iOS app = Talk Mode nativo. Android + Chrome = Talk Mode via webchat. Wake word passiva = macOS/iOS apenas. Cross-platform Talk Mode = via webchat com permissão de microfone no browser.

O OpenClaw suporta ElevenLabs para Text-to-Speech (o agente fala as respostas). Configure ELEVENLABS_API_KEY no .env e selecione a voz desejada. O ElevenLabs tem nível gratuito (10.000 caracteres/mês) e planos pagos para uso intenso.

A diferença entre TTS padrão e ElevenLabs é enorme — as vozes são quase indistinguíveis de humanos. Se você quer usar Voice Mode seriamente para uso cotidiano, o ElevenLabs muda completamente a experiência.

ELEVENLABS_API_KEY no .env. Free tier: 10k char/mês. Centenas de vozes disponíveis. Latência: 200–500ms por chunk de áudio. Fallback: sem key = TTS básico do browser. Clone de voz = plano pago. Vozes em PT-BR disponíveis no marketplace.

Whisper (OpenAI) é o modelo de transcrição de voz para texto que o OpenClaw usa. Duas opções: API da OpenAI (online, cobra por minuto de áudio) ou faster-whisper local (gratuito). O docker-openclaw inclui instalação opcional do faster-whisper no Dockerfile.

Com faster-whisper local, sua voz nunca sai da máquina. Com a API da OpenAI, é mais preciso e sem overhead de GPU, mas envia o áudio para nuvem e tem custo por minuto. Escolha conforme sua prioridade: privacidade vs conveniência.

faster-whisper = local, grátis, precisa de GPU/CPU razoável. OpenAI Whisper API = cloud, $0.006/min, sem GPU necessária. Dockerfile: linha pip install faster-whisper (ativar no Dockerfile). Qualidade: large-v3 > base (mais lento mas mais preciso).

Talk Mode é o modo de conversa contínua por voz — você fala, o agente responde por voz, você fala de novo, sem precisar pressionar nada entre turnos. Ative com /talk on no webchat. Desative com /talk off.

Talk Mode transforma o agente em assistente "hands-free" real. Ideal para: enquanto cozinha, organiza a mesa, faz outras tarefas. A experiência é muito mais fluída que digitar e ler a cada turno.

/talk on = ativa. /talk off = desativa. Silêncio > 3s = fim do turno. Funciona melhor com fone de ouvido (evita eco). Latência depende do modelo — modelos menores = mais rápido para voz. Webchat Chrome = melhor compatibilidade de microfone.

Para Voice Mode funcionar bem: (1) Use fone de ouvido — evita o agente "ouvir" a própria voz gerando eco, (2) Microfone dedicado ou headset > microfone integrado, (3) Ambiente silencioso melhora muito a transcrição, (4) Teste com uma frase simples antes de usar intensamente.

A qualidade do microfone impacta diretamente a precisão do Whisper. Ruído de fundo causa transcrições erradas e o agente entende comandos incorretos. Um headset básico ($30-50) resolve a maioria dos problemas.

Fone = essencial para Talk Mode (sem eco). Headset USB > P2 (mais consistente no Linux). Testar: abra webchat, ative Talk Mode, diga uma frase. Se transcrever errado = ajustar microfone ou ambiente. Microfone integrado + ambiente silencioso = suficiente para uso básico.

Live Canvas é a interface visual do OpenClaw — uma área ao lado do chat onde o agente cria e atualiza conteúdo rico em tempo real: tabelas, gráficos, formulários, dashboards. Diferente do chat (texto linear), o Canvas é persistente e interativo.

Para tarefas visuais — análise de dados, formulários, dashboards — o Canvas é muito mais eficiente que responder em texto no chat. O agente cria e você interage diretamente com o resultado visual.

Canvas = painel visual ao lado do chat. Requer webchat (porta 18789/chat). A2UI = tecnologia que permite ao agente criar UIs. Persiste até /new ou fechamento da sessão. Requer modelo com function calling (Claude, GPT-4, Qwen 2.5+).

A2UI (Agent-to-UI) é o protocolo do OpenClaw que permite ao agente gerar interfaces interativas. O agente escreve código A2UI (HTML/CSS/JS simplificado via tool call) e o webchat renderiza em tempo real no Canvas. O resultado é clicável e pode enviar dados de volta.

A2UI fecha o loop: o agente não apenas responde, mas cria ferramentas interativas. Você pode pedir "crie um formulário para registrar meus gastos diários" — o agente cria, você preenche, e os dados voltam para ele processar.

A2UI = subset de HTML + componentes pré-definidos. Criado pelo agente via tool call. Renderizado no Canvas em tempo real. Bidirecional: usuário interage → dados voltam ao agente. Requer modelo com function calling habilitado.

Peça ao agente: "Crie um dashboard com meu progresso de leitura este mês" ou "Faça um gráfico de barras com minhas despesas por categoria". O agente usa A2UI para criar a visualização e pode atualizá-la em tempo real conforme você fornece dados.

Dashboards no Canvas são mais úteis que tabelas em texto no chat — você vê tendências, pode interagir. E como o agente cria a UI, ela é customizada para exatamente o que você precisa, sem você precisar configurar nada.

Tipos suportados: tabelas, gráficos (linha, barra, pizza), cards de métricas, cronogramas. Dados: forneça em texto ou deixe o agente buscar de arquivos no workspace. Atualizar: "atualize o dashboard com estes dados" → agente modifica o Canvas existente.

O Canvas suporta formulários interativos. Exemplo: "Crie um formulário diário de humor e produtividade com escala 1-5 e campo de notas". O agente cria no Canvas, você preenche diariamente, os dados são salvos no workspace automaticamente.

Formulários no Canvas substituem planilhas para coleta de dados simples. Você pede uma vez, o agente cria, e você usa repetidamente. Perfeito para tracking pessoal: humor, exercícios, leituras, gastos, hábitos.

Tipos de campos: texto, número, seleção, escala, data, checkbox. Dados coletados: salvos em workspace/ ou MEMORY.md. Formulários persistem dentro da sessão. Export como CSV: peça ao agente para exportar os dados coletados.

Canvases são acessíveis localmente no webchat. Para compartilhar: use export (o agente exporta como HTML standalone), ou compartilhe acesso ao webchat via token de acesso. Não há compartilhamento cloud nativo no setup Docker local.

No setup Docker local, compartilhamento é limitado — o Canvas existe só na sua sessão. Para uso colaborativo real, use VPS com Tailscale ou acesso à rede local. Export como HTML é a solução mais simples para documentos compartilháveis.

Export = agente gera HTML standalone que funciona sem o servidor. Compartilhar webchat = via SSH tunnel ou Tailscale. Canvas = local por padrão. Para link compartilhável: "exporte como HTML" → agente cria arquivo em workspace/. Fácil de distribuir por email ou chat.

Limitações: (1) Requer webchat — não funciona no Telegram/WhatsApp/Discord, (2) Não persiste quando você faz /new ou reinicia o gateway, (3) Depende do modelo ter function calling — modelos simples não suportam A2UI, (4) Interações complexas podem ser lentas.

Conhecer as limitações evita frustração. Canvas não é um substituto para aplicações reais — é uma ferramenta de auxílio visual para sessões de trabalho no webchat. Para dados que precisam persistir, salve sempre no workspace/.

Funciona: webchat. Não funciona: Telegram, WhatsApp, Discord. Persiste: dentro da sessão ativa. Não persiste: após /new ou restart. Requer: modelos com function calling. Não requer: instalação extra (embutido no gateway). Salve dados importantes em workspace/ antes de encerrar.

Browser Control usa o Chrome DevTools Protocol (CDP) para dar ao agente controle sobre um Chrome/Chromium. O agente pode navegar URLs, clicar em elementos, preencher formulários, fazer scroll e extrair conteúdo — tudo via API, sem extensão de browser.

CDP é o protocolo padrão de automação de browsers — o mesmo usado pelo Puppeteer e Playwright. O OpenClaw usa CDP para dar ao agente capacidade de "usar o computador" como um humano faria no browser, mas de forma programática.

CDP = protocolo oficial do Chrome. Requer Chrome/Chromium rodando com --remote-debugging-port=9222. Sem extensão necessária. Funciona com Chrome, Chromium, Edge (baseados em Chromium). Firefox não suportado.

Com Browser Control o agente pode: navegar para URLs, clicar em botões e links, preencher formulários e fazer login, fazer screenshot de páginas, extrair texto e dados de páginas, executar JavaScript, aguardar carregamento de elementos e fazer scroll.

Isso transforma o agente em um "robô de browser" inteligente — ele automatiza tarefas que você faz manualmente: buscar preços, preencher formulários repetitivos, coletar dados de sites, fazer login em sistemas e extrair informações.

Capacidades: navigate, click, type, screenshot, evaluate (JS), waitFor, scroll, extract. Limitações: não resolve captcha (por design), não opera múltiplas janelas simultaneamente. Ética: use só em sites onde você tem permissão para automação.

Para usar Browser Control: (1) Inicie Chrome com: google-chrome --remote-debugging-port=9222 --no-first-run, (2) Configure o endpoint CDP no OpenClaw (ws://localhost:9222), (3) O agente então tem acesso ao browser aberto naquela instância.

O Chrome não aceita conexão CDP por padrão — precisa ser iniciado com a flag específica. Em Linux headless (servidor), use --headless=new para rodar sem tela. Em Docker, pode rodar um container separado com Chrome headless.

Flag obrigatória: --remote-debugging-port=9222. Headless: --headless=new (Chrome 112+). URL de controle: ws://127.0.0.1:9222. Verificar funcionamento: curl localhost:9222/json/version. Container Chromium headless: browserless/chromium é opção popular para Docker.

Exemplos reais: (1) "Acesse meu email e me dê um resumo dos não lidos", (2) "Verifique o preço deste produto em 3 sites", (3) "Preencha este formulário com estes dados", (4) "Faça login no GitHub e verifique meus PRs abertos", (5) "Extraia todos os emails desta lista".

Essas automações economizam dezenas de minutos por dia. São tarefas repetitivas e mecânicas — e o agente adiciona inteligência ao processo: não apenas executa, mas interpreta e age sobre o que encontrar.

Login: credenciais via workspace (nunca em texto claro no prompt). Extração: mais eficiente que copiar manualmente. Formulários: ideal para sistemas sem API. Anti-bot protections (Cloudflare) podem bloquear. Sempre teste manualmente antes de automatizar em produção.

Browser Control com acesso ao seu browser é poderoso e perigoso. Riscos: (1) O agente pode acessar qualquer site onde você está logado, (2) Com acesso a email/banco pode realizar ações indesejadas, (3) Prompt injection via conteúdo de página pode redirecionar o agente.

NUNCA dê ao agente acesso CDP ao seu browser pessoal sem restrições estritas em AGENTS.md. Use um Chrome separado ou perfil de browser dedicado para automações, sem cookies de login pessoal, exceto quando explicitamente necessário.

Perfil separado para automação = boa prática. Restrições em AGENTS.md: "só acesse os sites X, Y, Z". Prompt injection via página web = risco real. CDP em container isolado > CDP no browser pessoal. Monitore o que o agente faz pedindo screenshots após ações.

Caso completo: "Todo dia às 9h (Heartbeat), acesse meu Notion, extraia as tarefas do dia, priorize por impacto, e me mande no Telegram o plano do dia". Ou: "Quando eu pedir /pesquisa [tema], busque em 5 sites, extraia pontos principais e sintetize em 3 parágrafos".

A combinação Heartbeat + Browser Control + canais de mensagem é o stack completo para um assistente genuinamente autônomo. O agente acessa informação do mundo real, processa com inteligência e entrega no canal de sua preferência.

Stack completo: HEARTBEAT.md (agenda) + Browser Control (acessa web) + Tool use (processa) + Telegram (notifica). Comece simples: um Heartbeat sem Browser Control funciona antes de combinar tudo. Debug: logs detalhados do gateway mostram cada etapa.