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

외부 컨트롤러는 무엇을 제어하나요?

Clash Verge Rev에서 외부 컨트롤러는 프록시 트래픽을 전달하는 포트와 별도로, 실행 중인 Clash 또는 Mihomo 코어의 상태를 조회하고 제어하는 HTTP API입니다. 웹 패널은 이 API에 연결해 현재 선택된 프록시 그룹, 연결 목록, 규칙 매칭 결과, 메모리 사용량과 로그를 표시합니다. 따라서 외부 컨트롤러 포트는 브라우저나 다른 프로그램이 인터넷에 접속할 때 사용하는 mixed-port 또는 socks-port와 목적이 다릅니다.

Windows용 Clash Verge Rev에서 웹 패널이 열리지 않는 경우에는 먼저 코어가 실제로 실행 중인지 확인해야 합니다. 외부 컨트롤러 설정만 추가하고 프로필을 다시 로드하지 않으면 현재 실행 중인 코어에 변경 사항이 반영되지 않을 수 있습니다. 또한 설정 파일에 컨트롤러 주소를 적어 두었더라도 그래픽 클라이언트의 오버라이드 설정이나 실행 중인 프로필이 해당 값을 덮어쓸 수 있습니다.

이 기능은 특히 여러 설정을 전환하거나 연결 상태를 자세히 확인할 때 유용합니다. 그러나 외부 컨트롤러는 프록시 서버 자체가 아니므로 이 주소를 Windows 시스템 프록시, 브라우저 프록시 또는 터미널의 HTTP_PROXY 값으로 입력해서는 안 됩니다. 시스템 프록시는 mixed-port 같은 프록시 포트를 사용하고, 웹 패널은 외부 컨트롤러 포트를 사용합니다.

Windows에서 설정을 시작하기 전에 확인할 항목

먼저 Clash Verge Rev를 실행하고 사용할 프로필이 정상적으로 활성화되어 있는지 확인하세요. 프로필 목록에 표시된 이름만으로는 실제 적용 설정을 판단하기 어렵습니다. 선택한 프로필을 실행한 뒤 코어 상태가 실행 중으로 표시되는지, 노드와 프록시 그룹이 정상적으로 로드되는지, 오류 로그에 YAML 파싱 실패가 없는지 차례대로 살펴보는 것이 좋습니다.

외부 컨트롤러를 설정하기 전에 기존 값을 기록해 두면 문제 발생 시 되돌리기 쉽습니다. Windows에서 일반적으로 로컬 전용으로 사용하는 주소는 127.0.0.1 또는 localhost입니다. 포트는 이미 다른 프로그램이 사용하지 않는 번호를 선택해야 하며, 예제에서는 9090을 사용합니다. 컴퓨터 한 대에서 여러 Clash 계열 클라이언트를 동시에 실행한다면 각 인스턴스의 컨트롤러 포트가 서로 달라야 합니다.

설정을 수정하기 전에는 구독 원본과 로컬 오버라이드를 구분하세요. 구독으로 내려받은 YAML을 직접 수정하면 다음 업데이트 때 변경 내용이 사라질 수 있습니다. Clash Verge Rev에서 설정 병합, 오버라이드 또는 프로필 편집 기능을 제공한다면 장기간 유지할 항목은 해당 기능에 작성하는 편이 안전합니다. 메뉴 이름은 설치한 버전과 언어 설정에 따라 다를 수 있으므로 ‘설정’, ‘프로필’, ‘오버라이드’, ‘컨트롤러’와 비슷한 항목을 확인하세요.

  • 코어 상태: 프로필이 활성화되고 Mihomo 또는 호환 코어가 실행 중인지 확인합니다.
  • 프록시 포트: 시스템 프록시에 사용하는 mixed-port와 컨트롤러 포트를 혼동하지 않습니다.
  • 기존 포트: 9090 포트를 다른 서비스가 사용 중인지 점검합니다.
  • 인증 키: 외부 패널에 입력할 secret 값을 별도로 보관합니다.
  • 백업: 프로필과 오버라이드 변경 전 현재 설정을 복사해 둡니다.

