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

서론: 외부 컨트롤러란 무엇인가

Clash Verge Rev의 외부 컨트롤러(External Controller)는 실행 중인 Mihomo 코어를 웹 패널이나 별도의 관리 도구에서 제어할 수 있게 해 주는 API 인터페이스입니다. 일반적인 시스템 프록시 설정은 트래픽을 어디로 보낼지 결정하는 기능에 집중하지만, 외부 컨트롤러는 현재 연결 상태, 프록시 그룹, 선택된 노드, 규칙 명중 기록, 로그와 설정 정보를 확인하고 변경하는 역할을 담당합니다.

Windows에서 Clash Verge Rev를 사용하다 보면 기본 화면 대신 브라우저 기반 Web 패널에서 노드를 바꾸거나, 여러 기기에서 관리 화면을 열거나, 자동화 도구를 연결해야 하는 경우가 있습니다. 이때 외부 컨트롤러 주소와 API Secret이 올바르게 설정되어 있어야 합니다. 주소가 비어 있거나 포트가 다른 경우에는 Web 패널이 열리지 않고, Secret이 일치하지 않으면 화면은 표시되더라도 API 요청이 거부될 수 있습니다.

이 설정은 프록시 노드나 구독 링크를 새로 만드는 과정이 아닙니다. 이미 Clash Verge Rev가 설치되어 있고 Mihomo 코어가 실행 중이라는 전제에서, 관리 인터페이스를 연결하는 방법을 다룹니다. 따라서 먼저 프로필이 정상적으로 로드되고 시스템 프록시가 작동하는지 확인한 다음 아래 단계를 진행하는 것이 좋습니다.

1설정 전 확인할 항목

외부 컨트롤러를 활성화하기 전에 Clash Verge Rev와 Windows 환경을 간단히 점검하세요. 설정 메뉴의 명칭과 배치는 설치 버전, 선택한 코어, 언어에 따라 조금씩 다를 수 있지만, 핵심 항목은 대체로 동일합니다.

• Clash Verge Rev 실행 여부: 작업 표시줄 알림 영역에 프로그램이 실행 중인지 확인합니다. 창만 닫고 백그라운드에서 계속 실행되는 경우도 있으므로 트레이 아이콘을 함께 확인하세요.
• 프로필 로드 여부: 유효한 YAML 프로필을 선택하고 업데이트가 완료되었는지 확인합니다. 프로필 오류가 있으면 컨트롤러가 실행되어도 프록시 그룹 정보가 비어 있을 수 있습니다.
• Mihomo 코어 상태: 현재 사용 중인 코어가 정상적으로 시작되었는지 로그에서 확인합니다. 코어가 중지되어 있으면 API 포트도 연결되지 않습니다.
• 포트 충돌 여부: 다른 Clash 계열 클라이언트, Mihomo 서비스, 개발 도구가 같은 포트를 사용하지 않는지 확인합니다.
• 관리 범위: 같은 Windows PC에서만 사용할지, 같은 사설 네트워크의 다른 기기에서도 사용할지 먼저 결정합니다.

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

이제 Clash Verge Rev의 설정 화면에서 외부 컨트롤러 주소와 Secret을 지정합니다. 버전에 따라 항목이 Settings, Core, External Controller, 또는 API와 같은 이름으로 표시될 수 있습니다. 메뉴 이름보다 주소와 인증값이 실제 코어 설정에 반영되는지를 확인하는 것이 중요합니다.

1. Clash Verge Rev를 실행한 뒤 왼쪽 메뉴에서 설정 또는 코어 관련 화면을 엽니다.
2. External Controller 또는 유사한 API 주소 입력란을 찾습니다.
3. 주소에 127.0.0.1:9090을 입력합니다. 이미 다른 프로그램이 포트를 사용한다면 127.0.0.1:9095처럼 사용 가능한 포트를 선택할 수 있습니다.
4. Secret 입력란에 영문 대소문자와 숫자를 섞은 긴 값을 입력합니다. 공백이나 따옴표는 포함하지 않는 것이 안전합니다.
5. 저장 또는 적용 버튼을 누른 뒤 Mihomo 코어를 재시작합니다. 일부 버전에서는 애플리케이션을 완전히 종료한 후 다시 실행해야 변경 내용이 반영됩니다.

설정 파일을 직접 관리하는 환경이라면 다음과 같은 형태가 기본적인 예시가 됩니다. 실제 설정 파일에서는 기존 포트, DNS, 프로필 구조와 충돌하지 않도록 중복 키를 만들지 마세요.

external-controller는 API가 수신 대기할 주소와 포트를 의미하고, secret은 API 요청에 필요한 인증 토큰입니다. 두 값을 바꾼 뒤에는 기존 Web 패널에 저장된 연결 정보도 새 값으로 수정해야 합니다. 특히 포트만 변경하고 브라우저에서는 예전 포트로 접속하면 연결 실패처럼 보일 수 있습니다.

3Web 패널에 연결하는 방법

외부 컨트롤러 자체는 API이므로, 사용자가 보기 쉬운 화면을 표시하려면 Web 패널이 필요합니다. Clash Verge Rev에 내장된 패널을 사용하거나, 설치 버전에서 제공하는 관리 화면을 열 수 있습니다. 패널을 처음 실행하면 API 주소와 Secret을 입력하는 화면이 나타나며, 여기에는 앞에서 설정한 값과 동일한 정보를 입력해야 합니다.

