OpenClaw: o que é, como instalar e ligar ao Telegram

O OpenClaw apareceu no meu feed no inverno passado, quando o projeto mudou de nome duas vezes numa semana e ganhou centenas de milhares de estrelas no GitHub. Desde então, cada vez mais pessoas procuram «instalação do OpenClaw» e «OpenClaw Telegram».

Abaixo, percorro a documentação oficial: o que é esta ferramenta, em que difere do Claude Code, como a instalar no Windows, macOS ou Linux, como escolher um modelo e como ligar um bot do Telegram. Também abordo a segurança à parte, porque o OpenClaw esteve envolvido em alguns incidentes de grande repercussão.

Saiba como trabalhar com o serviço na documentação da Ailoot.

O que é o OpenClaw, em linguagem simples?#

O OpenClaw liga um modelo de IA ao seu bot do Telegram. Com as ferramentas e permissões necessárias configuradas, pode resumir mensagens ou agendar um lembrete. O processo do gateway e a configuração local funcionam no seu computador ou servidor. Isso não torna todas as conversas locais: ao selecionar um modelo na nuvem, o pedido e o contexto relevante da conversa são enviados a esse fornecedor. Se a ligação passar pela Ailoot, o pedido segue pela Ailoot até ao fornecedor do modelo selecionado. A inferência local exige um modelo local e ausência de alternativa automática na nuvem; as mensagens do Telegram continuam a passar pelo Telegram, e as ferramentas ativadas podem contactar outros serviços.

O projeto é desenvolvido pela comunidade open source do OpenClaw. O repositório do GitHub foi criado em 24 de novembro de 2025 e, a 22 de agosto de 2026, tinha 387 mil estrelas e 81 mil forks — um dos projetos abertos com crescimento mais rápido do ano. A linguagem é TypeScript.

O projeto tem uma história de nomes invulgar, que vale a pena conhecer para não se confundir com artigos mais antigos. Começou como Warelay, um gateway para o WhatsApp. Depois passou a chamar-se Clawdbot. Em janeiro de 2026, a Anthropic pediu uma mudança de nome por causa de uma marca registada, e o projeto passou alguns dias como Moltbot. A 30 de janeiro de 2026, recebeu o nome definitivo: OpenClaw. Por isso, se encontrar instruções sobre «Clawdbot» ou «Moltbot», trata-se do mesmo projeto; esses artigos foram escritos antes da mudança de nome.

O mascote do projeto é Molty, o lagostim, e a «muda» (a troca da carapaça) tornou-se a metáfora oficial de cada mudança de nome.

Em que difere o OpenClaw do Claude Code e do Hermes Agent?#

Perguntam-me constantemente sobre esta diferença porque, vistos de fora, todos parecem «agentes de IA». Eis uma tabela comparativa:

Como ler a tabela. Uso o Claude Code para desenvolvimento: é mais forte quando precisa de um modelo potente e trabalha com código. O OpenClaw e o Hermes servem para outra coisa: um agente que funciona continuamente, está no Telegram, se lembra da conversa de ontem e executa tarefas segundo um horário. A escolha entre OpenClaw e Hermes é mais subtil; já existe um guia do Hermes com instruções de instalação e configuração.

Se está apenas a escolher uma ferramenta, comece pela visão geral: o que as pessoas usam para programar em 2026 e que tarefas delegar a um agente de IA. Tenho também um artigo separado sobre a instalação do Claude Code.

O que precisa antes de instalar o OpenClaw?#

Verifique antecipadamente a sua versão do Node — é o único requisito estrito:

node --version

São suportadas as versões 22.22.3+, 24.15+ e 25.9+; recomenda-se o Node 26. Se o comando devolver «command not found» ou a versão for antiga, não se preocupe: o instalador oficial descarrega uma versão recente do Node por si, pelo que não precisa de instalar nada manualmente.

Falta decidir o modelo. O OpenClaw não pensa por si: chama o modelo que escolher. Eis as opções de custo: uma chave da Anthropic, OpenAI ou Google — paga ao fornecedor pela utilização efetiva; ou um modelo local através do Ollama — gratuito em termos monetários, mas exigente em termos de hardware. Abordo ambas as opções abaixo, em secções separadas.

Como instalar o OpenClaw no macOS e Linux?#

A opção recomendada é o instalador oficial:

1. Execute o instalador

   curl -fsSL https://openclaw.ai/install.sh | bash
   

   O script deteta o sistema operativo, verifica se tem o Node (e instala-o, se necessário), instala o OpenClaw e abre o assistente de configuração. Se quiser explorar antes de iniciar o assistente, acrescente a opção: bash -s -- --no-onboard.

