Solución de problemas de FreeGuard CLI

¿Tienes problemas con FreeGuard CLI? Esta guía cubre los problemas más comunes y sus soluciones. Para cada problema, intenta ejecutar freeguard doctor primero — detecta automáticamente la mayoría de los problemas de configuración y entorno.

Problemas de instalación

Permiso denegado durante la instalación

Síntoma: El script de instalación falla con Permission denied o EACCES.

Solución: En macOS/Linux, el instalador necesita acceso de escritura a /usr/local/bin. Ejecútalo con privilegios elevados:

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

En Windows, asegúrate de abrir PowerShell como Administrador antes de ejecutar el comando de instalación.

Comando no encontrado después de la instalación

Síntoma: Ejecutar freeguard devuelve command not found o not recognized.

Salida de Doctor:

✗ CLI binary:     Not in PATH

Solución: El binario puede no estar en el PATH de tu shell. Agrégalo manualmente:

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

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

En Windows, agrega %USERPROFILE%\.freeguard\bin a tu variable de entorno PATH del sistema y reinicia la terminal.

curl falla o se agota el tiempo de descarga

Síntoma: El script de instalación no puede descargar el binario.

Solución: Si estás detrás de un firewall corporativo o en una red restringida, descarga el binario manualmente desde la página de releases en GitHub y colócalo en ~/.freeguard/bin/. Luego hazlo ejecutable:

chmod +x ~/.freeguard/bin/freeguard

Problemas de inicio de sesión

Código de verificación no recibido

Síntoma: Después de ejecutar freeguard login --email [email protected] --send-code, no llega ningún correo electrónico.

Solución:

Revisa tu carpeta de spam/correo no deseado — los correos de verificación a veces se filtran.
Espera 2 minutos antes de solicitar nuevamente. Hay un límite de frecuencia en el envío de códigos.
Verifica que la dirección de correo electrónico sea correcta:

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

Intenta con un proveedor de correo diferente si el problema persiste.

Token expirado

Síntoma: Los comandos fallan con Authentication expired o Token invalid.

Salida de Doctor:

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

Solución: Inicia sesión nuevamente para actualizar tus credenciales:

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

Correo incorrecto — suscripción no encontrada

Síntoma: El inicio de sesión es exitoso pero freeguard connect dice No active subscription.

Salida de Doctor:

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

Solución: Asegúrate de iniciar sesión con el mismo correo que usaste para comprar tu suscripción. Si usaste un correo diferente:

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

Problemas de conexión

Tiempo de conexión agotado

Síntoma: freeguard connect se queda colgado o devuelve Connection timed out.

Salida de Doctor:

✗ Network:         Internet not reachable

Solución:

Verifica tu conexión a internet base (desconecta la VPN primero):

freeguard disconnect
ping 8.8.8.8

Intenta con un nodo o país diferente:

freeguard connect --country SG

Intenta con un protocolo diferente que pueda funcionar mejor en tu red:

freeguard connect --protocol hysteria2

El puerto 7890 ya está en uso

Síntoma: freeguard connect falla con Port 7890 is already in use.

Salida de Doctor:

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

Solución: Otra aplicación proxy está usando el puerto predeterminado. Detén la otra aplicación o cambia el puerto proxy de FreeGuard:

freeguard config set proxy.port 8080
freeguard connect

Fuga de DNS detectada

Síntoma: Las consultas DNS evitan el túnel VPN.

Solución: Cambia a una configuración DNS segura:

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

Puedes verificar que el DNS se enruta a través de la VPN:

freeguard doctor

Busca la verificación de DNS en la salida para confirmar que funciona correctamente.

Problemas de permisos

El modo TUN requiere sudo

Síntoma: freeguard connect --tun falla con Permission denied: TUN device.

Salida de Doctor:

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

Solución: El modo TUN crea una interfaz de red virtual, lo que requiere privilegios elevados:

# macOS/Linux
sudo freeguard connect --tun

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

Si no necesitas cobertura VPN a nivel de sistema, usa el modo proxy del sistema predeterminado (sin necesidad de sudo):

freeguard connect

Puerto inferior a 1024 requiere privilegios elevados

Síntoma: Configurar un puerto proxy inferior a 1024 falla con Permission denied.

Solución: Los puertos inferiores a 1024 están restringidos en la mayoría de los sistemas operativos. Usa un puerto superior a 1024:

freeguard config set proxy.port 7890

O ejecuta con privilegios elevados si necesitas específicamente un puerto bajo:

sudo freeguard connect

¿Sigues atascado?

Si freeguard doctor y las soluciones anteriores no resuelven tu problema, deja que la IA lo diagnostique automáticamente.

Visita la página de FreeGuard CLI Agent y describe tu problema. El agente puede leer la salida de freeguard doctor --json y guiarte paso a paso hacia una solución.

También puedes ejecutar el asistente interactivo de solución de problemas:

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

Preguntas frecuentes

¿Por qué FreeGuard CLI dice “connection refused”?

Esto generalmente significa que el servidor VPN no está disponible temporalmente. Intenta freeguard connect --server auto para seleccionar automáticamente el mejor servidor disponible, o verifica la configuración de tu firewall.

¿Cómo verifico si mi conexión VPN está funcionando?

Ejecuta freeguard status para ver el estado de tu conexión, el servidor actual y el protocolo. También puedes ejecutar curl ifconfig.me para verificar que tu dirección IP ha cambiado.

FreeGuard CLI no inicia después de una actualización del sistema. ¿Qué debo hacer?

Ejecuta freeguard update para obtener la última versión. Si eso falla, reinstala con el script de instalación: curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh.

¿Cómo reporto un error u obtengo ayuda?

Ejecuta freeguard debug para recopilar información de diagnóstico y luego contacta al soporte a través del sitio web o correo electrónico. Incluye la salida de debug para una resolución más rápida.

Última actualización: marzo de 2026