Windows용 Clash Verge Rev 외부 컨트롤러 설정 방법

외부 컨트롤러란 무엇이며 언제 필요한가

Clash Verge Rev의 외부 컨트롤러는 실행 중인 mihomo 코어를 웹 브라우저나 다른 관리 도구에서 제어할 수 있게 해 주는 HTTP API 인터페이스입니다. 일반적으로 Verge Rev 화면에서 프로필을 바꾸고 프록시 그룹을 선택하는 것만으로 충분하지만, 여러 장치에서 상태를 확인하거나 브라우저 대시보드를 사용하려면 외부 컨트롤러 주소가 필요합니다. Windows에서 Clash Verge Rev를 처음 설정하는 사용자라면 “웹 대시보드는 열리는데 연결되지 않는다”, “포트는 맞는데 401 오류가 나온다”와 같은 문제를 자주 만나게 됩니다.

외부 컨트롤러는 프록시 트래픽이 지나가는 mixed-port와 목적이 다릅니다. mixed-port는 브라우저나 다른 프로그램이 실제 인터넷 연결을 맡기는 프록시 포트이고, 외부 컨트롤러 포트는 설정 조회와 정책 변경 요청을 받는 관리용 포트입니다. 예를 들어 브라우저 프록시가 7890을 사용하고 외부 컨트롤러가 9090을 사용하도록 분리할 수 있습니다. 두 포트를 같은 값으로 설정하면 충돌하거나, 브라우저가 API 대신 일반 프록시 포트에 접속해 이상한 응답을 받는 상황이 생길 수 있습니다.

이 기능은 편리하지만 보안상 주의가 필요합니다. 외부 컨트롤러를 0.0.0.0에 열면 Windows PC의 모든 네트워크 인터페이스에서 접근을 시도할 수 있습니다. 공유기나 공용 Wi-Fi에 연결된 상태에서 인증 키 없이 API를 노출하면 다른 사용자가 프록시 그룹을 바꾸거나 현재 연결 상태를 읽을 수 있습니다. 따라서 처음에는 127.0.0.1 또는 localhost에만 바인딩하고, 반드시 충분히 긴 secret을 설정하는 것이 안전합니다.

Windows에서 설정하기 전 준비할 항목

설정을 열기 전에 Clash Verge Rev가 실제로 실행 중인지 확인하세요. Windows 작업 표시줄 오른쪽의 트레이 영역에 Verge Rev 아이콘이 있는지 보고, 메인 창의 프로필이나 코어 상태에 오류가 없는지 확인합니다. 프로필 파일만 수정하고 코어를 다시 불러오지 않으면 디스크에 저장된 값과 메모리에서 현재 실행 중인 값이 서로 달라질 수 있습니다. 이 상태에서 외부 컨트롤러에 접속하면 설정을 바꿨는데도 이전 포트가 계속 열려 있는 것처럼 보입니다.

다음으로 현재 사용 중인 코어가 mihomo인지 확인합니다. Clash Verge Rev의 릴리스와 설정 화면은 버전에 따라 메뉴 이름이 조금씩 달라질 수 있지만, 외부 컨트롤러의 핵심 항목은 대체로 External Controller, Controller Address, API Port, Secret처럼 표시됩니다. 일부 버전에서는 일반 설정 안에 있고, 일부 버전에서는 코어 또는 고급 설정 화면 안에 배치됩니다. 메뉴 이름이 다르더라도 “controller”, “API”, “external”이라는 단어를 찾으면 됩니다.

포트 번호는 이미 다른 프로그램이 사용하지 않는 범위에서 선택합니다. 9090, 9091, 9097처럼 기억하기 쉬운 값을 사용할 수 있지만, 회사 보안 프로그램이나 개발 서버가 같은 포트를 점유하고 있을 수도 있습니다. Windows에서 명령 프롬프트를 열고 다음 명령으로 포트 사용 여부를 확인할 수 있습니다.

netstat -ano | findstr :9090

결과가 아무것도 나오지 않으면 해당 포트를 현재 다른 프로세스가 듣고 있지 않을 가능성이 높습니다. 이미 줄이 표시된다면 다른 포트로 바꾸거나, 표시된 PID를 작업 관리자에서 확인해 어떤 프로그램이 사용 중인지 먼저 파악하세요. 무작정 기존 프로그램을 종료하면 개발 도구나 회사 보안 서비스가 중단될 수 있으므로 프로세스 이름을 확인한 뒤 결정하는 편이 좋습니다.

