1 웹으로 Mihomo를 다루려면 무엇부터 보나
Clash 계열 코어는 설정 파일만 읽는 것이 아니라, 실행 중에도 HTTP API로 모드 전환·프록시 선택·연결 목록 조회 같은 작업을 할 수 있습니다. GUI 앱은 내부적으로 이 API를 호출하는 경우가 많고, 외부 컨트롤러(external-controller)는 그 API가 어느 IP와 포트에서 듣도록 할지를 정하는 항목입니다. 주소만 알면 브라우저에서 동작하는 대시보드(예: Yacd)나 스크립트가 같은 기능을 재사용할 수 있습니다.
반대로 말하면, API가 불특정 다수에게 열리면 누군가 내 프록시 정책을 바꾸거나 연결 상태를 엿볼 수 있어 secret과 바인딩 주소를 함께 설계해야 합니다. 데스크톱 전용이라면 127.0.0.1에만 붙이고, 집 안 다른 기기에서만 쓰려면 같은 Wi-Fi 안의 사설 IP로 접근할지, 아니면 SSH 터널로만 닿게 할지부터 정하는 편이 안전합니다.
서버나 Linux에 코어만 올린 경우 Linux Mihomo 설치 가이드와 함께 읽으면 config.yaml 위치와 서비스 재시작 흐름이 맞물립니다. GUI로 구독을 덧씌우는 흐름은 구독 오버라이드·mixin 글과 역할이 나뉩니다.
2 external-controller: 주소와 포트 쓰는 법
설정 파일 최상단 근처에 보통 다음과 같이 둡니다. 로컬 전용이 가장 무난합니다. 이렇게 하면 같은 머신에서 돌아가는 브라우저·Yacd만 접속할 수 있고, 공유기 밖 인터넷에서는 API 포트가 보이지 않습니다.
# Listen only on this machine
external-controller: 127.0.0.1:9090
# Optional: separate binding for IPv6 loopback if needed
# external-controller: '[::1]:9090'
LAN 안의 휴대폰이나 노트북에서 패널을 쓰려면 코어가 사설 IP(예: 192.168.0.10)에도 바인딩되도록 바꾸거나, 0.0.0.0으로 모든 인터페이스에 열고 방화벽으로 출발지 IP를 제한하는 방식이 쓰입니다. 후자는 설정은 단순하지만 실수로 전 세계에 API가 노출될 수 있으므로 운영 환경에서는 추천하지 않습니다. 가능하면 한 대의 관리 PC에서만 SSH로 접속해 127.0.0.1:9090을 터널링하는 편이 낫습니다.
9090은 관례일 뿐이며, 다른 프로그램과 겹치면 자유롭게 바꿉니다. 바꾼 뒤에는 Yacd에 입력하는 주소와 방화벽 규칙도 같은 번호로 맞추세요.
3 secret: API 요청에 비밀번호 한 장 더 얹기
secret은 선택 항목이지만, API가 LAN에라도 열려 있으면 사실상 필수에 가깝습니다. 값이 설정되어 있으면 대부분의 관리 요청에 Authorization: Bearer … 헤더나 쿼리 파라미터로 토큰을 넣어야 하며, 웹 패널은 처음 연결할 때 이 문자열을 한 번 입력해 둡니다. 짧은 단어나 «password» 같은 기본값은 즉시 바꾸고, 길고 예측하기 어려운 문자열을 쓰는 것이 좋습니다.
external-controller: 127.0.0.1:9090
secret: "replace-with-long-random-string"
설정을 고친 뒤에는 사용 중인 클라이언트가 설정을 다시 읽도록 해야 합니다. systemd로 돌리는 경우 서비스 재시작, GUI 앱은 «설정 적용» 또는 앱 재실행 절차를 따릅니다. secret을 비우면 편하지만, 그만큼 로컬에서 API를 아는 사람은 누구나 정책을 바꿀 수 있다는 뜻이 되므로, 다중 사용자 PC나 원격 데스크톱 환경에서는 특히 위험합니다.
secret은 평문으로 YAML에 있습니다. 파일을 클라우드에 올리거나 스크린샷을 찍을 때 같이 노출되지 않게 관리하세요. 팀과 공유할 때는 별도 비밀 관리 도구를 고려하는 것이 안전합니다.
4 Yacd: Yet Another Clash Dashboard 연결 순서
Yacd는 브라우저에서 동작하는 Clash/Mihomo용 대시보드로, 공개된 정적 페이지에 API 베이스 URL과 secret만 넣으면 노드 목록·지연 측정·모드 전환을 할 수 있습니다. 배포 방식은 두 가지가 흔합니다. 첫째, 신뢰할 수 있는 호스트된 Yacd 페이지를 열고 연결 정보를 입력한다. 둘째, 릴리스 패키지를 받아 로컬에서 정적 파일을 연 뒤 같은 방식으로 API 주소를 넣는다.
연결 시 입력하는 값은 보통 http://127.0.0.1:9090 형태의 컨트롤러 주소(external-controller와 동일)입니다. HTTPS만 허용하는 브라우저 정책이나 혼합 콘텐츠 이슈가 있으면, 대시보드를 로컬 파일로 열거나 리버스 프록시로 TLS를 종료하는 방식을 검토합니다. Mihomo는 Clash와 같은 API를 대부분 유지하므로, 패널 쪽에서 «Meta» 옵션이 있다면 켜 두는 것이 맞습니다.
스크린 리더 사용자나 터미널 위주 환경이라면 웹 패널 대신 curl로 /configs·/proxies 등 엔드포인트를 직접 호출할 수도 있습니다. 다만 사람이 쓰기에는 Yacd 같은 UI가 실수를 줄여 줍니다.
5 LAN과 «원격»에서 노드 바꾸기
같은 Wi-Fi에 있는 폰 브라우저에서 PC의 Mihomo를 조작하려면, PC의 방화벽이 API 포트에 대한 연결을 허용하는지 먼저 확인합니다. 그다음 external-controller를 PC의 사설 IP(예: 192.168.1.5:9090)로 바꾸거나, 0.0.0.0 바인딩 + OS 방화벽으로 같은 서브넷만 허용하는 식으로 제한합니다. 공유기 포트포워딩으로 API를 인터넷에 직접 노출하는 구성은 매우 위험하므로, 꼭 필요하면 VPN이나 SSH 터널 안에서만 접근하게 만드는 편이 낫습니다.
«원격»이 회사 노트북에서 집 PC를 다루는 경우라면, 집 공유기에 포트를 뚫기보다 ZeroTier·Tailscale 같은 오버레이 네트워크로 사설 IP를 맞춘 뒤 그 안에서만 API를 여는 방식이 설정과 보안 면에서 균형이 잘 잡힙니다. 이때도 secret과 방화벽은 기본값으로 두지 마세요.
allow-lan은 프록시 포트(예: mixed-port)를 다른 기기에 열지 여부와 관련이 있고, external-controller는 관리 API입니다. 둘 다 «밖으로 열린 구멍」이므로 각각 따로 위험을 평가해야 합니다.
6 패널이 다른 사람에게 보이지 않게 하기
다음 습관을 묶어 쓰면 체감 보안이 확 달라집니다. 첫째, 기본은 127.0.0.1 바인딩으로 두고, LAN 접근이 필요할 때만 일시적으로 바꾼 뒤 다시 좁힌다. 둘째, secret을 항상 켜 두고 주기적으로 바꾼다. 셋째, 공인망에 API를 내보내야 한다면 SSH 로컬 포워딩(ssh -L 9090:127.0.0.1:9090 user@server)처럼 이미 신뢰하는 채널 위에 얹는다. 넷째, 조직망에서는 리버스 프록시 뒤에 두고 Basic 인증·IP 제한을 추가하는 방법도 있습니다.
공용 PC나 카페에서는 브라우저에 Yacd를 띄워 둔 채 자리를 비우면, 화면만 잠가도 세션이 남아 있을 수 있습니다. 민감한 환경에서는 패널을 쓴 뒤 브라우저 탭을 닫거나, 시크릿 창을 사용하는 것이 좋습니다. 모바일 브라우저는 주소와 토큰이 자동 완성에 남을 수 있으니 주의합니다.
마지막으로, API는 프록시 계정 자체를 바꾸지는 않더라도 어떤 노드로 나갈지를 바꿀 수 있으므로, 가족·동료와 기기를 나눠 쓰는 환경에서는 OS 사용자 계정 분리와 맞물려 생각하는 것이 좋습니다.
7 자주 묻는 문제
- Yacd가 연결되지 않음: 주소가
external-controller와 정확히 같은지, http/https를 맞췄는지 확인합니다. 방화벽이 포트를 막고 있지 않은지도 봅니다. - 401·403 오류:
secret이 설정된 경우 패널에 동일한 값을 입력했는지, 오타·앞뒤 공백이 없는지 확인합니다. - 다른 PC에서만 안 됨: 바인딩이
127.0.0.1이면 다른 호스트에서는 당연히 연결되지 않습니다. 의도라면 터널 또는 LAN 바인딩으로 바꿉니다. - HTTPS 페이지에서 HTTP API 호출 문제: 혼합 콘텐츠로 차단될 수 있어, 로컬 대시보드 파일을 열거나 프록시 뒤 HTTPS로 API를 통일합니다.
8 정리
Mihomo의 external-controller는 브라우저·스크립트가 코어를 같은 API로 제어하게 해 주는 관문이고, secret은 그 관문에 걸 수 있는 최소한의 자물쇠입니다. Yacd 같은 웹 패널은 이 둘만 정확히 맞추면 원격·LAN에서 노드 전환을 시각적으로 처리할 수 있어, 클라이언트 내장 UI와 역할을 나눠 쓰기 좋습니다. 다만 열린 포트는 곧 공격 면이 되므로, 바인딩 범위와 비밀 문자열·방화벽을 한 세트로 설계하는 습관을 들이는 것이 장기적으로 가장 이득입니다.
데스크톱 앱으로 구독·TUN까지 한 번에 쓰고 싶다면 생태계가 통일된 Clash 계열 클라이언트를 고르는 것이 편합니다. 설치 패키지는 저장소 직링크보다 사이트 다운로드 페이지에서 플랫폼별로 받는 흐름을 권장합니다. 웹 패널은 그 위에서 «어디서든 스위치»를 담당하고, 본문에서 다룬 API 보안은 운영 환경에 맞게 조절하면 됩니다.
