Clash 외부 제어 패널(Dashboard) 설정 및 사용법

이 글은 Clash 공식 사이트에서 제공합니다. GUI 클라이언트는 대부분의 일상적인 요구를 충족하지만, 실시간 연결을 확인하거나, 어떤 규칙이 어떤 노드에 매칭되었는지 진단하거나, 서버에서 GUI 없이 Mihomo 코어를 실행해야 할 때 외부 제어(External Controller)는 빠질 수 없는 기능입니다. RESTful API를 통해 타사 Web 패널(예: YACD, metacubexd)이 브라우저에서 트래픽, 로그, 정책 그룹 상태를 시각화하여 고급 사용자의 「운영 대시보드」가 됩니다. 이 글에서는 외부 제어를 안전하게 활성화하고 Dashboard로 Clash를 효율적으로 관리하는 방법을 소개합니다.

외부 제어 API란

Mihomo / Clash Meta는 로컬 또는 LAN에서 HTTP API 포트(기본값 9090)를 수신 대기하며, 설정 읽기, 출구 전환, 속도 테스트, 연결 목록 조회, 연결 종료 등의 쿼리 및 작업 인터페이스를 제공합니다. GUI 클라이언트의 많은 작업도 내부적으로는 동일한 API를 통해 이루어집니다.

Web Dashboard 자체는 코어에 내장되어 있지 않고 이 API에 연결되는 프론트엔드로서 데이터를 시각화합니다. 따라서 API 주소와 시크릿 키가 올바르게 설정되어 있다면, 어떤 기기의 브라우저에서도 PC, 소프트 라우터, 또는 VPS에서 실행 중인 코어 인스턴스를 관리할 수 있습니다.

외부 제어는 「리모컨」이고 Dashboard는 「리모컨의 화면」입니다. 먼저 API를 열고, 그 다음 패널을 연결하세요.

기본 설정 예시

YAML 설정 최상위에 external-controller와 선택적인 secret을 추가하세요:

external-controller: 127.0.0.1:9090
secret: "your-random-secret"
external-ui: ./dashboard

127.0.0.1은 로컬 기기에서만 접근 가능하여 가장 안전한 기본 선택입니다. LAN 내 다른 기기에서 관리해야 한다면 0.0.0.0:9090으로 변경할 수 있지만, 충분히 복잡한 secret을 반드시 설정하고 방화벽에서 소스 IP를 제한해야 합니다.

일부 배포판은 external-ui로 내장 정적 패널 디렉토리를 지정하는 것을 지원합니다. 독립 호스팅된 YACD / metacubexd를 사용해도 되며, 패널 설정에서 API 주소와 시크릿 키를 입력하면 연결됩니다.

주요 Web 패널

YACD: 클래식 경량 패널로 연결 목록, 규칙 테스트, 정책 그룹 전환을 지원하며 데스크톱 브라우저에 적합합니다.
metacubexd: Meta 코어에 최적화된 모던 인터페이스로 모바일 기기를 지원하며, 로그, 연결, 설정 미리보기까지 기능이 풍부합니다.
Clash Verge Rev 내장 페이지: 일부 클라이언트는 Dashboard 입구를 통합하고 있으며, 실질적으로는 로컬 API에 연결됩니다.

연결 시 패널에서 http://127.0.0.1:9090(또는 서버 IP)을 입력하고 Secret 란에 설정 파일과 동일한 시크릿 키를 입력하세요. 연결에 성공하면 실시간 업로드/다운로드 속도와 활성 연결 수를 확인할 수 있습니다.

Dashboard로 할 수 있는 것

연결 및 로그 진단

「연결」 페이지에는 현재 모든 TCP/UDP 세션이 나열되고, 대상 도메인, 매칭된 규칙, 사용된 정책 그룹과 노드가 표시됩니다. 특정 웹사이트가 열리지 않을 때 여기서 규칙이 직접 연결로 처리했는지, 노드가 타임아웃인지 한눈에 확인할 수 있는 경우가 많습니다. 「로그」 페이지의 debug 레벨 출력과 함께 사용하면 DNS 해석 및 규칙 매칭 세부 사항을 추적할 수 있습니다.

정책 그룹과 속도 테스트

메인 클라이언트로 돌아갈 필요 없이 패널에서 직접 「노드 선택」을 전환하거나 url-test 속도 테스트를 트리거할 수 있습니다. 원격 서버의 코어에 대해서는 스마트폰 브라우저로도 노드를 바꿀 수 있어 SSH 작업이 필요 없습니다.

규칙 테스트

일부 패널은 Rule Test 도구를 제공하여 도메인이나 IP를 입력하면 매칭 결과를 시뮬레이션할 수 있습니다. 새 규칙이 예상대로 DIRECT 또는 PROXY로 처리되는지 검증할 수 있어 무작위로 설정을 변경하는 것보다 훨씬 효율적입니다.

보안 주의 사항

API에 무단으로 접근하면 프록시 제어권이 완전히 노출됩니다. 반드시 다음 원칙을 지키세요:

로컬 사용 시에는 우선 127.0.0.1에 바인딩하고 공개 네트워크에 임의로 노출하지 마세요.
강력한 secret을 반드시 설정하고, 패널 연결 시 HTTPS 또는 역방향 프록시 TLS를 활성화하세요(프로덕션 환경 권장).
VPS에서 9090 포트를 개방해야 한다면 방화벽으로 본인의 IP만 허용하거나 SSH 터널을 통해 접근하세요.
공용 네트워크에서는 시크릿 키 없는 개방 API를 사용하지 마세요. 타인이 트래픽을 소모하거나 출구를 변조하는 것을 방지하세요.

CLI 코어 + Dashboard 전형적인 사용 흐름

Linux 서버에 Mihomo를 배포할 때 일반적인 조합은 systemd 백그라운드 실행 코어 + 브라우저로 YACD 접속입니다. 코어 시작 후 로컬에서 SSH 포트 포워딩을 실행하세요: ssh -L 9090:127.0.0.1:9090 user@server. 이렇게 하면 로컬 브라우저에서 패널을 열어 원격 API에 연결할 수 있으며, 관리 포트를 공개 네트워크에 노출할 필요가 없습니다.

정리

외부 제어와 Web Dashboard는 Clash를 「블랙박스 클라이언트」에서 관찰 가능하고 디버깅 가능한 시스템으로 변환시켜 줍니다. 일반 사용자가 매일 패널을 열 필요는 없지만, 규칙 진단, 노드 최적화, 서버 코어 원격 관리 시에는 대체 불가능한 도구입니다. 수신 주소와 시크릿 키를 올바르게 설정하는 것이 편리함을 누리면서 보안을 지키는 전제 조건입니다.

로컬에서 완전한 클라이언트 경험을 원하신다면 공식 다운로드 페이지를 방문하세요. 처음 설정하는 분은 설정 가이드를 참고하여 구독 가져오기와 시스템 프록시 설정을 완료하세요.

관련 글