Clash Verge Rev에서 외부 컨트롤러 활성화하기

Clash Verge Rev를 열고 설정 화면으로 이동한 뒤 외부 컨트롤러 관련 항목을 찾습니다. 버전에 따라 메뉴의 위치와 라벨은 다를 수 있지만, 아래 세 가지 값을 순서대로 확인하면 됩니다. 첫 번째는 컨트롤러가 요청을 받을 바인딩 주소, 두 번째는 API가 열릴 포트, 세 번째는 요청을 인증할 secret 키입니다.

바인딩 주소는 특별한 이유가 없다면 127.0.0.1로 두세요. localhost도 같은 PC를 가리키지만, 일부 프로그램은 IPv4와 IPv6 해석 차이 때문에 127.0.0.1보다 다르게 동작할 수 있습니다. 다른 Windows PC나 휴대폰에서 관리해야 할 때만 LAN 주소나 0.0.0.0 사용을 검토하고, 그 경우에는 방화벽 규칙과 secret을 함께 설정해야 합니다.

secret은 123456, clash, Windows 계정 이름처럼 추측하기 쉬운 값을 피합니다. 예를 들어 대문자와 소문자, 숫자를 섞은 긴 문자열을 비밀번호 관리 프로그램에 저장할 수 있습니다. 이 값은 브라우저 대시보드의 연결 설정에도 동일하게 입력해야 하므로, 특수문자를 복사하는 과정에서 앞뒤 공백이나 줄바꿈이 들어가지 않았는지 확인하세요.

값을 저장한 뒤에는 코어를 재시작하거나 프로필을 다시 로드해야 적용되는 릴리스가 있습니다. 저장 직후에도 접속되지 않는다면 Verge Rev를 완전히 종료한 뒤 트레이 아이콘에서 종료하고 다시 실행하세요. 창의 닫기 버튼만 누르면 백그라운드 프로세스가 남아 새 설정이 적용되지 않을 수 있습니다.

웹 브라우저에서 컨트롤러 연결 확인하기

설정이 적용되면 브라우저에서 컨트롤러 주소를 입력해 연결을 확인합니다. 로컬에서 실행하는 경우 주소는 보통 다음과 같은 형태입니다.

http://127.0.0.1:9090

단순히 주소를 열었을 때 화면이 표시되지 않아도 바로 실패라고 단정하지 마세요. 외부 컨트롤러는 일반 웹사이트가 아니라 API 엔드포인트이므로, 브라우저에 JSON 응답이나 “Unauthorized” 같은 짧은 문장이 나타나는 것이 정상일 수 있습니다. 별도의 웹 대시보드를 사용하는 경우에는 대시보드 설정에서 컨트롤러 주소를 127.0.0.1:9090으로 입력하고, secret 필드에 Verge Rev에 저장한 키를 입력합니다.

연결 성공 여부는 프록시 목록과 현재 모드가 표시되는지로 판단합니다. 대시보드에 Proxies, Proxy Groups, Rules, Connections 같은 메뉴가 나타나고 정책 그룹을 읽어 온다면 API 연결은 정상입니다. 이 단계에서는 실제 노드를 변경하기보다 현재 선택된 그룹과 모드를 읽기만 하면서 확인하는 것이 좋습니다. 읽기 요청부터 안정적으로 성공해야 이후에 그룹 전환이나 연결 종료 같은 변경 요청을 안전하게 테스트할 수 있습니다.

브라우저에서 인증 오류가 나오면 주소보다 secret을 먼저 확인합니다. secret이 비어 있거나, 설정 화면의 값과 대시보드에 입력한 값이 한 글자라도 다르면 401 Unauthorized 또는 연결 실패가 나타납니다. 브라우저 자동완성이 오래된 키를 넣는 경우도 있으므로 저장된 비밀번호를 지우고 직접 붙여 넣어 보세요. 반대로 페이지가 아예 열리지 않으면 포트, 코어 실행 상태, Windows 방화벽 순서로 점검하는 편이 효율적입니다.

간단한 API 요청으로 상태 확인하기

웹 대시보드가 문제인지 컨트롤러 자체가 문제인지 분리하려면 PowerShell에서 직접 상태 요청을 보낼 수 있습니다. 아래 예시의 secret은 자신의 값으로 바꾸고, 키를 명령 기록이나 화면 공유에 남기지 않도록 주의하세요.

