Windows에서 Clash Verge Rev 외부 컨트롤러 설정하는 방법

Windows에서 Clash Verge Rev를 사용하다 보면 프록시 노드 전환, 연결 상태 확인, 규칙 관리와 같은 작업을 브라우저 대시보드에서 처리하고 싶을 때가 있습니다. 이때 필요한 것이 외부 컨트롤러입니다. 외부 컨트롤러는 Clash 코어가 제공하는 HTTP API 주소이며, Metacubexd나 Yacd 같은 웹 대시보드가 이 API에 연결해 실행 상태를 읽고 설정을 제어합니다. 이 글에서는 Windows 초보자도 따라 할 수 있도록 Clash Verge Rev에서 외부 컨트롤러를 활성화하고, 포트와 인증 시크릿을 입력한 뒤 대시보드 연결을 확인하는 전체 과정을 설명합니다.

외부 컨트롤러의 역할과 준비 사항

외부 컨트롤러는 별도의 프록시 서버나 새로운 VPN 프로토콜이 아닙니다. Clash 코어가 로컬 컴퓨터의 특정 포트에서 실행하는 관리용 API 서버입니다. 일반적인 웹 트래픽은 HTTP 또는 SOCKS 포트를 사용하지만, 대시보드는 외부 컨트롤러 포트로 접속해 현재 선택된 노드, 프록시 그룹, 활성 연결, 규칙 매칭 결과와 같은 정보를 요청합니다.

Clash Verge Rev에서는 코어 종류와 버전에 따라 메뉴 이름이나 설정 위치가 조금 다를 수 있습니다. 특히 Mihomo 기반 프로필은 external-controller와 secret 필드를 직접 편집하는 방식을 가장 확실하게 지원합니다. 설정을 시작하기 전에 다음 항목을 확인하세요.

• Windows에 Clash Verge Rev가 정상적으로 설치되어 있고 최소 한 개의 프로필이 준비되어 있어야 합니다.
• 현재 실행 중인 코어가 Mihomo 또는 Clash Meta인지 확인합니다. 코어에 따라 지원되는 API 기능이 다를 수 있습니다.
• 사용할 관리 포트를 정합니다. 일반적으로 9090 또는 9097을 사용할 수 있지만, 다른 프로그램이 이미 사용 중이면 충돌이 발생합니다.
• 대시보드가 API에 접근할 때 사용할 긴 인증 문자열을 준비합니다.
• Windows 방화벽이나 보안 프로그램이 Clash Verge Rev의 로컬 통신을 차단하지 않는지 확인합니다.

Clash Verge Rev에서 외부 컨트롤러 설정하기

먼저 Clash Verge Rev를 실행하고 사용할 프로필을 선택합니다. 프로필 편집 화면에서 YAML 내용을 직접 수정할 수 있다면 해당 설정 파일에 외부 컨트롤러 항목을 추가합니다. 이미 같은 이름의 항목이 있다면 두 개를 만들지 말고 기존 값을 수정해야 합니다. YAML은 들여쓰기에 민감하므로 키 앞에 불필요한 공백을 넣거나 탭 문자를 사용하지 않는 것이 좋습니다.

external-controller: 127.0.0.1:9090
secret: change-this-to-a-long-random-secret

external-controller의 앞부분은 API가 수신할 주소이고, 콜론 뒤 숫자는 포트입니다. 127.0.0.1은 로컬 루프백 주소이므로 외부 네트워크에 포트를 공개하지 않습니다. 반대로 0.0.0.0:9090으로 설정하면 Windows의 모든 네트워크 인터페이스에서 접속을 받을 수 있습니다. 스마트폰이나 다른 PC에서 관리해야 하는 특별한 이유가 없다면 0.0.0.0은 사용하지 않는 편이 안전합니다.

secret은 대시보드가 API 요청을 보낼 때 사용하는 Bearer 인증 토큰입니다. 짧은 숫자나 123456처럼 추측하기 쉬운 문자열은 피하고, 영문 대소문자와 숫자를 섞은 충분히 긴 값을 사용하세요. 이 값은 대시보드의 시크릿 입력란에 정확히 동일하게 입력해야 합니다.

Clash Verge Rev에 별도의 외부 컨트롤러 입력 화면이 표시되는 경우에는 설정 메뉴에서 다음 값을 입력할 수 있습니다. 메뉴 이름은 버전에 따라 External Controller, 컨트롤러 주소, API 설정 등으로 표시될 수 있습니다.

설정 저장 후 코어와 API 상태 확인

설정을 저장한 뒤에는 프로필을 다시 읽거나 Clash 코어를 재시작해야 변경 사항이 적용됩니다. 단순히 설정 파일을 저장하는 것만으로는 이미 실행 중인 코어의 API 포트가 바뀌지 않을 수 있습니다. Clash Verge Rev의 프로필 화면에서 새로고침, 적용 또는 재시작 기능을 실행한 다음 시스템 트레이 아이콘의 상태가 정상인지 확인하세요.

Windows에서 포트가 실제로 열려 있는지 확인하려면 PowerShell을 사용할 수 있습니다. 시작 메뉴에서 PowerShell을 실행하고 다음 명령을 입력합니다.

Test-NetConnection 127.0.0.1 -Port 9090

결과에서 TcpTestSucceeded : True가 표시되면 해당 포트에서 연결을 받을 준비가 된 것입니다. False라면 코어가 실행되지 않았거나 포트 번호가 다르거나 다른 프로그램과 충돌했을 가능성이 있습니다. Clash Verge Rev에 표시된 실제 포트와 명령어의 포트가 같은지 먼저 비교하세요.

