Clash Verge Rev 외부 컨트롤러 설정 방법｜Windows Web 패널

Clash Verge Rev는 트레이 아이콘에서 모드와 프록시 그룹을 바꾸는 것뿐 아니라, 내부 코어가 제공하는 HTTP API를 통해 웹 브라우저에서도 상태를 관리할 수 있습니다. 이 API의 진입점이 바로 외부 컨트롤러입니다. 외부 컨트롤러를 활성화하면 Web UI에서 현재 노드, 프록시 그룹, 연결 목록, 규칙 매칭 결과와 트래픽 상태를 확인하고, Clash를 재시작하지 않은 채 사용할 노드를 전환할 수 있습니다.

이 글에서는 2026년 기준 Windows의 Clash Verge Rev에서 외부 컨트롤러를 설정하는 흐름을 단계별로 설명합니다. 설정 파일을 직접 수정하는 방법과 앱 화면에서 관리하는 방법을 함께 다루며, 포트와 시크릿의 역할, Web UI 연결 주소, 연결 실패 시 점검 순서까지 정리합니다. 단순히 포트를 열어 두는 것보다 로컬 접근과 인증을 어떻게 제한할지 이해하는 것이 중요합니다.

외부 컨트롤러의 역할과 기본 구조

외부 컨트롤러는 Clash 또는 Mihomo 코어가 열어 두는 로컬 HTTP 서버입니다. 일반적인 프록시 포트가 웹사이트의 요청을 전달하는 용도라면, 외부 컨트롤러 포트는 관리 프로그램이 코어의 상태를 조회하고 명령을 보내는 용도입니다. 따라서 브라우저에서 접속할 때 사용하는 주소와 실제 인터넷 트래픽이 통과하는 포트는 서로 다릅니다.

가장 안전한 기본값은 127.0.0.1:9090입니다. 이 주소는 현재 Windows 컴퓨터에서만 접속할 수 있으므로 같은 네트워크에 있는 다른 기기가 관리 API에 접근할 수 없습니다. 반대로 0.0.0.0:9090은 모든 네트워크 인터페이스에서 연결을 받기 때문에 다른 기기에서 접근할 수 있지만, 강력한 시크릿과 방화벽 규칙이 함께 필요합니다.

Windows에서 외부 컨트롤러 활성화하기

Clash Verge Rev를 실행한 뒤 먼저 사용 중인 코어가 Mihomo인지 확인합니다. 버전에 따라 메뉴 이름이나 설정 화면의 위치가 조금 다를 수 있지만, 일반적으로 설정 또는 Profiles 화면에서 현재 YAML 프로필을 열 수 있습니다. 프로필 편집 기능이 제공되지 않는 경우에는 프로필 파일을 메모장이나 다른 텍스트 편집기로 열어 아래 항목을 추가하면 됩니다.

1. Clash Verge Rev를 실행하고 사용할 프로필을 활성화합니다.
2. 프로필 메뉴에서 YAML 설정 파일을 엽니다. 자동 생성되는 프로필이라면 원본 설정이 덮어써지지 않는 위치에 복사본을 만들어 사용합니다.
3. 최상위 레벨에 external-controller와 secret을 추가합니다.
4. 파일을 저장하고 프로필을 다시 적용하거나 코어를 재시작합니다.
5. Windows 방화벽이나 보안 프로그램이 로컬 포트 연결을 차단하지 않는지 확인합니다.

# Clash Verge Rev / Mihomo 프로필의 최상위 레벨
external-controller: 127.0.0.1:9090
secret: replace-with-a-long-random-secret

# 선택 사항: 로컬 대시보드 파일을 제공할 때
external-ui: ui

YAML에서는 들여쓰기와 키의 위치가 중요합니다. 위 세 항목을 proxies:나 proxy-groups: 아래에 넣으면 하위 속성으로 잘못 해석될 수 있으므로 반드시 설정 파일의 최상위에 배치하세요. 이미 같은 키가 있다면 중복으로 추가하지 말고 기존 값을 수정해야 합니다.

