Clash의 그래픽 화면에서 노드를 바꾸는 작업은 정책 그룹의 선택 값을 변경하는 것입니다. Mihomo와 일부 Clash 호환 코어는 같은 작업을 external-controller API로 처리할 수 있어, 셸 스크립트나 모니터링 프로그램에서 현재 그룹과 선택된 노드를 확인하고 조건에 따라 전환할 수 있습니다. 다만 API는 프록시 코어의 제어 인터페이스이지 일반 프록시 포트가 아닙니다. 브라우저 트래픽을 보내는 주소로 사용하지 말고, 접근 권한과 노출 범위를 별도로 관리해야 합니다.

자동 전환을 설계할 때는 먼저 대상이 수동 선택이 가능한 Select 그룹인지 확인하고, 그 그룹이 제공하는 노드 이름만 선택해야 합니다. 지연 시간이 낮다는 이유만으로 즉시 전환하면 순간적인 측정 오차나 대상 서버의 응답 지연에 반응해 노드가 계속 바뀔 수 있습니다. 측정 대상 URL, 임계값, 재시도 횟수와 전환 간격을 함께 정하고, 문제가 생겼을 때 현재 설정을 그대로 유지하도록 구성하는 편이 안전합니다.

Clash external-controller API로 프록시 노드 자동 전환하기

external-controller API의 주소와 인증

external-controller는 그래픽 클라이언트나 외부 도구가 코어의 상태와 정책 그룹을 조회하고 제어하도록 제공하는 HTTP API입니다. 흔히 예시에서 사용하는 주소는 127.0.0.1:9090이지만, 실제 포트는 설정과 클라이언트에 따라 다를 수 있습니다. Clash Verge 또는 Mihomo 기반 클라이언트에서는 설정 화면이나 적용 중인 설정에서 컨트롤러 주소와 코어 상태를 확인하세요. API 포트와 mixed-port, socks-port 같은 프록시 수신 포트는 서로 다른 용도입니다.

API에 secret이 설정되어 있으면 요청에 인증 헤더를 포함해야 합니다. 일반적으로 다음 형식의 Bearer 토큰을 사용합니다.

Authorization: Bearer <컨트롤러 비밀 키>

먼저 로컬에서 정책 그룹 목록을 조회할 수 있는지 확인합니다. 아래 예시의 포트와 그룹 이름은 실제 설정에 맞게 바꾸세요.

curl -sS \
  -H "Authorization: Bearer $CLASH_SECRET" \
  http://127.0.0.1:9090/proxies

응답의 proxies 객체에는 정책 그룹과 프록시 정보가 포함됩니다. 선택 그룹은 보통 type이 Selector로 표시되고, 선택 가능한 구성원은 all 배열에, 현재 선택된 구성원은 now에 나타납니다. 그룹 이름이 한글이거나 공백, 기호를 포함한다면 URL 경로에서 인코딩해야 하므로 문자열을 직접 이어 붙이지 않는 것이 좋습니다.

API가 응답하지 않으면 자동 전환 코드를 수정하기 전에 코어가 실행 중인지, 설정이 적용되었는지, 컨트롤러 포트가 실제로 열려 있는지 확인하세요. HTTP 401 또는 403 계열 응답은 인증 키나 접근 정책을 점검해야 한다는 신호입니다. 반대로 연결 거부는 주소와 포트가 틀렸거나 컨트롤러가 리스닝하지 않는 경우가 흔합니다.

그룹 상태를 읽고 선택 노드 바꾸기

특정 그룹의 정보를 조회할 때는 GET /proxies/{그룹 이름}을 사용합니다. 현재 노드와 그룹 구성원을 확인한 다음, 선택 그룹에 대해서만 PUT /proxies/{그룹 이름} 요청을 보내 노드를 바꿉니다. 본문은 JSON이며 선택할 프록시의 이름을 name 필드에 지정합니다.

curl -sS \
  -H "Authorization: Bearer $CLASH_SECRET" \
  "http://127.0.0.1:9090/proxies/%E8%8A%82%E7%82%B9%E9%80%89%E6%8B%A9"

curl -sS -X PUT \
  -H "Authorization: Bearer $CLASH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"노드-A"}' \
  "http://127.0.0.1:9090/proxies/%E8%8A%82%E7%82%B9%E9%80%89%E6%8B%A9"

첫 번째 요청 경로는 그룹 이름을 URL 인코딩한 예입니다. 실제 사용에서는 직접 인코딩한 문자열을 복사하기보다 프로그램에서 인코딩 함수를 사용하세요. 두 번째 요청에서 지정하는 이름은 서버 주소나 노드 인덱스가 아니라 그룹의 구성원 이름이어야 합니다. 이름이 all 목록에 없거나 대상이 선택 그룹이 아니면 요청이 실패할 수 있습니다.

