Clash Verge Rev 외부 컨트롤러란 무엇인가
Clash Verge Rev 외부 컨트롤러는 실행 중인 Mihomo 코어를 브라우저나 별도 관리 도구에서 제어할 수 있게 해 주는 HTTP API입니다. 일반적인 대시보드에서 프록시 그룹을 바꾸거나 연결 로그를 확인하는 것뿐 아니라, 현재 선택된 노드, 규칙 매칭 결과, 메모리 사용량, 연결된 애플리케이션까지 API를 통해 조회할 수 있습니다. Windows에서 Clash Verge Rev를 사용하다가 브라우저용 WebUI를 연결하고 싶다면, 먼저 이 외부 컨트롤러의 주소와 인증 비밀키를 정확히 설정해야 합니다.
여기서 말하는 외부 컨트롤러는 인터넷에 공개된 원격 관리 서버와 같은 의미가 아닙니다. 기본적으로는 Windows PC 내부에서 127.0.0.1 또는 localhost로만 열어 두고, 같은 컴퓨터의 브라우저가 API에 접근하도록 구성하는 방식이 안전합니다. 외부 주소인 0.0.0.0에 바인딩하면 다른 장치에서도 접근할 가능성이 생기므로, 특별한 이유가 없다면 사용하지 않는 편이 좋습니다. 포트 번호와 secret을 잘못 입력하면 WebUI가 열리더라도 데이터를 불러오지 못하거나, 연결 직후 인증 오류가 발생할 수 있습니다.
먼저 확인할 점: 이 글은 Windows에서 Clash Verge Rev와 Mihomo를 정상적으로 설치하고 사용할 수 있는 환경을 전제로 합니다. 외부 컨트롤러 포트는 관리 권한을 가진 API이므로 회사·학교 네트워크 정책을 확인하고, secret을 다른 사람에게 공유하지 마세요.
설정 전 확인해야 할 포트와 secret
설정을 시작하기 전에 Clash Verge Rev가 실제로 사용하는 프로필과 코어 상태를 확인합니다. 외부 컨트롤러는 GUI 자체가 아니라 내부의 Mihomo 코어와 통신하므로, 프로필이 활성화되지 않았거나 코어가 실행되지 않은 상태에서는 올바른 포트를 입력해도 응답이 없을 수 있습니다. Windows 작업 표시줄의 트레이 아이콘에서 Clash Verge Rev가 실행 중인지 확인하고, 대시보드에서 현재 프로필과 프록시 그룹이 정상적으로 표시되는지 먼저 살펴보세요.
많은 설정에서 외부 컨트롤러 주소는 127.0.0.1:9090처럼 표시됩니다. 그러나 9090이 모든 설치 환경의 고정값은 아닙니다. 이미 다른 Clash 클라이언트나 개발 도구가 해당 포트를 사용하고 있다면 Verge Rev가 다른 포트로 실행되거나 충돌이 발생할 수 있습니다. 따라서 인터넷에 있는 예시를 그대로 복사하기보다, Clash Verge Rev의 설정 화면이나 실제 YAML 프로필에서 현재 값을 확인해야 합니다.
- API 주소: 일반적인 로컬 설정은
127.0.0.1:9090또는localhost:9090입니다. - secret: 외부 컨트롤러 API에 요청을 보낼 때 필요한 인증 문자열입니다. 비어 있을 수도 있지만, 가능하면 충분히 긴 값을 사용하세요.
- WebUI 주소: 브라우저에서 열 관리 화면의 주소입니다. API 주소와 WebUI 정적 파일 주소는 서로 다른 항목일 수 있습니다.
- 혼합 포트: 브라우저나 운영체제 프록시가 사용하는 HTTP·SOCKS 프록시 포트이며, 외부 컨트롤러 포트와 용도가 다릅니다.
특히 혼합 포트와 외부 컨트롤러 포트를 혼동하지 않는 것이 중요합니다. 혼합 포트는 일반 앱의 프록시 트래픽을 받아 처리하고, 외부 컨트롤러 포트는 상태 조회와 명령을 위한 API 요청을 받습니다. 예를 들어 혼합 포트가 7890이고 컨트롤러가 9090이라면 WebUI의 API 주소에는 7890이 아니라 9090을 입력해야 합니다.
Clash Verge Rev에서 외부 컨트롤러 활성화하기
Clash Verge Rev 버전에 따라 메뉴 이름과 배치가 조금 다를 수 있지만, 핵심 항목은 대체로 Settings, Core, External Controller, Controller 또는 프로필의 고급 설정 안에 있습니다. 번역 상태에 따라 한국어 메뉴가 완전히 일치하지 않을 수 있으므로, 설정 화면에서 controller, API, secret, WebUI 같은 단어를 기준으로 찾으면 빠릅니다.
- Windows에서 Clash Verge Rev를 실행하고, 먼저 활성 프로필과 Mihomo 코어가 정상적으로 시작되었는지 확인합니다.
- 왼쪽 메뉴에서 Settings 또는 설정을 연 다음, External Controller 또는 유사한 이름의 항목을 찾습니다.
- 컨트롤러 주소에
127.0.0.1:9090을 입력합니다. 실제 화면에 다른 포트가 표시되어 있다면 그 값을 사용합니다. - secret 또는 API Secret 입력란에 새 인증 문자열을 입력하고 저장합니다.
- WebUI 선택 항목이 있다면 내장 WebUI 또는 사용 중인 관리 화면을 지정한 뒤, Open WebUI 버튼을 눌러 브라우저에서 접속합니다.
secret을 직접 정할 수 있다면 짧은 숫자나 계정 이름보다는 영문 대소문자와 숫자를 섞은 긴 문자열이 낫습니다. 이 값은 비밀번호와 비슷한 역할을 하므로 공개 저장소, 화면 녹화, 지원 요청용 스크린샷에 그대로 포함하지 않아야 합니다. 설정을 저장한 뒤에는 코어를 한 번 재시작하는 것이 좋습니다. 일부 버전에서는 GUI에서 값을 바꿔도 이미 실행 중인 코어 프로세스에 새 설정이 즉시 반영되지 않을 수 있기 때문입니다.
안전한 기본값: 별도의 원격 관리가 필요하지 않다면 컨트롤러 주소는 127.0.0.1로 유지하세요. 0.0.0.0으로 변경하면 방화벽 설정과 공유 네트워크 환경에 따라 다른 기기에서 API가 보일 수 있습니다.
브라우저 WebUI에 연결하고 상태 확인하기
WebUI는 단순한 홈페이지가 아니라 Clash Verge Rev의 외부 컨트롤러 API에 연결하는 관리 화면입니다. 따라서 브라우저에서 화면이 표시되는 것과 API 인증이 성공하는 것은 별개의 단계입니다. WebUI가 로드되었는데 프록시 그룹이 비어 있거나 연결 목록이 계속 로딩 중이라면, 정적 페이지는 열렸지만 API 주소 또는 secret이 맞지 않는 상황일 가능성이 큽니다.
- Clash Verge Rev의 WebUI 실행 버튼을 누르거나, 제공된 WebUI 주소를 브라우저 주소창에 입력합니다.
- 연결 설정 창이 나타나면 API 주소에
http://127.0.0.1:9090처럼 프로토콜을 포함해 입력합니다. - secret 입력란에는 Clash Verge Rev에 저장한 값을 공백 없이 붙여넣고 Connect 또는 연결을 선택합니다.
- 대시보드에서 프록시 그룹, 현재 노드, 업로드·다운로드 트래픽, 메모리 정보가 표시되는지 확인합니다.
- 프록시 그룹을 조회하거나 테스트 노드를 선택해 명령이 실제 코어에 전달되는지 확인합니다.
브라우저 개발자 도구의 Network 탭을 사용할 수 있다면 실패 원인을 더 빠르게 좁힐 수 있습니다. 401 또는 403이 표시되면 secret이 다르거나 인증 헤더가 전달되지 않은 것입니다. 404라면 WebUI가 요청하는 API 경로와 Mihomo 버전의 API 구조가 맞지 않을 수 있습니다. ERR_CONNECTION_REFUSED는 해당 포트에서 컨트롤러가 실행되지 않았거나 주소와 포트를 잘못 입력했을 때 주로 나타납니다.
| 증상 | 가능한 원인 | 확인할 항목 |
|---|---|---|
| 페이지 자체가 열리지 않음 | WebUI 주소 오류 또는 파일 문제 | 내장 WebUI 주소, 브라우저 주소창, 확장 프로그램 차단 여부 |
| 페이지는 열리지만 데이터가 없음 | API 주소·포트·secret 불일치 | 127.0.0.1:9090 형식과 인증 문자열 |
| 401 또는 403 오류 | 인증 실패 | secret 앞뒤 공백, 오래된 저장값, 잘못된 코어 프로필 |
| 연결 후 명령이 반영되지 않음 | 코어 재시작 미실행 또는 API 호환성 문제 | 활성 코어, WebUI 버전, Clash 연결 로그 |
Windows에서 연결이 안 될 때 점검 순서
첫 번째로 확인할 것은 포트가 실제로 열려 있는지입니다. PowerShell을 열고 다음 명령을 실행하면 로컬 포트 응답 여부를 확인할 수 있습니다.
Test-NetConnection 127.0.0.1 -Port 9090TcpTestSucceeded : True가 나오면 해당 포트에서 무언가가 연결을 받고 있다는 뜻입니다. 그러나 이것만으로 secret 인증까지 성공했다는 의미는 아닙니다. 반대로 False라면 Clash Verge Rev가 종료되었거나, 컨트롤러 포트가 9090이 아니거나, 설정이 저장되지 않았을 가능성이 높습니다. 작업 관리자에서 여러 Clash 계열 프로그램이 동시에 실행 중인지도 확인하세요. 두 클라이언트가 비슷한 포트를 사용하면 한쪽이 먼저 포트를 차지해 다른 쪽의 컨트롤러가 시작되지 않을 수 있습니다.
두 번째는 주소의 차이입니다. localhost와 127.0.0.1은 일반적으로 같은 컴퓨터를 가리키지만, 일부 보안 프로그램이나 브라우저 확장 기능은 두 주소를 다르게 취급합니다. 우선 http://127.0.0.1:포트 형식으로 시도하고, HTTPS로 자동 변환되지 않는지 확인하세요. 로컬 API에 인증서가 없는데 브라우저가 HTTPS를 강제하면 연결이 실패할 수 있습니다.
세 번째는 WebUI와 코어의 호환성입니다. 오래된 WebUI가 최신 Mihomo API 경로를 제대로 이해하지 못하거나, 반대로 최신 WebUI가 이전 코어에서 제공하지 않는 엔드포인트를 요청하는 경우가 있습니다. 이때는 Clash Verge Rev의 내장 WebUI로 먼저 테스트하고, 외부 WebUI를 사용한다면 해당 프로젝트가 현재 Mihomo API를 지원하는지 확인합니다. 설정 파일을 여러 번 수정하기보다 한 번에 한 항목만 바꾸고, 변경 뒤 코어를 재시작하면 원인 추적이 쉬워집니다.
컨트롤러 포트를 인터넷에 공개하지 마세요: 외부 컨트롤러에 접근할 수 있는 사용자는 프록시 그룹 변경, 연결 종료, 설정 조회 같은 관리 작업을 수행할 수 있습니다. 포트 포워딩이나 공유기 노출은 피하고, 꼭 원격 관리가 필요하다면 인증·방화벽·VPN을 함께 검토해야 합니다.
결국 Windows에서 Clash Verge Rev 외부 컨트롤러를 안정적으로 쓰는 핵심은 혼합 포트와 컨트롤러 포트를 구분하고, 로컬 주소·secret·WebUI 호환성을 순서대로 확인하는 것입니다. 일부 유사 클라이언트는 메뉴가 지나치게 단순하거나 외부 컨트롤러 문서가 부족해 포트 충돌과 인증 오류를 찾는 데 시간이 오래 걸릴 수 있지만, Clash 공식 사이트는 Windows용 Clash 클라이언트와 Mihomo 설정을 한곳에서 비교하고 단계별 안내를 확인하기 쉽습니다. 이제 막 WebUI 관리를 시작하거나 현재 클라이언트의 설정 화면이 복잡하게 느껴진다면, Clash 공식 사이트 다운로드 페이지에서 자신에게 맞는 Clash 도구를 확인한 뒤 이 글의 순서대로 외부 컨트롤러를 연결해 보세요.