외부 컨트롤러 기능부터 이해하기
Clash Verge Rev의 외부 컨트롤러는 프록시 트래픽을 전달하는 포트가 아니라, 실행 중인 mihomo 코어를 관리하기 위한 HTTP API입니다. 웹 대시보드는 이 API에 접속해 현재 모드, 프록시 목록, 지연 시간, 활성 연결, 로그와 정책 그룹을 읽고 일부 설정을 변경합니다. 따라서 브라우저에 대시보드가 열리지 않는다고 해서 반드시 노드나 구독에 문제가 있는 것은 아닙니다. 코어가 실행 중인지, API가 어느 주소와 포트에서 수신 중인지, 대시보드가 올바른 시크릿을 보내는지를 별도로 확인해야 합니다.
Windows의 Clash Verge Rev에서는 메뉴 이름과 위치가 설치 버전이나 테마에 따라 조금 다를 수 있습니다. 일반적으로 프로필 또는 설정 화면에서 현재 사용 중인 YAML을 확인한 뒤, 코어 설정의 external-controller, secret, 필요하다면 external-ui 항목을 점검합니다. 앱 화면에 컨트롤러 관련 입력란이 있다면 그 값을 우선 사용하고, 직접 YAML을 수정할 때는 기존 오버라이드나 프로필 생성 규칙이 값을 덮어쓰지 않는지 확인해야 합니다.
| 항목 | 역할 | 권장 예시 |
|---|---|---|
| mixed-port | 브라우저와 앱이 프록시로 사용할 로컬 포트 | 127.0.0.1:7890 |
| external-controller | 대시보드와 API 클라이언트가 접속할 주소와 포트 | 127.0.0.1:9090 |
| secret | 외부 컨트롤러 API 인증용 토큰 | 충분히 긴 임의 문자열 |
| external-ui | 로컬에 저장된 웹 대시보드 파일의 위치 | ui 또는 앱이 지정한 경로 |
Windows에서 컨트롤러 설정하기
먼저 Clash Verge Rev를 실행하고 원하는 프로필을 활성화합니다. 외부 컨트롤러 설정은 파일에 저장되어 있더라도 코어가 다시 시작될 때 적용되는 경우가 많으므로, 설정을 변경한 뒤에는 현재 프로필을 다시 적용하거나 mihomo 코어를 재시작해야 합니다. 설정을 편집하기 전에 원본 YAML을 별도의 파일로 복사해 두면 잘못된 들여쓰기나 중복 키로 인해 코어가 시작되지 않는 상황을 쉽게 되돌릴 수 있습니다.
- Clash Verge Rev의 프로필 또는 설정 목록에서 현재 사용 중인 YAML을 확인합니다.
- 설정 편집 기능을 열고 최상위에 외부 컨트롤러 관련 필드를 추가하거나 기존 값을 수정합니다.
- 처음에는 외부 공개가 필요하지 않으므로 주소를
127.0.0.1로 제한합니다. - 시크릿에는 짧은 숫자 하나가 아니라 영문 대소문자, 숫자와 기호를 섞은 긴 문자열을 사용합니다.
- 파일을 저장하고 프로필을 다시 적용한 다음 코어가 정상적으로 실행되는지 로그에서 확인합니다.
mixed-port: 7890
allow-lan: false
mode: rule
external-controller: 127.0.0.1:9090
secret: "Windows-Local-Controller-Change-Me-2026"YAML에서 콜론, 해시 기호 또는 특수 문자가 들어간 시크릿은 따옴표로 감싸는 편이 안전합니다. 같은 키를 파일 안에 두 번 작성하면 파서나 오버라이드 처리 방식에 따라 예상하지 못한 값이 적용될 수 있으므로 기존 external-controller와 secret을 먼저 검색한 뒤 하나만 남기세요. 시크릿을 변경하면 기존 대시보드의 저장된 인증 정보가 더 이상 유효하지 않으므로 대시보드에서 토큰을 새로 입력해야 합니다.
LAN 접속을 허용해야 할 때
같은 Windows PC의 브라우저에서만 대시보드를 사용할 경우 127.0.0.1이 가장 안전합니다. 휴대폰이나 같은 공유기의 다른 컴퓨터에서 접속해야 할 때만 0.0.0.0:9090 또는 Windows의 실제 LAN 주소를 고려합니다. 이 경우 API 포트가 네트워크에 노출되므로 allow-lan을 켜는 것만으로 끝내지 말고 Windows 방화벽의 인바운드 규칙, 공유기 포트 포워딩, 강한 시크릿을 함께 점검해야 합니다.
allow-lan: true
external-controller: 0.0.0.0:9090
secret: "Use-A-Long-Random-Secret-Only-On-LAN"웹 대시보드에 연결하기
외부 컨트롤러가 정상적으로 실행되면 대시보드는 컨트롤러 주소와 API 포트를 기준으로 접속합니다. Clash Verge Rev에 내장된 대시보드 선택 메뉴가 있다면 대시보드 또는 UI 항목에서 원하는 인터페이스를 선택합니다. 별도의 로컬 UI를 사용하는 구성에서는 external-ui가 가리키는 디렉터리에 대시보드 파일이 있어야 하며, 단순히 external-controller만 설정했다고 해서 웹 화면 파일이 자동으로 설치되는 것은 아닙니다.
접속 주소는 설치된 대시보드 방식에 따라 달라질 수 있지만, 핵심 API 주소는 보통 http://127.0.0.1:9090입니다. 대시보드 입력란에는 이 주소와 시크릿을 정확히 넣습니다. 주소 끝에 불필요한 공백을 붙이지 말고, 시크릿을 큰따옴표까지 복사하지 않도록 주의하세요. 브라우저에서 대시보드 화면은 열리지만 프록시 목록이 비어 있다면 웹 파일 문제보다 API 주소, 인증 토큰 또는 실행 중인 코어의 컨트롤러 값을 먼저 확인해야 합니다.
API로 실행 상태 확인하기
Windows PowerShell에서는 브라우저보다 간단하게 외부 컨트롤러의 응답을 확인할 수 있습니다. 아래 명령의 시크릿과 포트는 자신의 설정에 맞게 바꿔야 합니다. 토큰이 포함된 명령 기록이나 출력 결과를 다른 사람에게 그대로 보내지 마세요.
$secret = "Windows-Local-Controller-Change-Me-2026"
$headers = @{ Authorization = "Bearer $secret" }
Invoke-RestMethod `
-Uri "http://127.0.0.1:9090/version" `
-Headers $headers정상적인 경우 JSON 형식으로 코어 버전과 API 버전이 반환됩니다. 401 Unauthorized가 나오면 주소는 도달했지만 시크릿이 비어 있거나 일치하지 않는 것입니다. 404 Not Found가 나오면 잘못된 경로를 사용했거나 해당 포트가 Clash API가 아닐 수 있습니다. 연결 자체가 거부되면 코어가 실행되지 않았거나 다른 프로그램이 해당 포트를 사용하고 있거나, 컨트롤러가 다른 주소에 바인딩된 상태일 가능성이 큽니다.
| 증상 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
| 페이지가 열리지 않음 | 대시보드 파일, 주소, 포트 | external-ui와 API 주소를 다시 확인 |
| 401 Unauthorized | secret 값 |
대시보드의 저장 토큰을 삭제하고 다시 입력 |
| Connection refused | 코어 실행 상태와 포트 수신 여부 | 코어 로그와 포트 점유 프로세스를 확인 |
| 대시보드는 열리지만 목록이 비어 있음 | API 대상 주소, 현재 실행 중인 코어 | 다른 포트의 API에 접속한 것은 아닌지 점검 |
| 원격 기기에서만 접속 실패 | 바인딩 주소와 Windows 방화벽 | LAN 허용 여부와 인바운드 규칙을 확인 |
포트와 Windows 방화벽 점검하기
설정 파일에 9090을 입력했더라도 다른 프로그램이 이미 해당 포트를 사용하면 mihomo가 시작되지 않거나 컨트롤러가 실제로는 다른 포트에서 실행될 수 있습니다. PowerShell에서 다음 명령으로 해당 포트의 수신 상태를 확인할 수 있습니다.
Get-NetTCPConnection -LocalPort 9090 -State Listen
Test-NetConnection 127.0.0.1 -Port 9090Test-NetConnection의 TcpTestSucceeded가 True이면 해당 주소와 포트에 TCP 연결이 가능하다는 뜻입니다. 이것만으로 시크릿 인증이나 대시보드 파일까지 정상이라는 의미는 아닙니다. 포트가 이미 사용 중이라면 Clash Verge Rev의 컨트롤 포트를 9091처럼 다른 값으로 바꾸고, 대시보드 주소도 같은 값으로 수정한 뒤 코어를 재시작합니다.
로컬 PC에서는 연결되지만 같은 네트워크의 다른 장치에서 실패한다면 Windows Defender 방화벽이 외부 인바운드 연결을 차단할 수 있습니다. 먼저 컨트롤러를 127.0.0.1에서 LAN 주소로 변경했는지 확인하고, 방화벽 규칙은 신뢰하는 사설 네트워크 프로필에서만 제한적으로 허용하세요. 공용 네트워크에서 무분별하게 포트를 열면 카페나 공항 Wi-Fi의 다른 장치가 API에 접근할 수 있습니다.
로그와 설정 우선순위 확인하기
설정을 저장했는데도 이전 포트가 계속 사용된다면 현재 활성 프로필이 다른 파일이거나, 전역 설정과 프로필 설정이 서로 덮어쓰고 있을 수 있습니다. Clash Verge Rev에서 현재 적용된 프로필 이름을 확인하고, 코어 시작 로그에 표시되는 실제 리스닝 주소를 기준으로 판단하세요. 파일에 external-controller: 127.0.0.1:9090을 적어 두었더라도 앱의 런타임 설정이나 오버라이드가 이를 바꾸면 화면의 최종 값이 우선합니다.
- 코어 시작 실패: YAML 들여쓰기, 중복 키, 포트 충돌과 지원되지 않는 필드를 확인합니다.
- API 포트가 열리지 않음: 현재 실행 중인 프로필과 코어 프로세스의 로그를 확인합니다.
- 토큰 오류: 시크릿을 변경한 뒤 브라우저에 남은 이전 인증 정보를 삭제합니다.
- 대시보드 데이터 오류: API 주소가 프록시 포트가 아닌 컨트롤러 포트를 가리키는지 확인합니다.
- 설정 재시작 후 원복: 구독 프로필의 자동 생성 또는 오버라이드가 값을 다시 덮어쓰는지 확인합니다.
안전한 운영을 위한 최종 점검
Windows에서 Clash Verge Rev 외부 컨트롤러를 사용할 때 가장 안정적인 기본값은 external-controller: 127.0.0.1:9090과 강한 secret의 조합입니다. 같은 PC에서 대시보드를 사용할 뿐이라면 LAN 공개를 활성화할 이유가 없습니다. 대시보드가 정상적으로 연결된 뒤에도 실제 코어가 원하는 프로필과 노드를 사용하고 있는지, 시스템 프록시 포트와 컨트롤 포트가 분리되어 있는지, 시크릿이 로그나 화면 공유에 노출되지 않았는지 확인하세요.
- 현재 활성 프로필과 mihomo 코어 실행 상태를 확인합니다.
external-controller가 실제로 사용할 주소와 포트인지 확인합니다.secret을 충분히 길게 설정하고 공개하지 않습니다.- PowerShell의
/version요청으로 API 응답과 인증을 테스트합니다. - 대시보드에 동일한 API 주소와 시크릿을 입력합니다.
- LAN 접속이 필요하지 않다면
127.0.0.1바인딩과allow-lan: false를 유지합니다. - 문제가 생기면 코어 로그, 포트 점유 상태, 방화벽과 설정 우선순위를 차례로 점검합니다.
외부 컨트롤러는 편리한 웹 관리 기능이지만, 프록시 연결을 위한 필수 포트는 아닙니다. API가 필요하지 않은 환경에서는 기능을 최소화하고 로컬 접속만 허용하는 것이 좋습니다. 반대로 여러 장치에서 관리해야 한다면 먼저 네트워크 범위와 인증 방식을 설계한 뒤 포트를 열어야 합니다. 이 원칙을 지키면 대시보드 연결 실패와 컨트롤러 노출 위험을 함께 줄일 수 있습니다.