설정 변경 후에도 API가 열리지 않는다면 프로필이 실제로 실행 중인 코어에 적용되었는지 확인하세요. Clash Verge Rev는 여러 프로필을 보관할 수 있고, 편집한 프로필과 현재 활성 프로필이 다를 수 있습니다. 또한 앱을 종료했다가 다시 실행하면 설정이 정상적으로 읽혔는지 확인하기 쉽습니다.

포트와 시크릿을 올바르게 설정하는 방법

external-controller 값은 IP 주소:포트 형식입니다. 127.0.0.1:9090에서 앞부분은 접속을 허용할 네트워크 인터페이스이고 뒷부분은 API 서버가 수신할 TCP 포트입니다. 9090 포트가 다른 프로그램에서 이미 사용 중이면 9091, 9095 또는 19090처럼 사용하지 않는 포트로 변경할 수 있습니다. 단, Web UI에 입력하는 주소도 같은 포트로 맞춰야 합니다.

시크릿은 Web UI가 API에 요청을 보낼 때 사용하는 Bearer 토큰입니다. 짧은 숫자나 password처럼 추측하기 쉬운 문자열은 피하고, 20자 이상의 무작위 문자열을 사용하는 편이 좋습니다. YAML에서 특수문자가 포함된 값은 작은따옴표나 큰따옴표로 감싸면 해석 오류를 줄일 수 있습니다.

external-controller: 0.0.0.0:9090
secret: 'V7mQ2x-9pL4sN8kR1tZ6'

LAN 접근을 활성화했다면 Windows Defender 방화벽에서 9090 포트를 모든 네트워크에 공개하지 않도록 주의하세요. 가능하면 사설 네트워크 프로필에서만 허용하고, 공용 Wi-Fi에서는 해당 인바운드 규칙을 끄는 것이 안전합니다. 인터넷에서 직접 접근할 수 있도록 라우터 포트 포워딩을 설정하는 것은 권장하지 않습니다. 원격 관리가 필요하다면 VPN 내부에서만 API를 노출하는 방식이 더 적절합니다.

Web UI에 API 주소와 인증값 입력하기

외부 컨트롤러가 실행되면 Web UI를 연결할 수 있습니다. Metacubexd나 다른 호환 대시보드는 보통 백엔드 주소, 시크릿 또는 API 토큰을 입력하는 화면을 제공합니다. 로컬에서 실행하는 경우 브라우저 주소창에 대시보드 URL을 열고 다음 값을 입력합니다.

• 백엔드 주소: http://127.0.0.1:9090
• 시크릿: YAML의 secret 값과 정확히 같은 문자열
• 프로토콜: HTTPS가 아닌 로컬 HTTP를 사용하는지 확인

주소 끝에 불필요한 경로를 추가하지 않는 것이 좋습니다. Web UI가 API 경로를 자동으로 붙이는 방식이라면 http://127.0.0.1:9090까지만 입력합니다. 반대로 자체 호스팅된 대시보드가 별도의 API URL 형식을 요구한다면 해당 UI의 안내를 따르되, 포트와 시크릿은 Clash 프로필의 값과 일치해야 합니다.

정상적으로 연결되면 대시보드에서 현재 모드, 프록시 그룹, 노드 목록이 표시됩니다. 프록시 그룹을 열어 노드를 클릭했을 때 선택 상태가 바뀌고, Clash Verge Rev의 화면에서도 동일한 선택이 반영되면 연결이 완료된 것입니다. 연결 탭에서는 현재 실행 중인 요청과 매칭된 규칙을 확인할 수 있으므로 설정 테스트에도 유용합니다.

연결되지 않을 때 점검하는 순서

Web UI에서 “연결할 수 없음”, “Network Error”, “Unauthorized” 같은 메시지가 표시되어도 원인은 각각 다를 수 있습니다. 한 번에 여러 설정을 바꾸기보다 아래 순서대로 확인하면 불필요한 시행착오를 줄일 수 있습니다.

