Clash API로 노드 자동 전환을 구성하는 이유

프록시 그룹을 수동으로 바꾸는 방식은 짧은 웹 검색이나 한 번의 다운로드에는 충분할 수 있지만, AI 서비스 호출, Git 저장소 동기화, 원격 개발 세션처럼 연결을 오래 유지해야 하는 작업에서는 한계가 분명합니다. 사용 중인 노드의 지연 시간이 갑자기 높아지거나 TLS 연결이 반복해서 실패하면, 사용자는 매번 Clash 화면을 열어 다른 노드를 선택해야 합니다. 특히 작업 중인 터미널, IDE, 브라우저 탭이 여러 개라면 어느 연결이 실제로 끊겼는지 확인하는 데에도 시간이 걸립니다.

Mihomo 기반 Clash 클라이언트는 로컬 외부 컨트롤러(External Controller)를 통해 현재 프록시 그룹과 노드 상태를 조회하고 변경할 수 있습니다. Clash Verge Rev, Mihomo Party, 일부 Clash for Android 계열 클라이언트에서는 API 주소와 비밀 토큰을 확인한 뒤 HTTP 요청으로 그룹 선택, 노드 지연 측정, 프로필 상태 확인을 수행할 수 있습니다. 이 기능을 이용하면 단순히 “가장 빠른 노드 하나”를 고르는 것이 아니라, 특정 도메인 그룹에 속한 노드만 검사하고 기준에 맞을 때만 전환하는 정책을 만들 수 있습니다.

이 글에서는 Clash API로 노드를 측정하고 프록시 그룹을 자동 변경하는 실전 구조를 설명합니다. YAML의 그룹 설계, API 인증, Python과 셸 스크립트 예시, 예약 실행, 전환 후 검증, 장애 로그 해석까지 한 흐름으로 다룹니다. 목적은 무조건 우회 트래픽을 늘리는 것이 아니라, 자신이 관리하는 합법적인 네트워크 환경에서 연결 품질을 일정하게 유지하고 수동 작업을 줄이는 것입니다.

⚠️
보안 및 준수: 외부 컨트롤러 포트는 인터넷에 직접 공개하지 마세요. API 비밀 토큰은 비밀번호처럼 보관하고, 프록시 사용은 거주 지역 법령·회사 보안 정책·각 서비스의 이용약관을 따라야 합니다.

외부 컨트롤러와 프록시 그룹의 작동 방식

Clash API 자동화는 크게 세 요소로 나뉩니다. 첫 번째는 연결 상태를 제공하는 외부 컨트롤러입니다. 두 번째는 실제로 노드를 묶어 둔 프록시 그룹이고, 세 번째는 일정한 간격으로 API를 호출하는 자동화 스크립트입니다. 스크립트는 그룹에 포함된 노드 목록을 읽고, 지정한 URL에 대한 지연 시간을 측정한 뒤, 조건을 만족하는 노드를 그룹의 현재 선택값으로 지정합니다.

  • 외부 컨트롤러 주소: 보통 127.0.0.1:9090 또는 클라이언트가 표시한 로컬 주소를 사용합니다. 실제 포트는 설정 화면이나 실행 로그에서 확인해야 합니다.
  • API 비밀 토큰: Authorization: Bearer 토큰값 형식의 HTTP 헤더로 전달합니다. 토큰이 비어 있는 설치도 있지만, 자동화 환경에서는 반드시 인증을 켜는 편이 안전합니다.
  • 프록시 그룹: select, url-test, fallback 등 목적에 맞는 유형을 사용합니다. API 스크립트가 특정 그룹을 조작하려면 이름이 정확히 일치해야 합니다.
  • 테스트 URL: 모든 노드가 접근할 수 있고 응답이 비교적 일정한 HTTPS 주소를 선택합니다. 큰 파일 다운로드나 변동이 심한 서비스 주소는 단순 지연 측정용으로 적합하지 않습니다.

url-test 그룹은 클라이언트 코어가 정해진 간격으로 노드를 검사하고 가장 빠른 후보를 선택하는 데 유용합니다. 반면 API 자동화는 측정 대상과 전환 조건을 직접 통제할 수 있다는 장점이 있습니다. 예를 들어 일반 웹용 그룹은 300ms 이하의 노드 중 가장 빠른 대상을 선택하고, 원격 개발용 그룹은 지연보다 연속 성공 횟수와 안정성을 우선할 수 있습니다. 두 그룹을 같은 기준으로 처리하면 개발 세션 중 노드가 자주 바뀌는 문제가 생기므로 용도별 정책을 분리하는 것이 좋습니다.

