Risoluzione dei problemi di FreeGuard CLI

Stai riscontrando problemi con FreeGuard CLI? Questa guida copre i problemi più comuni e le relative soluzioni. Per ogni problema, prova prima a eseguire freeguard doctor — rileva automaticamente la maggior parte dei problemi di configurazione e ambiente.

Problemi di installazione

Permesso negato durante l’installazione

Sintomo: Lo script di installazione fallisce con Permission denied o EACCES.

Soluzione: Su macOS/Linux, l’installer necessita di accesso in scrittura a /usr/local/bin. Esegui con privilegi elevati:

curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sudo sh

Su Windows, assicurati di aprire PowerShell come Amministratore prima di eseguire il comando di installazione.

Comando non trovato dopo l’installazione

Sintomo: L’esecuzione di freeguard restituisce command not found o not recognized.

Output Doctor:

✗ CLI binary:     Not in PATH

Soluzione: Il file binario potrebbe non essere nel PATH della tua shell. Aggiungilo manualmente:

# macOS/Linux — add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$HOME/.freeguard/bin:$PATH"

# Then reload your shell
source ~/.zshrc  # or ~/.bashrc

Su Windows, aggiungi %USERPROFILE%\.freeguard\bin alla variabile d’ambiente PATH del sistema e riavvia il terminale.

curl fallisce o il download va in timeout

Sintomo: Lo script di installazione non riesce a scaricare il file binario.

Soluzione: Se ti trovi dietro un firewall aziendale o in una rete con restrizioni, scarica il binario manualmente dalla pagina delle release su GitHub e posizionalo in ~/.freeguard/bin/. Quindi rendilo eseguibile:

chmod +x ~/.freeguard/bin/freeguard

Problemi di accesso

Codice di verifica non ricevuto

Sintomo: Dopo aver eseguito freeguard login --email [email protected] --send-code, nessuna email arriva.

Soluzione:

Controlla la cartella spam/posta indesiderata — le email di verifica a volte vengono filtrate.
Attendi 2 minuti prima di richiedere nuovamente. C’è un limite di frequenza sull’invio dei codici.
Verifica che l’indirizzo email sia corretto:

freeguard login --email [email protected] --send-code

Prova un provider email diverso se il problema persiste.

Token scaduto

Sintomo: I comandi falliscono con Authentication expired o Token invalid.

Output Doctor:

✗ Credentials:     Token expired (last refresh: 2026-03-01)

Soluzione: Accedi nuovamente per aggiornare le tue credenziali:

freeguard logout
freeguard login --email [email protected] --send-code

Email sbagliata — abbonamento non trovato

Sintomo: L’accesso riesce ma freeguard connect dice No active subscription.

Output Doctor:

✓ Credentials:     Logged in (email: u***@example.com)
✗ Subscription:    No active subscription found

Soluzione: Assicurati di accedere con la stessa email utilizzata per acquistare l’abbonamento. Se hai usato un’email diversa:

freeguard logout
freeguard login --email [email protected] --send-code

Problemi di connessione

Timeout della connessione

Sintomo: freeguard connect si blocca o restituisce Connection timed out.

Output Doctor:

✗ Network:         Internet not reachable

Soluzione:

Verifica la connessione Internet di base (disconnetti prima la VPN):

freeguard disconnect
ping 8.8.8.8

Prova un nodo o un paese diverso:

freeguard connect --country SG

Prova un protocollo diverso che potrebbe funzionare meglio sulla tua rete:

freeguard connect --protocol hysteria2

La porta 7890 è già in uso

Sintomo: freeguard connect fallisce con Port 7890 is already in use.

Output Doctor:

✗ Port 7890:       In use by another process (PID: 12345)

Soluzione: Un’altra applicazione proxy sta usando la porta predefinita. Interrompi l’altra applicazione o cambia la porta proxy di FreeGuard:

freeguard config set proxy.port 8080
freeguard connect

Perdita DNS rilevata

Sintomo: Le query DNS bypassano il tunnel VPN.

Soluzione: Passa a una configurazione DNS sicura:

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

Puoi verificare che il DNS venga instradato attraverso la VPN:

freeguard doctor

Cerca il controllo DNS nell’output per confermare che funziona correttamente.

Problemi di permessi

La modalità TUN richiede sudo

Sintomo: freeguard connect --tun fallisce con Permission denied: TUN device.

Output Doctor:

✗ TUN permission:  Not available (run with sudo for TUN mode)

Soluzione: La modalità TUN crea un’interfaccia di rete virtuale, che richiede privilegi elevati:

# macOS/Linux
sudo freeguard connect --tun

# Windows — run PowerShell as Administrator
freeguard connect --tun

Se non hai bisogno della copertura VPN a livello di sistema, usa la modalità proxy di sistema predefinita (non serve sudo):

freeguard connect

Porta inferiore a 1024 richiede privilegi elevati

Sintomo: L’impostazione di una porta proxy inferiore a 1024 fallisce con Permission denied.

Soluzione: Le porte inferiori a 1024 sono limitate sulla maggior parte dei sistemi operativi. Usa una porta superiore a 1024:

freeguard config set proxy.port 7890

Oppure esegui con privilegi elevati se hai specificamente bisogno di una porta bassa:

sudo freeguard connect

Ancora bloccato?

Se freeguard doctor e le soluzioni sopra non risolvono il tuo problema, lascia che l’AI lo diagnostichi automaticamente.

Visita la pagina FreeGuard CLI Agent e descrivi il tuo problema. L’agente può leggere l’output di freeguard doctor --json e guidarti passo dopo passo verso una soluzione.

Puoi anche eseguire la procedura guidata interattiva di risoluzione dei problemi:

freeguard doctor --json | pbcopy
# Then paste the output into the CLI Agent chat

Domande frequenti

Perché FreeGuard CLI dice “connection refused”?

Questo di solito significa che il server VPN è temporaneamente non disponibile. Prova freeguard connect --server auto per selezionare automaticamente il miglior server disponibile, oppure controlla le impostazioni del firewall.

Come verifico se la mia connessione VPN funziona?

Esegui freeguard status per vedere lo stato della connessione, il server attuale e il protocollo. Puoi anche eseguire curl ifconfig.me per verificare che il tuo indirizzo IP sia cambiato.

FreeGuard CLI non si avvia dopo un aggiornamento di sistema. Cosa devo fare?

Esegui freeguard update per ottenere l’ultima versione. Se fallisce, reinstalla con lo script di installazione: curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh.

Come segnalo un bug o ottengo assistenza?

Esegui freeguard debug per raccogliere informazioni diagnostiche, quindi contatta il supporto tramite il sito web o email. Includi l’output di debug per una risoluzione più rapida.

Ultimo aggiornamento: marzo 2026