API를 통해 정책 그룹의 선택을 바꿔도 전체 설정 파일의 모든 부분을 수정하는 것은 아닙니다. 다른 그룹이 별도로 선택 상태를 관리하거나, 규칙이 다른 그룹을 참조한다면 해당 연결에는 영향이 없을 수 있습니다. 먼저 연결 기록이나 그룹 구조에서 실제 트래픽이 어느 그룹으로 라우팅되는지 확인하세요. 자동화 대상 그룹은 가능한 한 명확하게 하나로 지정하고, 다른 그룹의 선택 값을 실수로 변경하지 않도록 이름을 고정 설정으로 관리하는 것이 좋습니다.

Python으로 지연 시간을 측정하고 조건부 전환하기

다음 예시는 표준 라이브러리만 사용해 지정한 Selector 그룹의 후보 노드별 지연 시간을 측정하고, 현재 노드가 실패했거나 더 나은 후보가 임계값 이상 빠를 때 전환하는 기본 구조입니다. 코어마다 API 지원 범위와 응답 세부 형식이 다를 수 있으므로, 운영 전에 설치된 Mihomo 또는 호환 코어의 API 응답을 확인하세요. 측정 URL은 실제로 접근 가능한 HTTPS 주소로 바꾸고, 네트워크 환경에서 안정적으로 응답하는지 먼저 테스트해야 합니다.

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

BASE = "http://127.0.0.1:9090"
GROUP = "노드 선택"
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
SWITCH_MARGIN_MS = 80
SECRET = os.environ.get("CLASH_SECRET", "")

if not SECRET:
    raise SystemExit("CLASH_SECRET 환경 변수를 설정하세요.")

def api(method, path, payload=None, attempts=3):
    body = None if payload is None else json.dumps(payload).encode("utf-8")
    headers = {"Authorization": f"Bearer {SECRET}"}
    if body is not None:
        headers["Content-Type"] = "application/json"

    for attempt in range(attempts):
        request = Request(BASE + path, data=body, headers=headers, method=method)
        try:
            with urlopen(request, timeout=8) as response:
                raw = response.read()
                return json.loads(raw) if raw else {}
        except (HTTPError, URLError, TimeoutError) as error:
            if attempt + 1 == attempts:
                raise RuntimeError(f"API 요청 실패: {type(error).__name__}") from error
            time.sleep(1 + attempt)

def main():
    group_path = "/proxies/" + quote(GROUP, safe="")
    group = api("GET", group_path)

    if group.get("type") != "Selector":
        raise RuntimeError("대상 그룹이 Selector가 아니므로 전환하지 않습니다.")

    current = group.get("now")
    members = group.get("all", [])
    candidates = [
        name for name in members
        if name not in {"DIRECT", "REJECT", "PASS"} and name != GROUP
    ]

    if not candidates:
        raise RuntimeError("측정할 프록시 구성원이 없습니다.")

    query = urlencode({"url": TEST_URL, "timeout": TIMEOUT_MS})
    delays = {}

    for name in candidates:
        path = "/proxies/" + quote(name, safe="") + "/delay?" + query
        try:
            result = api("GET", path, attempts=2)
            delay = result.get("delay")
            if isinstance(delay, (int, float)) and delay > 0:
                delays[name] = delay
        except RuntimeError:
            continue

    if not delays:
        print("유효한 측정 결과가 없어 현재 선택을 유지합니다.")
        return

    best = min(delays, key=delays.get)
    current_delay = delays.get(current)

    print("현재:", current, "측정값:", current_delay)
    print("최저 지연 노드:", best, "측정값:", delays[best])

    current_failed = current not in delays
    sufficiently_better = (
        current_delay is not None
        and delays[best] + SWITCH_MARGIN_MS < current_delay
    )

    if best != current and (current_failed or sufficiently_better):
        api("PUT", group_path, {"name": best})
        print("전환 요청 완료:", best)
    else:
        print("전환 조건을 충족하지 않아 현재 노드를 유지합니다.")

if __name__ == "__main__":
    main()

API 키는 코드에 직접 적지 않고 환경 변수에서 읽도록 했습니다. 셸에서 실행하기 전에 현재 터미널 세션에만 키를 설정하면 코드 파일이나 버전 관리 기록에 비밀 값이 남을 가능성을 줄일 수 있습니다. 운영체제별 환경 변수 설정 방법은 다르므로, 공유 PC에서는 셸 기록이나 자동화 작업의 환경 정보에 키가 노출되지 않는지도 확인해야 합니다.

