설정 Clash 입문 VPN 비교 프록시 초보 가이드

Clash API로 노드 자동 전환하는 고급 스크립트 설정법

2026년 8월 24일 업데이트: 2026년 8월 24일 약 10분 소요

서론: 수동 노드 전환의 한계

개발 환경에서 GitHub, Docker Hub, 패키지 저장소 또는 AI 도구를 자주 사용한다면 네트워크 품질이 작업 속도에 직접적인 영향을 줍니다. 페이지가 열리지 않거나 git clone이 중단되고, Docker 이미지 다운로드가 멈출 때마다 Clash 화면을 열어 노드를 하나씩 바꾸는 방식은 시간이 많이 걸릴 뿐 아니라 동일한 문제가 반복될 가능성도 높습니다.

노드 이름에 국가나 통신사 정보가 표시되어 있어도 실제 품질은 시간대, 사용자 수, 서버 상태, 목적지와의 경로에 따라 계속 달라집니다. 따라서 “일본 노드가 항상 빠르다” 또는 “미국 노드가 AI 서비스에 가장 적합하다”라고 고정하는 것보다, 현재 시점의 지연 시간(Latency)과 연결 성공률을 측정해 자동으로 판단하는 편이 더 합리적입니다.

Clash Verge Rev, Clash for Windows, Mihomo 기반 클라이언트는 로컬의 외부 컨트롤러(External Controller) API를 제공합니다. 이 API를 사용하면 현재 프록시 그룹을 조회하고, 노드 상태를 확인하며, 조건에 맞는 노드를 선택해 그룹을 변경할 수 있습니다. 이 글에서는 Python 스크립트를 기준으로 안전한 API 연결, 노드 평가, 자동 전환, 운영 시 주의할 점까지 단계별로 구성합니다.

가이드 목표

정해진 국가를 무조건 선택하는 것이 아니라, 여러 노드의 응답 상태를 주기적으로 검사하고 안정성과 속도를 함께 평가해 프록시 그룹을 자동으로 전환하는 구조를 완성합니다.

1Clash API 활성화와 사전 준비

자동화 스크립트를 실행하기 전에 Clash가 API 요청을 받을 수 있도록 설정해야 합니다. 대부분의 Mihomo 기반 클라이언트에서는 설정 파일의 external-controller 항목으로 API 주소와 포트를 지정합니다. 포트는 예시로 9090을 사용하지만, 실제 환경에서는 클라이언트에 표시된 값을 확인해야 합니다.

# Clash 또는 Mihomo 설정 예시 external-controller: 127.0.0.1:9090 secret: "change-this-to-a-long-random-token"

secret은 API 인증에 사용하는 토큰입니다. 외부 컨트롤러를 인터넷에 직접 노출하면 다른 사람이 노드 전환, 설정 조회, 트래픽 관련 정보를 조작할 수 있으므로 0.0.0.0:9090처럼 모든 인터페이스에 바인딩하는 설정은 피하는 것이 좋습니다. 원격 장치에서 제어해야 한다면 방화벽과 별도의 인증 터널을 함께 사용하고, 공유 네트워크에서는 API 포트를 공개하지 마세요.

API 연결 확인

Clash를 다시 시작한 뒤 터미널에서 다음 요청을 실행합니다. 토큰을 설정했다면 Authorization 헤더를 반드시 포함해야 합니다.

curl -H "Authorization: Bearer change-this-to-a-long-random-token" \ http://127.0.0.1:9090/version

정상적으로 연결되면 코어의 버전 정보가 JSON 형식으로 반환됩니다. 연결 거부가 발생하면 포트, 코어 실행 여부, 방화벽을 순서대로 확인하세요.

스크립트가 제어해야 하는 그룹 이름도 미리 확인해야 합니다. API의 /proxies 엔드포인트는 전체 프록시와 그룹 정보를 반환합니다. 일반적으로 실제 노드를 보유한 그룹은 select, url-test, fallback 등의 형태로 표시되지만, 구독 설정에 따라 이름은 달라질 수 있습니다.

보안 주의

API 토큰을 GitHub 저장소, 셸 기록, 공개 로그에 남기지 마세요. 환경 변수나 별도의 로컬 설정 파일에 저장하고, 필요하지 않다면 외부 컨트롤러의 원격 접근 자체를 차단하는 것이 안전합니다.

2지연 시간과 성공률로 노드 평가하기

노드 자동 선택에서 가장 단순한 기준은 측정 결과가 가장 작은 노드를 고르는 것입니다. 그러나 한 번의 측정값만 사용하면 순간적인 네트워크 변동에 쉽게 영향을 받습니다. 예를 들어 응답 시간이 80ms인 노드가 실제로는 요청 5회 중 2회만 성공한다면, 150ms이지만 매번 응답하는 노드보다 개발 작업에 적합하지 않습니다.

