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

macOS에서 외부 컨트롤러가 필요한 이유

Clash Verge Rev를 Mac에서 실행하면 메뉴와 대시보드만으로도 프록시 그룹, 규칙 모드, 시스템 프록시를 어느 정도 관리할 수 있습니다. 하지만 여러 기기에서 상태를 확인하거나, 브라우저 기반 관리 화면을 사용하거나, 다른 도구와 Clash 상태를 연동하려면 외부 컨트롤러(External Controller)가 필요합니다. 외부 컨트롤러는 Clash 코어가 열어 둔 로컬 HTTP API의 주소이며, 이 API를 통해 프록시 목록, 현재 모드, 연결 로그, 프로필과 일부 런타임 상태를 읽고 변경할 수 있습니다.

macOS에서 자주 쓰는 주소는 127.0.0.1:9090 또는 127.0.0.1:9097처럼 로컬 루프백 인터페이스에 바인딩된 형태입니다. 포트 번호는 설치 버전, 코어 종류, 기존 설정 파일에 따라 달라질 수 있으므로 다른 글의 숫자를 그대로 복사하기보다 현재 Clash Verge Rev가 실제로 사용하는 값을 확인해야 합니다. 주소를 0.0.0.0으로 열면 같은 네트워크의 다른 장치에서도 접근할 수 있지만, 방화벽과 인증을 제대로 설정하지 않으면 API가 외부에 노출될 수 있습니다.

시작 전 확인: Clash Verge Rev와 Mihomo 코어

먼저 Clash Verge Rev를 최신 안정 버전으로 실행하고, 실제로 어떤 코어가 활성화되어 있는지 확인합니다. 최근 환경에서는 대개 Mihomo 계열 코어가 사용되지만, 코어 버전이나 앱 빌드에 따라 설정 항목의 이름과 지원 범위가 조금씩 다를 수 있습니다. 앱의 설정 화면에서 코어 상태가 정상인지, 프로필이 하나 이상 로드되어 있는지, 시스템 프록시 또는 TUN 모드가 의도한 상태인지부터 점검하세요.

설정을 변경하기 전에 현재 프로필을 백업하는 것도 좋습니다. 외부 컨트롤러 주소와 시크릿은 보통 일반 프록시 노드 정보와 별개의 런타임 설정이지만, 프로필을 교체하거나 코어를 재시작하는 과정에서 API 설정이 초기화되는 경우가 있습니다. 특히 원격 구독이 전체 YAML을 다시 생성하는 구조라면 로컬에서 직접 수정한 줄이 다음 업데이트 때 사라질 수 있습니다.

Clash Verge Rev에서 외부 컨트롤러 활성화하기

Clash Verge Rev를 열고 설정 또는 일반 설정 화면으로 이동합니다. 릴리스에 따라 메뉴가 Settings, General, Profiles 주변에 배치될 수 있지만, 검색해야 할 키워드는 External Controller, External Controller Address, API Port입니다. 항목이 보이지 않는다면 앱의 그래픽 설정만 보고 있는 것이 아니라, 현재 실행 중인 코어의 설정 편집 화면을 열어야 할 수 있습니다.

주소 입력란에는 처음부터 원격 주소를 넣기보다 127.0.0.1:9090 같은 로컬 주소를 사용합니다. 포트가 이미 다른 프로그램에서 사용 중이면 코어가 시작되지 않거나 설정 저장은 성공한 것처럼 보이면서 API만 응답하지 않을 수 있습니다. 이때는 포트를 임의로 여러 번 바꾸기보다 하나를 정해 저장한 뒤 코어를 완전히 재시작하고, 로그에서 “listening” 또는 “external controller”에 해당하는 메시지를 확인하는 편이 정확합니다.

설정 파일을 직접 편집해야 한다면 다음과 같이 주소와 시크릿 필드를 확인할 수 있습니다. 실제 파일의 키 이름은 코어 버전에 따라 달라질 수 있으므로 예시를 그대로 덮어쓰기보다 기존 구조와 들여쓰기를 먼저 비교하세요.

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