proxy-groups:
  - name: WORK-AUTO
    type: select
    proxies:
      - node-a
      - node-b
      - node-c
      - DIRECT

  - name: AI-AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - node-a
      - node-b
      - node-c

위 설정에서 그룹 이름은 예시일 뿐이며 실제 프로필의 노드 이름과 일치해야 합니다. 구독을 갱신하면 노드 이름에 지역명이나 숫자가 추가될 수 있으므로, 스크립트가 고정된 이름만 찾도록 작성하면 갱신 직후 아무 대상도 찾지 못할 수 있습니다. 운영 환경에서는 고정된 프록시 그룹을 만들고, 그 안에 구독에서 들어온 노드를 연결하거나 이름 규칙을 확인하는 절차를 함께 두는 편이 안정적입니다.

API 자동 전환을 단계별로 구성하기

자동화는 한 번에 모든 기능을 넣기보다, 조회와 측정을 먼저 검증한 다음 전환 명령을 추가하는 순서가 안전합니다. 아래 단계는 Clash Verge Rev 또는 Mihomo 계열 클라이언트에서 공통으로 적용할 수 있지만, 메뉴 이름과 API가 열리는 방식은 버전에 따라 다를 수 있습니다.

  1. 외부 컨트롤러와 토큰 확인

    클라이언트 설정에서 외부 컨트롤러 포트와 API 비밀값을 확인합니다. 컨트롤러가 127.0.0.1에만 바인딩되어 있는지 먼저 살펴보세요. 같은 컴퓨터에서만 자동화할 계획이라면 LAN 전체에 포트를 열 필요가 없습니다. 주소가 0.0.0.0으로 되어 있다면 방화벽 규칙과 접근 가능한 네트워크 범위를 반드시 검토해야 합니다.

  2. 그룹 목록과 현재 선택값 조회

    먼저 읽기 요청으로 그룹 목록이 반환되는지 확인합니다. API 주소는 설치 환경에 따라 다르므로 아래 명령에서 포트와 토큰을 자신의 값으로 바꿔야 합니다.

    curl -H "Authorization: Bearer YOUR_SECRET" \
      http://127.0.0.1:9090/proxies

    응답 JSON에서 WORK-AUTO 같은 그룹을 찾고, all 배열에 실제 노드가 들어 있는지 확인합니다. 이 단계에서 401이 나오면 토큰이 틀렸거나 헤더 형식이 잘못된 것이고, 연결 거부가 나오면 포트·컨트롤러 실행 상태·방화벽을 확인해야 합니다.

  3. 노드별 지연 시간 측정

    각 노드의 이름을 URL 인코딩해 지연 시간 API를 호출합니다. 노드 이름에 공백, 괄호, 이모지가 포함되어 있을 수 있으므로 문자열을 직접 URL에 붙이지 말고 반드시 인코딩해야 합니다.

    curl -H "Authorization: Bearer YOUR_SECRET" \
      "http://127.0.0.1:9090/proxies/node-a/delay?url=https%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"

    응답의 delay 값만 보고 바로 전환하지 않는 것이 중요합니다. 한 번의 측정은 순간적인 큐 지연이나 DNS 상태를 반영할 수 있습니다. 같은 노드를 두세 번 확인하거나, 최근 성공 횟수와 실패 횟수를 함께 기록하면 잘못된 전환을 줄일 수 있습니다.

  4. 그룹 변경 요청 보내기

    선택 그룹의 현재 프록시를 변경할 때는 그룹 이름과 선택할 노드 이름을 JSON으로 전달합니다.

    curl -X PUT \
      -H "Authorization: Bearer YOUR_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"name":"node-b"}' \
      "http://127.0.0.1:9090/proxies/WORK-AUTO"

    정상 응답이 없거나 404가 나온다면 그룹이 select 유형인지, URL 인코딩된 그룹 이름이 올바른지, 노드가 해당 그룹에 실제로 포함되어 있는지 확인하세요. 일부 자동 선택 그룹은 사용자가 직접 선택하는 그룹과 동작이 다르므로, API로 조작할 그룹은 명확한 목적을 가진 select 그룹으로 시작하는 것이 좋습니다.

  5. 전환 후 실제 트래픽 검증

    API가 200 응답을 반환했다고 해서 모든 연결이 새 노드로 이동한 것은 아닙니다. 기존 TCP 세션은 이전 출구를 계속 사용할 수 있고, DNS 캐시나 애플리케이션 연결 풀도 남아 있을 수 있습니다. Clash 연결 화면에서 새 요청이 의도한 그룹을 통과하는지 확인하고, 필요하면 테스트용 HTTP 요청을 새로 만들어 규칙 적중 그룹과 노드 이름을 검증합니다.

