외부 컨트롤러가 필요한 이유
Clash Verge Rev(이하 CVR)를 Windows에서 사용하다 보면 브라우저로 프록시 상태를 확인하거나, 현재 연결된 노드와 모드를 바꾸거나, 실행 중인 코어의 로그를 다른 장치에서 열어 보고 싶은 순간이 생깁니다. 이때 사용하는 기능이 외부 컨트롤러(External Controller)입니다. 외부 컨트롤러는 CVR의 관리 API를 특정 주소와 포트로 열어 주며, Web 패널이나 호환되는 관리 도구가 해당 API에 접속해 상태를 읽고 설정을 변경하도록 합니다.
다만 외부 컨트롤러는 일반적인 웹사이트 주소가 아닙니다. 프록시 노드 목록, 현재 모드, 연결 로그, 프로필 정보처럼 민감한 데이터가 노출될 수 있고, 쓰기 권한이 있는 패널이라면 프록시 전환이나 설정 변경도 가능합니다. 따라서 Windows에서 처음 설정할 때는 단순히 포트만 입력하는 것보다 컨트롤러 주소, 포트, 인증 토큰, 접속 범위를 함께 확인해야 합니다. 이 글에서는 CVR의 버전에 따라 메뉴 이름이 조금 다를 수 있다는 점을 고려해, 공통적으로 적용할 수 있는 확인 순서를 설명합니다.
이 설정은 다음과 같은 상황에 특히 유용합니다.
- 브라우저에서 CVR의 현재 프록시 모드와 활성 노드를 확인하고 싶은 경우
- Windows 작업 표시줄 메뉴를 열지 않고 Web 패널에서 노드를 바꾸고 싶은 경우
- 같은 PC의 다른 관리 도구가 CVR의 API를 읽어야 하는 경우
- 연결 실패 시 어떤 도메인이 어느 정책 그룹으로 분기되었는지 확인해야 하는 경우
설정 전 확인할 Windows와 CVR 상태
먼저 Clash Verge Rev가 정상적으로 실행 중인지 확인합니다. 프로필이 하나 이상 등록되어 있고, 그중 하나가 활성 프로필로 선택되어 있어야 합니다. 프로필이 비어 있거나 코어가 시작되지 않은 상태에서도 컨트롤러 포트 자체는 열릴 수 있지만, Web 패널에는 노드와 규칙 정보가 표시되지 않거나 오류가 나타날 수 있습니다. 따라서 외부 컨트롤러를 설정하기 전에 CVR 메인 화면에서 코어 상태가 실행 중인지, 프록시 모드가 Rule이나 Global 중 원하는 값으로 지정되어 있는지 먼저 봅니다.
Windows의 보안 프로그램이나 기업용 방화벽이 로컬 포트 연결을 차단하는지도 점검해야 합니다. 같은 PC의 브라우저가 127.0.0.1 또는 localhost에 접속하는 경우에는 대부분 문제가 없지만, 다른 PC나 휴대폰에서 접속하려면 Windows 방화벽의 인바운드 정책이 영향을 줍니다. 회사·학교 네트워크에서는 로컬 관리 API를 LAN에 공개하는 행위가 정책 위반이 될 수 있으므로, 개인 장치와 관리되는 장치를 구분해 설정하세요.
| 확인 항목 | 권장 기준 | 문제가 생길 때 나타나는 현상 |
|---|---|---|
| CVR 코어 | 실행 중이며 활성 프로필이 존재 | 패널은 열리지만 노드·규칙 정보가 비어 있음 |
| 컨트롤러 주소 | 같은 PC는 127.0.0.1, LAN은 필요한 경우에만 허용 | 브라우저에서 연결 거부 또는 시간 초과 |
| 컨트롤러 포트 | 다른 프로그램이 사용하지 않는 포트 | CVR이 API를 열지 못하거나 시작할 때 포트 충돌 발생 |
| 인증 토큰 | 충분히 긴 임의 문자열을 사용 | 401 또는 unauthorized 응답 |
| Windows 방화벽 | 외부 공개가 필요한 경우에만 제한적으로 허용 | 같은 PC는 접속되지만 다른 장치에서는 접속 실패 |
127.0.0.1로 두고 같은 Windows PC의 브라우저에서 먼저 테스트하세요. 로컬 접속이 성공한 뒤에만 LAN 접속을 검토하면 방화벽과 주소 문제를 한꺼번에 추적하지 않아도 됩니다.
Clash Verge Rev에서 외부 컨트롤러 설정하기
CVR을 열고 설정 화면에서 External Controller, 외부 컨트롤러, 또는 컨트롤러 주소를 의미하는 항목을 찾습니다. CVR의 릴리스나 한국어 번역 상태에 따라 메뉴가 Settings, Profiles, Core 주변에 배치될 수 있으므로 특정 버튼 이름보다 입력 항목의 의미를 기준으로 확인하는 것이 좋습니다. 일반적으로 입력해야 하는 값은 주소와 포트, 그리고 Secret 또는 API Token입니다.
- Clash Verge Rev를 실행하고 설정 화면을 엽니다.
- 외부 컨트롤러 주소 입력란에
127.0.0.1:9090과 같은 형식을 입력합니다. - Secret 또는 Token 입력란에 인증용 임의 문자열을 입력합니다.
- 저장 또는 적용 버튼을 누른 뒤 코어를 재시작합니다.
- 설정 화면에 표시된 주소와 실제 API 포트가 일치하는지 다시 확인합니다.
포트 번호는 반드시 CVR에서 실제로 저장된 값을 사용해야 합니다. 인터넷에서 찾은 예제 때문에 무조건 9090을 입력할 필요는 없습니다. 다른 프로그램이 이미 해당 포트를 사용하고 있거나, 구독 프로필과 함께 생성된 설정이 별도 포트를 지정한 경우에는 CVR의 현재 값이 우선입니다. 주소 앞에 http://를 넣어야 하는 Web 패널도 있고, 입력란이 주소와 포트를 분리해 받는 경우도 있으므로 필드에 안내된 형식을 그대로 따르세요.
토큰은 기억하기 쉬운 짧은 숫자보다 영문 대소문자와 숫자를 섞은 긴 문자열이 안전합니다. 토큰을 Windows 메모장, 공개 채팅, 저장소의 YAML 파일에 그대로 보관하지 말고, 다른 사람에게 전달할 때도 전체 값을 노출하지 않는 편이 좋습니다. 이미 토큰을 여러 곳에 공유했다면 새 토큰으로 교체하고, 이전 토큰을 사용하는 Web 패널이나 스크립트도 함께 갱신해야 합니다.
LAN의 다른 장치에서 CVR을 관리해야 한다면 주소를 0.0.0.0으로 열거나 Windows의 로컬 IP를 지정하는 선택지가 있을 수 있습니다. 그러나 이 설정은 모든 네트워크 인터페이스에서 API를 받을 가능성을 키웁니다. 공유기나 공용 Wi-Fi에 연결된 상태에서 무심코 LAN 공개를 켜면 같은 네트워크의 다른 사용자가 포트에 접근할 수 있으므로, 실제로 필요한 경우에만 사용하고 방화벽에서 허용된 사설 대역을 제한하세요.
브라우저에서 Web 패널 연결 확인
설정을 저장했다면 같은 Windows PC에서 브라우저를 열어 CVR이 제공하는 Web 패널 주소로 접속합니다. 패널이 로드되면 컨트롤러 주소와 포트를 입력하고, Secret 또는 Token 항목에는 CVR에 저장한 인증 값을 입력합니다. 일부 패널은 처음 접속할 때 토큰을 한 번만 요구하고 브라우저 저장소에 보관하므로, 공용 PC나 다른 사람과 함께 사용하는 Windows 계정에서는 자동 저장 기능을 사용하지 않는 편이 안전합니다.
정상 연결이라면 대시보드에 현재 모드, 업로드·다운로드 통계, 활성 프록시 그룹, 노드 목록 또는 연결 기록이 표시됩니다. 단순히 로그인 화면이 열린 것만으로 성공했다고 판단하지 말고, 노드 목록을 새로 고치거나 현재 모드를 조회해 보세요. 읽기 요청은 성공하지만 노드 전환만 실패한다면 패널의 API 호환성이나 컨트롤러 권한 설정을 별도로 확인해야 합니다.
브라우저의 개발자 도구를 사용할 수 있다면 Network 탭에서 컨트롤러 API 요청의 상태 코드도 확인합니다. 200은 일반적으로 정상 응답이며, 401은 토큰이 없거나 틀렸다는 뜻입니다. 404는 Web 패널이 예상하는 API 경로와 CVR 코어의 API가 다를 가능성이 있고, Failed to fetch나 연결 시간 초과는 주소·포트·방화벽 문제일 때 자주 나타납니다.
| 상태 | 가능성이 높은 원인 | 확인할 내용 |
|---|---|---|
| 401 Unauthorized | 토큰 불일치 | 공백 포함 여부, 대소문자, 저장 후 재시작 여부 |
| Connection refused | 포트가 닫혔거나 코어가 중지됨 | CVR 코어 상태와 컨트롤러 포트 번호 |
| Timeout | LAN 주소 또는 방화벽 차단 | 같은 PC 접속 여부, Windows 방화벽 규칙 |
| 패널은 열리나 데이터 없음 | API 호환성 또는 코어 미실행 | 코어 버전, 활성 프로필, 패널의 지원 범위 |
LAN 접속과 보안 설정
휴대폰이나 같은 사무실의 다른 PC에서 Web 패널을 열 목적이라면 먼저 Windows의 사설 IP를 확인합니다. 명령 프롬프트에서 ipconfig를 실행하면 현재 어댑터의 IPv4 주소를 볼 수 있습니다. 예를 들어 Windows PC가 192.168.0.25라면 다른 장치에서는 컨트롤러 포트와 결합한 주소를 사용하게 됩니다. 단, 해당 장치가 같은 사설 네트워크에 있어야 하며, 게스트 Wi-Fi처럼 클라이언트 간 통신을 차단하는 네트워크에서는 주소가 맞아도 접속되지 않습니다.
Windows 방화벽에서 포트를 허용할 때는 모든 프로필과 모든 원격 주소에 공개하는 방식보다 Private 네트워크에만 허용하고, 필요한 로컬 대역만 지정하는 방식이 낫습니다. 공용 네트워크 프로필에서 컨트롤러 포트를 열지 말고, 공유기 포트 포워딩으로 인터넷에 직접 노출하는 것도 피하세요. 외부에서 관리해야 한다면 일반 포트 공개보다 VPN이나 안전한 원격 접속 경로를 사용하는 것이 적절합니다.
컨트롤러 API는 프록시 트래픽을 전달하는 mixed port와 목적이 다릅니다. 두 포트를 같은 번호로 설정하거나, Web 패널 주소에 프록시 포트를 넣으면 접속이 되지 않을 수 있습니다. 또한 프록시 URL에 토큰을 붙여 공유하는 식으로 인증을 우회하지 마세요. API 토큰은 관리 권한의 열쇠이므로 브라우저 주소 기록, 스크린샷, 화면 공유에 남지 않게 관리해야 합니다.
연결되지 않을 때의 진단 순서
문제가 생기면 먼저 범위를 좁혀야 합니다. 같은 PC의 브라우저에서도 연결되지 않는다면 LAN이나 공유기보다 CVR 설정, 코어 상태, 포트 충돌을 먼저 확인합니다. 반대로 같은 PC에서는 정상인데 휴대폰이나 다른 Windows PC에서만 실패한다면 컨트롤러 주소가 로컬호스트로 고정되어 있거나 방화벽이 외부 접속을 막고 있을 가능성이 큽니다.
명령 프롬프트에서 포트가 열려 있는지 확인할 때는 netstat -ano | findstr :9090처럼 실제 포트 번호를 넣어 볼 수 있습니다. 아무 결과도 나오지 않으면 CVR이 해당 포트를 열지 않았거나 다른 포트로 저장된 것입니다. 다른 프로세스가 포트를 차지하고 있다면 PID를 확인한 뒤, 불필요한 프로그램을 종료하거나 CVR에 사용하지 않는 포트를 지정합니다. 포트를 변경한 뒤에는 Web 패널의 주소도 반드시 새 값으로 바꿔야 합니다.
토큰 오류는 복사·붙여넣기 과정에서 앞뒤 공백이 들어가는 경우가 흔합니다. CVR에 보이는 값을 직접 다시 복사하고, 패널에 저장된 기존 인증 정보를 삭제한 후 재입력하세요. 그래도 401이 계속되면 CVR을 재시작하고 새 토큰으로 테스트합니다. 패널이 오래된 Mihomo API 경로를 사용하거나 CVR 코어가 지원하지 않는 기능을 호출하는 경우에는 대시보드 일부만 비어 있을 수 있으므로, 기본 상태 조회와 노드 전환을 나누어 확인하는 것이 좋습니다.
설정 변경 뒤에는 연결 로그의 시간을 맞춰 보는 습관도 도움이 됩니다. Web 패널에서 노드를 바꾼 시각과 CVR 로그에 기록된 정책 그룹 변경 시각이 일치하는지 확인하고, 실제 애플리케이션 요청이 새 노드를 사용하는지도 살펴보세요. 외부 컨트롤러 연결 성공은 Web 패널과 API 사이의 통신이 된다는 의미이지, 모든 Windows 애플리케이션이 자동으로 프록시를 사용한다는 뜻은 아닙니다. 시스템 프록시, TUN, 애플리케이션별 프록시 설정은 별도로 점검해야 합니다.
다른 프록시 관리 도구는 메뉴가 단순한 대신 API 포트가 고정되어 있거나, 인증 토큰과 LAN 공개를 세밀하게 나누기 어려운 경우가 있습니다. 반면 Clash Verge Rev는 Windows에서 프로필·코어·컨트롤러·연결 로그를 한 흐름으로 확인할 수 있고, 로컬호스트부터 제한적인 LAN 접근까지 단계적으로 조정할 수 있어 외부 컨트롤러를 관리하기 편합니다. 브라우저에서 상태를 확인하면서도 보안 범위를 직접 통제하고 싶다면, 먼저 CVR의 현재 빌드에 맞는 클라이언트를 준비해 두는 것이 자연스러운 다음 단계입니다.