저장 후에는 Clash Verge Rev를 단순히 창만 닫지 말고 코어가 다시 로드되었는지 확인합니다. 메뉴 막대에서 앱을 종료했다가 다시 실행하거나, 코어 재시작 버튼을 사용하세요. 프로필 화면에 오류가 표시되면 YAML 문법, 포트 충돌, 권한 문제를 차례로 살펴봐야 합니다.

API 시크릿을 안전하게 등록하는 방법

외부 컨트롤러를 열 때 가장 중요한 값은 API 시크릿입니다. 시크릿이 비어 있으면 로컬 컴퓨터 안의 다른 프로세스가 API에 접근할 수 있고, 주소를 외부 인터페이스에 바인딩한 경우에는 같은 네트워크의 다른 장치가 프록시 그룹이나 연결 상태를 조작할 위험이 있습니다. 시크릿은 짧은 단어, Mac 사용자 이름, Wi-Fi 비밀번호처럼 추측하기 쉬운 문자열을 피하고 길고 무작위적인 값을 사용하세요.

시크릿을 입력할 때는 앞뒤 공백과 따옴표가 실제 값에 포함되지 않았는지 확인합니다. 일부 관리 화면은 시크릿을 한 번만 보여 주므로 비밀번호 관리자에 저장해 두는 것이 좋습니다. 팀이나 가정에서 여러 대의 Mac을 관리한다면 기기별로 서로 다른 시크릿을 발급하고, 더 이상 사용하지 않는 대시보드나 스크립트의 토큰은 즉시 폐기하세요.

127.0.0.1 바인딩과 0.0.0.0 바인딩 비교

127.0.0.1은 현재 Mac 내부에서만 접근할 수 있는 주소입니다. 브라우저 대시보드, 로컬 스크립트, 같은 Mac에서 실행되는 모니터링 도구만 사용할 때 가장 권장되는 선택입니다. 반대로 0.0.0.0은 Mac의 여러 네트워크 인터페이스에서 요청을 받을 수 있다는 뜻이므로, 편리함보다 노출 범위를 먼저 계산해야 합니다.

iPhone이나 다른 Mac에서 대시보드를 열어야 한다면 먼저 Mac의 사설 IP와 방화벽 상태를 확인하고, 공유기 포트 포워딩은 사용하지 않는 편이 좋습니다. 꼭 원격 접근이 필요하다면 신뢰할 수 있는 로컬 VPN이나 SSH 터널처럼 인증된 경로를 사용하세요. API 포트를 인터넷에 직접 공개하는 것은 외부 컨트롤러 설정의 일반적인 사용 방법이 아닙니다.

Web 대시보드에 연결하고 기능 확인하기

API가 실행되면 지원되는 Web 대시보드에서 컨트롤러 주소를 입력합니다. 대시보드가 같은 Mac에서 실행된다면 컨트롤러 주소는 http://127.0.0.1:9090처럼 입력하고, 시크릿 필드에는 Clash Verge Rev에 등록한 동일한 값을 넣습니다. 포트 번호가 다르면 URL의 마지막 숫자만 현재 설정에 맞게 바꾸면 됩니다.

연결이 성공하면 대시보드에서 현재 모드, 프록시 그룹, 선택된 노드, 연결 목록을 확인할 수 있습니다. 테스트는 먼저 읽기 기능부터 진행하세요. 프록시 그룹을 실제로 변경하기 전에 현재 설정이 표시되는지, 연결 로그가 갱신되는지, 코어 상태가 온라인으로 보이는지를 확인하면 잘못된 시크릿과 잘못된 포트를 빠르게 구분할 수 있습니다.

연결되지 않을 때의 진단 순서

첫 번째는 주소입니다. 같은 Mac에서 접근하는데도 사설 IP나 호스트 이름을 사용하고 있다면 우선 127.0.0.1로 바꿔 로컬 연결을 분리해서 테스트하세요. 두 번째는 포트입니다. Clash Verge Rev가 표시하는 포트와 브라우저에 입력한 포트가 같은지 확인하고, 이전에 사용하던 Clash 포트가 남아 있지 않은지 살펴봅니다. 세 번째는 시크릿입니다. 시크릿을 다시 생성했다면 기존 대시보드가 저장한 이전 값으로 계속 요청할 수 있습니다.