1. 코어 실행 상태 확인: Clash Verge Rev가 열려 있고 해당 프로필이 실제로 실행 중인지 확인합니다. 앱만 실행되어 있고 코어가 중지된 상태라면 포트도 열리지 않습니다.
2. 주소와 포트 확인: YAML의 external-controller와 Web UI의 백엔드 주소가 같은지 비교합니다. 9090과 9091을 혼동하는 경우가 흔합니다.
3. 시크릿 확인: 공백, 따옴표, 대소문자까지 정확히 일치해야 합니다. 시크릿을 설정하지 않은 코어에 토큰을 입력하면 인증 오류가 발생할 수 있습니다.
4. HTTP와 HTTPS 확인: 로컬 컨트롤러가 HTTP로 열려 있는데 Web UI에 https://를 입력하면 연결이 실패할 수 있습니다.
5. 포트 충돌 확인: 다른 프로그램이 같은 포트를 사용하면 코어가 API를 바인딩하지 못할 수 있습니다. 포트를 변경하고 코어를 재시작하세요.
6. 방화벽 확인: 로컬 접근은 대체로 허용되지만, 보안 소프트웨어가 Clash 또는 Mihomo의 네트워크 통신을 차단할 수 있습니다.

Windows PowerShell에서는 포트가 실제로 LISTEN 상태인지 확인할 수 있습니다. 아래 명령에서 결과가 나오지 않으면 외부 컨트롤러가 실행되지 않았거나 다른 포트를 사용 중일 가능성이 큽니다.

Test-NetConnection 127.0.0.1 -Port 9090

인증 오류가 아니라 CORS 오류가 표시되는 경우에는 Web UI의 출처가 API 서버에서 허용되지 않는 상황일 수 있습니다. 사용하는 코어 버전에 따라 external-controller-cors 관련 옵션을 지원할 수 있지만, 무작정 모든 출처를 허용하는 설정은 피해야 합니다. 먼저 로컬에서 공식 또는 신뢰할 수 있는 대시보드를 사용하고, 필요한 경우에만 허용 출처를 제한적으로 추가하세요.

안전한 운영과 설정 백업

외부 컨트롤러 설정은 한 번 연결한 뒤 잊어버리기 쉽지만, 프로필을 공유하거나 네트워크 환경을 바꿀 때 보안 상태가 달라질 수 있습니다. 특히 0.0.0.0으로 바인딩한 설정 파일을 다른 PC에 복사하면 의도하지 않게 LAN 전체에 관리 포트가 열릴 수 있습니다.

• 개인용 Windows PC에서는 가능하면 127.0.0.1을 유지합니다.
• 시크릿을 공개 저장소, 화면 캡처, 로그 파일에 남기지 않습니다.
• Web UI에서 사용하지 않는 연결과 프로필을 정리하고, 의심스러운 노드 설정은 다시 가져오기 전에 확인합니다.
• 프로필을 수정하기 전에 원본 YAML을 백업해 잘못된 들여쓰기나 키 중복에 대비합니다.
• Clash Verge Rev와 Mihomo를 업데이트한 뒤 외부 컨트롤러 호환성을 다시 확인합니다.
• 공용 네트워크에서는 LAN 바인딩을 끄고 로컬 전용 주소로 되돌립니다.

결국 외부 컨트롤러의 핵심은 복잡한 명령어가 아니라 세 가지 값의 일치입니다. 코어가 실행 중이어야 하고, Web UI가 올바른 IP와 포트로 요청해야 하며, 입력한 시크릿이 YAML의 인증값과 같아야 합니다. 이 조건을 만족하면 Windows에서도 브라우저 하나로 노드 상태와 연결 흐름을 확인하면서 Clash Verge Rev를 훨씬 편리하게 운영할 수 있습니다.