Clash 노드 자동 전환 구현하기: API 설정과 장애 감지 스크립트

자동 전환을 시작하기 전에 동작 구조부터 정리

Clash 노드 자동 전환은 단순히 “응답이 늦으면 다른 노드를 선택한다”는 한 가지 동작으로 끝나지 않습니다. 외부 스크립트가 실행 중인 Clash 또는 Mihomo의 제어 인터페이스에 인증해 프록시 그룹과 노드 목록을 읽고, 각 노드의 지연 시간을 확인한 뒤, 필요할 때 그룹의 선택값을 변경하는 흐름입니다. 제어 인터페이스가 꺼져 있거나 스크립트가 잘못된 그룹 이름을 사용하면 노드 측정 자체가 정상이어도 전환은 일어나지 않습니다.

자동 전환을 구성할 때는 먼저 그룹 유형을 확인하세요. 스크립트가 직접 노드를 선택하려면 대상 그룹은 보통 select 유형이어야 합니다. url-test 그룹은 코어가 지정된 URL을 주기적으로 검사하고 가장 적합한 항목을 선택하므로, 외부 스크립트까지 같은 그룹을 변경하면 선택값이 서로 덮어써질 수 있습니다. 두 방식을 섞지 말고, 코어의 자동 검사에 맡길지 외부 로직으로 전환할지 결정하는 것이 좋습니다.

또한 “지연 시간이 가장 낮은 노드”가 항상 실제 사용에 가장 좋은 노드는 아닙니다. 측정 URL까지의 왕복 시간은 접속 가능성과 대략적인 응답성을 보여 주지만, 다운로드 속도, 패킷 손실, 서비스별 연결 품질을 모두 나타내지는 않습니다. 자동화의 목적은 순간적인 숫자 경쟁이 아니라 장애가 지속될 때 안정적으로 대체 노드로 옮기고, 일시적인 흔들림에는 불필요하게 반응하지 않는 것입니다.

external-controller와 API 인증 설정

external-controller는 그래픽 클라이언트나 외부 도구가 코어의 상태를 조회하고 정책 그룹을 제어할 때 사용하는 HTTP API 주소입니다. 로컬 컴퓨터에서 스크립트를 실행한다면 제어 인터페이스를 루프백 주소에만 바인딩하는 편이 안전합니다. 예를 들어 포트가 9090이면 스크립트는 http://127.0.0.1:9090으로 요청을 보냅니다. 이는 일반 프록시 포트인 7890과 다른 용도이므로, 프록시 리스닝 포트를 API 주소로 착각하지 마세요.

external-controller: 127.0.0.1:9090
secret: "긴 임의 문자열로 변경"

설정 파일을 직접 수정하는 경우 적용 위치가 구독 설정인지 로컬 오버라이드인지 확인한 뒤 변경하세요. 구독 업데이트가 파일을 덮어쓰면 API 주소와 인증 값이 사라질 수 있습니다. 클라이언트가 자체 컨트롤러 설정 화면을 제공한다면 그 화면에서 실제 적용 주소와 포트를 확인하는 편이 낫습니다. 코어를 다시 불러오거나 클라이언트를 재시작한 다음 API가 응답하는지 점검합니다.

API 요청에는 다음처럼 인증 헤더를 포함합니다. secret이 설정되어 있으면 헤더를 생략하거나 값이 다를 때 인증 오류가 반환됩니다. 토큰은 명령 기록이나 공개 로그에 남기지 말고, 아래 명령의 예시 값을 실제 비밀값으로 교체하세요.

curl -sS \
  -H "Authorization: Bearer 긴_임의_문자열" \
  http://127.0.0.1:9090/version

정상 응답은 코어 버전 정보를 담은 JSON입니다. 연결 거부가 발생하면 코어가 실행 중인지, 포트 번호가 맞는지, 제어 인터페이스가 해당 주소에서 수신 중인지 확인하세요. 인증 실패라면 설정에 기록된 secret과 요청 헤더를 비교합니다. 인터페이스를 LAN 주소에 바인딩해야 하는 경우에는 강한 비밀값만으로 충분하다고 가정하지 말고 방화벽에서 접근 가능한 기기를 제한하세요. 제어 API는 상태 조회뿐 아니라 프록시 선택 변경 등 동작을 수행할 수 있습니다.

