Como instalar Moltbot em um servidor privado

Configurar o Moltbot (antes conhecido como Clawdbot) em um servidor privado envolve preparar o ambiente do seu VPS (Servidor Virtual Privado), clonar o repositório do Moltbot, executar o script de instalação via Docker, configurar as credenciais do seu provedor de IA e conectar a ferramenta a uma plataforma de mensagens.

No geral, é um processo simples que leva cerca de 30 minutos do início ao fim. E, no final, você já vai ter seu próprio assistente de IA respondendo mensagens 24 horas.

Tecnicamente, dá para rodar o Moltbot no seu notebook, mas isso tem limitações. Se você fechar o computador ou perder a conexão com a internet, o bot sai do ar.

Por isso, instalar em um servidor privado faz tanta diferença. Você garante disponibilidade constante e execução em segundo plano mesmo quando estiver offline — assim, o bot continua rodando 24 horas por dia, 7 dias por semana sem precisar de supervisão.

1. Prepare um servidor privado para o Moltbot.

Para preparar um servidor privado para o Moltbot, você precisa de um VPS Linux com acesso administrativo completo. Essa é a base do projeto, porque um servidor sempre ligado garante que o bot nunca “durma”.

Você não precisa de um supercomputador, mas é importante seguir alguns requisitos para ter estabilidade e evitar dor de cabeça na instalação.

Confira este checklist do servidor:

• Sistema operacional Linux (Ubuntu 22.04 ou 24.04 funciona muito bem).
• Acesso administrativo (permissões de root ou sudo).
• Docker e Docker Compose.
• Pelo menos 2 GB de RAM (4 GB recomendados para melhor desempenho).
• Mais de 10 GB de espaço em disco para imagens Docker, dados de aplicativos e logs.

Para esta configuração, usaremos a hospedagem de Moltbot da Hostinger, porque o Docker Manager facilita bastante o processo. Mas os mesmos princípios valem para qualquer outro provedor de VPS.

Se você está começando agora com servidores virtuais privados, veja primeiro como configurar um VPS. Siga o passo a passo inicial para garantir que você consegue acessar o servidor via SSH antes de continuar.

2. Verifique se o Docker está disponível no VPS

O Docker é como vamos rodar o Moltbot. Pense nele como um container que “empacota” tudo o que o Moltbot precisa em um único lugar. Em vez de instalar dependências manualmente e ajustar configurações uma por uma, o Docker cuida disso. O resultado é uma instalação mais limpa, mais confiável e muito mais fácil de gerenciar.

No hPanel da Hostinger, procure pelo Docker Manager. Ele deve mostrar o Docker como instalado (ou oferecer a opção de ativar). Esse é o caminho mais simples.

Se você estiver usando outro VPS ou quiser confirmar pelo terminal, conecte via SSH e execute:

docker --version
 
docker compose version

Você deve ver o número da versão do Docker e do Docker Compose. Se aparecer “command not found”, significa que o Docker ainda não está instalado.

Uma instalação correta do Moltbot com Docker depende de um ambiente saudável, então se você precisar fazer uma instalação manual, leia nosso tutorial sobre como instalar Docker no Ubuntu e depois repita a verificação.

Assim que o Docker estiver confirmado e em execução, você seguir para a parte prática de deploy do Moltbot.

3. Clone o repositório do Moltbot

Agora vem a parte boa. Vamos clonar o repositório do Moltbot e usar o script oficial de setup com Docker para montar e colocar tudo no ar.

Primeiro, você precisa baixar o código do Moltbot no seu servidor:

# Instale o git (se ainda não tiver)

sudo apt install git -y

# Clone o repositório

git clone https://github.com/moltbot/moltbot.git

# Entre na pasta do projeto

cd moltbot

Em seguida, execute o script de setup do Docker. O Moltbot já inclui um script que automatiza praticamente tudo:

./docker-setup.sh

