mihomo 설정 및 문제 해결 용어
Clash 용어집
config.yaml의 설정 항목부터 로그에 표시된 출구까지 확인하세요.
생소한 옵션은 먼저 정의를 확인하고, 연결 문제가 생기면 트래픽 처리, DNS 확인, 규칙 매칭, 출구 순서로 살펴보세요. 카드 제목을 누르면 각 용어로 바로 이동할 수 있습니다.
커널 및 프로토콜
앱, 커널, 원격 서버의 역할을 구분하면 오류를 어느 단계에서 살펴봐야 할지 알 수 있습니다.
- mihomo
- mihomo는 Clash 생태계의 프록시 커널로, 설정을 읽고 연결을 받아 규칙에 따라 출구를 선택합니다. GUI 클라이언트는 설정 가져오기와 기능 전환을 담당하고, 실제 연결 처리는 커널이 맡습니다. '지원하지 않는 설정 항목' 오류가 나면 화면에 표시된 클라이언트 버전보다 실제로 로드된 커널 버전을 먼저 확인하세요.
- 프록시 프로토콜
- 프록시 프로토콜은 클라이언트가 원격 서버에 연결하고 인증한 뒤 데이터를 주고받는 방식을 정합니다. 노드를 정의할 때는 보통
type을 먼저 확인하고, 해당 프로토콜에 필요한 설정 항목을 살펴봅니다. 로컬 앱이 HTTP 프록시로 연결된다고 해서 커널도 원격 서버에 HTTP 프록시 프로토콜로 연결하는 것은 아닙니다.
- 혼합 포트(mixed-port)
- 혼합 포트를 사용하면 커널이 하나의 로컬 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받습니다. 예를 들어
7890으로 설정하면 로컬 앱에서127.0.0.1:7890을 지정하고 지원하는 프록시 유형을 선택할 수 있습니다. 이 포트는 앱이 연결하는 포트이지, 구독 주소나 원격 서버의 포트가 아닙니다.
- UDP 포워딩
- UDP 포워딩은 프록시 경로를 통해 UDP 데이터그램을 전달하는 기능으로, 음성 통화와 일부 게임에서 사용됩니다. 연결을 받는 쪽에서 UDP를 지원해야 하며, 선택한 출구와 원격 서버도 이를 지원해야 합니다. 웹페이지가 열린다고 해서 관련 연결이 모두 정상인 것은 아닙니다. 통화 문제를 진단할 때는 앱의 UDP 트래픽이 어디로 전달되는지 따로 확인하세요.
설정 파일 구조
원본 파일과 실제 적용되는 설정을 구분하세요. 전체 구조는 설정 항목에서 확인할 수 있습니다.
- YAML
- YAML은 mihomo 설정에 사용하는 데이터 형식입니다. 들여쓰기로 계층을 구분하고 하이픈으로 목록 항목을 표시합니다. 탭 대신 공백을 사용하고 같은 단계의 항목은 들여쓰기를 맞추세요. 파싱 오류가 특정 줄을 가리켜도 바로 윗줄의 콜론과 들여쓰기를 확인해야 합니다. 구조가 맞지 않는 문제를 커널이 다음 줄에서야 감지할 수도 있습니다.
- 기본 설정(config.yaml)
- 기본 설정은 커널을 시작하거나 다시 불러올 때 읽는 설정이며, 흔히
config.yaml이라는 파일명을 사용합니다. 기본 옵션, 프록시 정의, 프록시 그룹, 규칙을 포함하거나 외부 리소스를 참조할 수 있습니다. GUI 클라이언트는 설정을 가져온 뒤 실행용 파일을 별도로 저장하기도 하므로, 현재 가진 동명 파일을 수정해도 커널이 읽는 설정에는 반영되지 않을 수 있습니다.
- 프록시 정의(proxies)
proxies는 기본 설정에서 프록시 노드를 하나씩 정의하는 목록입니다. 각 항목은name으로 이름을 지정하고 프로토콜에 맞춰 서버 주소, 포트 등의 값을 설정합니다. 프록시 그룹은 이름으로 노드를 참조할 수 있습니다. 노드 이름을 바꾼 뒤 그룹에서 찾지 못한다면 네트워크 문제를 살펴보기 전에 참조 이름도 변경했는지 확인하세요.
- 설정 덮어쓰기 및 병합
- 설정 덮어쓰기와 병합은 기존 설정을 바탕으로 실제 적용할 설정을 새로 만드는 방식입니다. 단일 값 변경과 목록 항목 추가는 다르게 처리될 수 있습니다. 클라이언트에 따라 목록 전체를 교체하거나, 앞에 삽입하거나, 뒤에 추가할 수 있습니다. 규칙을 추가한 뒤에는 실제 적용 목록을 확인해 기존 규칙이 남아 있는지, 새 규칙이 기본 규칙 뒤로 밀리지 않았는지 살펴보세요.
프록시 그룹 및 규칙
규칙은 연결을 어느 그룹으로 보낼지 결정하고, 프록시 그룹은 실제 출구를 선택합니다.
- 규칙 기반 라우팅
- 규칙 기반 라우팅은 규칙 모드에서 조건에 따라 연결의 출구를 선택합니다. 일반 규칙은 위에서부터 확인하며, 처음 일치한 규칙이 적용됩니다. 특정 도메인 규칙은 이를 덮어쓸 수 있는 포괄적인 규칙보다 앞에 배치하세요. 사용자 규칙을 진단할 때는 먼저
mode: rule인지 확인한 다음 연결 세부 정보에서 실제로 일치한 규칙을 살펴보세요.
- 프록시 그룹(proxy-groups)
- 프록시 그룹은 여러 출구 선택지를 하나의 이름으로 묶어 규칙에서 참조할 수 있게 합니다. 그룹에는 노드, 다른 프록시 그룹 또는 내장 출구를 넣을 수 있으며, 선택 방식은 그룹 유형에 따라 다릅니다. 규칙이 그룹과 일치하는 것은 첫 단계일 뿐입니다. 연결이 실제로 어디로 가는지 확인하려면 그룹에서 현재 선택된 항목도 확인하세요.
- 도메인 접미사 규칙(DOMAIN-SUFFIX)
- 도메인 접미사 규칙은 지정한 도메인과 그 하위 도메인을 함께 일치시킵니다. 예를 들어
DOMAIN-SUFFIX,example.com,DIRECT는example.com과api.example.com에 일치하지만notexample.com에는 일치하지 않습니다. 도메인 하나만 정확히 지정하려면DOMAIN을 사용하세요.
- GeoIP
- GeoIP는 IP 주소 대역 데이터에 따라 지역을 분류하는 규칙 유형입니다.
GEOIP,CN,DIRECT는 대상 IP가 데이터에서 CN으로 분류되는지 확인하며, 도메인이.cn으로 끝나는지는 확인하지 않습니다. 같은 도메인도 서로 다른 IP 주소로 해석될 수 있으므로 일치 결과가 달라질 수 있습니다.
- 기본 규칙(MATCH)
MATCH에는 일치 조건이 없으며, 규칙 목록 끝까지 도달한 연결을 처리합니다.MATCH,DIRECT는 앞선 규칙에 일치하지 않은 연결을 직접 연결하라는 뜻입니다. 마지막 항목에서 프록시 그룹을 지정할 수도 있습니다.MATCH뒤에 일반 규칙을 추가해도 기본 규칙이 먼저 연결을 처리하므로 해당 규칙은 적용되지 않습니다.
- 자동 지연 시간 측정 그룹(url-test)
url-test그룹은 지정한 URL에 연결 테스트를 수행하고 결과에 따라 출구를 선택합니다. 자주 사용하는 설정 항목은url,interval,tolerance입니다. 허용 오차를 두면 지연 시간이 조금 달라질 때마다 출구가 바뀌는 일을 줄일 수 있습니다. 테스트 주소에 빠르게 연결된다고 해서 이용하려는 사이트도 빠르거나 다운로드 대역폭이 넓다는 뜻은 아닙니다.
트래픽 처리 방식
데이터 패킷이 커널에 들어왔는지와 도메인을 어느 DNS 서버가 조회했는지는 따로 확인하세요.
- 시스템 프록시
- 시스템 프록시는 운영체제가 앱에 제공하는 프록시 설정입니다. 시스템 전체 트래픽이 처리된다는 뜻은 아닙니다. 해당 설정을 읽는 앱은 로컬 프록시 포트에 연결하지만, 자체 프록시 설정을 사용하는 앱은 시스템 프록시를 거치지 않을 수 있습니다. 브라우저는 연결되는데 터미널에서는 안 된다면 먼저 명령줄 도구가 어떤 프록시 설정을 읽는지 확인하세요.
- TUN 모드
- TUN 모드는 가상 네트워크 인터페이스로 라우팅된 IP 패킷을 받아 커널에서 처리합니다. 앱이 HTTP나 SOCKS 프록시를 직접 지원하지 않아도 되지만, 실제로 처리되는 트래픽 범위는 라우팅, 권한, 제외 설정에 따라 달라집니다. 기능을 켰는데 연결 목록에 관련 기록이 없다면 가상 네트워크 인터페이스와 라우팅이 실제로 적용됐는지 먼저 확인하세요.
- Fake-IP
- Fake-IP는 DNS 처리 모드의 하나로, 커널이 앱에 임시 주소를 반환하고 해당 주소와 도메인의 대응 관계를 기록합니다. 이후 앱이 그 주소에 연결하면 커널이 매핑을 바탕으로 도메인을 찾아 규칙 매칭에 사용할 수 있습니다. 실제 DNS 응답에 의존하는 서비스라면 해당 도메인을
fake-ip-filter에 추가해야 하는지 먼저 확인하세요.
- DNS 가로채기(dns-hijack)
- mihomo의 TUN 설정에서
dns-hijack은 조건에 맞는 DNS 쿼리를 커널의 DNS 모듈로 전달하는 항목입니다. 상위 DNS 서버 주소를 지정하는 항목이 아니며, 앱이 HTTPS로 보내는 DNS 쿼리까지 자동으로 처리하지도 않습니다. 설정을 변경한 뒤에는 쿼리가 실제로 수신되는지, 수신된 쿼리가 어느 상위 DNS 서버로 전달되는지 각각 확인하세요.
- DNS 유출
- DNS 유출은 지정된 경로로 보내야 할 쿼리가 예상하지 못한 출구를 통해 전송되는 현상입니다. 웹페이지가 프록시를 통해 열린다고 해서 앞서 진행된 도메인 조회도 같은 경로를 이용했다고 단정할 수는 없습니다. 진단할 때는 운영체제와 앱의 DNS 설정을 각각 확인하고, 커널 로그를 대조해 쿼리가 예상한 DNS 서버를 거쳤는지 살펴보세요.
- DNS 분기(nameserver-policy)
- DNS 분기는 쿼리한 도메인에 따라 상위 DNS 서버를 선택합니다. 예를 들어 사내 도메인은 해당 도메인을 조회할 수 있는 조직 내부 DNS 서버로 보내고 나머지는 일반 DNS 서버를 사용하도록 설정할 수 있습니다. 이 설정은 쿼리에 응답할 서버를 정할 뿐, 해당 주소에 연결할 때 직접 연결할지 프록시를 사용할지는 정하지 않습니다. 연결 방식은 별도의 규칙으로 결정됩니다.
구독 및 노드
가져오기, 파싱, 연결은 각각 따로 확인해야 하는 단계입니다.
- 구독
- 구독은 클라이언트가 설정이나 노드 목록을 정기적으로 가져오는 경로이며, 보통 링크 형태로 제공됩니다. 전체 설정에는 규칙과 프록시 그룹이 포함될 수 있지만, 노드 목록만 제공되는 경우에는 기존 설정에서 사용해야 할 수도 있습니다. 가져오기 전에 클라이언트가 어떤 형식을 지원하는지 확인하세요. 문제 해결 화면을 공유할 때는 구독 링크를 함께 올리지 마세요.
- 노드
- 노드는 커널이 연결을 전달할 때 선택할 수 있는 원격 프록시 항목입니다. 이름은 주로 화면 표시와 설정에서 참조하는 데 사용되며, 실제 연결에는 서버 주소, 포트, 프로토콜 설정이 필요합니다. 목록에 노드 이름이 보인다는 것은 항목이 로드되었다는 뜻일 뿐입니다. 사용할 수 있는지는 원격 서버 연결과 인증 결과도 확인해야 합니다.
- 노드 지연 시간
- 클라이언트에 표시되는 노드 지연 시간은 보통 해당 노드를 통해 테스트 주소에 접속했을 때 걸린 응답 시간입니다. 노드 주소에 대한 단순 연결 확인값이 아니며 다운로드 속도로 바로 환산할 수도 없습니다. 비교할 때는 같은 테스트 주소와 네트워크를 사용하세요. 한 번 시간 초과가 발생했다고 해서 항상 연결할 수 없는 것은 아니며, 해당 테스트가 제한 시간 안에 끝나지 않았다는 뜻입니다.
- 구독 업데이트
- 구독 업데이트는 원격 콘텐츠를 다시 가져와 클라이언트가 파싱한 뒤 구독 데이터를 교체하거나 갱신하는 과정입니다. 요청 시간이 초과되면 먼저 구독 주소에 연결할 수 있는지 확인하고, 응답을 가져왔지만 가져오기에 실패하면 응답 형식을 살펴보세요. 업데이트에 성공했는데도 프록시 그룹에 이전 항목이 보인다면 현재 활성화된 설정이 해당 구독을 참조하는지 확인하세요.