ℹ️
운영 팁: 자동 전환 조건에 최소 지연 시간만 넣지 말고 최대 허용 지연, 연속 실패 횟수, 전환 후 쿨다운 시간을 함께 두세요. 쿨다운이 없으면 경계값 근처에서 노드가 계속 바뀌는 플래핑이 발생합니다.

스크립트 설계와 장애 분석 절차

간단한 Python 스크립트는 API 응답을 읽고 노드를 정렬한 다음, 현재 노드와 새 후보가 다를 때만 전환하도록 만들 수 있습니다. 아래 예시는 구조를 보여 주기 위한 기본형입니다. 실제 운영에서는 토큰을 소스 코드에 직접 쓰지 말고 환경 변수나 운영체제의 비밀 저장소에서 읽으세요.

import os
import time
import requests

BASE = os.getenv("CLASH_API", "http://127.0.0.1:9090")
TOKEN = os.environ["CLASH_SECRET"]
GROUP = "WORK-AUTO"
TEST_URL = "https://www.gstatic.com/generate_204"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

data = requests.get(f"{BASE}/proxies", headers=HEADERS, timeout=5).json()
group = data["proxies"][GROUP]
candidates = [name for name in group["all"] if name != "DIRECT"]

results = []
for name in candidates:
    try:
        response = requests.get(
            f"{BASE}/proxies/{requests.utils.quote(name, safe='')}/delay",
            params={"url": TEST_URL, "timeout": 5000},
            headers=HEADERS,
            timeout=7,
        )
        delay = response.json().get("delay")
        if delay:
            results.append((delay, name))
    except requests.RequestException:
        continue

if results:
    results.sort()
    best_delay, best_name = results[0]
    if best_delay <= 350 and best_name != group.get("now"):
        requests.put(
            f"{BASE}/proxies/{requests.utils.quote(GROUP, safe='')}",
            json={"name": best_name},
            headers=HEADERS,
            timeout=5,
        )
        print(f"switched to {best_name}: {best_delay} ms")
else:
    print("no healthy candidate")

이 예시는 가장 빠른 노드를 고르지만, 실전에서는 몇 가지 보강이 필요합니다. 첫째, 응답 코드와 JSON 형식을 함께 검증해야 합니다. 둘째, DIRECT, 다른 정책 그룹, 사용하지 않을 노드를 후보에서 제외해야 합니다. 셋째, 최저 지연이 80ms인 노드가 30초마다 실패한다면 140ms이지만 안정적인 노드보다 나쁜 선택일 수 있습니다. 따라서 최근 측정 결과를 파일이나 작은 데이터베이스에 보관해 지연 점수와 실패율을 함께 계산하는 방식이 더 적합합니다.

예약 실행은 운영체제에 맞춰 구성합니다. Linux나 macOS에서는 cron 또는 systemd timer로 5~10분마다 실행하고, Windows에서는 작업 스케줄러에 Python 실행 작업을 등록할 수 있습니다. 단, 너무 짧은 간격은 API와 노드에 불필요한 측정 요청을 보내며, 측정 순간마다 그룹이 변경되어 장시간 세션을 끊을 수 있습니다. AI 작업이나 원격 개발 중에는 자동 전환을 잠시 중지하거나, 현재 세션이 끝난 뒤에만 변경하도록 “쿨다운” 플래그를 두는 것이 좋습니다.