Esse script é o “pacote completo” para colocar o Moltbot rodando. Ele faz o seguinte:

1. Cria a imagem Docker do Moltbot localmente (usando o Dockerfile do próprio projeto).
2. Executa o assistente de configuração inicial dentro de um container Docker.
3. Gera um gateway token para acessar a Control UI.
4. Cria os diretórios de configuração necessários.
5. Inicia o gateway do Moltbot via Docker Compose.

Todo o processo é automatizado. Diferente de muitos apps em Docker, em que você só baixa uma imagem pronta, o Moltbot cria a imagem localmente no seu servidor. Isso significa que:

• Você sempre roda exatamente a versão que está no repositório.
• A primeira build pode levar alguns minutos.
• As próximas builds ficam mais rápidas graças ao cache de camadas do Docker.
• Você tem controle total sobre o que entra na imagem.

4. Configure credenciais e configurações do Moltbot

O script de setup do Docker abre um assistente interativo de configuração inicial que prepara o Moltbot para você. É aqui que você define as credenciais do provedor de IA e outras configurações essenciais.

Ao executar o script ./docker-setup.sh, depois que a imagem é criada, o assistente aparece e faz algumas perguntas importantes:

Modo gateway:

• Local (rodar nesta máquina)
• Remote (conectar a um gateway existente)

Escolha Local. Assim, o gateway vai rodar no seu VPS.

Método de autenticação:

Essa é a parte mais importante, porque é onde você informa como o Moltbot vai acessar os modelos de IA:

• Anthropic API Key (recomendado)
• OpenAI API Key
• OAuth (assinatura Claude Pro/Max)
• OpenAI Code (assinatura Codex)

Se você seguir a opção recomendada (Anthropic API Key), o processo é assim: crie uma conta (ou faça login) na Anthropic, vá até a seção de API Keys, gere uma nova chave, copie e cole no assistente.

Guarde essa chave com segurança. Qualquer pessoa com acesso a ela pode usar o Claude na sua conta — e o consumo será cobrado de você.

Com as outras opções, a lógica é parecida: você pega a chave na plataforma de IA e adiciona no setup. O assistente salva essas credenciais como variáveis de ambiente no Linux dentro dos arquivos de configuração.

Depois disso, você escolhe o modelo da plataforma selecionada e ajusta as configurações de segurança.

Um dos erros mais comuns na configuração do Moltbot é esquecer a API key. Sem uma chave válida da Anthropic ou da OpenAI, ele simplesmente não funciona. Além disso, tanto a Anthropic quanto a OpenAI exigem um método de pagamento cadastrado para liberar acesso via API — então confirme que sua chave está ativa e com billing configurado.

5. Inicie o Moltbot e confirme que ele está rodando

Depois que o script de setup termina, o Moltbot já deve estar em execução.

Para confirmar que está tudo certo, verifique o status dos containers:

# Garanta que você está no diretório do Moltbot

cd ~/moltbot

# Veja os containers em execução

docker compose ps

Você deverá ver o moltbot-gateway com status “Up” ou “Running”. Outros sinais de que está tudo funcionando incluem:

• Uma mensagem do tipo “Moltbot initialized”
• Provedor de modelo conectado (Anthropic/OpenAI)
• Nenhum erro de autenticação

Por outro lado, se aparecer algo como “Invalid API key”, “Authentication failed”, “Connection refused”, ou se o container ficar reiniciando sem parar, então existe algum problema na configuração.

Nesse caso, pare por aqui e corrija antes de continuar, checando os logs:

docker compose logs moltbot-gateway

Isso é importante para a resolução de problemas. Os logs do Moltbot mostram exatamente o que o bot está tentando fazer, ajudando você a identificar e resolver o erro com mais rapidez.

6. Acesse a interface do Moltbot

O painel do Moltbot fica disponível pelo IP do seu VPS na porta 18789:

http://ip-do-seu-vps:18789

