Windows Mihomo Party 외부 컨트롤러 설정과 안전한 활성화 방법

Windows에서 Mihomo Party의 외부 컨트롤러를 설정하면 별도의 Web 패널이나 관리 도구가 Mihomo의 상태를 조회하고, 프록시 그룹을 변경하며, 현재 연결 정보를 읽을 수 있습니다. 하지만 외부 컨트롤러는 단순한 웹페이지 주소가 아닙니다. 지정된 주소와 포트에서 API 서버를 열고, 필요하면 secret 인증까지 통과해야 하므로 주소·포트·인증 헤더 중 하나만 틀려도 연결에 실패합니다.

이 글에서는 Windows용 Mihomo Party를 기준으로 외부 컨트롤러 메뉴를 찾는 방법, 로컬 전용으로 안전하게 활성화하는 방법, Web 패널에 입력할 값, PowerShell에서 실제 API 응답을 확인하는 순서를 설명합니다. 클라이언트 버전에 따라 메뉴 이름이나 설정 화면의 배치는 조금 다를 수 있지만, 최종적으로 확인해야 할 핵심 값은 external-controller와 secret입니다.

외부 컨트롤러가 하는 일

mihomo 커널은 프록시 연결을 처리하는 동시에 HTTP 기반의 외부 컨트롤러 API를 제공합니다. Mihomo Party 자체 화면도 내부적으로 이 API를 사용해 현재 모드, 프록시 그룹, 연결 수, 메모리 사용량과 로그를 표시합니다. 외부 컨트롤러를 활성화하면 다른 관리 패널이 같은 API에 접속해 설정 상태를 읽거나 일부 동작을 요청할 수 있습니다.

• 상태 조회—커널 버전, 현재 모드, 업로드·다운로드 통계, 활성 연결을 확인합니다.
• 프록시 그룹 변경—select 그룹의 현재 노드를 바꾸거나 url-test 그룹의 상태를 조회합니다.
• 설정 점검—현재 로드된 설정, DNS 상태, 규칙 매칭 결과를 확인하는 데 사용합니다.
• Web 패널 연결—브라우저 기반 패널이 mihomo API를 통해 대시보드 정보를 표시하도록 합니다.

여기서 외부라는 표현은 반드시 인터넷에 공개된다는 뜻이 아닙니다. 127.0.0.1에만 바인딩하면 같은 Windows 컴퓨터에서 실행 중인 프로그램만 접근할 수 있습니다. 반대로 0.0.0.0에 바인딩하면 모든 네트워크 인터페이스에서 접속을 받을 수 있으므로, Windows 방화벽과 공유기 설정에 따라 같은 네트워크의 다른 기기나 원격 사용자가 API 포트에 접근할 가능성이 생깁니다.

Mihomo Party에서 설정 메뉴 찾기

Mihomo Party의 버전과 테마에 따라 설정 화면의 명칭은 "외부 컨트롤러", "External Controller", "API", "External Controller API"처럼 다르게 표시될 수 있습니다. 먼저 Mihomo Party를 실행한 뒤 설정 아이콘 또는 톱니바퀴 메뉴를 열고, 일반 설정이나 고급 설정에서 컨트롤러 관련 항목을 찾습니다. Profiles 화면의 YAML 편집기에서 직접 값을 수정하는 방식도 있지만, GUI에 같은 항목이 있다면 GUI를 우선 사용하는 편이 오타와 설정 덮어쓰기 문제를 줄일 수 있습니다.

1. Windows에서 Mihomo Party를 실행하고 트레이 아이콘이 정상적으로 표시되는지 확인합니다.
2. 왼쪽 메뉴의 설정 또는 Settings를 연 다음 일반, 고급, Core 또는 mihomo 관련 영역을 차례로 살펴봅니다.
3. 외부 컨트롤러 주소를 127.0.0.1:9090으로 입력합니다. 이미 다른 프로그램이 9090 포트를 사용한다면 127.0.0.1:9091처럼 사용하지 않는 포트로 변경합니다.
4. Secret 또는 API Secret 입력란에 충분히 긴 임의의 문자열을 입력합니다. 예를 들어 MP-local-2026-Only-ChangeMe-7fQ2처럼 다른 사람이 쉽게 추측하기 어려운 값을 사용합니다.
5. 저장 또는 적용을 누른 뒤 커널 재시작, 프로필 다시 적용, Mihomo Party 재시작 중 필요한 동작을 실행합니다.