전환이 실패할 때 확인할 로그 순서

  • API 연결 실패: 컨트롤러 프로세스가 실행 중인지, 포트가 맞는지, 로컬 방화벽이 차단하지 않는지 확인합니다.
  • 401 Unauthorized: 토큰 값, Bearer 접두사, 공백과 줄바꿈이 포함되지 않았는지 점검합니다.
  • 404 Not Found: 그룹 또는 노드 이름의 대소문자, 특수문자, URL 인코딩 상태를 확인합니다.
  • 지연 값이 계속 비어 있음: 테스트 URL이 해당 노드에서 응답하지 않거나, DNS·TLS·UDP 정책이 측정을 방해할 수 있습니다. 다른 HTTPS 테스트 주소와 비교하세요.
  • 전환 후에도 연결이 끊김: 기존 세션의 출구가 즉시 바뀌지 않는 정상적인 동작일 수 있습니다. 새 연결과 기존 연결을 분리해 확인합니다.
  • 노드가 계속 왕복함: 측정 간격이 너무 짧거나 허용 오차가 지나치게 작습니다. 최소 유지 시간과 전환 쿨다운을 추가하세요.

AI 서비스, Git 저장소, 원격 개발 도구를 하나의 그룹에 모두 넣는 것도 피하는 편이 좋습니다. Git의 작은 API 요청에는 짧은 지연이 중요할 수 있지만, 원격 개발의 장시간 SSH·HTTPS 세션은 안정적인 출구 유지가 더 중요합니다. AI-AUTO, DEV-STABLE, GENERAL-AUTO처럼 목적별 그룹을 나누고, 각 그룹에 다른 테스트 URL과 임계값을 적용하면 장애 원인을 훨씬 빨리 좁힐 수 있습니다.

Clash API 자동 전환 FAQ

외부 컨트롤러 포트를 인터넷에 열어도 되나요?

권장하지 않습니다. 외부 컨트롤러는 프록시 그룹 변경과 연결 정보 조회 같은 강한 권한을 제공하므로, 인터넷에 노출되면 토큰이 유출되지 않았더라도 공격 표면이 커집니다. 자동화 스크립트와 Clash가 같은 컴퓨터에서 실행된다면 127.0.0.1 바인딩을 사용하세요. 다른 장치에서 접근해야 한다면 방화벽으로 특정 IP만 허용하고, 강한 토큰과 암호화된 관리 경로를 함께 사용해야 합니다.

url-test와 API 스크립트를 함께 써도 되나요?

가능하지만 같은 그룹을 동시에 조작하면 선택값이 서로 덮어써질 수 있습니다. 코어의 url-test는 일반적인 자동 선택에 맡기고, API 스크립트는 안정성 검증이 필요한 별도 select 그룹을 관리하는 방식이 안전합니다. 한 그룹을 꼭 공유해야 한다면 검사 주기, 허용 오차, API 쿨다운을 조정해 잦은 충돌을 피하세요.

지연 시간이 가장 낮은 노드가 항상 가장 좋은가요?

아닙니다. 지연 시간은 측정 URL과 측정 시점에 따라 달라지며, 짧은 요청에 대한 결과만 보여 줍니다. 장시간 개발 세션에서는 패킷 손실, TLS 재협상, 연결 유지 시간, 실제 서비스까지의 경로가 더 중요할 수 있습니다. 최소 세 번 이상 측정하고 실패율과 장시간 연결 결과를 함께 평가하는 것이 좋습니다.

모든 Clash 클라이언트에서 같은 API를 사용할 수 있나요?

Clash 계열이라도 코어와 클라이언트 버전에 따라 엔드포인트, 컨트롤러 설정 위치, 지원 필드가 다를 수 있습니다. 특히 구형 코어와 Mihomo 코어는 프록시 유형이나 상태 응답 형식이 다르게 보일 수 있습니다. 먼저 클라이언트가 제공하는 API 문서와 실제 /proxies 응답을 확인한 뒤 스크립트를 맞추세요.

일부 범용 VPN 앱은 노드 자동 선택 기능은 제공하지만, 그룹별 규칙·API 조회·지연 임계값·전환 로그를 세밀하게 조정하기 어렵고 원격 개발 세션이 끊겼을 때 원인을 추적할 정보도 부족합니다. ClashSky는 Mihomo 기반 환경에서 그룹과 규칙을 한눈에 관리하고, 외부 컨트롤러와 연결 상태를 확인하면서 자동화 스크립트를 단계적으로 적용하기 쉽다는 장점이 있습니다. 복잡한 설정 파일을 직접 다루는 부담을 줄이면서도 노드 선택과 장애 분석을 세밀하게 제어하고 싶다면, 먼저 ClashSky를 내려받아 자신의 작업 환경에서 테스트해 보세요.

ClashSky 다운로드