설정 2026-08-31 · 약 15분

Clash API로 프록시 노드 자동 전환하는 고급 설정 가이드

Clash Verge Rev는 기존 Clash for Windows의 개발 중단 이후 가장 강력한 대안으로 떠오른 오픈 소스 클라이언트입니다. 현대적인 UI와 Mihomo 커널의 강력한 기능을 결합하여 더 빠르고 안정적인 네트워크 환경을 제공합니다. 본 가이드에서는 초보자가 가장 어려워하는 구독 URL 등록부터 최적의 노드 선택까지의 전 과정을 상세히 다룹니다.

Clash API로 자동 전환을 설계하는 이유

Clash의 external-controller API는 실행 중인 Clash 또는 Mihomo 코어의 상태를 외부 프로그램에서 조회하고 변경할 수 있게 해 줍니다. 웹 UI에서 프록시 노드를 클릭하는 대신, 현재 선택된 노드와 지연 시간, 연결 상태를 주기적으로 확인한 뒤 조건에 맞는 노드로 정책 그룹을 바꾸는 운영 흐름을 만들 수 있습니다. 이 방식은 여러 기기에서 같은 프록시를 사용하거나, 장시간 실행되는 서버·라우터에서 수동 복구가 어려울 때 특히 유용합니다.

자동 전환의 핵심은 “가장 빠른 노드를 무조건 선택한다”가 아닙니다. 먼저 실제로 사용할 프록시 그룹을 정하고, 그 그룹에 속한 후보를 일정한 간격으로 검사한 다음, 실패 횟수와 지연 시간에 따라 전환해야 합니다. 순간적인 네트워크 혼잡만으로 노드가 계속 바뀌면 연결이 끊기고 로그인 세션이나 다운로드가 중단될 수 있으므로, 측정·판정·전환·복구의 네 단계를 분리하는 것이 안정적입니다.

이 글에서는 Clash API와 Mihomo 계열 클라이언트를 기준으로 설명합니다. Clash Verge Rev, Clash for Windows의 일부 빌드, Linux 서버에서 실행하는 Mihomo는 화면 구성이 달라도 API의 기본 개념은 비슷합니다. 다만 버전이나 코어 종류에 따라 지원 엔드포인트와 응답 필드가 다를 수 있으므로, 자동화 전에 현재 버전의 API 응답을 직접 확인해야 합니다.

external-controller와 API 인증 설정

API를 사용하려면 설정 파일에 컨트롤러 주소를 지정해야 합니다. 일반적으로 같은 장치에서 스크립트를 실행한다면 127.0.0.1에 바인딩하는 것이 가장 안전합니다. LAN의 다른 장치나 원격 서버에서 접근해야 할 때만 관리 주소를 열고, 반드시 비밀번호와 방화벽 규칙을 함께 적용하세요. 컨트롤러를 0.0.0.0으로 열어 둔 채 인증 없이 사용하는 것은 누구나 노드 목록을 읽거나 현재 정책을 바꿀 수 있는 위험한 구성입니다.

기본 설정 예시

external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-token"
external-ui: dashboard
allow-lan: false

secret은 짧은 단어나 구독 URL에 사용한 토큰을 재사용하지 말고, 충분히 긴 무작위 문자열로 정하는 편이 좋습니다. API 요청에는 보통 다음과 같은 헤더를 넣습니다.

Authorization: Bearer change-this-to-a-long-random-token

설정을 변경한 뒤에는 코어를 재시작하거나 프로필을 다시 적용해야 할 수 있습니다. 브라우저에서 대시보드가 열리는 것만으로 API가 올바르게 설정되었다고 판단하지 말고, 인증을 포함한 요청과 인증을 제외한 요청을 각각 시험해 보세요. 인증 없이 401 Unauthorized가 반환된다면 보호 기능은 작동하는 것입니다.

주의