실무에서는 다음과 같은 점수 구조를 사용할 수 있습니다. 각 노드에 테스트 URL을 여러 번 요청하고, 성공한 횟수와 평균 지연 시간을 수집합니다.

  • 성공률: 전체 테스트 중 정상 응답한 비율입니다. 성공률이 80% 미만인 노드는 빠르더라도 후보에서 제외합니다.
  • 평균 지연: 성공한 요청의 평균 응답 시간입니다. 지나치게 큰 값은 연결이 불안정하다는 신호일 수 있습니다.
  • 최고 지연: 평균은 낮지만 특정 요청만 오래 걸리는 노드를 식별하는 데 사용합니다.
  • 전환 여유 시간: 현재 노드보다 약간 빠른 노드가 발견될 때마다 바꾸면 전환이 반복되므로 최소 개선 폭을 둡니다.

아래 예시는 API의 GET /proxies/{name}/delay 요청을 이용해 노드별 지연을 측정하는 기본 형태입니다. URL 인코딩이 필요한 노드 이름이 있을 수 있으므로 Python의 quote를 사용합니다.

import os import time import requests from urllib.parse import quote API = os.getenv("CLASH_API", "http://127.0.0.1:9090") TOKEN = os.environ["CLASH_SECRET"] GROUP = os.getenv("CLASH_GROUP", "PROXY") TEST_URL = "https://www.gstatic.com/generate_204" session = requests.Session() session.headers.update({"Authorization": f"Bearer {TOKEN}"}) def check_delay(node, timeout=5): endpoint = f"{API}/proxies/{quote(node, safe='')}/delay" params = {"url": TEST_URL, "timeout": timeout * 1000} try: result = session.get(endpoint, params=params, timeout=timeout + 2) result.raise_for_status() value = result.json().get("delay") return int(value) if value else None except (requests.RequestException, ValueError, TypeError): return None

이 함수는 각 노드에 대해 한 번만 검사합니다. 더 안정적인 결과를 얻으려면 같은 노드를 3회 검사하고 중앙값을 사용하는 방법이 좋습니다. 평균은 일시적인 지연에 민감하지만 중앙값은 한 번의 이상값을 어느 정도 무시할 수 있습니다. 또한 테스트 URL은 실제로 사용할 서비스와 가까운 특성을 가져야 합니다. GitHub 작업을 주로 한다면 GitHub 관련 도메인을, Docker 이미지를 주로 받는다면 Docker Hub 또는 레지스트리에 가까운 주소를 별도 기준으로 사용할 수 있습니다.

3가장 안정적인 노드로 프록시 그룹 자동 전환

노드 목록은 먼저 /proxies에서 읽고, 지정한 그룹의 all 배열을 순회하면 됩니다. 이후 점수가 가장 좋은 노드를 찾은 다음, 현재 선택된 노드와 비교해 충분한 개선이 있을 때만 PUT /proxies/{group}으로 변경합니다. 수동 선택 그룹인 select는 이 방식으로 전환할 수 있지만, 이미 자동 측정 기능을 제공하는 url-test나 fallback 그룹은 별도의 정책을 먼저 확인해야 합니다.