API가 응답하는지도 확인할 수 있습니다. 시크릿을 설정했다면 인증 헤더를 포함해 요청해야 합니다.

$headers = @{ Authorization = "Bearer change-this-to-a-long-random-secret" }
Invoke-RestMethod -Uri "http://127.0.0.1:9090/version" -Headers $headers

정상적으로 연결되면 Clash 코어의 버전 정보가 JSON 형태로 반환됩니다. 401 Unauthorized가 나타나면 시크릿이 틀렸거나 Bearer 표기가 빠진 것입니다. 연결 거부 오류가 나타나면 주소, 포트, 코어 실행 상태를 다시 확인해야 합니다.

웹 대시보드에 연결하는 방법

외부 컨트롤러가 작동하는 것을 확인했다면 이제 웹 대시보드를 연결할 수 있습니다. Metacubexd와 Yacd는 모두 비슷한 방식으로 API 주소와 시크릿을 입력합니다. 대시보드 페이지를 열고 백엔드 또는 컨트롤러 주소 입력란에 http://127.0.0.1:9090을 입력합니다. 주소 끝에 불필요한 공백이나 중복된 슬래시를 넣지 마세요.

1. 브라우저에서 사용할 대시보드를 엽니다.
2. 백엔드 주소 또는 API 주소 필드에 http://127.0.0.1:9090을 입력합니다.
3. Secret 또는 API 비밀번호 필드에 Clash 설정의 secret 값을 붙여 넣습니다.
4. 연결, 저장 또는 확인 버튼을 클릭합니다.
5. 프록시 그룹과 현재 노드 목록이 표시되는지 확인합니다.

연결이 성공하면 대시보드에서 프록시 그룹, 규칙, 프로바이더, 현재 연결 수와 트래픽 통계를 볼 수 있습니다. 특정 노드를 클릭해 선택이 바뀌는지 확인하면 읽기뿐 아니라 제어 API도 정상적으로 작동하는지 검증할 수 있습니다. 단, 노드 전환 직후에는 새 연결부터 변경된 노드가 적용되며 이미 연결된 세션은 잠시 기존 경로를 유지할 수 있습니다.

연결되지 않을 때 점검할 항목

대시보드가 연결되지 않는 문제는 대부분 주소, 포트, 시크릿 중 하나가 일치하지 않아서 발생합니다. 아래 표의 증상과 원인을 순서대로 비교하면 문제를 빠르게 좁힐 수 있습니다.

특히 Clash Verge Rev에서 여러 프로필을 관리하는 경우에는 수정한 파일과 현재 실행 중인 파일이 서로 다를 수 있습니다. 설정을 바꿨는데도 API가 이전 포트에서 계속 응답한다면 활성 프로필 이름을 확인하세요. 또한 자동 생성되는 프로필을 직접 편집하면 다음 업데이트 때 변경 내용이 덮어써질 수 있으므로, 가능한 경우 오버라이드 설정이나 유지 관리가 가능한 로컬 프로필을 사용하세요.

시크릿을 변경한 뒤 대시보드가 갑자기 작동하지 않는 것도 흔한 상황입니다. Clash 코어와 대시보드에 같은 새 값을 입력해야 하며, 브라우저가 이전 인증 정보를 기억하고 있다면 대시보드에서 연결 프로필을 삭제한 후 다시 등록하는 것이 좋습니다. 포트가 이미 사용 중이라면 PowerShell에서 다음 명령으로 해당 포트를 점유한 프로세스를 확인할 수 있습니다.

Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue |
    Select-Object LocalAddress, LocalPort, State, OwningProcess

Get-Process -Id <PID>

안전하고 안정적으로 사용하는 방법

외부 컨트롤러는 관리 편의성을 크게 높여 주지만, 일반 프록시 포트와 달리 설정 변경 권한까지 제공할 수 있습니다. 따라서 필요하지 않은 경우에는 로컬 주소에만 바인딩하고, 시크릿을 반드시 설정하는 것이 기본 원칙입니다. 원격 관리가 꼭 필요할 때만 LAN 주소에 바인딩하고 Windows 방화벽에서 신뢰하는 사설 네트워크 대역만 허용하세요.

• 관리 포트를 인터넷에 직접 공개하지 않습니다.
• 시크릿을 화면 캡처, 공개 설정 저장소, 공유 문서에 노출하지 않습니다.
• 대시보드 URL을 열 때 브라우저 주소가 공식 또는 신뢰할 수 있는 배포처인지 확인합니다.
• 연결 목록에서 예상하지 못한 외부 접속이 있는지 가끔 확인합니다.
• Clash Verge Rev와 Mihomo 코어를 신뢰할 수 있는 경로에서 업데이트합니다.
• 문제가 해결된 뒤 임시로 연 방화벽 규칙이나 원격 접속 설정을 다시 닫습니다.

정리하면 Windows에서 외부 컨트롤러를 설정하는 핵심은 127.0.0.1:포트 주소와 secret 값을 정확히 맞추는 것입니다. 설정을 저장하고 코어를 재시작한 뒤 PowerShell의 포트 검사와 /version API 요청으로 상태를 확인하면 대시보드 문제와 Clash 자체 문제를 구분할 수 있습니다. 이 과정을 익혀 두면 프록시 노드 전환이나 연결 추적을 위해 매번 YAML 파일을 직접 수정하지 않아도 됩니다.