Pi Bot

Um assistente pessoal no Telegram ou no WhatsApp.

Um container, um volume, nenhum painel web. Roda no harness do pi.dev. Você escolhe o modelo. As ferramentas vêm do Composio, do Executor, do Upsy ou de um gateway MCP seu.

GitHub Instalar

Beta. A configuração e os comandos ainda podem mudar entre versões.

Instalar
# Nada no .env é obrigatório para subir.
git clone https://github.com/forge-z/pi-bot.git
cd pi-bot
cp .env.example .env
docker compose up -d --build
# Gateway, modelos e MCP. O serviço se chama pi-bot.
docker compose exec pi-bot npm run setup

Os valores no .env são overrides opcionais. Se o gateway já estiver rodando na hora de parear o WhatsApp, leia o QR em docker compose logs.

O chat de um lado, as ferramentas do outro

  1. 01

    A mensagem chega no Telegram ou no WhatsApp. Um gateway por instalação.

  2. 02

    Só a lista de permitidos recebe resposta. O resto é ignorado.

  3. 03

    O modelo de texto que você escolheu responde. Um modelo de imagem lê fotos e um de áudio transcreve mensagens de voz. A resposta é texto.

  4. 04

    O que sai do chat passa por ferramentas MCP que você conecta. Uma chamada que precisa de aprovação espera você.

Configuração, credenciais e conversas ficam em SQLite no volume, em /app/data. A imagem é somente leitura. O assistente não tem shell, sistema de arquivos nem navegador próprios.

Cinco passos, no terminal

npm run setup edita uma seção por vez. Enter mantém o valor salvo. Segredos ficam ocultos. Save and back grava a seção.

  1. Abra o menu

    Com o container no ar, rode npm run setup. Um container novo continua saudável enquanto espera. O menu lista gateway, modelo de texto, de imagem, de áudio e plataforma MCP.

    Terminal com o menu principal do npm run setup: gateway, modelo de texto, de imagem, de áudio e plataforma MCP.
    O menu do setup.
    Captura: menu do setup
  2. Escolha o gateway

    Telegram ou WhatsApp. Salvar um desliga o outro. Quem nunca escolhe fica no Telegram.

    O Telegram pede o token do bot e os ids numéricos autorizados a falar com ele.

    Terminal com Setup gateway e as opções Telegram e WhatsApp.
    Um gateway por instalação.
    Captura: Setup gateway
  3. Vincule o WhatsApp

    O número do dono, com código do país. Números extras são opcionais. Depois, pareie com um QR em Aparelhos conectados, ou com um código. A sessão fica no volume.

    Terminal com o menu do WhatsApp: números permitidos, parear com QR e parear com código.
    Números permitidos, depois um QR ou um código.
    Captura: pareamento do WhatsApp
  4. Escolha os modelos

    Texto: qualquer provedor oficial do pi-ai, com chave, ou login do ChatGPT Plus/Pro sem chave. Imagem e áudio são opcionais.

    Terminal na seção Text model, no começo da lista de provedores, incluindo ChatGPT.
    Modelo de texto. O setup para antes de um login externo.
    Captura: modelo de texto
  5. Conecte as ferramentas

    Plataforma MCP: Composio, Executor, Upsy, um gateway self-hosted, Executor mais Composio, ou nenhum. Save and restart gateway recarrega o bot a partir do volume, sem rebuild. /status mostra modelo, MCPs e versão.

    Terminal com a configuração salva e a opção Save and restart gateway.
    Gravado no volume. O gateway reinicia a partir dele.
    Captura: setup concluído

Como é uma conversa

As duas imagens são mockups. Nomes e números nelas são fictícios.

WhatsApp

Mockup de um chat consigo mesmo no WhatsApp. As respostas do assistente começam com Pi:.
Mockup de um chat no WhatsApp.
Mockup: chat no WhatsApp
  • Respostas em texto puro. Títulos e negrito viram *negrito* do WhatsApp.
  • Aprovações são uma lista numerada. Responda com o número.
  • No chat da própria conta vinculada, as respostas começam com Pi: .

Telegram

Mockup de um chat no Telegram com o assistente.
Mockup de um chat no Telegram.
Mockup: chat no Telegram
  • O menu de comandos é registrado na inicialização.
  • Aprovações chegam com botões.
  • Cada tópico de fórum tem histórico, modelo e esforço próprios.

O que ele faz hoje

Gateway
Telegram pela Bot API, ou WhatsApp vinculado como aparelho. Um por instalação, com lista de permitidos.
Modelo
Qualquer provedor oficial do pi-ai, ou ChatGPT Plus/Pro. Troque com /model e /thinking.
Fotos e áudio
Um modelo de visão lê fotos. Um de áudio transcreve mensagens de voz. A resposta continua texto.
Agendamentos
Peça um lembrete único ou um cron de cinco campos, cada um com seu fuso. A execução fica em silêncio se não tiver o que dizer. /crons gerencia.
Ferramentas
Composio, Executor, Upsy (OAuth, sem chave), um gateway self-hosted, ou uma lista JSON de servidores MCP extras.
Aprovações
Quando o Executor pausa uma chamada, o bot repassa. Uma escrita com resultado incerto não é reenviada. /resume continua ou descarta.
Conversas
/new começa outra e guarda a anterior no volume. /compact condensa uma conversa longa. No Telegram, cada tópico de fórum é separado.
Skills
Pastas SKILL.md no volume, nomeadas no config.yaml. O modelo pode lê-las em toda resposta, inclusive nas execuções agendadas.
Tarefas de código
sandbox_code_task roda um trabalho longo numa máquina Instabox. Fica desligado até você configurar. A allow list de repositórios começa vazia. Push e pull request esperam aprovação.
Hospedagem
Docker Compose, imagem somente leitura, capabilities removidas e health check. Segredos configurados são redatados nos logs.

Comandos

No Telegram eles aparecem no menu do bot. No WhatsApp, digite. Os nomes continuam em inglês.

Comando O que faz
/status Modelo, tokens e custo, MCPs e versão
/model Escolhe o provedor e o modelo
/thinking Escolhe o esforço de raciocínio
/crons Lista os agendamentos. No WhatsApp, responda com o número para ligar ou desligar
/new Começa outra conversa. A anterior fica no volume
/compact Condensa esta conversa. O texto depois do comando é um foco opcional
/resume Retoma uma tarefa travada, ou descarta um resultado incerto
/stop Interrompe o trabalho atual
/help Mostra a lista

Perguntas

Dá para usar Telegram e WhatsApp na mesma instalação?

Não. Cada instalação tem um gateway. Salvar o WhatsApp desliga o Telegram, e o contrário. Quem nunca escolhe fica no Telegram.

A conexão com o WhatsApp é oficial?

Não. O gateway usa Baileys, que fala o protocolo não oficial do WhatsApp Web, e isso pode levar a restrições na conta.

Preciso de uma chave de API?

Não para o login do ChatGPT Plus/Pro. Os outros provedores oficiais do pi-ai pedem a chave deles no setup.

Onde ficam os dados?

No volume Docker pi_bot_data, montado em /app/data: configuração, credenciais, conversas e a sessão do WhatsApp. A imagem é somente leitura.

Ele responde com voz?

Não. Transcreve áudio quando há um modelo de áudio, mas responde em texto. Uma ferramenta pode gerar um arquivo de áudio. Um balão de voz não está implementado.

Dá para usar em produção?

O Pi Bot está em beta: serve para o dia a dia, mas configuração e comandos ainda podem mudar. Faça backup do volume antes de atualizar.