external-controller와 secret 설정하기

Clash 계열 설정에서는 external-controller가 외부 컨트롤러의 수신 주소를 지정하고, secret이 API 인증 키 역할을 합니다. Windows 컴퓨터에서만 웹 패널을 사용할 계획이라면 다음처럼 루프백 주소를 사용하는 구성이 가장 안전합니다.

external-controller: 127.0.0.1:9090
secret: "Windows-Clash-Controller-2026"

127.0.0.1:9090은 같은 컴퓨터에서 9090 포트로 API를 열겠다는 뜻입니다. 다른 PC나 휴대폰에서 이 컨트롤러에 접속할 필요가 없다면 0.0.0.0:9090으로 바꾸지 않는 것이 좋습니다. 모든 네트워크 인터페이스에서 수신하도록 설정하면 LAN의 다른 기기가 API에 접근할 가능성이 생기며, Windows 방화벽 규칙과 공유기 환경까지 함께 관리해야 합니다.

secret에는 짧은 숫자만 사용하기보다 충분히 긴 임의 문자열을 입력하세요. YAML에서 특수 문자가 포함된 인증 키는 따옴표로 감싸는 것이 안전합니다. 이 키는 구독 URL 비밀번호와 같은 개념이 아니며, 프록시 노드 인증 정보와도 다릅니다. 웹 패널에 입력할 때 공백이나 앞뒤 줄바꿈이 포함되지 않았는지 확인해야 합니다.

설정을 저장한 뒤에는 프로필을 다시 적용하거나 코어를 재시작해야 합니다. 단순히 파일을 저장하는 것만으로 기존 프로세스의 수신 주소가 바뀌지 않는 경우가 있기 때문입니다. 재시작 후 로그에 컨트롤러 시작 오류, 포트 점유 오류 또는 설정 파싱 오류가 나타나는지 확인하세요.

주요 필드의 역할

설정 필드 역할 권장 Windows 예시
external-controller 웹 패널과 API가 연결할 주소와 포트 127.0.0.1:9090
secret 컨트롤러 API 인증 키 긴 임의 문자열
mixed-port HTTP·SOCKS 프록시 요청을 받는 포트 7890
allow-lan 다른 기기의 프록시 접근 허용 여부 로컬 사용 시 false

웹 패널에 주소와 인증 키 입력하기

컨트롤러가 실행되면 웹 패널에서 연결 정보를 입력합니다. 사용 중인 패널의 화면 구성은 다를 수 있지만, 보통 컨트롤러 주소 또는 API 주소 입력란, Secret 입력란, 연결 버튼으로 구성됩니다. 주소에는 http://127.0.0.1:9090처럼 프로토콜을 포함한 값을 입력하거나 패널이 안내하는 형식에 맞춰 127.0.0.1:9090을 입력합니다. 입력 형식은 패널마다 다르므로 주소 칸의 예시 문구를 우선하세요.

인증 키 입력란에는 YAML의 secret 값과 완전히 동일한 문자열을 넣습니다. 대소문자, 하이픈, 밑줄, 숫자와 공백이 모두 인증 결과에 영향을 줍니다. 연결에 실패한다고 해서 먼저 키를 삭제하거나 컨트롤러를 LAN에 공개하지 마세요. 주소의 포트 번호와 코어에 실제 적용된 Secret을 다시 비교하는 것이 우선입니다.

연결에 성공하면 웹 패널에서 현재 모드, 프록시 그룹, 연결 수, 업로드·다운로드 트래픽 또는 로그가 표시됩니다. 프록시 그룹을 클릭했을 때 선택 노드가 바뀌고 Clash Verge Rev의 연결 기록에도 변화가 나타난다면 단순히 웹페이지가 열린 것이 아니라 API 제어까지 정상적으로 이루어진 것입니다.