컨트롤러 포트를 인터넷에 직접 노출하지 마세요. 원격 관리가 필요하면 VPN, SSH 포트 포워딩, 접근 제어가 적용된 내부 네트워크를 사용하고, 공유기 포트 포워딩으로 9090을 공개하는 방식은 피해야 합니다. 로그나 셸 히스토리에 Bearer 토큰이 남지 않도록 명령어와 스크립트의 출력도 점검하세요.

상태 확인에 필요한 API 엔드포인트

자동 전환 스크립트는 먼저 현재 코어가 응답하는지 확인하고, 그 다음 그룹과 노드의 상태를 읽어야 합니다. 아래 엔드포인트는 계열과 버전에 따라 필드가 조금 달라질 수 있지만, 실전 점검의 출발점으로 사용할 수 있습니다.

목적 요청 확인할 내용
코어 상태 GET / API 응답 가능 여부와 버전
전체 프록시 정보 GET /proxies 정책 그룹, 현재 선택 노드, 후보 목록
그룹별 지연 측정 GET /proxies/{name}/delay 지정 URL에 대한 지연 시간과 실패 여부
현재 연결 GET /connections 오래 걸린 연결과 실제 사용 중인 체인
그룹 전환 PUT /proxies/{name} 정책 그룹의 선택 노드 변경

그룹 이름에는 공백이나 한글, 괄호가 들어갈 수 있으므로 URL 경로에 직접 이어 붙이지 말고 반드시 URL 인코딩해야 합니다. 예를 들어 Proxy, 자동 선택, 🇯🇵 Japan은 서로 다른 문자열로 취급됩니다. 또한 모든 프록시를 동일하게 검사할 필요는 없습니다. 실제 서비스에 사용할 그룹 하나를 정하고, 그 그룹에서 노드를 선택하게 하는 편이 요청 수와 오작동 가능성을 줄입니다.

지연 측정 URL도 하나만 고정하지 않는 것이 좋습니다. 특정 도메인이 일시적으로 차단되거나 응답이 느려질 수 있기 때문입니다. 짧은 응답을 돌려주는 HTTPS 주소를 기본값으로 사용하되, 업무 환경에 맞는 두세 개의 검사 대상을 순환하고, 한 번의 실패가 아니라 연속 실패를 기준으로 장애를 판정하세요.

curl로 API 연결과 노드 전환 테스트

자동화 스크립트를 만들기 전에 curl로 수동 요청을 실행하면 주소, 포트, 인증 토큰, 그룹 이름의 문제를 빠르게 분리할 수 있습니다. 아래 예시의 토큰과 그룹 이름은 본인 설정에 맞게 바꾸세요.

export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="change-this-to-a-long-random-token"

curl -fsS \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/proxies" | jq '.proxies | keys'

curl -fsS \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/proxies/Proxy/delay?url=https%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"

curl -fsS -X PUT \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Node-A"}' \
  "${CLASH_API}/proxies/Proxy"

첫 번째 요청에서 실제 정책 그룹 이름과 노드 이름을 확인한 뒤, 두 번째 요청으로 지연 측정을 실행합니다. 응답에 지연 값이 나오더라도 그것은 검사 URL까지의 한 번의 측정 결과일 뿐입니다. 세 번째 요청은 그룹의 현재 선택을 바꾸므로, 먼저 테스트용 그룹에서 실행하고 기존 연결이 끊길 수 있다는 점을 고려하세요.

팁

응답이 없을 때는 곧바로 노드 장애로 결론 내리지 마세요. 127.0.0.1:9090에서 컨트롤러가 실제로 열려 있는지, 설정을 적용한 코어가 Mihomo인지 원본 Clash인지, 방화벽이 로컬 포트를 차단하지 않는지 순서대로 확인하세요. 401은 인증 문제이고, 404는 엔드포인트나 코어 버전 차이일 가능성이 큽니다.

지연 시간 기반 자동 전환 스크립트