2. Verifique se tudo foi instalado

   openclaw --version
   openclaw doctor
   openclaw gateway status
   

   O primeiro comando mostra a versão, o segundo verifica a configuração e o terceiro confirma que o gateway está a funcionar e a escutar na porta 18789.

Se utiliza npm e quer gerir a instalação por si:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

Há aqui uma armadilha recente, abordada num capítulo separado da documentação. O npm 12 bloqueia por predefinição os scripts de instalação dos pacotes e, sem a opção --allow-scripts=openclaw, a instalação para com uma mensagem allowScripts. No npm 11.15 e anteriores, a opção não é necessária — essa restrição ainda não existe. Verifique a sua versão com: npm --version.

A opção --install-daemon do segundo comando configura o arranque automático: no macOS, é um LaunchAgent; no Linux, um serviço systemd. Inicia o gateway após reinício ou início de sessão, sujeito às condições do gestor de serviços. Não impede suspensão nem funciona com o computador desligado. Telegram exige máquina acordada e rede; use um servidor sempre ligado se precisar de respostas enquanto o portátil dorme ou está desligado.

Como instalar o OpenClaw no Windows?#

A primeira opção destina-se a quem prefere janelas ao terminal. O Windows Hub é uma aplicação nativa do OpenClaw para Windows 10 (20H2+) e Windows 11, atualmente em beta. Aceda à página de lançamentos do Windows Hub e descarregue o instalador para o seu processador: OpenClawCompanion-Setup-x64.exe para computadores normais, ou arm64 para ARM. Após a instalação, o OpenClaw Companion aparecerá no menu Iniciar, com um ícone na área de notificação, uma janela de chat e definições.

No primeiro arranque, a aplicação sugerirá «Set up locally» — aceite. Criará um ambiente WSL dedicado chamado OpenClawGateway, instalará nele o gateway e estabelecerá a ligação. Não afetará a sua instalação existente do Ubuntu, caso tenha uma.

A segunda opção é através do PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw gateway install

A primeira linha instala o OpenClaw; a segunda regista o arranque automático através do Agendador de Tarefas do Windows. Se as políticas do seu computador bloquearem a criação de tarefas, o OpenClaw muda automaticamente para uma alternativa: um atalho na pasta Arranque, para que o gateway inicie quando iniciar sessão.

A terceira opção é o WSL2, que a documentação considera o ambiente de execução mais compatível no Windows. Instale o Ubuntu, ative o systemd e siga as instruções para Linux da secção anterior:

wsl --install -d Ubuntu-24.04

Dentro do WSL, ative o systemd em /etc/wsl.conf (na secção [boot], na linha systemd=true), reinicie o WSL executando wsl --shutdown no PowerShell e instale o OpenClaw com o comando para Linux. Se «distribuição» e «systemd» não significam nada para si, use o Windows Hub; ele faz tudo isto por si.

Como escolher um modelo e concluir a configuração inicial?#

O modelo é o motor do assistente. O assistente de configuração apresenta uma lista de fornecedores; eis três opções práticas:

A Anthropic tem um detalhe útil: se o Claude Code já estiver instalado no seu computador e tiver sessão iniciada, o OpenClaw pode utilizar esse início de sessão. Primeiro, execute claude auth login na máquina e, em seguida, diga ao OpenClaw para o utilizar:

openclaw models auth login --provider anthropic --method cli --set-default

Se o gateway funcionar como serviço em segundo plano (como acontece com --install-daemon), a chave tem de estar disponível para o serviço. Para isso, coloque-a em ~/.openclaw/.env — o assistente fá-lo por si, pelo que não precisa de editar manualmente o ficheiro. Depois de quaisquer alterações, reinicie e verifique:

openclaw gateway restart
openclaw models status

Se tiver dificuldade em pagar, a solução é um modelo local da secção sobre Ollama.

Como ligar o OpenClaw ao Telegram?#

O Telegram é o canal mais rápido de ligar: só precisa de um token de bot, sem verificação de conta empresarial. A documentação descreve-o como a maneira mais fácil de começar a enviar mensagens ao assistente a partir do telemóvel. Eis o processo completo:

1. Crie um bot com o BotFather

   Abra uma conversa no Telegram com o @BotFather (confirme que é exatamente esse nome de utilizador — há muitas falsificações), envie /newbot e escolha um nome e um nome de utilizador terminado em bot. Receberá como resposta um token como 123456789:ABCdef... — é a chave do seu bot, por isso guarde-o como uma palavra-passe.

2. Introduza o token no OpenClaw

   A maneira mais fácil é usar o assistente: execute openclaw configure e selecione o canal Telegram. A alternativa manual é a definição channels.telegram.botToken ou a variável de ambiente TELEGRAM_BOT_TOKEN. A documentação esclarece especificamente que o comando openclaw channels login telegram não existe; o Telegram liga-se apenas através de um token.