패널이 빈 화면으로 열리거나 데이터가 표시되지 않는 경우에는 브라우저 개발자 도구보다 먼저 다음 세 가지를 확인하세요. 첫째, 주소가 프록시 포트가 아닌 컨트롤러 포트를 가리키는지 확인합니다. 둘째, 웹 패널이 요구하는 인증 방식이 Secret 입력인지 확인합니다. 셋째, Clash Verge Rev에서 현재 활성화한 프로필이 설정한 컨트롤러 값을 실제로 사용하고 있는지 로그와 실행 상태를 대조합니다.

컨트롤러 주소: http://127.0.0.1:9090
Secret: Windows-Clash-Controller-2026

프록시 주소와 혼동하지 않기:
HTTP/SOCKS 프록시: 127.0.0.1:7890
외부 컨트롤러 API: 127.0.0.1:9090

Windows에서 연결 상태를 직접 테스트하는 방법

웹 패널에서 연결되지 않을 때는 PowerShell로 해당 포트가 열려 있는지 먼저 확인할 수 있습니다. 다음 명령은 Windows의 로컬 TCP 포트에 연결할 수 있는지만 판단합니다. 인증 키의 유효성이나 프록시 노드의 연결 상태까지 검증하는 명령은 아니므로 결과를 구분해서 해석해야 합니다.

Test-NetConnection 127.0.0.1 -Port 9090

결과에서 TcpTestSucceeded : True가 표시되면 9090 포트에 프로세스가 응답하고 있을 가능성이 높습니다. False라면 Clash 코어가 실행 중인지, 포트 번호가 맞는지, 다른 프로그램이 설정을 덮어쓰지 않았는지 확인하세요. 포트 점유 상태는 다음 명령으로 확인할 수 있습니다.

netstat -ano | findstr :9090

Get-NetTCPConnection -LocalPort 9090 -State Listen

netstat 결과에 LISTENING이 없으면 컨트롤러가 해당 포트에서 수신 중이지 않은 것입니다. PID가 표시되면 작업 관리자에서 해당 프로세스를 확인할 수 있습니다. Clash Verge Rev를 종료했는데도 9090 포트가 남아 있다면 다른 Clash 인스턴스나 별도 프로그램이 포트를 점유하고 있을 수 있습니다.

포트 연결은 성공하지만 웹 패널이 인증 오류를 표시한다면 Secret을 점검하세요. 반대로 인증 오류가 아니라 연결 거부가 표시되면 주소, 포트, 코어 실행 상태를 먼저 확인해야 합니다. 웹 패널에서 프록시 그룹이 보이지만 실제 사이트 접속이 실패한다면 컨트롤러 문제가 아니라 노드, DNS, 규칙 또는 시스템 프록시 설정 문제일 가능성이 큽니다.

  1. 포트 확인: Test-NetConnection으로 9090의 TCP 연결 여부를 확인합니다.
  2. 프로세스 확인: netstat -ano로 포트를 점유한 PID를 찾습니다.
  3. 인증 확인: YAML의 secret과 패널 입력값을 문자 단위로 비교합니다.
  4. API 동작 확인: 패널에서 프록시 그룹과 연결 기록이 실제로 표시되는지 확인합니다.
  5. 프록시 테스트: 웹 패널 연결과 별도로 mixed-port를 사용한 브라우저 접속을 테스트합니다.

Windows 방화벽과 연결 오류 해결

로컬 주소인 127.0.0.1에 연결하는 경우 Windows 방화벽이 직접적인 원인이 아닐 때가 많습니다. 방화벽 예외를 무작정 추가하기 전에 코어가 올바른 주소에서 수신 중인지, 9090 포트가 다른 프로그램에 할당되지 않았는지, Clash Verge Rev가 관리자 권한이나 보안 프로그램에 의해 차단되지 않았는지 확인하세요.