Por exemplo: http://45.123.45.67:18789

Na primeira vez que você abrir a Control UI, será necessário informar o gateway token gerado durante a configuração. Você pode encontrá-lo com:

cat ~/.clawdbot/.env | grep CLAWDBOT_GATEWAY_TOKEN

Outra opção é conferir o output do comando ./docker-setup.sh — ele mostra o token no final do processo.

Observação: apesar de o projeto ter sido renomeado para Moltbot, alguns arquivos e diretórios de configuração ainda usam o nome “clawdbot” (como ~/.clawdbot/ e CLAWDBOT_GATEWAY_TOKEN). Isso é normal durante a transição e não afeta o funcionamento.

Depois de entrar no painel, vá em Settings → Token (ou você pode ser direcionado automaticamente). Cole o gateway token e clique em Save ou Authenticate.

Essa interface é o seu centro de controle. Você não precisa configurar tudo agora — o mais importante é confirmar que consegue acessar e que o Moltbot aparece como saudável (healthy).

Se você não conseguir abrir a interface, tente estes passos de solução de problemas:

• Verifique se o container está em execução: docker compose ps
• Verifique se o seu firewall não está bloqueando a porta.
• Garanta que você está usando HTTP, não HTTPS
• Teste o acesso direto no próprio servidor via terminal: curl http://localhost:18789

7. Conecte um canal de mensagens ao Moltbot

O painel web que você configurou serve para gerenciamento. Mas a interação com o Moltbot acontece mesmo por um app de mensagens, onde as conversas com IA rolam no dia a dia.

Aqui vamos usar o Telegram porque é bem simples, mas o processo é parecido em outras plataformas.

Veja como fazer a configuração do Moltbot no Telegram:

Passo 1: crie um bot no Telegram

1. Abra o Telegram e procure por @BotFather
2. Inicie um bate-papo e envie /newbot
3. Siga as instruções:
   • Escolha um nome (por exemplo, Meu Assistente Moltbot)
   • Escolha um nome de usuário (deve terminar em “bot”, como “myawesomemoltbot”)
4. O BotFather vai gerar um bot token. Copie esse token.

Passo 2: adicione o Telegram ao Moltbot

No seu servidor, execute:

# Garanta que você está no diretório do Moltbot

cd ~/moltbot

# Adicione o Telegram usando o token do bot

docker compose run --rm moltbot-cli providers add --provider telegram --token TOKEN_DO_SEU_BOT

Substitua TOKEN_DO_SEU_BOT pelo token que você recebeu do BotFather.

Passo 3: ative as permissões necessárias do bot

No chat do BotFather:

1. Envie /mybots
2. Selecione seu bot
3. Vá em Bot Settings → Group Privacy
4. Desative a privacidade de grupo (isso permite que o bot leia mensagens em grupos).

Passo 4: Comece a conversar

1. Abra o Telegram e procure pelo seu bot (pelo nome de usuário que você escolheu).
2. Inicie uma conversa
3. Envie uma mensagem para testar.

Se você configurou o pareamento por DM durante o setup, você vai receber um código de pareamento. No servidor, aprove esse código com:

docker compose run --rm moltbot-cli pairing approve telegram <o-codigo-que-voce-recebeu>

Após a aprovação, envie outra mensagem. O Moltbot deve responder!

Se as mensagens não estiverem funcionando na sua configuração do Moltbot com Telegram:

• Verifique os logs do Moltbot para encontrar erros.
• Confirme se as API keys continuam válidas.
• Veja se o container não reiniciou ou caiu.
• Garanta que as credenciais da plataforma de mensagens estão corretas.

Como resolver problemas comuns na instalação do Moltbot

Para solucionar problemas comuns na configuração do Moltbot, comece verificando o status do container, confirme se o gateway token está correto e analise os logs em busca de mensagens de erro específicas. A maioria dos problemas cai em alguns cenários bem previsíveis — e, quando você sabe o que procurar, costuma ser rápido de resolver.