3. Inicie o gateway e envie uma mensagem ao bot

   openclaw gateway
   

   Abra o seu bot no Telegram e envie-lhe uma mensagem. Ele responderá com um código de emparelhamento de oito caracteres. É uma medida de proteção: as mensagens não serão processadas até aprovar o remetente.

4. Aprove o seu próprio acesso

   openclaw pairing list telegram
   openclaw pairing approve telegram CODE
   

   O código é válido durante uma hora, por isso não espere demasiado. O primeiro remetente aprovado torna-se automaticamente o proprietário dos comandos privilegiados.

Há dois pontos complicados com que as pessoas se deparam frequentemente.

O primeiro são os grupos. O OpenClaw bloqueia todos os grupos por predefinição: tem de permitir explicitamente o bot nas definições channels.telegram.groups e manter ativado o modo requireMention: true dentro do grupo. Assim, só responderá quando for chamado pelo nome de utilizador e não se intrometerá na conversa geral. O Telegram também tem o seu próprio modo de privacidade dos bots: num grupo, um bot só vê comandos por predefinição. Desative-o com /setprivacy através do @BotFather. Depois de alterar esta opção, tem de remover o bot do grupo e adicioná-lo novamente; caso contrário, o Telegram não aplicará a definição.

O segundo é não abrir o acesso a toda a gente. As definições incluem um modo dmPolicy: "open" com um asterisco na lista de acesso: qualquer pessoa que encontre o bot pelo nome de utilizador pode dar-lhe comandos. Para um assistente pessoal, isso é um caminho direto para deixar outra pessoa controlar a sua máquina. Mantenha ativado o emparelhamento por código ou introduza o seu ID numérico em allowFrom.

Como executar o OpenClaw com um modelo local através do Ollama?#

Esta opção mantém a inferência do modelo no seu hardware quando escolhe um percurso exclusivamente local, sem alternativa automática na nuvem, e não exige um endpoint de modelo pago. Isso não torna todo o fluxo do Telegram local: as mensagens continuam a passar pelo Telegram e as ferramentas online ativadas podem enviar dados para outros serviços.

1. Instale o Ollama

   Descarregue o instalador em ollama.com/download — existem versões para macOS, Windows e Linux.

2. Descarregue um modelo

   ollama pull gemma4
   

3. Ligue o Ollama ao OpenClaw

   openclaw onboard
   

   Escolha o fornecedor Ollama e um modo: Local only (apenas os seus próprios modelos), Cloud only (modelos de ollama.com) ou Cloud + Local. O assistente encontrará o servidor local e apresentará os modelos instalados.

4. Verifique

   openclaw models list --provider ollama
   

Eis a ressalva honesta sem a qual esta secção pareceria publicidade. A documentação do OpenClaw afirma diretamente que a utilização confortável de agentes com um modelo local exige hardware ao nível de dois Mac Studios totalmente equipados, enquanto uma placa gráfica de 24 GB só consegue lidar com pedidos simples, com atrasos. Os modelos pequenos e muito comprimidos truncam o contexto e resistem menos a instruções maliciosas escondidas no texto de outra pessoa. Em termos práticos: um modelo local num bom portátil é suficiente para «experimentar e perceber do que se trata», mas um modelo na cloud continua a ser muito mais fiável para o trabalho diário com um assistente que utiliza ferramentas.

Mais um aviso da documentação, para quem estiver a montar uma configuração WSL2 + Ollama + GPU NVIDIA: o instalador oficial do Ollama para Linux ativa o arranque automático com uma política de reinício «always» e, no WSL2 com uma GPU, isto pode colocar a máquina num ciclo de reinícios. A solução é desativar o arranque automático do serviço. Se isto lhe acontecer, consulte a secção de resolução de problemas da página do Ollama na documentação.

É seguro executar o OpenClaw?#

Vou começar pelo ponto principal, que nem toda a gente compreende. O OpenClaw tem acesso à sua máquina: ficheiros, comandos e browser. A documentação é clara: o projeto foi concebido para um único utilizador de confiança, e não deve dar acesso ao seu bot a pessoas de fora. Se alguém puder enviar mensagens ao seu agente, poderá usá-lo para agir no seu computador.

O mínimo a fazer na prática:

1. Mantenha ativado o emparelhamento por código ou utilize uma lista de acesso — expliquei como configurar isto na secção sobre o Telegram.
2. Não exponha o gateway externamente, a menos que precise. Por predefinição, só escuta na sua máquina; deixe-o assim.
3. Execute a verificação integrada após quaisquer alterações à configuração:

openclaw security audit

Verifica se há acesso aberto, permissões de ferramentas demasiado abrangentes, tokens fracos e portas expostas. Algumas conclusões podem ser corrigidas automaticamente com a opção --fix.

Uma nota separada sobre burlas — e não se trata de algo teórico. Quando o projeto mudou de nome à pressa em janeiro de 2026, bots que ocupavam nomes alheios tomaram conta dos endereços antigos em segundos e publicaram de imediato uma carteira de criptomoedas; falsos «programadores do OpenClaw» começaram a promover uma burla com um token. Daí resultam duas regras inabaláveis. Descarregue o OpenClaw apenas de openclaw.ai ou github.com/openclaw/openclaw. E o projeto não tem criptomoeda: qualquer «token OpenClaw» é uma burla. Não lhe envie dinheiro em circunstância alguma.

O que pode fazer o OpenClaw depois da instalação?#

Eis o que experimentaria, por esta ordem:

1. Gateway e modelo. Execute openclaw gateway status e abra openclaw dashboard. Um painel carregado confirma que a Control UI está acessível. No chat do painel, envie «Responde com: teste de ligação ao modelo» e verifique se chega uma resposta da IA; carregar a página não testa o modelo.
2. Telegram e a tarefa pretendida. Depois de configurar o bot e aprovar o seu próprio emparelhamento, envie uma mensagem nova a esse bot no Telegram e verifique se a resposta chega lá. Depois experimente uma tarefa limitada com resultado visível, como resumir uma pasta de teste inofensiva que lhe autorizou a ler. Para um lembrete, verifique separadamente o agendamento guardado e a entrega do lembrete. Uma resposta no painel não demonstra entrega no Telegram nem execução agendada.
3. Tarefas agendadas. O assistente pode executar tarefas segundo um horário — um resumo matinal no Telegram, verificações regulares de e-mail. É por isso que mantém o gateway a funcionar 24 horas por dia.
4. Memória. O OpenClaw guarda a memória de longo prazo em ficheiros Markdown normais na sua pasta de trabalho: quem é, como lhe deve responder e o que recordou de conversas anteriores. Pode abrir e ler os ficheiros — não há nenhuma caixa negra.
5. Competências. O projeto tem um catálogo de competências e plugins prontos a usar, com verificações de segurança integradas. A competência de outra pessoa é código dessa pessoa na sua máquina, por isso o catálogo verifica-as.

Há uma regra: não ative tudo de uma vez. Comece com uma conversa estável, depois adicione o Telegram e, por fim, os horários. Assim, cada falha aparece na respetiva etapa, em vez de se transformar em «avariou tudo e não sei onde».

O que fazer se a instalação correr mal?#

Vamos percorrer três situações comuns.

«openclaw: command not found» logo após a instalação. Quase sempre é um problema com o caminho: a pasta dos pacotes npm globais não está no PATH do terminal. Estes são os comandos de diagnóstico indicados na documentação:

node -v
npm prefix -g
echo "$PATH"

O caminho do segundo comando deve aparecer no terceiro. Se não aparecer, adicione-o às definições da sua shell ou feche e volte a abrir o terminal: por vezes, o caminho do Node só aparece numa nova sessão após a instalação.

O gateway está a funcionar, mas o assistente está em silêncio. O sintoma descrito nas perguntas frequentes da documentação é este: não há resposta à primeira mensagem e o contador de tokens está a zero. Isso significa que o agente nem sequer foi iniciado — na maioria das vezes, o modelo não está configurado. Verifique por esta ordem:

openclaw gateway restart
openclaw status
openclaw models status

Se houver um modelo configurado e mesmo assim não houver resposta, openclaw logs --follow mostrará o registo em direto e onde o processo está bloqueado.

O bot do Telegram não responde. Verifique por esta ordem: o token pertence ao bot a quem está a enviar mensagens; o gateway está a funcionar (openclaw gateway status); e o seu emparelhamento foi aprovado (openclaw pairing list telegram). Um código de emparelhamento é válido durante uma hora — se enviou uma mensagem ao bot ontem, volte simplesmente a fazê-lo e aprove o novo código.

Quando estiver completamente bloqueado, a documentação sugere algo inesperado, mas sensato: forneça os diagnósticos a um agente de IA local que consiga ver a sua máquina. O Claude Code ou o Codex, se receberem o resultado de openclaw status --all e openclaw doctor, conseguem interpretar a configuração mais depressa do que o chat de suporte. Fecha-se o ciclo — a IA corrige a IA.

Que outras perguntas fazem sobre o OpenClaw?#

Conheça a Ailoot.