def get_group(): data = session.get(f"{API}/proxies", timeout=5).json() return data["proxies"][GROUP] def switch_node(node): endpoint = f"{API}/proxies/{quote(GROUP, safe='')}" response = session.put(endpoint, json={"name": node}, timeout=5) response.raise_for_status() def choose_node(): group = get_group() candidates = group.get("all", []) current = group.get("now") results = [] for node in candidates: if node in ("DIRECT", "REJECT"): continue samples = [] for _ in range(3): delay = check_delay(node) if delay is not None: samples.append(delay) time.sleep(0.2) if len(samples) >= 2: samples.sort() median = samples[len(samples) // 2] results.append((median, node)) if not results: raise RuntimeError("사용 가능한 노드가 없습니다.") results.sort(key=lambda item: item[0]) best_delay, best_node = results[0] current_delay = check_delay(current) if current else None minimum_gain = 30 if current != best_node and ( current_delay is None or best_delay + minimum_gain < current_delay ): switch_node(best_node) return current, best_node, best_delay return current, current, current_delay

위 구조의 핵심은 히스테리시스입니다. 현재 노드보다 단지 5ms 빠르다는 이유로 전환하지 않고, 최소 30ms 이상의 개선이 있을 때만 바꾸도록 했습니다. 이 여유값은 회선 특성에 맞춰 조절해야 합니다. 이동이 잦은 모바일 네트워크에서는 50~100ms로 높이고, 안정적인 사무실 회선에서는 20~30ms 정도로 낮출 수 있습니다.

실패 기록과 복구 처리

운영용 스크립트라면 전환 결과를 기록해야 합니다. 시간, 기존 노드, 새 노드, 측정값, 실패 원인을 로그에 남기면 특정 노드가 반복적으로 탈락하는지 확인할 수 있습니다. 단, 토큰이나 전체 설정 JSON을 로그에 저장해서는 안 됩니다. 모든 노드가 실패했을 때는 무한히 전환하지 말고, 현재 노드를 유지한 채 일정 시간 후 재시도하는 것이 좋습니다.

운영 팁

처음에는 자동 전환 대신 후보와 점수만 출력하는 관찰 모드로 실행하세요. 결과가 신뢰할 만하다고 판단된 후 API 변경 요청을 활성화하면 예기치 않은 연결 끊김을 줄일 수 있습니다.

4실행 주기, 규칙 분리와 문제 해결

스크립트를 너무 자주 실행하면 모든 노드에 반복적인 테스트 요청이 발생하고, 오히려 구독 서비스나 대상 서버에서 비정상 트래픽으로 판단할 수 있습니다. 일반적인 데스크톱 사용 환경에서는 5~15분 간격이 적당합니다. 중요한 작업을 시작하기 직전에 한 번 실행하는 방식도 효율적입니다.

Linux와 macOS에서는 cron 또는 systemd timer를 사용할 수 있고, Windows에서는 작업 스케줄러에 Python 실행 작업을 등록할 수 있습니다. 환경 변수는 스케줄러가 읽지 못하는 경우가 있으므로 실행 파일 내부에 토큰을 직접 작성하기보다 제한된 권한의 환경 파일이나 운영체제 자격 증명 저장소를 이용하세요.

# Linux cron 예시: 10분마다 실행 */10 * * * * /usr/bin/python3 /home/user/bin/clash-switch.py >> /home/user/logs/clash-switch.log 2>&1

서비스별로 요구하는 노드가 다르면 하나의 전역 그룹을 무작정 전환하지 않는 것이 좋습니다. Clash의 rules에서 GitHub, Docker Hub, AI 도구를 별도 그룹에 연결하고, 각 그룹에 맞는 테스트 URL과 노드 지역을 사용하면 업무 트래픽 간섭을 줄일 수 있습니다. 예를 들어 국내 서비스는 DIRECT, GitHub와 Docker Hub는 국제 회선 그룹, 특정 AI 도구는 별도의 안정적인 그룹으로 분리할 수 있습니다.

  • API 401 오류: 토큰 값과 Bearer 표기, 공백 및 따옴표를 확인합니다.
  • API 404 오류: 그룹 또는 노드 이름을 URL에 넣을 때 인코딩이 되었는지 확인합니다.
  • 지연 측정 실패: 테스트 URL이 차단되었거나 노드가 해당 프로토콜을 지원하지 않을 수 있으므로 다른 HTTPS URL로 비교합니다.
  • 전환 후에도 연결이 안 됨: DNS 캐시, 기존 TCP 연결, TUN 모드의 상태 때문에 즉시 결과가 반영되지 않을 수 있습니다. 짧게 기다린 뒤 새 요청으로 재확인합니다.
  • 노드가 계속 바뀜: 측정 횟수와 최소 개선 폭을 높이고, 한 번 전환한 뒤 일정 시간 동안 잠그는 쿨다운을 추가합니다.

자동화는 “가장 빠른 노드 하나”를 영구적으로 찾는 기능이 아닙니다. 네트워크 상태는 계속 변하므로, 측정 기준과 전환 조건을 기록하고 주기적으로 조정해야 합니다. API 접근을 로컬로 제한하고, 실패 시 현재 설정을 보존하며, 자동 전환을 언제든 중지할 수 있는 수동 선택 경로를 남겨 두면 훨씬 안전한 운영이 가능합니다.

최종 점검 목록

외부 컨트롤러가 로컬에서만 열려 있는지, 토큰이 안전하게 보관되는지, 테스트 URL이 실제 업무와 맞는지, 최소 개선 폭과 쿨다운이 설정되어 있는지 확인한 뒤 자동 전환을 시작하세요.

이 구조를 적용하면 GitHub 작업이나 Docker 이미지 다운로드 중 네트워크가 느려질 때마다 직접 메뉴를 찾을 필요가 줄어듭니다. Clash API는 단순히 현재 노드를 바꾸는 기능을 넘어, 측정 결과와 운영 정책을 결합해 네트워크 경로를 지속적으로 관리할 수 있는 확장 지점입니다.

Clash 무료 다운로드 — 원활한 인터넷 경험을 시작하세요 →