A seguir estão os erros mais comuns quando o Moltbot não funciona como esperado.

Container fica parando

Se o container inicia e logo em seguida para:

1. Verifique o estado do container: docker compose ps
2. Veja os logs para identificar erros: docker compose logs moltbot-gateway
3. Procure o erro específico: docker compose logs moltbot-gateway | grep -i “error”

As causas mais comuns incluem API key ausente ou inválida, porta 18789 já em uso, problemas na configuração do Docker Compose ou permissões insuficientes.

Falhas de autenticação

Esse é, de longe, o problema mais frequente. Se você ver mensagens como “authentication failed”, “invalid API key” ou requisições ao modelo falhando, revise sua API key:

cat ~/.clawdbot/.env

Procure por ANTHROPIC_API_KEY ou OPENAI_API_KEY. Certifique-se de que:

• A chave existe e não está vazia
• Não há espaços extras nem aspas desnecessárias
• A chave não foi revogada e não expirou

Também vale conferir no painel da plataforma de IA se a chave está ativa e se o billing está configurado, já que Anthropic e OpenAI exigem cobrança ativa para uso de API.

Depois, atualize as credenciais e reinicie o gateway:

# Edite o arquivo .env
nano ~/.clawdbot/.env

# Adicione ou atualize sua API key
ANTHROPIC_API_KEY=sua_chave_real_aqui

# Reinicie o gateway
docker compose restart moltbot-gateway

Conflito de portas

Se aparecer “port already in use” ou “address already in use”:

• Verifique o que está usando a porta: sudo lsof -i :18789
• Altere a porta do Moltbot editando o arquivo docker-compose.yml.
• Use um mapeamento de porta diferente, como por exemplo: -p 18790:18789

Loop de reinicialização do container

Se o container fica reiniciando sem parar, geralmente é por variáveis de ambiente faltando, arquivos de configuração corrompidos, configuração inválida do modelo ou problemas de permissão.

Para corrigir:

• Pare tudo: docker compose down
• Remova containers e volumes antigos: docker compose down -v
• Refaça o build e reinicie o setup: ./docker-setup.sh

Não consigo acessar a interface

Se o container está rodando, mas o painel não abre:

• Verifique as regras do firewall e permita a porta 18789: sudo ufw allow 18789/tcp
• Verifique se o container está escutando: curl http://localhost:18789
• Também vale checar as configurações do provedor do VPS, já que alguns exigem ajustes em “security groups” para liberar tráfego de entrada na porta 18789.

Reiniciar com segurança

Você vai precisar reiniciar o Moltbot quando mudar variáveis de ambiente, quando o bot ficar sem responder ou depois de ajustes específicos de configuração.

Reiniciar também ajuda a resolver comportamentos estranhos, porque um “start limpo” pode eliminar problemas que não aparecem claramente nos logs.

Para reiniciar rápido:

docker restart moltbot-gateway

Ou, para uma reinicialização completa, onde você para e inicia o container manualmente (útil quando você deseja mais controle sobre o processo ou precisa verificar se o container parou completamente):

docker stop moltbot-gateway

docker start moltbot-gateway

Quais são as melhores práticas para rodar o Moltbot?

As melhores práticas para rodar o Moltbot incluem manter o gateway token em segurança, monitorar o uso de recursos com regularidade e ficar em dia com as atualizações.

Rodar um bot de IA em um servidor traz responsabilidades, mas elas são bem administráveis quando você cria bons hábitos desde o início — principalmente em segurança, manutenção e monitoramento.

Práticas de segurança

• Nunca compartilhe seu gateway token. Trate como uma senha, porque qualquer pessoa com esse token pode controlar o seu bot.
• Use firewall. Exponha apenas as portas que você realmente precisa (como a 18789 para a interface).
• Mantenha o SSH seguro. Prefira autenticação por chave (SSH key) em vez de senha.
• Restrinja o acesso ao painel. Se você não precisa que o dashboard seja público, use VPN ou whitelist de IP.