LAN의 다른 기기에서 컨트롤러에 접속하려고 주소를 컴퓨터의 사설 IP로 변경했다면 방화벽 규칙이 영향을 줄 수 있습니다. 이 경우에는 Windows Defender 방화벽에서 Clash Verge Rev 또는 해당 실행 파일의 네트워크 허용 상태를 확인하고, 필요한 경우 신뢰할 수 있는 사설 네트워크 프로필에서만 제한적으로 허용해야 합니다. 공용 네트워크 프로필에서 컨트롤러 포트를 넓게 허용하는 방식은 피하세요.

‘연결 거부’는 대개 수신 프로세스가 없거나 포트가 잘못된 경우에 나타납니다. ‘시간 초과’는 방화벽, 잘못된 LAN 주소, 네트워크 격리 또는 다른 기기에서의 접근 제한을 의심할 수 있습니다. ‘401’ 또는 인증 실패는 포트 연결 자체는 성공했지만 Secret이 일치하지 않는다는 뜻입니다. 오류 메시지를 유형별로 나누면 불필요하게 노드나 구독을 바꾸는 일을 줄일 수 있습니다.

CONNECTION REFUSED

연결 거부

해당 주소와 포트에서 수신 중인 컨트롤러가 없거나 포트 번호가 잘못된 상태일 가능성이 큽니다.

TIMEOUT

시간 초과

방화벽, LAN 접근 제한, 잘못된 IP 주소 또는 네트워크 프로필을 점검해야 합니다.

UNAUTHORIZED

인증 실패

컨트롤러 포트에는 연결되었지만 Secret이 없거나 설정에 저장된 값과 다를 때 발생합니다.

외부 컨트롤러를 안전하게 운영하는 방법

외부 컨트롤러는 프록시 그룹 전환과 연결 정보 조회뿐 아니라 실행 중인 코어의 상태를 변경할 수 있으므로 일반 웹페이지처럼 취급하면 안 됩니다. 로컬 전용 사용자는 127.0.0.1 바인딩을 유지하고, Secret을 다른 사람에게 공유하지 않는 것이 기본 원칙입니다. 화면 캡처나 설정 파일을 공개할 때는 Secret, 구독 URL, 서버 인증 정보와 개인 식별이 가능한 주소를 삭제하세요.

컴퓨터를 여러 사용자가 함께 사용하거나 원격 관리가 필요하다면 컨트롤러 포트를 인터넷에 직접 열지 말고 접근 범위를 최소화하세요. LAN 접근이 꼭 필요할 때도 특정 사설 네트워크에서만 허용하고, 사용이 끝나면 다시 루프백 주소로 되돌리는 편이 안전합니다. allow-lan은 프록시 접근 설정과 관련된 필드이므로 이를 켠다고 컨트롤러 API가 자동으로 안전해지는 것은 아닙니다.

설정 변경 후에는 웹 패널에서 프록시 그룹 전환, 연결 목록 조회, 로그 확인을 각각 테스트하세요. 세 기능이 모두 작동하면 주소와 인증 키뿐 아니라 API가 현재 실행 중인 코어에 정상적으로 연결된 것으로 볼 수 있습니다. 이후 Clash Verge Rev를 업데이트하거나 프로필을 교체할 때는 external-controller와 secret이 유지되는지 다시 확인해야 합니다.

정리하면 Windows용 Clash Verge Rev의 외부 컨트롤러 설정은 네 단계로 진행됩니다. 활성 프로필과 코어 상태를 확인하고, 로컬 컨트롤러 주소와 포트를 지정한 다음, Secret을 설정하고, 웹 패널에서 동일한 주소와 인증 키로 연결합니다. 연결되지 않을 때는 방화벽보다 먼저 포트, 활성 설정, 프로세스와 인증 값을 순서대로 확인하면 원인을 빠르게 좁힐 수 있습니다.

Clash 다운로드