macOS의 시스템 프록시가 켜져 있다고 해서 외부 컨트롤러 API도 반드시 프록시를 통해야 하는 것은 아닙니다. 오히려 로컬 API 요청이 프록시 규칙에 들어가 루프백 연결이 이상하게 처리되는 경우가 있으므로, 테스트 시에는 브라우저 개발자 도구의 네트워크 오류와 Clash 연결 로그를 함께 비교하세요. API 요청 자체가 로그에 보이지 않는다면 주소나 브라우저 확장 문제일 가능성이 높고, 요청은 보이지만 401이 나온다면 시크릿 문제에 가깝습니다.

설정을 바꾼 뒤에는 코어 재시작, 대시보드 새로 고침, 시스템 프록시 상태 확인을 순서대로 진행합니다. 한 번에 여러 값을 수정하면 원인을 찾기 어렵습니다. 정상화된 뒤에는 현재 주소, 포트, 시크릿 보관 위치, 사용 중인 코어 버전을 개인 운영 문서에 기록하되 실제 시크릿은 문서에 평문으로 남기지 않는 것이 안전합니다.

자주 묻는 질문

외부 컨트롤러 포트는 꼭 9090이어야 하나요?

아닙니다. 9090은 널리 쓰이는 예시일 뿐이며 Clash Verge Rev와 활성 코어가 실제로 열어 둔 포트를 사용해야 합니다. 다른 서비스와 충돌한다면 사용 가능한 포트로 바꿀 수 있지만, 저장 후 코어를 재시작하고 대시보드 주소도 함께 수정해야 합니다.

API 시크릿 없이 로컬에서만 사용해도 되나요?

기술적으로는 가능한 구성도 있지만 권장하지 않습니다. 로컬 컴퓨터에서 실행되는 브라우저 확장, 개발 도구, 다른 사용자 계정의 프로세스가 API에 접근할 가능성이 있기 때문입니다. 로컬 바인딩을 유지하더라도 길고 무작위적인 시크릿을 설정하는 편이 안전합니다.

다른 Mac에서 Web 대시보드에 접속할 수 있나요?

가능합니다. 다만 컨트롤러를 로컬호스트가 아닌 사설 네트워크 주소에 바인딩하고 macOS 방화벽 규칙을 검토해야 합니다. 인터넷에 포트를 직접 공개하지 말고, 신뢰할 수 있는 VPN이나 SSH 터널을 사용하며, 기기별 시크릿과 최소한의 접근 범위를 유지하세요.

설정 후 Clash Verge Rev가 시작되지 않으면 어떻게 하나요?

외부 컨트롤러 주소의 오타, YAML 들여쓰기, 사용 중인 포트, 지원되지 않는 코어 필드를 먼저 확인합니다. 백업한 프로필로 되돌린 뒤 코어를 다시 실행하고, 설정을 한 항목씩 추가하면 어느 줄에서 문제가 생겼는지 확인하기 쉽습니다.

단순히 Web 화면만 열고 싶은 경우에도 오래된 GUI 클라이언트는 외부 컨트롤러 메뉴가 숨겨져 있거나 API 시크릿 관리가 불편하고, 일부 경량 도구는 Mihomo 코어의 최신 상태와 호환되지 않을 수 있습니다. 반면 Clash V.CORE는 macOS 환경에서 코어 상태, 로컬 API, 프로필 관리와 접근 보안을 한 흐름으로 점검하기 쉬워 외부 컨트롤러를 처음 설정하는 사용자에게 더 일관된 운영 경험을 제공합니다. 이 글의 절차대로 로컬 바인딩과 시크릿을 먼저 구성한 뒤, 필요한 기능과 호환성을 확인하고 Clash V.CORE 다운로드로 안전하게 시작해 보세요.