운영용 스크립트는 후보 목록을 읽고, 각 노드의 지연을 측정하고, 유효한 결과 중 가장 안정적인 대상을 선택한 뒤, 현재 노드와 다를 때만 PUT 요청을 보내야 합니다. 매 주기마다 같은 노드를 다시 선택하는 요청은 불필요하며, 연결 추적과 로그를 복잡하게 만듭니다.

간단한 Python 구현 예시

import os
import time
import requests

API = os.getenv("CLASH_API", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = os.getenv("CLASH_GROUP", "Proxy")
TEST_URL = "https://www.gstatic.com/generate_204"
HEADERS = {"Authorization": f"Bearer {SECRET}"}
TIMEOUT = 5

def get_json(path):
    response = requests.get(API + path, headers=HEADERS, timeout=TIMEOUT)
    response.raise_for_status()
    return response.json()

def choose_node():
    data = get_json("/proxies")
    group = data["proxies"][GROUP]
    candidates = group.get("all", [])
    results = []

    for node in candidates:
        if node == "DIRECT" or node == "REJECT":
            continue
        path = f"/proxies/{requests.utils.quote(node, safe='')}/delay"
        try:
            result = requests.get(
                API + path,
                params={"url": TEST_URL, "timeout": "5000"},
                headers=HEADERS,
                timeout=TIMEOUT + 1
            )
            result.raise_for_status()
            delay = result.json().get("delay")
            if isinstance(delay, int) and delay > 0:
                results.append((delay, node))
        except requests.RequestException:
            continue

    if not results:
        return None
    return min(results)[1]

def switch_to(node):
    requests.put(
        API + f"/proxies/{requests.utils.quote(GROUP, safe='')}",
        json={"name": node},
        headers=HEADERS,
        timeout=TIMEOUT
    ).raise_for_status()

while True:
    try:
        selected = choose_node()
        if selected:
            current = get_json("/proxies")["proxies"][GROUP].get(" now")
            if current != selected:
                switch_to(selected)
                print(f"switched to {selected}")
    except Exception as error:
        print(f"check failed: {error}")
    time.sleep(60)

예시는 API 구조를 이해하기 위한 최소 구현입니다. 실제로 사용할 때는 현재 선택 필드가 코어 응답에서 어떤 이름으로 제공되는지 확인하고, 후보 이름에 URL 인코딩을 적용해야 합니다. 일부 버전은 그룹 정보에 now와 all을 제공하지만, 프로필이나 코어에 따라 필드 구성이 달라질 수 있습니다. 응답 JSON을 먼저 저장해 두고 필드 존재 여부를 방어적으로 처리하면 업데이트 후 장애를 줄일 수 있습니다.

안정적인 페일오버를 위해 다음 정책을 추가하세요. 첫째, 새 노드가 기존 노드보다 아주 조금 빠른 정도라면 전환하지 않는 히스테리시스를 둡니다. 예를 들어 현재 노드보다 150ms 이상 빠를 때만 바꾸면 불필요한 진동이 줄어듭니다. 둘째, 새 노드가 두세 번 연속 성공한 뒤 전환합니다. 셋째, 전환 후 일정 시간은 다시 평가하지 않는 쿨다운을 둡니다. 마지막으로 모든 후보가 실패하면 현재 노드를 즉시 삭제하지 말고, 다음 주기에 재시도하면서 로그에 장애 시각과 결과를 남기세요.

로그 분석과 운영 안정화

자동 전환이 제대로 작동하는지 판단하려면 “전환했다”는 메시지만 기록해서는 부족합니다. 측정 시각, 그룹 이름, 후보 수, 각 노드의 지연 값, 실패 원인, 최종 선택, 전환 전후의 연결 수를 함께 남겨야 합니다. 그래야 특정 시간대에만 발생하는 회선 문제인지, 검사 URL 문제인지, API 인증 만료인지 구분할 수 있습니다.

  • timeout: 검사 대상까지의 응답이 제한 시간 안에 오지 않은 상태입니다. 노드 장애, 방화벽, 과도하게 짧은 타임아웃을 함께 확인합니다.
  • connection refused: 컨트롤러 포트가 열려 있지 않거나 잘못된 주소를 사용한 경우가 많습니다.
  • 401 Unauthorized: secret과 Bearer 토큰이 일치하지 않거나 공백·따옴표가 포함된 경우입니다.
  • 404 Not Found: 엔드포인트 경로가 현재 코어에서 지원되는지, 그룹 이름을 URL 인코딩했는지 확인합니다.
  • 전환 후 인터넷 끊김: 노드 자체가 아니라 DNS, 규칙 그룹, TUN 라우팅, 기존 연결 캐시 문제일 수 있습니다.

운영 환경에서는 스크립트를 무한 루프로 실행하기보다 Linux의 systemd 서비스나 컨테이너의 재시작 정책으로 관리하는 방법이 좋습니다. 로그가 무한히 쌓이지 않도록 보존 기간과 파일 크기를 제한하고, API 토큰은 코드에 직접 적지 말고 환경 변수나 권한이 제한된 별도 파일에서 읽으세요. 여러 사용자가 접근하는 서버라면 스크립트 파일의 권한을 최소화하고, 노드 이름과 구독 URL이 로그에 그대로 남지 않도록 마스킹하는 것도 필요합니다.

또한 자동화의 목적을 “항상 최저 지연 노드”로 정의하면 사용자가 기대한 결과와 실제 체감이 달라질 수 있습니다. 지연 시간이 짧아도 패킷 손실이 많거나 특정 서비스가 차단될 수 있고, 먼 지역의 노드가 스트리밍에는 더 안정적일 수 있습니다. 따라서 업무용, 일반 웹, 동영상처럼 용도가 다르면 정책 그룹을 나누고, 그룹마다 검사 URL과 허용 노드 목록을 다르게 설정하는 편이 현실적입니다. 수동 전환이 필요한 비상 그룹을 남겨 두면 자동화 오류가 발생해도 복구 경로를 확보할 수 있습니다.

운영 전 최종 점검

  • 컨트롤러는 필요한 범위에서만 열려 있고 API 인증이 켜져 있는가?
  • 스크립트가 실제 그룹의 now, all 필드를 올바르게 읽는가?
  • 연속 실패, 전환 임계값, 쿨다운이 설정되어 노드가 반복해서 바뀌지 않는가?
  • API 장애와 프록시 노드 장애를 로그에서 구분할 수 있는가?
  • 자동 전환을 중지하고 수동으로 복구할 방법이 남아 있는가?

일부 GUI 클라이언트는 수동 노드 선택과 기본 지연 표시에는 편리하지만, 여러 조건을 조합한 페일오버나 장기 로그 보관, 재시도 간격 조정까지 제공하지 않는 경우가 있습니다. 반대로 Clash의 external-controller API를 사용하면 이미 실행 중인 코어를 그대로 유지하면서 정책 그룹·측정 주기·인증·복구 규칙을 세밀하게 조정할 수 있습니다. 설정 파일을 직접 반복 편집하는 도구보다 변경 범위를 작게 유지하고, Windows·macOS·Linux 환경에서 같은 운영 개념을 적용하기도 쉽습니다. 자동화의 기반을 안정적으로 마련하고 싶다면 Clash 클라이언트 다운로드 후 먼저 API를 수동으로 검증하고, 작은 그룹에서 자동 전환을 단계적으로 적용해 보세요.

최고의 속도를 경험할 준비가 되셨나요?

Clash Verge Rev를 통해 지연 없는 글로벌 네트워크를 구축하세요. 2026년형 최신 빌드를 제공합니다.

Clash 무료 다운로드(Windows / macOS)