📚 Documentação
Cada funcionalidade, cada definição.
Tudo o que a app faz e cada definição que tem — escrito para a versão que está a executar. Da barra de menus ao registo de competências, este é o manual completo.
Nesta página
Início rápido A app da barra de menus Definições, explicadas Separador Modelo Separador Telegram Páginas por bot Separador App Competências e funcionalidades Registo de competências Atualizações Dados e privacidade Resolução de problemasInício rápido
- Instale. Transfira o .dmg e arraste Telebot AI para Aplicações. O build ainda não está notarizado; se o macOS mostrar um aviso, clique com o botão direito (Control-clique) na app e escolha Abrir — uma vez.
- Crie um bot. Envie mensagem para @BotFather no Telegram, execute /newbot e copie o token. Um token por bot — pode executar vários.
- Adicione o token. Abra o Telebot AI a partir da barra de menus, abra as Definições e cole o token no campo Token de um bot. É guardado no momento em que escreve — não há botão de guardar.
- Ligue um cérebro. No separador Modelo, defina o URL do servidor (http://localhost:11234 para mlx-serve, http://localhost:11434 para Ollama) e o nome do modelo, ou use qualquer API cloud compatível com OpenAI. Carregue em Testar para verificar a ligação.
- Inicie o bot. Volte à barra de menus e escolha Iniciar bot. Envie uma mensagem ao seu bot no Telegram — ele responde a partir desse momento.
Novo nos modelos locais? Leia o guia — cobre mlx-serve, Ollama e LM Studio, e quanta RAM cada modelo precisa.
A app da barra de menus
O Telebot AI vive na sua barra de menus (ícone ⌘). O menu dá-lhe:
- Iniciar / Parar / Reiniciar — por bot ou todos de uma vez. Os bots correm como LaunchAgents: sempre ativos, fora do seu caminho.
- Abrir Definições — a janela de definições.
- Registos — acompanhe o registo do bot para ver o que está a fazer ou depurar um problema.
- Sair — para tudo (e desativa os LaunchAgents até iniciar novamente).
Definições, explicadas
A janela de definições tem uma barra lateral com dois tipos de páginas:
- Padrões — Modelo, Telegram, App, Competências e funcionalidades, Registo de competências, Acerca de, Atualizações. Os valores que cada bot herda.
- Bots — uma página por bot. Cada campo mostra o que este bot usa realmente: um valor substitui o padrão, um campo vazio herda-o (o explicador sob cada linha diz isso). É por isso que não há caixas «Usar global» — um campo vazio é «usar global».
Tudo é guardado automaticamente enquanto escreve ou alterna. As definições vivem em ~/.mlx-serve/config.json.
Padrões → Modelo
| Definição | O que faz |
|---|---|
| URL do servidor | O endpoint compatível com OpenAI. Os servidores locais não precisam de chave. |
| Chave API | Vazio para servidores locais (mlx-serve, Ollama, LM Studio). O botão de olho mostra ou esconde-a. |
| Nome do modelo | Que modelo nesse servidor, ex. deepseek-v4-flash-free. |
| Testar | Verifica a ligação com os valores atuais — útil antes de guardar qualquer coisa. |
| Modelos de reserva | Tentados por ordem quando o principal falha ou limita. Cada um tem o seu alcunha, URL, chave e modelo, além de Testar, reordenar e remover. Adicionar fica desativado até a última linha estar completa. |
Padrões → Telegram
| Definição | O que faz |
|---|---|
| IDs de chat permitidos | IDs de utilizador/grupo separados por vírgulas que podem falar com o bot. Vazio = qualquer um. |
| Hora do briefing diário | Quando o bot envia o briefing diário — menus suspensos de hora/minuto em formato 24 h (ex. 08:00). |
| Indicação do briefing | O que o briefing deve cobrir — ex. «meteorologia, os meus lembretes de hoje e quaisquer alertas de preço». |
| Máx. tokens de resposta | Teto de segurança para respostas; respostas longas são divididas em várias mensagens. |
| Contexto por chat | Quantas mensagens recentes o bot mantém por chat como contexto. |
| Memórias por utilizador | Memórias de longo prazo recordadas por utilizador, por cada mensagem que o bot responde. |
| Tamanho da base de memória (por utilizador) | Máximo de memórias armazenadas por utilizador; além disso, as mais antigas são removidas. |
| Tokens dos relatórios de investigação | Orçamento para os relatórios /research e /insiders. |
| Tempo limite da API (s) | Segundos antes de abandonar um fornecedor lento — as filas gratuitas podem demorar mais de um minuto. |
| Ficheiro soul | A personalidade com que os bots correm. Os ficheiros .md desta pasta (soul*.md, *persona*.md) aparecem no menu suspenso Personalidade de cada bot. |
| Palavras de ativação do bot | Palavras separadas por vírgulas que fazem o bot responder em grupos (além de @menção, resposta ou comando) — ex. «momo, jarvis, hey bot». |
| Palavras de ativação de clips de vídeo/áudio | Palavras que fazem o bot capturar um vídeo ou áudio anexado como clip — ex. «clip this, save this». |
Páginas por bot
Cada bot da barra lateral tem a sua própria página. Os campos vazios herdam os padrões; o explicador sob cada linha indica o que é herdado.
| Definição | O que faz |
|---|---|
| Token | O token @BotFather do bot (botão de olho para revelar). Alterá-lo renomeia a entrada do bot na barra lateral. |
| Alcunha | Usada no estado, registos e barra lateral — ex. «Trading». |
| IDs de chat permitidos / Palavras de ativação / Palavras de clip | As substituições deste bot para os padrões correspondentes. |
| URL do servidor, chave API, modelo | O menu suspenso oferece os fornecedores configurados em Padrões → Modelo, além de qualquer valor personalizado. Modelos de reserva próprios podem ser adicionados por bot. |
| Hora do briefing diário / Indicação do briefing | Briefing próprio do bot, com um botão «Usar global» que limpa a substituição. |
| Modo | Investigador, Assistente, Programador, Chef ou Nenhum — vazio usa o modo predefinido. |
| Ficheiro soul | A substituição de personalidade deste bot, escolhida entre os ficheiros soul/persona encontrados no disco. |
| Competências | Abre a folha de competências do bot — desative competências para este bot além dos padrões, ou reponha os padrões. |
Padrões → App
| Definição | O que faz |
|---|---|
| Mostrar no Dock | Se a app da barra de menus também aparece no Dock. |
| Iniciar no início de sessão | Iniciar o Telebot AI no início de sessão. |
| Pasta de dados | Onde vivem a configuração, a memória, os lembretes e os registos (padrão ~/.mlx-serve). |
| Abrir registo / Abrir pasta de dados | Salte diretamente para o ficheiro de registo ou pasta de dados no Finder. |
| Exportar configuração | Guarda a configuração completa (incluindo chaves API) num ficheiro — para cópias de segurança ou mudança de Mac. |
| Importar configuração | Carrega um ficheiro de configuração e aplica-o imediatamente. |
Competências e funcionalidades
As capacidades do bot são competências orientadas pelo modelo — instruções claras que o modelo segue com as suas ferramentas, para descrever o que quer em linguagem natural em vez de memorizar comandos. Cada grupo tem um interruptor mestre; as competências individuais podem ser ligadas ou desligadas.
| Grupo | Competências | Experimente dizer |
|---|---|---|
| Investigação | stock-research, stocks-crypto, insider-trading, currency | «investiga TSLA», «preço do BTC», «transações de insiders para AAPL», «quanto é 50 USD em CAD?» |
| Diário | briefing, digest, reminders, habits, review, pomodoro, bookmarks, expenses | «/briefing», «resume este chat», «lembra-me às 17h», «hábito de hoje feito», «revisão semanal», «/pomodoro 25», «regista 25 de almoço» |
| Multimédia | media, voice, translation, feeds | «analisa este vídeo», «lê isto em voz alta», «traduz isto para português», «o que há de novo nos meus feeds?» |
| Ferramentas | memory | «de que falámos ontem?» |
| Do registo | Competências que instala a partir do registo | — |
Registo de competências
O separador Registo permite instalar competências prontas do catálogo público anthropics/skills — tratamento de PDF e documentos, folhas de cálculo, apresentações, testes de apps web, construção de servidores MCP, arte e mais. Carregue o catálogo, escolha uma competência e ela aparece no separador Competências e funcionalidades como qualquer outra.
Atualizações
O separador Atualizações compara o manifesto do site com a sua versão instalada e mostra a versão mais recente com uma ligação de transferência. As verificações são silenciosas — offline ou inacessível significa apenas «atualizado». Para atualizar: transfira o novo .dmg e arraste-o sobre a app antiga em Aplicações. Definições, bots e memórias vivem fora da app, por isso ficam intactos.
Dados e privacidade
- Onde vivem as coisas: configuração, memória de chat, lembretes, competências e registos ficam todos na sua pasta de dados (padrão ~/.mlx-serve).
- O que sai do seu Mac: a própria API do Telegram, o servidor de modelos para onde aponta o bot, e estatísticas de utilização anónimas (arranques da app e ações de menu). Sem conteúdo de chat, sem tokens, sem dados pessoais.
Resolução de problemas
- «A Apple não consegue verificar se a app contém software malicioso» — é normal: clique com o botão direito (Control-clique) na app em Aplicações → Abrir → Abrir novamente. Uma vez, e depois funciona normalmente.
- O bot não responde. Abra Definições → a página do bot: o token está certo? Depois Padrões → Modelo → Testar o fornecedor. Depois veja o registo (barra de menus → Registos, ou separador App → Abrir registo).
- Respostas lentas ou bot em silêncio. Os fornecedores gratuitos podem demorar mais de um minuto — aumente o tempo limite da API e adicione modelos de reserva para o bot mudar quando o principal limita.
- Servidor local sem resposta. Confirme que o servidor está mesmo a correr (mlx-serve, Ollama…) antes de testar no separador Modelo.
- Atualizações dizem «atualizado» de forma estranha. A verificação é silenciosa por design — se o manifesto estiver inacessível, reporta atualizado.
- Outra coisa? Enviar feedback — cada mensagem chega ao Telegram do programador e recebe uma resposta real.
Transferir Telebot AI · Está a gostar? Oferece-me um café ☕