Clash API 자동 전환은 어떤 방식으로 동작하는가
Clash에서 노드를 바꾸는 작업은 화면에서 직접 선택하는 방법만 있는 것이 아닙니다. Mihomo를 비롯한 Clash 계열 코어는 로컬 컨트롤 API를 제공하며, 이 API를 통해 현재 프록시 그룹의 선택 노드를 조회하거나 다른 노드로 변경할 수 있습니다. 여기에 노드 상태를 확인하는 지연 시간 API와 운영체제의 예약 작업을 결합하면, 일정한 간격으로 여러 노드를 검사하고 조건에 맞지 않는 노드를 자동으로 제외하는 구성을 만들 수 있습니다.
다만 “가장 빠른 노드로 무조건 교체”하는 방식은 실제 사용 환경에서 자주 문제를 일으킵니다. 순간적인 네트워크 혼잡 때문에 한 번의 측정값이 튀거나, 노드가 바뀌는 순간 기존 다운로드·WebSocket·로그인 세션이 끊길 수 있기 때문입니다. 따라서 안정적인 자동 전환은 상태 점검, 임계값 판단, 연속 실패 횟수, 쿨다운 시간을 함께 고려해야 합니다. 짧은 테스트 한 번의 결과보다 최근 여러 번의 측정 결과와 현재 연결 수를 보는 편이 안전합니다.
이 글에서는 로컬 API를 이용해 특정 그룹의 노드를 확인하고, 응답 시간이 기준을 넘거나 연결 테스트가 실패했을 때 대체 노드로 전환하는 흐름을 설명합니다. 예시는 Mihomo 호환 API를 기준으로 하지만, Clash Verge Rev나 다른 GUI 클라이언트에서는 API 포트와 비밀번호를 현재 프로필에 맞게 바꿔야 합니다.
127.0.0.1에만 바인딩하며 강한 비밀번호를 사용하세요. 프록시 이용은 거주 지역의 법령과 서비스 약관을 따라야 합니다.
컨트롤 API와 프록시 그룹을 안전하게 준비하기
먼저 Clash 프로필에서 API가 활성화되어 있는지 확인합니다. 클라이언트마다 메뉴 이름은 다르지만 보통 외부 컨트롤러, External Controller, API 포트 또는 REST API라는 이름으로 표시됩니다. 설정 파일을 직접 관리한다면 다음과 같은 형태를 참고할 수 있습니다.
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
proxy-groups:
- name: AUTO-NODE
type: select
proxies:
- Node-A
- Node-B
- Node-C
- DIRECT
external-controller의 주소는 스크립트가 요청을 보낼 위치이며, secret은 HTTP 요청의 Authorization 헤더에 넣습니다. 그룹 이름은 예시와 다를 수 있으므로 API로 그룹 목록을 먼저 조회해 실제 이름을 확인해야 합니다. 구독이 갱신되면 노드 이름이나 그룹 구조가 바뀔 수 있으므로, 스크립트 안에 특정 노드 하나만 영구적으로 고정하기보다 이름 패턴이나 그룹 응답을 확인하는 방어 로직을 두는 것이 좋습니다.
- API는 로컬 주소에 바인딩:
0.0.0.0:9090처럼 모든 인터페이스에 열어 두면 같은 네트워크의 다른 기기가 접근할 수 있습니다. - 긴 비밀번호 사용: 짧은 숫자나 클라이언트 이름을 비밀번호로 쓰지 말고, 운영체제의 안전한 난수 도구로 생성한 값을 사용합니다.
- API 포트 충돌 확인: 다른 프로그램이 같은 포트를 사용하면 클라이언트는 실행되어도 자동화 스크립트가 연결되지 않을 수 있습니다.
- 관리 트래픽은 프록시하지 않기: API 요청이 다시 Clash의 프록시 규칙을 거치면 루프나 불필요한 지연이 생길 수 있으므로 로컬 주소로 직접 요청합니다.
연결 테스트용 URL도 신중하게 골라야 합니다. 너무 큰 파일을 매번 다운로드하면 속도 측정이 아니라 데이터 사용량 측정이 되고, 특정 서비스에 과도한 요청을 보내면 차단될 수 있습니다. 응답 코드와 왕복 시간을 확인할 수 있는 작고 안정적인 HTTPS 엔드포인트를 사용하고, 테스트 간격을 지나치게 짧게 설정하지 않는 것이 바람직합니다.
curl로 API 포트가 응답하는지, 인증 헤더가 올바른지, 실제 그룹 이름이 무엇인지 각각 확인하세요. API 자체가 작동하지 않는 상태에서 스크립트만 수정하면 원인을 찾기 어렵습니다.
노드 상태를 확인하고 자동 전환하는 스크립트 구성
가장 단순한 자동화는 그룹의 노드 목록을 읽고 각 노드의 지연 시간을 요청한 다음, 기준을 통과한 후보 중 가장 빠른 노드를 선택하는 방식입니다. 아래 Python 예시는 구조를 이해하기 위한 출발점입니다. API 포트, 비밀번호, 그룹 이름, 테스트 URL은 자신의 환경에 맞게 수정해야 합니다.
import os
import time
import requests
API = os.getenv("CLASH_API", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = "AUTO-NODE"
TEST_URL = "https://www.gstatic.com/generate_204"
headers = {"Authorization": f"Bearer {SECRET}"}
def get_group():
response = requests.get(
f"{API}/proxies/{GROUP}",
headers=headers,
timeout=5
)
response.raise_for_status()
return response.json()
def measure(node):
name = requests.utils.quote(node, safe="")
response = requests.get(
f"{API}/proxies/{name}/delay",
params={"url": TEST_URL, "timeout": 3000},
headers=headers,
timeout=5
)
if response.ok:
return response.json().get("delay")
return None
group = get_group()
candidates = group.get("all", [])
results = []
for node in candidates:
if node in {"DIRECT", "REJECT"}:
continue
delay = measure(node)
if delay is not None and delay <= 800:
results.append((delay, node))
if results:
results.sort()
selected = results[0][1]
current = group.get("now")
if current != selected:
requests.put(
f"{API}/proxies/{requests.utils.quote(GROUP, safe='')}",
json={"name": selected},
headers=headers,
timeout=5
)
print(f"switched: {current} -> {selected}")
else:
print("no healthy node found")
이 코드는 기본 흐름만 보여 줍니다. 실제 운영에서는 몇 가지 보강이 필요합니다. 첫째, 노드 이름에 한글·공백·특수문자가 포함될 수 있으므로 URL 인코딩을 반드시 적용해야 합니다. 둘째, 측정 실패를 곧바로 장애로 판단하지 말고 최소 두세 번 재시도하거나 최근 결과를 저장해야 합니다. 셋째, 현재 노드가 기준을 조금 넘었다고 즉시 바꾸면 노드가 계속 교체되는 플래핑이 발생할 수 있으므로, 현재 노드에는 다른 후보보다 일정 수준 이상 느릴 때만 전환하는 여유 폭을 두는 것이 좋습니다.
임계값과 안정화 조건을 어떻게 정할까
예를 들어 정상 기준을 500ms로 정하고 현재 노드가 650ms가 되었다고 해서 바로 바꿀 필요는 없습니다. 무선 네트워크의 순간 지연, DNS 재시도, 서버 측 일시 부하로 충분히 발생할 수 있는 값이기 때문입니다. 다음처럼 조건을 나누면 불필요한 전환을 줄일 수 있습니다.
- 경고 구간: 500~800ms가 한 번 관측되면 기록만 남기고 현재 노드를 유지합니다.
- 전환 구간: 800ms 초과 또는 연속 테스트 실패가 두세 번 이어질 때 대체 후보를 검사합니다.
- 히스테리시스: 새 노드가 현재 노드보다 100ms 이상 빠를 때만 교체합니다.
- 쿨다운: 한 번 전환한 뒤 5~15분 동안은 다시 자동 전환하지 않습니다.
- 세션 보호: 다운로드나 실시간 연결이 많은 시간에는 전환을 늦추거나 수동 확인을 요구합니다.
노드를 무작정 가장 낮은 지연 순서로 선택하는 것도 주의해야 합니다. 지연이 낮아도 패킷 손실률이 높거나 대역폭이 부족하면 실제 웹 페이지와 영상 재생은 더 느릴 수 있습니다. 가능하다면 응답 시간, 연속 성공률, 최근 전환 횟수를 함께 점수화하고, 특정 노드가 반복해서 실패하면 일정 시간 동안 후보 목록에서 제외하세요.
예약 실행, 로그 확인과 장애 분석
스크립트를 한 번 실행해 성공했다고 자동화가 끝나는 것은 아닙니다. Windows에서는 작업 스케줄러에 Python 실행 작업을 등록하고, macOS와 Linux에서는 cron 또는 사용자 서비스로 일정한 주기를 설정할 수 있습니다. 처음에는 10~15분 간격으로 시작한 뒤, 로그와 데이터 사용량을 확인하면서 조정하는 편이 안전합니다.
# Linux/macOS cron example: run every 15 minutes
*/15 * * * * /usr/bin/python3 /home/user/bin/clash_switch.py >> /home/user/logs/clash-switch.log 2>&1
예약 작업의 실행 환경은 터미널에서 직접 실행할 때와 다를 수 있습니다. 특히 PATH, Python 가상 환경, 환경 변수에 저장한 API 비밀번호, 현재 작업 디렉터리가 달라지는 경우가 많습니다. 비밀번호를 스크립트에 평문으로 적기보다 운영체제 환경 변수나 권한이 제한된 별도 설정 파일에 보관하고, 로그에는 토큰과 전체 요청 헤더가 절대 출력되지 않도록 해야 합니다.
장애가 발생하면 다음 순서로 범위를 좁히세요. 먼저 Clash 클라이언트가 실행 중이고 API 포트가 열려 있는지 확인합니다. 그다음 401 응답이면 비밀번호나 인증 형식을, 404이면 그룹명·노드명·API 경로를 확인합니다. timeout이 반복되면 API 자체의 응답 지연인지 특정 프록시의 측정 실패인지 분리해야 합니다. API 그룹 조회는 빠른데 delay 요청만 느리다면 노드 또는 테스트 URL 문제일 가능성이 높습니다.
- 현재 노드가 바뀌지 않음: 그룹 타입이
select인지, PUT 요청의 그룹명이 실제 이름과 같은지 확인합니다. - 노드 이름을 찾지 못함: 구독 갱신으로 이름이 변경되었는지
/proxies/GROUP응답의all배열을 확인합니다. - 계속 노드가 교체됨: 측정 간격을 늘리고 히스테리시스와 쿨다운을 추가합니다.
- 스크립트는 성공하지만 인터넷이 끊김: 그룹의 상위 그룹, 규칙 순서, DNS, TUN 모드가 새 노드와 호환되는지 확인합니다.
- 측정값과 체감 속도가 다름: 단일 HTTPS 지연만 보지 말고 패킷 손실, 실제 서비스 연결, 시간대별 혼잡도도 함께 기록합니다.
일부 클라이언트는 GUI에서 API 설정을 관리하므로 프로필 파일을 직접 덮어쓰면 다음 구독 업데이트 때 설정이 사라질 수 있습니다. Clash Verge Rev나 Mihomo 기반 클라이언트를 사용한다면 현재 활성 프로필, 런타임 설정, 구독 업데이트 후의 병합 결과를 각각 확인하세요. 자동화의 목적은 모든 결정을 대신하는 것이 아니라, 반복적인 상태 확인을 줄이고 사용자가 검토해야 할 상황을 명확히 알려 주는 데 있습니다.
다른 범용 VPN 앱은 단순 연결 버튼과 전체 회선 전환에는 편리하지만, 그룹별 API 제어·노드별 지연 확인·규칙과 로그를 함께 보는 작업에서는 설정 선택지가 제한되거나 원인 분석 과정이 불투명할 수 있습니다. ClashSky는 로컬 컨트롤 API와 Mihomo 기반 구성을 활용해 노드 자동 전환, 상태 점검, 예약 스크립트 연동을 한 흐름으로 관리하기 쉽고, GUI에서 현재 정책과 연결 상태를 확인하기도 편합니다. API 자동화를 처음 시도한다면 먼저 안전한 로컬 설정으로 작은 그룹을 시험해 보는 것을 권하며, 필요한 클라이언트를 ClashSky 다운로드에서 무료로 확인해 보세요.