노드 지연 측정과 프록시 그룹 변경

Mihomo API에서는 GET /proxies로 현재 프록시와 정책 그룹 정보를 확인할 수 있습니다. 특정 노드의 지연 측정은 GET /proxies/{노드 이름}/delay?url={검사 주소}&timeout={밀리초} 형태로 요청합니다. 노드 이름과 검사 주소는 URL 인코딩이 필요할 수 있으므로, 직접 문자열을 이어 붙이는 스크립트보다 URL 인코딩 기능을 제공하는 라이브러리를 사용하세요. 측정 결과는 지연 시간(밀리초)을 나타내며, 연결할 수 없거나 제한 시간 안에 응답하지 못하면 요청이 실패할 수 있습니다.

선택 그룹의 현재 노드를 변경할 때는 PUT /proxies/{그룹 이름}으로 JSON 본문 {"name":"노드 이름"}을 전송합니다. 그룹과 노드 이름은 설정에 표시된 이름과 정확히 일치해야 합니다. 아래 예시는 Python 표준 라이브러리만 사용하며, API 인증, URL 인코딩, 재시도, 두 차례 측정, 지연값 비교와 그룹 선택 변경을 포함합니다. GROUP과 CANDIDATES를 실제 설정의 이름으로 바꾸고, 토큰은 환경 변수로 전달하세요.

import json
import os
import statistics
import time
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen

