FreeGuard VPN
HomeVPN 노드가격 책정
FreeGuard CLI 문제 해결
FreeGuard CLI에서 문제가 발생하셨나요? 이 가이드는 가장 일반적인 문제와 해결 방법을 다룹니다. 모든 문제에 대해 먼저 `freeguard doctor`를 실행해 보세요 — 대부분의 구성 및 환경 문제를 자동으로 감지합니다.
Table of Contents

FreeGuard CLI 문제 해결

FreeGuard CLI에서 문제가 발생하셨나요? 이 가이드는 가장 일반적인 문제와 해결 방법을 다룹니다. 모든 문제에 대해 먼저 freeguard doctor를 실행해 보세요 — 대부분의 구성 및 환경 문제를 자동으로 감지합니다.

설치 문제

설치 중 권한 거부

증상: 설치 스크립트가 Permission denied 또는 EACCES로 실패합니다.

해결 방법: macOS/Linux에서 설치 프로그램은 /usr/local/bin에 대한 쓰기 권한이 필요합니다. 관리자 권한으로 실행하세요:

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

Windows에서는 설치 명령을 실행하기 전에 PowerShell을 관리자 권한으로 여세요.

설치 후 명령어를 찾을 수 없음

증상: freeguard를 실행하면 command not found 또는 not recognized이 반환됩니다.

Doctor 출력:

✗ CLI binary:     Not in PATH

해결 방법: 바이너리가 셸의 PATH에 없을 수 있습니다. 수동으로 추가하세요:

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

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

Windows에서는 시스템 PATH 환경 변수에 %USERPROFILE%\.freeguard\bin을 추가하고 터미널을 재시작하세요.

curl 실패 또는 다운로드 시간 초과

증상: 설치 스크립트가 바이너리를 다운로드할 수 없습니다.

해결 방법: 기업 방화벽 뒤에 있거나 제한된 네트워크에 있는 경우, GitHub Releases 페이지에서 바이너리를 수동으로 다운로드하여 ~/.freeguard/bin/에 넣으세요. 그런 다음 실행 가능하게 만드세요:

chmod +x ~/.freeguard/bin/freeguard

로그인 문제

인증 코드가 수신되지 않음

증상: freeguard login --email [email protected] --send-code 실행 후 이메일이 도착하지 않습니다.

해결 방법:

  1. 스팸/정크 폴더를 확인하세요 — 인증 이메일이 필터링되는 경우가 있습니다.
  2. 재요청 전에 2분간 기다리세요. 코드 발송에는 속도 제한이 있습니다.
  3. 이메일 주소가 올바른지 확인하세요:
freeguard login --email [email protected] --send-code
  1. 문제가 지속되면 다른 이메일 제공업체를 사용해 보세요.

토큰 만료

증상: 명령이 Authentication expired 또는 Token invalid로 실패합니다.

Doctor 출력:

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

해결 방법: 다시 로그인하여 자격 증명을 갱신하세요:

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

잘못된 이메일 — 구독을 찾을 수 없음

증상: 로그인은 성공하지만 freeguard connect가 No active subscription이라고 표시합니다.

Doctor 출력:

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

해결 방법: 구독을 구매할 때 사용한 것과 동일한 이메일로 로그인하고 있는지 확인하세요. 다른 이메일을 사용한 경우:

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

연결 문제

연결 시간 초과

증상: freeguard connect가 멈추거나 Connection timed out을 반환합니다.

Doctor 출력:

✗ Network:         Internet not reachable

해결 방법:

  1. 기본 인터넷 연결을 확인하세요 (먼저 VPN 연결을 해제하세요):
freeguard disconnect
ping 8.8.8.8
  1. 다른 노드 또는 국가를 시도하세요:
freeguard connect --country SG
  1. 네트워크에서 더 잘 작동할 수 있는 다른 프로토콜을 시도하세요:
freeguard connect --protocol hysteria2

포트 7890이 이미 사용 중

증상: freeguard connect가 Port 7890 is already in use로 실패합니다.

Doctor 출력:

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

해결 방법: 다른 proxy 애플리케이션이 기본 포트를 사용하고 있습니다. 다른 애플리케이션을 중지하거나 FreeGuard proxy 포트를 변경하세요:

freeguard config set proxy.port 8080
freeguard connect

DNS 누출 감지

증상: DNS 쿼리가 VPN 터널을 우회합니다.

해결 방법: 보안 DNS 구성으로 전환하세요:

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

DNS가 VPN을 통해 라우팅되고 있는지 확인할 수 있습니다:

freeguard doctor

출력에서 DNS 검사를 찾아 올바르게 작동하는지 확인하세요.

권한 문제

TUN 모드에는 sudo가 필요

증상: freeguard connect --tun이 Permission denied: TUN device로 실패합니다.

Doctor 출력:

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

해결 방법: TUN 모드는 가상 네트워크 인터페이스를 생성하며, 이를 위해 관리자 권한이 필요합니다:

# macOS/Linux
sudo freeguard connect --tun

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

시스템 전체 VPN 적용이 필요하지 않은 경우 기본 시스템 proxy 모드를 사용하세요 (sudo 불필요):

freeguard connect

1024 미만 포트는 관리자 권한 필요

증상: 1024 미만의 proxy 포트를 설정하면 Permission denied로 실패합니다.

해결 방법: 대부분의 운영 체제에서 1024 미만의 포트는 제한되어 있습니다. 1024 이상의 포트를 사용하세요:

freeguard config set proxy.port 7890

또는 낮은 포트가 특별히 필요한 경우 관리자 권한으로 실행하세요:

sudo freeguard connect

여전히 해결되지 않나요?

freeguard doctor와 위의 해결 방법으로 문제가 해결되지 않으면 AI가 자동으로 진단하도록 하세요.

FreeGuard CLI Agent 페이지를 방문하여 문제를 설명하세요. 에이전트가 freeguard doctor --json 출력을 읽고 단계별로 해결 방법을 안내합니다.

대화형 문제 해결 마법사도 실행할 수 있습니다:

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

자주 묻는 질문

FreeGuard CLI가 "connection refused"라고 하는 이유는?

이는 일반적으로 VPN 서버가 일시적으로 사용 불가능함을 의미합니다. freeguard connect --server auto로 최적의 서버를 자동 선택하거나 방화벽 설정을 확인하세요.

VPN 연결이 작동하는지 어떻게 확인하나요?

freeguard status를 실행하여 연결 상태, 현재 서버 및 프로토콜을 확인하세요. curl ifconfig.me를 실행하여 IP 주소가 변경되었는지 확인할 수도 있습니다.

시스템 업데이트 후 FreeGuard CLI가 시작되지 않습니다. 어떻게 해야 하나요?

freeguard update를 실행하여 최신 버전을 받으세요. 실패하면 설치 스크립트로 재설치하세요: curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh.

버그를 신고하거나 도움을 받으려면 어떻게 하나요?

freeguard debug를 실행하여 진단 정보를 수집한 다음 웹사이트 또는 이메일을 통해 지원팀에 문의하세요. 더 빠른 해결을 위해 디버그 출력을 포함하세요.

최종 업데이트: 2026년 3월