Clash External Controller API로 프록시 노드 자동 전환하기

External Controller API란 무엇인가요?

Clash의 External Controller는 실행 중인 코어의 상태를 외부 프로그램에서 조회하고 변경할 수 있도록 제공하는 HTTP API입니다. 많은 사용자가 이를 웹 대시보드를 표시하는 기능으로만 생각하지만, 실제로는 프록시 노드 목록 확인, 현재 선택된 정책 그룹 조회, 노드 변경, 연결 목록 확인, 프로필 리로드까지 자동화할 수 있는 운영 인터페이스에 가깝습니다.

이 기능은 Clash for Windows, Clash Verge, Clash Verge Rev, ClashX 일부 버전, Clash for Android 계열 및 Mihomo 기반 클라이언트에서 이름과 화면은 조금씩 달라도 비슷한 방식으로 제공됩니다. 다만 모든 클라이언트가 같은 API와 같은 설정 키를 지원하는 것은 아니므로, 먼저 사용 중인 클라이언트가 Mihomo 또는 호환 코어를 사용하는지 확인해야 합니다. 특히 최신 기능인 프로바이더 상태, 연결별 메타데이터, 일부 관리 엔드포인트는 코어 버전에 따라 응답 형식이 달라질 수 있습니다.

자동 전환의 기본 원리는 간단합니다. 스크립트가 일정한 간격으로 정책 그룹에 포함된 노드의 지연 시간이나 연결 가능 여부를 확인하고, 기준을 만족하지 못한 현재 노드가 발견되면 같은 그룹의 다른 노드를 선택합니다. 사람이 Proxies 화면을 열어 하나씩 바꾸는 대신 API가 반복 작업을 처리하므로, 장시간 실행되는 PC·서버·라우터 환경에서 특히 유용합니다.

API를 켜기 전에 준비할 항목

자동화 스크립트를 작성하기 전에 세 가지 정보를 먼저 정리하면 시행착오가 줄어듭니다. 첫째는 API가 열려 있는 주소와 포트, 둘째는 인증 토큰, 셋째는 자동으로 제어할 정책 그룹의 정확한 이름입니다. 기본 설정에서는 컨트롤러가 비활성화되어 있거나 127.0.0.1:9090에만 바인딩되어 있을 수 있습니다.

• 컨트롤러 주소: 같은 컴퓨터에서만 사용할 경우 127.0.0.1:9090처럼 로컬 주소를 권장합니다.
• 외부 접근 주소: 다른 장치에서 호출해야 할 때만 LAN IP 또는 0.0.0.0 바인딩을 검토합니다. 인터넷 전체에 공개하는 설정은 피해야 합니다.
• 인증 토큰: secret 값은 추측하기 어려운 긴 문자열로 설정하고, 스크립트와 설정 파일의 권한을 제한합니다.
• 정책 그룹: 자동으로 바꿀 대상은 보통 Proxy, PROXY, 🚀 Proxy처럼 구성 파일에 정의된 select 그룹입니다.
• 판정 기준: 지연 시간만 볼지, 일정 횟수의 실패와 타임아웃까지 함께 볼지 미리 정합니다.

설정 파일을 직접 관리한다면 다음과 같이 컨트롤러와 시크릿을 지정할 수 있습니다. 클라이언트 UI에서 같은 항목을 제공하는 경우에는 General, External Controller, API 또는 고급 설정 화면에서 입력해도 됩니다.

external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-token"

external-controller는 API 서버의 수신 주소입니다. secret을 설정하면 요청 헤더에 Authorization: Bearer 토큰을 포함해야 합니다. 일부 클라이언트는 설정을 저장한 뒤 코어를 다시 시작해야 변경 사항이 적용되므로, 포트가 실제로 열렸는지 상태 화면과 로그에서 함께 확인하세요.

자주 사용하는 External Controller 엔드포인트

Clash API는 JSON을 주고받는 REST 형태로 동작합니다. 먼저 읽기 요청으로 현재 상태를 확인한 다음, 조건이 충족될 때만 변경 요청을 보내는 방식이 안정적입니다. API 문서나 코어 버전에 따라 일부 필드가 추가될 수 있으므로, 자동화 프로그램은 사용하지 않는 필드를 발견해도 오류로 처리하지 않도록 작성하는 편이 좋습니다.

정책 그룹 이름에 공백, 이모지, 한글이 포함되어 있으면 URL 경로에서 올바르게 인코딩해야 합니다. 예를 들어 그룹 이름이 🚀 Proxy일 때 단순히 문자열을 이어 붙이지 말고 URL 인코딩을 적용해야 합니다. 스크립트에서 HTTP 클라이언트를 사용할 경우 대부분 자동 처리되지만, 직접 명령어를 조합한다면 이 부분을 확인하세요.