연결이 완료되면 Web 패널에서 선택된 프록시 그룹의 노드를 바꾸거나, 규칙 모드와 전역 모드를 확인하고, 현재 요청이 어떤 규칙에 의해 처리되는지 살펴볼 수 있습니다. 다만 Web 패널에서 변경한 값은 프로필 파일 자체를 영구적으로 수정하지 않을 수 있습니다. 프로필을 다시 적용하거나 업데이트하면 선택한 노드가 초기화될 수 있으므로, 항상 필요한 설정은 원본 프로필 또는 오버라이드 설정에도 반영하세요.

4연결 실패 해결과 보안 점검

외부 컨트롤러 연결이 실패했을 때는 무작정 포트를 바꾸기보다, 네트워크 범위를 좁혀 한 단계씩 확인하는 것이 빠릅니다. 먼저 Clash Verge Rev가 완전히 실행 중인지 확인하고, 설정에 입력한 주소와 브라우저에 입력한 주소가 정확히 일치하는지 비교하세요. localhost와 127.0.0.1은 대부분 같은 PC를 가리키지만, 문제가 지속되면 후자를 사용해 보세요.

Windows에서 포트 사용 상태 확인

PowerShell 또는 명령 프롬프트에서 다음 명령을 실행하면 해당 포트를 다른 프로세스가 사용 중인지 확인할 수 있습니다.

결과가 나타나면 마지막 숫자인 PID를 확인한 뒤 작업 관리자에서 해당 프로세스를 찾습니다. 이미 다른 Clash 클라이언트가 포트를 점유하고 있다면 두 프로그램 중 하나를 종료하거나, Clash Verge Rev의 외부 컨트롤러 포트를 다른 값으로 변경하세요. 변경 후에는 Web 패널 주소도 함께 바꿔야 합니다.

Secret과 접근 범위 보호

• Secret을 공개하지 않기: Secret을 가진 사용자는 프록시 그룹 변경, 연결 정보 확인 등 API가 허용하는 관리 작업을 수행할 수 있습니다. 화면 캡처나 로그를 공유할 때 Secret을 가리세요.
• 로컬 주소 우선: 혼자 사용하는 Windows PC라면 127.0.0.1이 가장 안전합니다. 공유기 내부에서 다른 기기가 접근해야 할 때만 사설 IP 바인딩을 고려하세요.
• 공용 인터넷에 직접 노출하지 않기: 외부 컨트롤러 포트를 공유기 포트 포워딩이나 공인 IP에 연결하지 마세요. TLS, 방화벽, 별도 인증 계층 없이 API를 인터넷에 공개하면 자동 스캐너의 공격 대상이 될 수 있습니다.
• Windows 방화벽 확인: 로컬 연결은 대체로 허용되지만, 다른 기기에서 접근할 때는 방화벽 인바운드 규칙이 영향을 줄 수 있습니다. 필요한 경우에도 전체 인터넷이 아닌 신뢰할 수 있는 사설 네트워크로 범위를 제한하세요.

5최종 점검 체크리스트

모든 설정을 마친 뒤에는 아래 순서로 최종 테스트를 진행하세요. 먼저 Web 패널에서 현재 노드와 프록시 그룹이 표시되는지 확인하고, 노드를 변경했을 때 Clash Verge Rev의 대시보드에도 같은 상태가 반영되는지 살펴봅니다. 그다음 브라우저에서 실제 웹사이트를 열어 트래픽이 정상적으로 흐르는지 확인합니다.

1. Clash Verge Rev와 Mihomo 코어가 실행 중인지 확인합니다.
2. 외부 컨트롤러 주소가 127.0.0.1:포트 형식으로 설정되어 있는지 확인합니다.
3. Web 패널의 API 주소, 포트, Secret이 Clash 설정과 일치하는지 확인합니다.
4. 노드 선택, 규칙 모드, 연결 상태가 Web 패널과 데스크톱 화면에서 동일한지 확인합니다.
5. 사용하지 않는 포트는 닫고, Secret을 주기적으로 교체합니다.

이 과정을 완료하면 Windows용 Clash Verge Rev의 외부 컨트롤러를 안정적으로 사용할 수 있습니다. 핵심은 복잡한 설정을 많이 추가하는 것이 아니라, 정확한 API 주소, 일치하는 Secret, 제한된 접근 범위를 유지하는 것입니다. 연결 오류가 발생해도 포트 충돌, 인증값, 코어 상태, Web 패널 주소를 순서대로 점검하면 대부분의 문제를 빠르게 해결할 수 있습니다.

또한 외부 컨트롤러는 편리한 관리 기능인 만큼 보안 관리가 중요합니다. 다른 기기에서 접근할 필요가 없다면 로컬 주소를 유지하고, 설정 파일이나 화면을 공유하기 전에는 Secret을 반드시 삭제하거나 가리세요. 이렇게 기본 원칙을 지키면 Web 패널을 이용한 노드 관리와 상태 확인을 보다 안전하게 운영할 수 있습니다.