설정 화면에 주소와 secret을 각각 입력하는 칸이 있다면 주소에는 인증 정보를 붙이지 않습니다. 주소는 127.0.0.1:9090처럼 호스트와 포트만 작성하고, secret은 별도 입력란에 넣어야 합니다. 일부 Web 패널은 URL을 http://127.0.0.1:9090 형태로 요구하지만, mihomo 설정의 external-controller 값은 보통 프로토콜을 제외한 127.0.0.1:9090 형식입니다.

안전한 YAML 설정과 주소 선택

GUI에 외부 컨트롤러 항목이 보이지 않거나 저장 후 값이 사라진다면 현재 프로필의 YAML 설정을 확인할 수 있습니다. 다음은 로컬 컴퓨터에서만 API를 열고 secret 인증을 사용하는 기본 예시입니다.

external-controller: 127.0.0.1:9090
secret: "MP-local-2026-Only-ChangeMe-7fQ2"

YAML은 들여쓰기와 특수문자에 민감합니다. secret에 콜론, 해시, 앞뒤 공백 같은 문자가 포함될 수 있으므로 큰따옴표로 감싸는 편이 안전합니다. 설정 파일에 이미 external-controller가 있다면 같은 키를 두 번 만들지 말고 기존 값을 수정하세요. 중복 키는 편집기마다 다르게 처리될 수 있으며, 화면에 보이는 값과 실제 커널이 읽은 값이 달라질 수 있습니다.

외부 기기에서 Web 패널을 사용해야 한다는 이유로 처음부터 모든 인터페이스에 바인딩할 필요는 없습니다. 먼저 같은 PC의 브라우저에서 로컬 연결을 검증한 뒤, 정말 필요한 경우에만 LAN 주소 바인딩을 검토하세요. LAN에서 사용할 때에도 Windows Defender 방화벽에서 해당 포트를 전체 인터넷이 아닌 신뢰할 수 있는 사설 네트워크에만 허용하는 방식이 안전합니다.

Windows에서 실제 API 응답 확인하기

Web 패널의 오류 메시지만 보면 주소 문제인지 secret 문제인지 구분하기 어렵습니다. Windows PowerShell에서 API를 직접 호출하면 커널이 실제로 실행 중인지, 포트가 열려 있는지, 인증이 통과하는지를 단계별로 확인할 수 있습니다. 아래 예시에서 secret은 실제로 입력한 값으로 바꾸고, 명령줄 기록이 저장되거나 공유되지 않도록 주의하세요.

1. PowerShell을 열고 다음 명령으로 포트가 열려 있는지 확인합니다.

Test-NetConnection 127.0.0.1 -Port 9090

결과의 TcpTestSucceeded : True가 나오면 해당 포트에서 TCP 연결을 받을 가능성이 있습니다. False라면 Mihomo Party가 실행되지 않았거나, 커널이 외부 컨트롤러를 열지 않았거나, 포트 번호가 다르거나, 다른 프로그램이 설정을 덮어쓴 경우를 확인해야 합니다.

1. secret을 Authorization 헤더에 넣고 커널 버전 API를 호출합니다.

$secret = "MP-local-2026-Only-ChangeMe-7fQ2"
$headers = @{ Authorization = "Bearer $secret" }
Invoke-WebRequest -Uri "http://127.0.0.1:9090/version" -Headers $headers

인증과 연결이 모두 정상이라면 HTTP 상태 코드 200과 함께 mihomo의 버전 정보가 JSON으로 반환됩니다. JSON 내용을 보기 쉽게 표시하려면 다음처럼 실행할 수 있습니다.

(Invoke-WebRequest -Uri "http://127.0.0.1:9090/version" -Headers $headers).Content | ConvertFrom-Json

이제 프록시 그룹 API도 확인합니다.

$result = Invoke-WebRequest -Uri "http://127.0.0.1:9090/proxies" -Headers $headers
$result.StatusCode
$result.Content | ConvertFrom-Json

/proxies 응답에 정책 그룹과 노드 정보가 표시되면 단순한 포트 개방을 넘어 mihomo API가 정상적으로 작동하는 상태입니다. Web 패널에 연결할 때에는 주소에 http://를 포함하고, 패널의 secret 입력란에는 동일한 secret을 넣습니다. 패널에 "API URL"과 "Secret"이 따로 있다면 각각 http://127.0.0.1:9090과 secret 값을 입력하세요.

Web 패널 연결과 권한 점검