BASE = os.getenv("CLASH_API", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = "자동 선택"
CANDIDATES = ["노드 A", "노드 B", "노드 C"]
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
SAMPLES = 2
IMPROVEMENT_MS = 40

def request_json(path, method="GET", payload=None, attempts=2):
    body = None if payload is None else json.dumps(payload).encode("utf-8")
    req = Request(
        BASE + path,
        data=body,
        method=method,
        headers={
            "Authorization": "Bearer " + SECRET,
            "Content-Type": "application/json",
        },
    )
    last_error = None
    for attempt in range(attempts):
        try:
            with urlopen(req, timeout=8) as response:
                raw = response.read()
                return json.loads(raw) if raw else {}
        except (HTTPError, URLError, TimeoutError, OSError) as error:
            last_error = error
            if attempt + 1 < attempts:
                time.sleep(1 + attempt)
    raise RuntimeError(f"API 요청 실패: {last_error}")

def measure(name):
    path_name = quote(name, safe="")
    query = urlencode({"url": TEST_URL, "timeout": TIMEOUT_MS})
    path = f"/proxies/{path_name}/delay?{query}"
    values = []
    for _ in range(SAMPLES):
        try:
            result = request_json(path)
            values.append(int(result["delay"]))
        except (RuntimeError, KeyError, TypeError, ValueError):
            pass
        time.sleep(0.3)
    return statistics.median(values) if values else None

def main():
    proxies = request_json("/proxies")
    group = proxies.get("proxies", {}).get(GROUP)
    if not group:
        raise RuntimeError(f"그룹을 찾을 수 없음: {GROUP}")

    allowed = set(group.get("all", []))
    names = [name for name in CANDIDATES if name in allowed]
    if not names:
        raise RuntimeError("후보 노드가 그룹 구성원과 일치하지 않음")

    results = {name: measure(name) for name in names}
    available = {name: delay for name, delay in results.items()
                 if delay is not None}
    print("측정 결과(ms):", results)
    if not available:
        raise RuntimeError("응답 가능한 후보가 없음")

    best = min(available, key=available.get)
    current = group.get("now")
    current_delay = results.get(current)

    # 현재 노드가 실패했거나, 후보가 40ms 이상 빠를 때만 전환
    if current not in available or current_delay is None:
        switch = True
    else:
        switch = available[best] + IMPROVEMENT_MS < current_delay

    if switch and best != current:
        request_json(
            "/proxies/" + quote(GROUP, safe=""),
            method="PUT",
            payload={"name": best},
        )
        print(f"전환 완료: {current} -> {best} ({available[best]}ms)")
    else:
        print(f"유지: {current}, 최저 측정값 {best} ({available[best]}ms)")

if __name__ == "__main__":
    main()

스크립트를 실행하기 전에 환경 변수로 비밀값을 제공하세요. Linux와 macOS의 예시는 다음과 같습니다. 셸 기록에 토큰이 그대로 저장되지 않도록 실제 운영 환경에서는 권한이 제한된 환경 파일이나 운영체제의 비밀값 저장 기능을 사용하는 편이 안전합니다.

export CLASH_SECRET='여기에-실제-비밀값'
python3 auto_switch.py

이 예시는 현재 그룹에 포함된 후보만 측정하며, 이름이 그룹의 all 목록에 없으면 제외합니다. 이름 비교가 실패하면 공백, 대소문자, 한글 표기와 실제 적용 설정을 확인하세요. 그룹에 다른 정책 그룹이 포함된 경우에는 해당 그룹의 지연 측정 결과가 실제 노드 검사와 다르게 해석될 수 있으므로, 직접 검사할 노드를 후보 목록에 지정하는 것이 단순합니다.

재시도와 전환 임계값으로 잦은 변동 방지

한 번의 지연 측정만으로 바로 노드를 바꾸면 일시적인 혼잡, 검사 서버의 응답 지연, 무선 네트워크 변동에도 선택값이 계속 바뀔 수 있습니다. 예시 스크립트는 각 후보를 두 번 확인하고 유효한 응답의 중앙값을 사용합니다. 중앙값은 한 번의 튀는 측정값이 결과를 과도하게 좌우하는 것을 줄여 줍니다. 실제 운영에서는 횟수를 늘릴 수 있지만, 노드 수가 많으면 API 호출량과 전체 검사 시간이 함께 증가합니다.

  • 장애 판정: 현재 노드가 두 번 모두 실패했을 때만 장애로 취급하도록 하면 일시적인 타임아웃에 덜 민감합니다. 서비스 특성에 따라 실패 횟수 2~3회와 회복 확인 횟수를 별도로 정하세요.
  • 전환 임계값: 현재 노드보다 후보가 최소 40ms 이상 빠를 때만 전환하도록 두면 5~10ms 차이에 따른 반복 변경을 줄일 수 있습니다. 실제 임계값은 평소 측정 분포를 기록한 뒤 조정하세요.
  • 검사 주기: 1~2초 간격은 API 요청을 지나치게 자주 만들 수 있습니다. 일반적인 데스크톱 환경에서는 30~60초처럼 여유 있는 간격으로 시작하고, 장애 대응 시간과 측정 부하의 균형을 확인하는 편이 안전합니다.
  • 복귀 조건: 장애 노드가 한 번 응답했다고 즉시 원래 노드로 돌아가게 하지 마세요. 일정 횟수 연속 성공, 충분히 낮은 지연, 최소 유지 시간 등을 함께 적용하면 노드 간 왕복 전환을 줄일 수 있습니다.

스크립트를 주기적으로 실행하는 경우에는 한 번의 실행이 끝나기 전에 다음 실행이 시작되지 않도록 해야 합니다. 실행 시간이 검사 주기보다 길면 두 프로세스가 서로 다른 측정 결과를 바탕으로 그룹을 번갈아 변경할 수 있습니다. 동시에 여러 스크립트나 모니터링 도구가 같은 그룹을 제어하지 않는지도 확인하세요. 로그에는 시각, 그룹 이름, 현재 노드, 후보별 지연 또는 실패, 전환 이유와 API 오류를 남기면 실제 장애와 임계값 문제를 구분하기 쉽습니다.

문제가 생겼을 때는 먼저 API가 응답하는지, 그다음 그룹 이름과 멤버 목록이 맞는지, 마지막으로 개별 지연 측정과 그룹 변경 요청이 성공하는지 순서대로 확인하세요. API 응답은 정상이지만 모든 노드 측정이 실패한다면 검사 URL의 접근성, DNS, 코어 로그와 노드 상태를 점검합니다. 측정은 성공하지만 선택값이 바뀌지 않는다면 그룹 유형이 select인지, 스크립트가 실제 선택 그룹을 대상으로 하는지, PUT 요청의 인증과 JSON 본문이 올바른지 확인하세요. 이러한 단계를 분리하면 노드 장애와 자동화 스크립트의 설정 오류를 혼동하지 않고 원인을 좁힐 수 있습니다.

Clash 다운로드