지연 시간 테스트는 일반 연결 테스트와 다릅니다. API가 숫자 값을 반환했다고 해서 모든 웹사이트가 정상적으로 열리는 것은 아닙니다. 측정 URL이 특정 지역에서 차단되거나 DNS가 실패할 수 있으므로, 실제 사용 목적에 가까운 HTTPS URL을 선택하고 여러 번의 결과를 평균 내는 것이 좋습니다.

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

동작 설정: 장애 노드를 감지하고 자동 전환하기

자동 전환을 구성할 때는 “가장 빠른 노드 하나를 매번 선택”하는 것보다 “현재 노드가 실제로 문제가 있을 때만 바꾸기”가 안정적입니다. 지연 시간이 잠시 높아졌다는 이유로 계속 노드를 바꾸면 연결이 끊기고, 스트리밍이나 다운로드 세션이 반복해서 재설정될 수 있습니다. 따라서 실패 횟수, 최소 전환 간격, 후보 노드 수를 함께 사용하세요.

수동으로 API를 호출해 정책 그룹 변경이 되는지 먼저 시험해 보세요. 아래 요청에서 Proxy는 실제 그룹 이름으로 바꿔야 하며, JSON 본문에는 그룹에 포함된 정확한 노드 이름을 사용해야 합니다.

curl -X PUT \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tokyo-01"}' \
  "http://127.0.0.1:9090/proxies/Proxy"

자동화 로직에는 다음과 같은 보호 장치를 넣는 것이 좋습니다. 현재 노드가 이미 정상이라면 아무 작업도 하지 않고, 실패가 한 번 발생한 것만으로 전환하지 않습니다. 또한 후보 노드가 하나뿐이거나 모든 후보가 타임아웃이면 정책 그룹을 무리하게 변경하지 말고 로그에 원인을 남겨야 합니다.

• 연속 실패 조건: 예를 들어 3회 연속 타임아웃일 때만 장애로 판정합니다.
• 쿨다운 시간: 전환 후 최소 5~10분 동안은 다시 바꾸지 않습니다.
• 히스테리시스: 새 노드가 현재 노드보다 확실히 빠르거나 안정적일 때만 전환합니다.
• 실패 노드 보류: 방금 실패한 노드는 일정 시간 후보에서 제외합니다.
• 상태 기록: 마지막 검사 시각, 응답 시간, 실패 횟수, 전환 사유를 파일이나 로그에 저장합니다.

간단한 Python 구현에서는 requests 같은 HTTP 라이브러리로 API를 호출할 수 있습니다. 다만 이 글의 목적은 특정 스크립트를 그대로 복사하는 것보다, API 응답을 검증하고 예외를 처리하는 구조를 이해하는 데 있습니다. 실제 운영 환경에서는 API 서버가 재시작되거나 프로필이 업데이트되어 그룹 이름이 바뀌는 상황까지 고려해야 합니다.

import time
import requests

API = "http://127.0.0.1:9090"
HEADERS = {"Authorization": "Bearer YOUR_SECRET"}
GROUP = "Proxy"

def get_group():
    response = requests.get(
        f"{API}/proxies/{GROUP}",
        headers=HEADERS,
        timeout=5
    )
    response.raise_for_status()
    return response.json()

def switch_node(node_name):
    response = requests.put(
        f"{API}/proxies/{GROUP}",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"name": node_name},
        timeout=5
    )
    response.raise_for_status()

group = get_group()
print("현재 노드:", group.get("now"))
# 후보를 점검한 뒤 조건을 만족할 때만 switch_node() 호출

스크립트 실행 주기는 너무 짧게 설정하지 않는 편이 좋습니다. 10초마다 전체 노드를 검사하면 API와 프록시 제공업체 양쪽에 불필요한 부하가 생길 수 있습니다. 일반적인 데스크톱 환경에서는 1~5분 간격으로 확인하고, 네트워크가 불안정한 서버라면 연속 실패와 백오프 시간을 늘리는 방식이 더 적절합니다.

접근 제한과 문제 해결

External Controller API는 프록시를 사용하는 것보다 더 높은 수준의 권한을 가집니다. 공격자가 API에 접근하면 노드 선택뿐 아니라 연결 종료, 프로필 조작, 런타임 설정 변경 등을 시도할 수 있습니다. 따라서 토큰만 설정하는 것으로 끝내지 말고 네트워크 경계와 운영 권한을 함께 관리해야 합니다.

