O OpenClaw é um assistente de IA pessoal que você instala no seu próprio servidor. A grande sacada dele não é mais uma interface de chat no navegador, e sim a capacidade de conversar com você nos aplicativos de mensagem que você já usa todos os dias: WhatsApp, Telegram, Slack, Discord e mais de uma dezena de outros canais. Em vez de abrir uma aba no navegador, você manda mensagem para um contato no Telegram e recebe a resposta de um modelo de IA por trás.
Para que isso funcione 24 horas por dia, sem depender do seu notebook ligado, o OpenClaw precisa rodar em algum lugar estável. Por isso o cenário mais comum é colocar ele em um VPS Linux. Neste guia vamos instalar o OpenClaw em um VPS, conectar um bot do Telegram e enviar a primeira mensagem em cerca de 15 minutos. O guia foi escrito para iniciantes que sabem se conectar via SSH e copiar comandos no terminal.
Conceitos principais do OpenClaw
Antes de partir para o terminal, vale entender cinco palavras que vão aparecer o tempo todo. Gateway é o processo principal que roda no servidor. Ele escuta na porta 18789, mantém o estado das conversas e direciona mensagens entre os canais e o modelo de IA. Channels são os aplicativos de mensagem conectados, como Telegram, WhatsApp, Slack e Discord. Cada channel é uma porta de entrada para o assistente.
Agents representam a personalidade do bot, com prompt e configurações próprias. A descrição de cada agente fica em um arquivo SOUL.md, e dá para manter vários agentes em paralelo (um para trabalho, outro pessoal, outro focado em código). Skills são extensões modulares que ampliam o que o agente sabe fazer: navegar na web, executar comandos, consultar APIs externas. Cada skill mora em ~/.openclaw/workspace/skills/<skill>/SKILL.md. Por fim, Models são os provedores de LLM externos: Anthropic Claude, OpenAI, Google Gemini. O OpenClaw não roda o modelo no seu servidor; ele apenas usa a API desses provedores. Toda a configuração do sistema fica em ~/.openclaw/openclaw.json.
Como o OpenClaw funciona
A arquitetura é mais simples do que parece. O Gateway funciona como uma central de controle. Ele não conversa direto com o usuário; em vez disso, fica entre dois mundos: de um lado, os mensageiros como Telegram; do outro, a API do provedor de LLM.
Quando você manda uma mensagem para o bot no Telegram, o caminho é o seguinte. O Telegram entrega a mensagem ao Gateway via long polling. O Gateway identifica em qual sessão essa conversa está, monta o contexto (histórico, instruções do agente, skills disponíveis) e envia tudo para a API do modelo escolhido. O modelo gera a resposta, devolve para o Gateway, e o Gateway entrega para o Telegram, que mostra a mensagem na tela do seu celular.
O que fica armazenado no servidor: histórico de diálogos, configurações dos agentes, skills instaladas e o arquivo de configuração. O que sai para fora: apenas o texto enviado para a API do provedor de LLM. Isso significa que dá para trocar de modelo (passar do Claude para o GPT, por exemplo) sem perder o histórico, e que o servidor é a fonte da verdade. Por isso vale fazer backup da pasta ~/.openclaw/ periodicamente.
A vantagem em relação a um chatbot web fica clara aqui. O bot está sempre online, lembra o que foi conversado antes, é acessível pelo aplicativo de mensagem que você já usa no celular, e dá para integrar com ferramentas de trabalho.
Casos de uso
Os cenários mais frequentes para um deploy do OpenClaw em VPS são:
- Assistente pessoal no WhatsApp ou Telegram. O bot responde como um contato comum, com memória entre conversas, disponível direto da palma da mão.
- Bot de equipe no Slack ou Discord. O assistente atende perguntas dentro do canal, ajuda com documentação interna e automatiza respostas de suporte.
- Automação de rotina. Lembretes, triagem de e-mails, monitoramento de repositórios no GitHub, acompanhamento de tarefas, tudo via mensagem.
- Ajudante de código no celular. Você manda uma dúvida sobre um trecho de código pelo Telegram durante o trajeto e recebe a explicação na hora.
- Triagem de mensagens. Resumo de conversas longas em grupos, classificação de notificações por prioridade, extração de itens de ação.
Requisitos e preparação do servidor
O OpenClaw é leve quando comparado a soluções que rodam o modelo localmente, justamente porque o LLM mora na nuvem do provedor. Ainda assim, vale ter folga de memória para o Gateway e para a build do daemon na primeira execução.
| Recurso | Mínimo | Recomendado |
|---|---|---|
| RAM | 1 GB | 2 GB |
| CPU | 1 vCPU | 2 vCPU |
| Disco | 10 GB SSD | 20 GB SSD |
| Sistema | Ubuntu 22.04 / Debian 12 | Ubuntu 24.04 LTS |
| Node.js | 22.14+ | 24 LTS |
| Acesso | SSH com chave | SSH com chave |
Para esse guia vamos usar um VPS Linux com Ubuntu 24.04. Qualquer provedor que ofereça VPS com pelo menos 2 GB de RAM atende. Se você ainda não tem um servidor pronto, dá para alugar um VPS na Serverspace em poucos minutos e seguir o guia direto. Antes de instalar qualquer coisa, conecte ao servidor por SSH e mantenha a aba aberta para os próximos passos.
Instalação passo a passo
Passo 1. Conectar ao servidor e atualizar o sistema
Conecte ao VPS por SSH usando o cliente da sua preferência. No terminal, atualize a lista de pacotes e aplique as atualizações pendentes:
sudo apt update && sudo apt upgrade -yIsso garante que o sistema parta de uma base atualizada e evita surpresas com bibliotecas defasadas durante a instalação.
Passo 2. Instalar o OpenClaw
A forma mais rápida é o script oficial. Ele detecta o sistema, instala o Node.js 24 caso ainda não exista no servidor, baixa o OpenClaw e prepara o ambiente:
curl -fsSL https://openclaw.ai/install.sh | bashSe você já administra o Node.js no servidor por conta própria, dá para usar o npm direto:
npm install -g openclaw@latestA escolha entre os dois caminhos é gosto. Para iniciantes, o script oficial é o atalho mais seguro porque cuida da versão do Node automaticamente.
Passo 3. Executar o onboarding
Com o OpenClaw instalado, rode o assistente de configuração:
openclaw onboard --install-daemonA opção --install-daemon configura o Gateway como serviço do systemd em modo usuário, o que faz com que ele suba sozinho depois de reinicializações. O assistente vai perguntar três coisas:
- Provedor de LLM. Escolha entre Anthropic, OpenAI, Google ou outros.
- Chave de API. Cole a chave gerada no console do provedor escolhido. Sem essa chave, o bot não responde nada.
- Configurações do Gateway. Pode aceitar os padrões e seguir.
A chave de API é gerada no painel de cada provedor (console.anthropic.com, platform.openai.com, ai.google.dev). Esse passo precisa ser feito antes do onboarding, porque o assistente vai pedir a chave logo de cara.
Passo 4. Verificar se o Gateway está rodando
Confirme que o Gateway subiu corretamente:
openclaw gateway statusA saída deve indicar que o Gateway está escutando na porta 18789. Para uma checagem mais completa do estado da configuração, use:
openclaw doctorEsse comando aponta problemas comuns: chave de API ausente, conflito de versão, permissões erradas. Se algo aparecer aqui, vale resolver antes de seguir.
Passo 5. Conectar o Telegram
O Telegram é o canal mais simples para começar, porque exige apenas um token. Abra o Telegram e converse com @BotFather. Envie o comando /newbot, escolha um nome e um username terminado em bot. O BotFather devolve um token no formato 123456:ABC-DEF.... Copie esse valor.
Em seguida, abra o arquivo de configuração do OpenClaw:
nano ~/.openclaw/openclaw.jsonE adicione o bloco do Telegram dentro de channels:
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "SEU_TOKEN_AQUI",
"dmPolicy": "pairing"
}
}
}
Salve o arquivo e reinicie o Gateway para aplicar as mudanças:
openclaw gateway restartAgora abra a conversa com o bot que você criou e mande qualquer mensagem. O Gateway vai exigir um pareamento na primeira interação. No servidor, liste os pedidos pendentes:
openclaw pairing list telegramAprove o código que aparecer:
openclaw pairing approve telegram <CODIGO>Passo 6. Enviar a primeira mensagem
Volte para o Telegram e envie uma pergunta ao bot. A resposta deve chegar em poucos segundos, gerada pelo modelo que você escolheu no passo 3. Pronto: o assistente está rodando 24 horas por dia no seu servidor e responde direto no aplicativo. Se nada acontecer, siga para a seção de erros comuns abaixo.
Erros comuns e como resolver
Mesmo seguindo cada passo, alguns tropeços aparecem com frequência. A tabela abaixo cobre os mais comuns.
| Sintoma | Causa | Solução |
|---|---|---|
openclaw: command not found após a instalação |
O diretório bin global do npm não está no $PATH |
Adicionar $(npm prefix -g)/bin ao ~/.bashrc e abrir um novo terminal |
| Build interrompida com exit code 137 (OOM) | VPS com menos de 2 GB de RAM | Aumentar o plano para 2 GB ou usar o script oficial em vez do build do Docker |
| O bot não responde em grupos do Telegram | Privacy Mode do bot ativo por padrão | No BotFather, executar /setprivacy e marcar Disable, depois remover e adicionar o bot ao grupo de novo |
Conflito getUpdates 409 nos logs |
Duas instâncias do Gateway usando o mesmo token | Parar a instância duplicada e reiniciar o Gateway com openclaw gateway restart |
| O bot não responde nem para o dono | allowFrom vazio ou ausente |
Adicionar o ID numérico do Telegram em channels.telegram.allowFrom e reiniciar o Gateway |
Para diagnosticar qualquer problema fora dessa lista, acompanhe os logs em tempo real:
openclaw logs --followBoa parte das falhas aparece com mensagem clara nessa saída.
Conclusão
Em cerca de 15 minutos saímos de um VPS limpo para um assistente de IA acessível pelo Telegram, com memória entre diálogos e disponível 24 horas por dia. O passo natural seguinte é conectar mais canais (WhatsApp, Slack, Discord), adicionar skills para ampliar o que o agente sabe fazer, criar um segundo agente com personalidade diferente e configurar backup automático da pasta ~/.openclaw/.
A peça que mantém tudo em pé é o servidor. Como o Gateway guarda histórico, configurações e estado dos canais, vale rodar em um VPS estável com IP fixo. Para quem precisa subir uma máquina rápida, o catálogo de planos de VPS da Serverspace cobre as configurações citadas neste guia, com sistemas Ubuntu prontos para o apt install.
