Installazione, configurazione e tutti gli errori che puoi incontrare — con la soluzione passo-passo. La guida copre Linux e macOS; dove i comandi differiscono, è indicato esplicitamente.
OPENFREEDOM si installa dal terminale, con un solo comando. Zero sudo: tutto vive nella tua home. Lo script controlla la macchina PRIMA di toccare qualsiasi cosa (Python 3.10+, spazio, rete) e, se si interrompe, rilancia lo stesso comando per riprendere da dove era.
curl -sSL https://openfreedom.it/installer/install.php | bash
Al termine lo script avvia la webui e apre il browser. Per riavviare OPENFREEDOM in seguito:
~/.openfreedom/avvia-of.sh
curl -sSL https://openfreedom.it/installer/install-mac.php | bash
Stesso flusso: installa in ~/.openfreedom, avvia la webui e apre il browser. Il metodo via terminale non passa da Gatekeeper (niente quarantena).
Nota di sicurezza: puoi leggere lo script prima di eseguirlo — curl -sSL https://openfreedom.it/installer/install.php | less. Se qualcosa va storto, lo script genera diagnosi.txt con le indicazioni.
Al primo avvio il campo Provider è vuoto: è voluto. Scegli tu il provider e poi premi 💾 Salva.
.txt dalla scrivania.🔴 "Chiave non valida o scaduta (401)" nel menu modelli
La chiave salvata non è accettata dal provider. Soluzione: 1) apri il sito del provider e verifica che la chiave sia attiva (rigenerala se necessario); 2) nel Setup, 🗑 Rimuovi chiave; 3) incolla la nuova chiave nel campo (verrà nascosta subito); 4) premi 🔐 Inserisci e poi 🔍 Aggiorna nel menu modelli.
🔴 "Modalità senza LLM non supportata nella Fase 1 v2… Riavvia con chiave API"
La chat non vede una chiave valida. Soluzione: 1) apri il Setup (⚙️); 2) seleziona il provider e Salva; 3) inserisci la chiave API nel campo (mai in chat); 4) attendi 2 secondi e riscrivi in chat. Non serve riavviare il programma: la disponibilità si aggiorna da sola.
🟡 Il menu "Modelli" è vuoto
Di solito manca la chiave o il provider non è salvato. Soluzione: inserisci la chiave, premi Salva sul provider e poi 🔍 Aggiorna. Se il menu dice "— inserisci la chiave per vedere i modelli —", la chiave è assente; se dice "— chiave non valida o scaduta —", vedi il caso sopra.
🟡 Dopo l'inserimento della chiave i modelli non compaiono in automatico
Seleziona prima il provider nel menu (il campo parte vuoto per i nuovi utenti) e poi premi 🔍 Aggiorna. I modelli si caricano dal provider selezionato, non da quello salvato in precedenza.
🔴 "Clona da principale" senza aver salvato nulla
È il comportamento corretto: finché non salvi provider+modello nel Setup non esiste un "modello principale". Soluzione: vai nel tab LLM, seleziona provider e modello, premi 💾 Salva, poi riprova il clone.
🔴 Errore 401 anche con una chiave appena generata (es. Kimi/Moonshot)
Verifica che la chiave salvata sia davvero quella incollata (in passato la mascheratura poteva salvare gli asterischi: se il problema persiste, Rimuovi chiave e reinseriscila). Poi controlla che il provider scelto corrisponda alla chiave: una chiave Moonshot non funziona su DeepSeek o OpenAI.
🔴 "Vault bloccato: serve la password per questa macchina"
Inserisci la password di attivazione nel campo dedicato (tab 🔐 Sicurezza) e premi 🔓 Sblocca. È la password scelta in installazione.
🔴 Password dimenticata
La password è derivata da te e dalla tua macchina: senza di essa i dati cifrati (chiavi API, token, siti) non sono recuperabili, per design. Soluzione: reinstallare OPENFREEDOM e ricreare le credenziali (le chiavi API vanno reinserite dal sito del provider). La memoria e le skill restano recuperabili se avevi un backup (vedi sezione Backup).
🟡 "Nessun vault" o chiavi che spariscono
Il vault non è inizializzato o è stato spostato. Soluzione: completa l'installazione (esegui l'installer una volta) oppure verifica che la cartella dati non sia stata cancellata. Le chiavi vanno reinserite dopo.
🟡 La voce non parla / il toggle è spento
La sintesi predefinita usa un servizio cloud (Microsoft Edge TTS): serve internet. Se sei offline, OPENFREEDOM usa il fallback locale espeak-ng (su Linux va installato: sudo apt install espeak-ng; su macOS: brew install espeak-ng). Controlla anche che il volume di sistema non sia a zero.
🟡 La voce legge hashtag, link o percorsi di cartelle
Versione aggiornata: i simboli (#, link, percorsi) vengono rimossi dalla lettura automaticamente. Se li senti, aggiorna OPENFREEDOM all'ultima versione.
🟡 "Ollama non raggiungibile"
Ollama non è in esecuzione. Soluzione: avvia Ollama (Linux: ollama serve o l'app; macOS: apri Ollama dall'applicazioni) e riprova. Verifica anche che la porta 11434 non sia bloccata (vedi Rete).
🔴 "Nessuna GPU rilevata: la sezione Ollama è disattivata"
OPENFREEDOM disattiva Ollama se non trova una GPU, perché i modelli locali ne hanno bisogno per essere usabili. Soluzione: verifica i driver GPU (Linux: nvidia-smi o /dev/dri/renderD*; macOS: Metal è sempre presente su Apple Silicon). Se hai una GPU ma non viene vista, aggiorna i driver.
🟡 Installazione modello locale lenta o fallita
I modelli pesano GB e il download richiede tempo. Se fallisce con "non trovato sul catalogo", controlla il nome UFFICIALE su ollama.com/library (es. llama3.2:3b, qwen2.5:7b). OPENFREEDOM verifica i requisiti della tua macchina prima di scaricare.
🟡 "Timeout" o "lista API non raggiungibile"
Il computer non raggiunge il provider (api.deepseek.com, api.moonshot.ai, api.z.ai, api.openai.com). Soluzione: verifica la connessione; se usi un firewall (es. UFW su Linux), apri le porte del provider in uscita — le API usano HTTPS (443). Su Linux: sudo ufw status e, se serve, sudo ufw allow out 443/tcp.
🟡 La chat famiglia (Tailscale) non si collega
La chat P2P usa Tailscale. Soluzione: installa Tailscale, fai tailscale up e premi Rileva nel setup. Entrambi i dispositivi devono essere sulla stessa rete privata Tailscale.
🔴 "curl: command not found"
Manca curl. Soluzione: installalo dal gestore pacchetti — Debian/Ubuntu: sudo apt install curl; Fedora: sudo dnf install curl; Arch: sudo pacman -S curl. (su macOS curl è già presente).
🔴 Il pre-flight si ferma: Python 3.10+ non trovato
OPENFREEDOM richiede Python 3.10 o superiore. Soluzione: installa Python (sudo apt install python3 su Debian/Ubuntu, sudo dnf install python3 su Fedora), verifica con python3 --version e rilancia lo stesso comando di installazione.
🟡 La webui non si apre / porta occupata
La porta predefinita (8080) potrebbe essere occupata. Soluzione: chiudi il programma che la usa (ss -tlnp | grep 8080) oppure avvia su un'altra porta seguendo le istruzioni del terminale.
🟡 Su Wayland lo screenshot o l'audio non funzionano
Wayland ha permessi più rigidi. Per lo screenshot usa il supporto di Portal (installato di default sulle distro moderne); per l'audio verifica il mixer. In caso di problemi persistenti, la sessione X11 è il fallback più compatibile.
🟡 Gatekeeper blocca lo script salvato
Il metodo consigliato è curl … | bash (niente quarantena). Se invece salvi lo script e lo esegui, usa sempre bash install-mac.sh dal Terminale: così eviti i blocchi di Gatekeeper.
🟡 L'installazione si interrompe (Ctrl+C o errore)
Rilancia lo stesso comando: lo script riprende da dove era, non ricomincia. Se l'errore persiste, apri ~/.openfreedom-installer/diagnosi.txt e seguine le indicazioni — o scrivi a team@openfreedom.it includendo quel file.
🟡 La webui non si apre al termine dell'installazione
Avviala manualmente: ~/.openfreedom/avvia-of.sh e apri http://127.0.0.1:8080 nel browser. Se la porta 8080 è occupata, chiudi il programma che la usa o segui le indicazioni del terminale.
🟡 RAM o GPU non rilevate dal test hardware
Il browser non espone tutti i dati (RAM precisa solo su Chrome/Edge). È un limite del browser, non del software. Su macOS i modelli locali funzionano bene con Apple Silicon.
🟡 "Hai raggiunto il limite di 200 task della versione trial"
La versione trial (gratuita) consente 200 task di prova, poi si blocca. Soluzione: acquista la licenza a vita (49,90 € IVA inclusa, in promozione lancio) dal sito — bottone PayPal o QR — e ricevi la chiave di attivazione via email. Per qualsiasi problema, scrivi a team@openfreedom.it.
🟡 Il blocco compare anche dopo la reinstallazione
È voluto: il contatore del trial è registrato sul server legato alla tua macchina (reinstallare non lo azzera). L'unica via è la licenza completa.
OPENFREEDOM crea backup automatici dei dati (memoria, configurazione, skill). Per un backup manuale, copia la cartella dati in un posto sicuro. Su Linux si trova in ~/.openfreedom/; su macOS nella cartella utente corrispondente. Il backup NON contiene le chiavi segrete in chiaro: senza password di attivazione non si leggono (per design).
Per qualsiasi problema non coperto da questa guida scrivi a team@openfreedom.it: ti risponderemo subito. Includi il tuo sistema (Linux o macOS, versione) e il messaggio d'errore esatto.
← Torna alla home