$headers = @{ Authorization = "Bearer YOUR_SECRET" }
Invoke-RestMethod -Uri "http://127.0.0.1:9090/version" -Headers $headers

정상이라면 코어 버전과 관련된 JSON 응답을 받을 수 있습니다. 응답이 오면 Windows 네트워크와 컨트롤러 포트는 동작하는 것이므로, 별도 대시보드의 주소 형식이나 인증 방식에 문제가 있을 가능성이 큽니다. 반대로 연결 거부가 나타나면 컨트롤러가 실행되지 않았거나 포트가 잘못되었거나, 다른 프로세스가 해당 포트를 사용 중일 수 있습니다.

Windows에서 자주 발생하는 접속 문제와 해결 순서

가장 흔한 문제는 포트 불일치입니다. Verge Rev에는 9090을 입력했지만 대시보드에는 기본값인 9097이 남아 있으면 브라우저는 다른 서비스에 접속하거나 연결을 거부합니다. 설정 화면과 브라우저 주소를 한 글자씩 비교하고, 포트 변경 후 코어가 재시작되었는지 확인하세요.

두 번째는 mixed-port와 controller-port 혼동입니다. 브라우저의 프록시 설정에는 7890을 넣어야 하는데 여기에 9090을 입력하면 일반 인터넷 요청이 관리 API 포트로 향합니다. 반대로 대시보드에는 프록시 포트가 아니라 컨트롤러 포트를 입력해야 합니다. 아래처럼 용도를 분리해 적어 두면 설정을 재현하기 쉽습니다.

• 프록시 연결: 브라우저 또는 애플리케이션 → 127.0.0.1:7890
• 관리 API: 웹 대시보드 또는 PowerShell → 127.0.0.1:9090
• 인증: API 요청 헤더의 Bearer 값 → Verge Rev의 secret

세 번째는 Windows 방화벽입니다. 로컬호스트에서만 접속하는데도 차단된다면 보안 프로그램이 해당 실행 파일의 네트워크 수신을 막았는지 확인합니다. 다른 장치에서 접속할 때는 Windows Defender 방화벽의 인바운드 규칙이 추가로 필요할 수 있습니다. 이때 모든 포트를 열기보다 선택한 컨트롤러 포트 하나만 허용하고, 신뢰할 수 있는 사설 네트워크 프로필에만 적용하세요.

네 번째는 주소 바인딩 문제입니다. PC 안에서는 127.0.0.1:9090이 열리지만 휴대폰에서는 열리지 않는다면 컨트롤러가 로컬 인터페이스에만 바인딩된 상태일 수 있습니다. 다른 장치에서 접근해야 한다면 Windows의 실제 사설 IP를 확인하고, Verge Rev가 LAN 접근을 허용하도록 설정해야 합니다. 다만 이 방식은 노출 범위가 넓어지므로 테스트가 끝난 뒤 다시 로컬호스트 바인딩으로 되돌리는 것을 권장합니다.

마지막으로 설정 파일의 YAML을 직접 수정했다면 들여쓰기와 키 이름을 점검하세요. external-controller와 secret은 코어가 읽는 설정 위치에 있어야 하며, 탭 문자가 섞이면 일부 값이 무시될 수 있습니다. GUI에서 저장한 값과 파일의 값이 계속 다르다면 구독 프로필이 갱신될 때 로컬 수정이 덮어써지는 구조인지도 확인해야 합니다. 이런 경우에는 활성 프로필을 먼저 확인하고, 수정한 프로필을 실제 코어가 사용하고 있는지부터 다시 검증하세요.

오래된 GUI는 외부 컨트롤러 메뉴가 제한적이거나 코어와 API 동작이 맞지 않을 수 있고, 단순 웹 대시보드는 인증 키 관리와 Windows 방화벽 안내가 부족한 경우가 있습니다. 반면 Clash V.CORE는 Windows 환경에서 최신 mihomo 코어와 프로필 관리, 컨트롤러 연결을 한 흐름으로 점검하기 쉽고, 포트·secret·실행 상태를 분리해 확인할 수 있어 이 글과 같은 문제를 재현하고 해결하기에 유리합니다. 다른 클라이언트에서 메뉴가 지나치게 복잡하거나 업데이트가 느려 컨트롤러 설정을 안정적으로 관리하기 어렵다면, 필요한 기능을 확인한 뒤 Clash V.CORE를 다운로드해 Windows 설정을 새로 구성해 보세요.