Gerenciamento de recursos

O Moltbot é relativamente leve, mas você ainda deve ficar de olho em:

• Uso de memória. Verifique ocasionalmente com docker stats moltbot-gateway
• Espaço em disco. Logs podem acumular. Se for rodar por muito tempo, considere configurar rotação de logs.
• Uso de CPU. Picos durante conversas são normais, mas uso alto constante pode indicar algum problema.

Se você notar gargalos, pode ser necessário fazer upgrade no VPS ou investigar o que está causando consumo excessivo.

Estratégia de atualizações

Novas versões do Moltbot são lançadas periodicamente com melhorias e correções.

• Verifique atualizações todo mês (ou acompanhe os anúncios do projeto).
• Se possível, teste atualizações antes em um ambiente que não seja produção.
• Faça backup da configuração atual antes de atualizar.
• Leia as release notes para entender o que mudou.

Monitoramento do tempo de atividade

Tenha um monitoramento básico para saber se o Moltbot saiu do ar:

• A política de restart do Docker ajuda na recuperação automática.
• Use um monitor de uptime simples (existem várias opções gratuitas).
• Confira os logs de tempos em tempos para detectar erros ou avisos incomuns.
• Teste seus canais de mensagens ocasionalmente para confirmar que está tudo respondendo.

Backup do setup

Suas variáveis de ambiente (principalmente o gateway token) são parte essencial do setup. Por isso, documente tudo com segurança:

• Guarde o token em um gerenciador de senhas.
• Mantenha anotações sobre as configurações que você usou.
• Documente quaisquer variáveis de ambiente personalizadas que você adicionou.

Como gerenciar o Moltbot depois da instalação

Para gerenciar o Moltbot após a configuração inicial, acompanhe os logs com frequência, atualize o container quando novas versões forem lançadas e fique de olho nas métricas de desempenho.

No dia a dia, o trabalho é mínimo quando tudo está rodando bem — mas um pouco de atenção contínua ajuda a manter o sistema saudável. Veja o que você precisa fazer.

Verifique os logs regularmente.

Crie o hábito de consultar os logs semanalmente usando:

docker compose logs --tail 100 moltbot-gateway

Procure por erros ou avisos repetidos, problemas de performance, falhas de conexão ou qualquer padrão estranho.

Na maioria das vezes, você vai ver apenas o funcionamento normal — mas identificar sinais de problema cedo evita dor de cabeça depois.

Atualize o Moltbot

Quando sair uma nova versão, use o setup para puxar o código mais recente:

git pull

Depois, rode o script novamente (isso mantém sua configuração):

./docker-setup.sh

Monitore a disponibilidade

Verifique o status do container de tempos em tempos. Ele deve aparecer como “Up”. Se estiver reiniciando com frequência, vale investigar pelos logs.

Monitore o desempenho

A cada algumas semanas, confira o uso de recursos:

docker stats moltbot-gateway

Isso mostrará o uso de CPU, memória e rede em tempo real. Se o consumo estiver alto, você pode:

• Investigar o motivo (olhando os logs)
• Fazer upgrade do VPS, caso a configuração atual não esteja mais dando conta
• Ajustar sua configuração para otimizar o uso

Na maioria dos casos, você não precisa se preocupar com escalabilidade, cluster ou otimizações complexas. O Moltbot costuma rodar bem em um único VPS para uso pessoal ou em times pequenos.

O foco é manter tudo estável: rodando com confiança, atualizando quando necessário, monitorando erros e cuidando do básico de segurança.

Para uma referência rápida aos comandos do Docker que você usará ao gerenciar o Moltbot, consulte este guia de referência rápida do Docker.

Todo o conteúdo dos tutoriais deste site segue os rigorosos padrões editoriais e valores da Hostinger.