• 가능하면 127.0.0.1에만 바인딩하고, 원격 호출이 필요할 때만 LAN 주소를 사용합니다.
• 운영체제 방화벽에서 API 포트를 특정 관리 장치의 IP에만 허용합니다.
• 토큰을 공개 저장소, 화면 공유, 셸 히스토리에 남기지 않습니다.
• 스크립트에 토큰을 하드코딩하기보다 환경 변수나 읽기 권한이 제한된 비밀 파일을 사용합니다.
• 공유기 포트 포워딩과 UPnP가 API 포트를 외부에 노출하지 않는지 확인합니다.
• 전환 스크립트가 실패할 때를 대비해 수동으로 클라이언트 UI에서 노드를 바꾸는 경로를 남겨 둡니다.

API 호출이 401 Unauthorized를 반환하면 토큰이 없거나 형식이 잘못된 경우입니다. 404라면 엔드포인트 또는 그룹 이름을 확인하고, 400이 나오면 요청 본문의 노드 이름이 실제 목록과 일치하는지 살펴보세요. connection refused는 컨트롤러가 꺼져 있거나 포트가 다른 경우가 많으며, timeout은 API 문제가 아니라 지연 측정 대상 노드나 테스트 URL의 문제일 수 있습니다.

프로필 업데이트 직후 자동 전환이 멈췄다면 정책 그룹이 삭제되었거나 이름이 변경되었을 가능성이 큽니다. 이때는 먼저 GET /proxies의 전체 응답을 저장해 새 그룹 이름과 후보 목록을 비교하세요. 노드 이름에 국가명이나 이모지가 자동으로 붙는 구독도 있으므로, 고정된 문자열 대신 그룹의 all 배열을 읽어 동적으로 후보를 구성하는 방식이 안전합니다.

자주 묻는 질문

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

기본 REST 구조는 비슷하지만 지원 엔드포인트, 포트 기본값, 런타임 설정 항목은 클라이언트와 코어 버전에 따라 다를 수 있습니다. Clash Verge Rev나 Mihomo 기반 클라이언트에서 먼저 확인하고, 사용하는 버전의 API 응답을 직접 저장해 필드 이름을 검증하세요.

지연 시간이 가장 짧은 노드로 항상 바꾸면 더 빠른가요?

반드시 그렇지는 않습니다. 측정 URL까지의 왕복 시간과 실제 서비스의 경로는 다를 수 있고, 짧은 측정 간격은 잦은 전환을 일으킵니다. 연속 실패, 안정적인 응답, 최소 유지 시간까지 함께 판단하는 것이 체감 품질에 더 유리합니다.

다른 컴퓨터에서 API를 호출하려면 어떻게 해야 하나요?

컨트롤러를 LAN 주소에 바인딩하고 운영체제 방화벽에서 관리할 컴퓨터의 IP만 허용하세요. 인터넷에 포트를 공개하는 대신 같은 사설망이나 VPN을 통해 접근하고, 강한 토큰과 접근 로그를 사용해야 합니다.

정책 그룹을 찾지 못한다는 오류가 납니다.

Proxy라는 이름이 항상 존재하는 것은 아닙니다. 구독 설정에 따라 PROXY, 🚀 Proxy 또는 다른 사용자 지정 이름이 사용됩니다. GET /proxies로 실제 그룹 목록을 확인하고, URL 인코딩과 대소문자까지 정확히 맞추세요.

일부 GUI 프록시 도구는 노드 목록을 보여 주는 데는 편리하지만, 장애 감지 기준이나 정책 그룹 전환을 세밀하게 자동화하려면 별도 플러그인과 복잡한 예약 작업이 필요할 수 있습니다. 또한 클라이언트마다 자동 선택 기능의 동작과 로그 형식이 달라 원인을 추적하기 어려운 경우도 있습니다.

Clash는 External Controller API를 통해 현재 상태 조회, 노드 지연 측정, 정책 그룹 변경을 하나의 일관된 인터페이스로 제공하므로 운영체제의 작업 스케줄러나 Python·Shell 스크립트와 연결하기 쉽습니다. 인증 토큰, 로컬 바인딩, 방화벽 제한을 함께 적용하면 편의성과 보안을 균형 있게 유지할 수 있습니다. 직접 상태를 관리하는 자동 전환 환경을 구성하고 싶다면 Clash 다운로드 후 사용 중인 클라이언트의 API 포트와 그룹 이름부터 확인해 보세요.