API 직접 호출이 성공한 다음에 Web 패널을 연결해야 합니다. 패널에서 먼저 API 주소를 입력하고, 끝에 불필요한 경로를 붙이지 않습니다. 기본 주소가 http://127.0.0.1:9090이라면 /version이나 /proxies를 패널 주소에 직접 넣지 않습니다. 패널이 내부적으로 필요한 API 경로를 추가하기 때문입니다.

• 주소—Mihomo Party와 Web 패널이 같은 Windows PC에서 실행되면 http://127.0.0.1:9090을 사용합니다.
• secret—YAML의 secret 값과 대소문자까지 완전히 같아야 합니다.
• 프로토콜—로컬 기본 설정은 일반적으로 http입니다. HTTPS를 사용하지 않으면서 https://를 입력하면 TLS 오류가 발생할 수 있습니다.
• 브라우저 권한—Web 패널이 다른 출처에서 API를 호출하는 구조라면 CORS 관련 오류가 나타날 수 있습니다. 이때 secret을 반복해서 바꾸기보다 패널이 mihomo API를 지원하는지 먼저 확인합니다.

연결이 되더라도 Web 패널의 모든 기능이 Mihomo Party 버전과 완전히 호환된다는 뜻은 아닙니다. mihomo API 버전, 패널이 기대하는 엔드포인트, 패널이 사용하는 기능에 따라 일부 통계나 설정 화면이 비어 있을 수 있습니다. /version과 /proxies가 정상 응답하는데 특정 화면만 작동하지 않는다면 기본 연결이 아니라 패널 호환성 문제일 가능성이 큽니다.

보안 유지와 변경 후 점검

외부 컨트롤러를 장기간 사용할 때는 secret을 설정 파일과 동일하게 관리해야 합니다. 설정 파일을 다른 사람에게 보내거나 화면을 캡처해 공유할 때 secret이 노출되지 않도록 가립니다. 구독 URL처럼 외부 컨트롤러 secret도 API 접근 권한으로 취급해야 하며, 채팅 기록이나 공개 문서에 그대로 남기지 않는 것이 좋습니다.

• 로컬 전용 사용이라면 항상 127.0.0.1 바인딩을 우선합니다.
• 9090 포트가 이미 사용 중이면 임의로 방화벽을 끄지 말고 다른 로컬 포트를 선택합니다.
• 설정 변경 후 Mihomo Party의 커널 재시작 또는 프로필 재적용을 실행합니다.
• API가 필요 없을 때는 외부 컨트롤러를 비활성화하거나 포트를 닫아 공격 표면을 줄입니다.
• secret을 바꾼 뒤 기존 Web 패널에 저장된 이전 인증 정보를 삭제하고 새 값으로 다시 연결합니다.

자주 묻는 질문

외부 컨트롤러 메뉴가 Mihomo Party에 보이지 않습니다

버전에 따라 일반 설정이 아니라 고급 설정, Core 설정 또는 프로필 YAML 편집 화면에 표시될 수 있습니다. 현재 적용된 프로필에 external-controller와 secret을 추가한 뒤 커널을 다시 시작해 보세요. GUI에서 값을 관리하는 기능이 있다면 YAML과 GUI에 중복으로 작성하지 않는 것이 좋습니다.

401 오류가 계속 발생하는 이유는 무엇인가요?

secret이 실제 적용된 프로필의 값과 다르거나, API 호출 헤더가 Authorization: Bearer secret값 형식이 아닐 가능성이 높습니다. 앞뒤 공백, 따옴표 자체를 값에 포함했는지, 대소문자가 바뀌었는지를 확인하세요.

127.0.0.1 대신 0.0.0.0을 사용해도 되나요?

다른 기기에서 관리해야 하는 명확한 이유가 있을 때만 검토하세요. 0.0.0.0은 모든 인터페이스에서 요청을 받을 수 있으므로 Windows 방화벽의 허용 범위와 네트워크 프로필을 함께 제한해야 합니다. 같은 PC에서 사용하는 Web 패널이라면 127.0.0.1이 더 안전합니다.

API 포트는 열렸지만 Web 패널만 연결되지 않습니다

PowerShell에서 /version과 /proxies가 200을 반환한다면 주소와 커널은 정상일 가능성이 큽니다. 패널 주소에 잘못된 경로를 붙였거나 HTTPS를 잘못 선택했거나, 해당 패널이 현재 mihomo API와 호환되지 않는지 확인하세요.