측정 API가 반환하는 지연 시간은 지정한 URL에 대한 연결 결과이지, 모든 서비스의 체감 속도를 보장하는 값은 아닙니다. 테스트 URL이 특정 노드에서 차단되거나 대상 서버가 응답하지 않으면 정상 노드도 실패로 판단될 수 있습니다. 먼저 수동으로 두세 개 후보를 측정하고, 결과가 실제 사용 상황과 대략 일치하는지 확인하세요. 값이 자주 요동친다면 전환 임계값을 높이거나 자동 실행 간격을 늘리는 편이 안정적입니다.

  1. API 접근을 확인합니다. 그룹 조회가 성공하고 type, all, now 값이 예상과 일치하는지 확인합니다.
  2. 후보 목록을 제한합니다. 자동 선택에 포함할 노드를 정하고, DIRECT, 차단 정책, 다른 중첩 그룹은 제외합니다.
  3. 측정만 먼저 실행합니다. 전환 요청을 잠시 비활성화하고 노드별 지연과 실패 빈도를 기록합니다.
  4. 조건을 정한 뒤 낮은 빈도로 실행합니다. 현재 노드 실패 또는 일정 수준 이상의 개선이 있을 때만 전환하고, 매분 반복하는 대신 충분한 간격을 둡니다.
  5. 전환 후 상태를 재확인합니다. 그룹 API의 now 값과 연결 기록을 확인해 요청이 실제 적용되었는지 점검합니다.

장애 재시도와 제어 API 보안

자동 전환 스크립트는 네트워크 오류, API 오류, 빈 측정값을 서로 구분해야 합니다. API 요청이 실패했을 때 곧바로 임의의 노드를 선택하면 일시적인 컨트롤러 응답 지연이 설정 변경으로 이어질 수 있습니다. 위 예시는 조회를 제한적으로 재시도하고, 모든 후보 측정이 실패하면 현재 상태를 유지합니다. 재시도 횟수를 무한정 늘리지 말고, 마지막 실패 원인과 실행 시각을 로그에 남기되 인증 헤더나 구독 정보를 기록하지 마세요.

보안 측면에서는 컨트롤러를 가능하면 127.0.0.1에만 바인딩하고, 강한 secret을 설정하세요. LAN에 공개해야 하는 특별한 이유가 있다면 신뢰할 수 있는 주소 범위와 방화벽 규칙을 제한하고, 공용 네트워크나 인터넷에 포트를 그대로 노출하지 마세요. 제어 API 접근 권한을 얻은 사용자는 상태 조회뿐 아니라 정책 그룹 변경 같은 동작도 할 수 있습니다. 토큰을 스크립트 저장소, 화면 캡처, 로그에 올리지 말고, 노출이 의심되면 즉시 교체하세요.

클라이언트가 코어를 재시작하거나 설정을 다시 불러오면 컨트롤러 포트, 인증 키, 그룹 이름이 바뀔 수 있습니다. 스크립트 실행이 갑자기 실패한다면 자동화 자체를 반복 실행하기 전에 클라이언트의 적용 설정과 시작 로그를 확인하세요. 또한 여러 Clash 또는 Mihomo 인스턴스를 동시에 실행한다면 각 인스턴스의 API 포트와 그룹 이름을 명확히 구분해야 합니다. 잘못된 인스턴스를 대상으로 하면 엉뚱한 그룹을 바꾸거나 조회 결과를 실제 사용 트래픽과 혼동할 수 있습니다.

자주 묻는 질문

모든 프록시 그룹에서 PUT 요청으로 노드를 바꿀 수 있나요?

아닙니다. 사용자가 구성원을 직접 고르는 Selector 그룹이 대표적인 대상입니다. URLTest, Fallback, LoadBalance처럼 자체 선택 로직을 가진 그룹은 동작 방식이 다르므로 무조건 같은 방식으로 변경하려 해서는 안 됩니다. 먼저 그룹의 type을 조회하고, 설치된 코어가 지원하는 API 동작을 확인하세요.

지연 시간이 가장 낮은 노드로 항상 전환하는 것이 좋은가요?

꼭 그렇지는 않습니다. 지연 시간은 측정 URL과 시점에 따라 달라지고, 실제 서비스의 처리량이나 안정성을 모두 나타내지 않습니다. 현재 노드와 차이가 작은 경우에는 유지하고, 큰 개선이 반복해서 확인될 때만 전환하도록 임계값과 쿨다운을 설정하세요.

API 요청은 성공했는데 인터넷 연결이 바뀌지 않는 이유는 무엇인가요?

요청한 그룹이 실제 트래픽 경로에서 사용되지 않거나, 연결이 기존 세션을 계속 재사용할 수 있습니다. 그룹의 현재 선택 값과 Clash 연결 기록의 적용 정책을 함께 확인하세요. 브라우저나 앱에서 새 연결을 만들어 다시 시험하고, 다른 클라이언트 인스턴스의 API에 요청을 보낸 것은 아닌지도 점검합니다.

컨트롤러를 LAN에 열어야 다른 기기에서 스크립트를 실행할 수 있나요?

스크립트를 실행하는 기기에서 Clash가 실행 중인 컴퓨터로 접근해야 하는 상황이라면 네트워크 접근 설정이 필요할 수 있습니다. 하지만 단순히 자동 전환을 위해 인터넷 전체에 포트를 공개할 필요는 없습니다. 가능한 경우 스크립트를 Clash가 실행되는 같은 기기에서 실행하고, 원격 접근이 불가피하다면 방화벽과 주소 범위를 제한하고 강한 인증 키를 사용하세요.

Clash 다운로드