📚 Documentazione
Ogni funzione, ogni impostazione.
Tutto ciò che l'app fa e ogni impostazione che ha — scritto per la versione che stai eseguendo. Dalla barra menu al registro skill, questo è il manuale completo.
In questa pagina
Guida rapida L'app della barra menu Impostazioni, spiegate Scheda Modello Scheda Telegram Pagine per bot Scheda App Skill & Funzioni Registro Skill Aggiornamenti Dati & privacy Risoluzione dei problemiGuida rapida
- Installa. Scarica il .dmg, trascina Telebot AI in Applicazioni. La build non è ancora notarizzata, quindi se macOS mostra un avviso, clic destro (Control-clic) sull'app e scegli Apri — una volta sola.
- Crea un bot. Scrivi a @BotFather su Telegram, esegui /newbot e copia il token. Un token per bot — puoi eseguirne diversi.
- Aggiungi il token. Apri Telebot AI dalla barra menu, apri Impostazioni e incolla il token nel campo Token di un bot. Viene salvato nel momento in cui scrivi — non c'è un pulsante Salva.
- Collega un cervello. Nella scheda Modello, imposta l'URL del server (http://localhost:11234 per mlx-serve, http://localhost:11434 per Ollama) e il nome del modello, oppure usa qualsiasi API cloud compatibile con OpenAI. Premi Test per verificare la connessione.
- Avvia il bot. Torna nella barra menu e scegli Avvia bot. Scrivi al tuo bot su Telegram — risponde da quel momento in poi.
Novità dei modelli locali? Leggi la guida — copre mlx-serve, Ollama e LM Studio e quanta RAM serve a ogni modello.
L'app della barra menu
Telebot AI vive nella tua barra menu (icona ⌘). Il menu ti dà:
- Avvia / Ferma / Riavvia — per ogni bot e tutti insieme. I bot girano come LaunchAgent: sempre attivi, fuori dai piedi.
- Apri impostazioni — la finestra delle impostazioni.
- Log — segui il log del bot per vedere cosa sta facendo o per fare debug di un problema.
- Esci — ferma tutto (e disabilita i LaunchAgent finché non riavvii).
Impostazioni, spiegate
La finestra delle impostazioni ha una barra laterale con due tipi di pagine:
- Predefiniti — Modello, Telegram, App, Skill & Funzioni, Registro Skill, Informazioni, Aggiornamenti. Valori che ogni bot eredita.
- Bot — una pagina per bot. Ogni campo mostra cosa usa realmente questo bot: un valore sostituisce il predefinito, un campo vuoto lo eredita (la spiegazione sotto ogni riga lo dice). Ecco perché non ci sono checkbox "Usa globale" — un campo vuoto è "usa globale".
Tutto si salva da solo mentre scrivi o attivi. Le impostazioni vivono in ~/.mlx-serve/config.json.
Predefiniti → Modello
| Impostazione | Cosa fa |
|---|---|
| URL server | L'endpoint compatibile con OpenAI. I server locali non richiedono chiavi. |
| Chiave API | Vuota per i server locali (mlx-serve, Ollama, LM Studio). Il pulsante a forma di occhio la mostra o la nasconde. |
| Nome modello | Quale modello su quel server, es. deepseek-v4-flash-free. |
| Test | Verifica la connessione con i valori correnti — utile prima di salvare qualsiasi cosa. |
| Modelli di backup | Provati in ordine quando il primario fallisce o limita. Ognuno ha il suo soprannome, URL, chiave e modello, più Test, riordina e rimuovi. Aggiungi è disabilitato finché l'ultima riga non è completa. |
Predefiniti → Telegram
| Impostazione | Cosa fa |
|---|---|
| ID chat consentiti | ID utente/gruppo separati da virgola che possono parlare col bot. Vuoto = chiunque. |
| Ora del briefing giornaliero | Quando il bot invia il suo briefing giornaliero — menu a tendina ora/minuti su 24 ore (es. 08:00). |
| Prompt del briefing | Cosa deve coprire il briefing — es. "meteo, i miei promemoria di oggi e gli avvisi sui prezzi". |
| Token massimi per risposta | Limite di sicurezza per le risposte; le risposte lunghe vengono divise in più messaggi. |
| Contesto per chat | Quanti messaggi recenti il bot tiene per chat come contesto. |
| Memorie per utente | Memorie a lungo termine richiamate per utente, per ogni messaggio a cui il bot risponde. |
| Dimensione database memoria (per utente) | Max memorie memorizzate per utente; oltre questo limite le più vecchie vengono eliminate. |
| Token report di ricerca | Budget per i report /research e /insiders. |
| Timeout API (s) | Secondi prima di abbandonare un provider lento — le code del piano gratuito possono bloccarsi oltre un minuto. |
| File Soul | La persona con cui girano i bot. I file .md in questa cartella (soul*.md, *persona*.md) compaiono nel menu a tendina Soul di ogni bot. |
| Parole trigger del bot | Parole separate da virgola che fanno rispondere il bot nei gruppi (oltre a @menzione, risposta o comando) — es. "momo, jarvis, hey bot". |
| Parole trigger clip video/audio | Parole che fanno trattare al bot un video o audio allegato come clip — es. "clip this, save this". |
Pagine per bot
Ogni bot nella barra laterale ha la sua pagina. I campi vuoti ereditano i predefiniti; la spiegazione sotto ogni riga indica cosa eredita.
| Impostazione | Cosa fa |
|---|---|
| Token | Il token @BotFather del bot (pulsante a forma di occhio per rivelarlo). Modificarlo rinomina la voce del bot nella barra laterale. |
| Soprannome | Usato in stato, log e barra laterale — es. "Trading". |
| ID chat consentiti / Parole trigger / Parole clip | Le sostituzioni di questo bot per i predefiniti corrispondenti. |
| URL server, Chiave API, Modello | Il menu a tendina offre i provider configurati in Predefiniti → Modello, più qualsiasi valore personalizzato. Si possono aggiungere modelli di backup propri per bot. |
| Ora del briefing giornaliero / Prompt del briefing | Briefing per bot con un pulsante "Usa globale" che cancella la sostituzione. |
| Modalità | Ricercatore, Assistente, Programmatore, Chef o Nessuno — vuoto usa la modalità predefinita. |
| File Soul | La sostituzione della persona di questo bot, scelta dai file soul/persona trovati su disco. |
| Skill | Apre il foglio skill del bot — disabilita le skill per questo bot in aggiunta ai predefiniti, oppure ripristina i predefiniti. |
Predefiniti → App
| Impostazione | Cosa fa |
|---|---|
| Mostra nel Dock | Se l'app della barra menu appare anche nel Dock. |
| Avvia all'accesso | Avvia Telebot AI quando accedi. |
| Cartella dati | Dove vivono configurazione, memoria, promemoria e log (predefinito ~/.mlx-serve). |
| Apri registro / Apri cartella dati | Vai direttamente al file di log o alla cartella dati in Finder. |
| Esporta impostazioni | Salva l'intera configurazione (incluse le chiavi API) in un file — per backup o per cambiare Mac. |
| Importa impostazioni | Carica un file di configurazione e applicalo immediatamente. |
Skill & Funzioni
Le abilità del bot sono skill guidate dal modello — semplici istruzioni che il modello segue con i suoi strumenti, così puoi descrivere quello che vuoi in linguaggio semplice invece di memorizzare comandi. Ogni gruppo ha un interruttore principale; le singole skill possono essere attivate o disattivate.
| Gruppo | Skill | Prova a dire |
|---|---|---|
| Ricerca | stock-research, stocks-crypto, insider-trading, currency | "ricerca su TSLA", "prezzo di BTC", "operazioni insider per AAPL", "quanto fa 50 USD in CAD?" |
| Quotidiano | briefing, digest, reminders, habits, review, pomodoro, bookmarks, expenses | "/briefing", "riepiloga questa chat", "ricordami alle 17", "segna l'abitudine di oggi come fatta", "revisione settimanale", "/pomodoro 25", "registra pranzo 25" |
| Multimedia | media, voice, translation, feeds | "analizza questo video", "leggi questo ad alta voce", "traduci questo in cinese", "cosa c'è di nuovo nei miei feed?" |
| Strumenti | memory | "di cosa parlavamo ieri?" |
| Dal registro | Skill che installi dal registro | — |
Registro Skill
La scheda Registro ti permette di installare skill pronte dal catalogo pubblico anthropics/skills — gestione di PDF e documenti, fogli di calcolo, presentazioni, test di app web, creazione di server MCP, arte e altro. Carica il catalogo, scegli una skill e appare nella scheda Skill & Funzioni come qualsiasi altra.
Aggiornamenti
La scheda Aggiornamenti controlla il manifest del sito rispetto alla versione installata e mostra l'ultima release con un link di download. I controlli sono silenziosi — offline o irraggiungibile significa semplicemente "aggiornato". Per aggiornare: scarica il nuovo .dmg e trascinalo sopra l'app vecchia in Applicazioni. Impostazioni, bot e memorie vivono fuori dall'app, quindi si conservano intatti.
Dati & privacy
- Dove vivono le cose: configurazione, memoria chat, promemoria, skill e log restano tutti nella tua cartella dati (predefinito ~/.mlx-serve).
- Cosa lascia il tuo Mac: l'API Telegram stessa, il server di modelli a cui punti il bot e statistiche di utilizzo anonime (avvii dell'app e azioni nel menu). Nessun contenuto chat, nessun token, nessun dato personale.
Risoluzione dei problemi
- "Apple non può verificare che l'app non contenga software dannoso" — previsto: clic destro (Control-clic) sull'app in Applicazioni → Apri → Apri di nuovo. Una volta sola, poi gira normalmente.
- Il bot non risponde. Apri Impostazioni → la pagina del bot: il token è giusto? Poi Predefiniti → Modello → Test del provider. Poi controlla il log (barra menu → Log, o scheda App → Apri registro).
- Le risposte sono lente o il bot tace. I provider del piano gratuito possono bloccarsi oltre un minuto — alza il timeout API e aggiungi modelli di backup così il bot passa al secondo quando il primario limita.
- Il server locale non risponde. Assicurati che il server sia davvero in esecuzione (mlx-serve, Ollama…) prima di fare il test nella scheda Modello.
- Gli aggiornamenti dicono "aggiornato" in modo strano. Il controllo è silenzioso di proposito — se il manifest non è raggiungibile, riporta aggiornato.
- Qualcos'altro? Invia feedback — ogni messaggio arriva nel Telegram dello sviluppatore e riceve una risposta vera.
Scarica Telebot AI · Ti piace? Offrimi un caffè ☕