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

Clash External Controller API로 노드 자동 전환하는 고급 설정

2026년 9월 15일 업데이트: 2026년 9월 15일 약 10분 소요

서론: External Controller 자동화의 가치

Clash External Controller API는 Clash의 상태를 조회하고 프록시 그룹을 원격으로 변경할 수 있는 관리 인터페이스입니다. 일반적인 사용자는 GUI에서 노드를 직접 클릭하지만, API를 활용하면 연결 상태, 지연 시간, 실패 횟수와 같은 정보를 수집한 뒤 조건에 따라 최적의 노드를 자동으로 선택할 수 있습니다. 이는 단순히 “빠른 노드 하나를 고르는 기능”을 넘어, 장시간 연결을 안정적으로 유지하는 운영 방식에 가깝습니다.

예를 들어 현재 선택된 노드의 응답 시간이 갑자기 800ms 이상으로 증가하거나 연결 테스트가 연속으로 실패하면, 스크립트가 External Controller에 요청을 보내 다른 노드로 전환할 수 있습니다. 반대로 짧은 순간의 지연 증가만으로 노드를 바꾸면 연결이 불필요하게 끊길 수 있으므로, 여러 번의 측정 결과와 최소 유지 시간을 함께 고려해야 합니다. 이 글에서는 Clash Verge Rev, Mihomo, Clash Meta 계열에서 공통으로 이해할 수 있는 API 흐름과 안전한 자동 전환 설계를 단계별로 설명합니다.

핵심 요약

External Controller는 노드 자체가 아니라 Clash의 관리 API입니다. 인증 토큰을 보호하고, API 응답을 검증하며, 지나치게 잦은 전환을 막는 것이 안정적인 자동화의 핵심입니다.

이 기능을 적용하기 전에는 사용 중인 코어가 외부 컨트롤러와 프록시 그룹 변경 API를 지원하는지 확인해야 합니다. 클라이언트의 설정 화면에서 API 주소와 포트가 표시되더라도, 배포판이나 코어 버전에 따라 지원되는 엔드포인트와 응답 형식이 다를 수 있습니다. 따라서 자동화 스크립트는 특정 화면의 동작에 의존하기보다 실제 API 응답을 먼저 확인하는 방식으로 작성하는 것이 좋습니다.

1External Controller 활성화와 인증 보호

External Controller는 보통 127.0.0.1의 특정 포트에서 대기합니다. 로컬 컴퓨터에서만 자동화한다면 모든 인터페이스에 바인딩하는 것보다 루프백 주소를 사용하는 편이 안전합니다. 외부 주소에 열어 두면 같은 네트워크의 다른 기기가 API에 접근할 가능성이 있으며, 토큰을 탈취한 사용자가 프록시 그룹을 임의로 변경하거나 연결 정보를 조회할 수 있습니다.

기본 설정 항목 확인

  • External Controller 주소: 로컬 자동화에는 127.0.0.1:9090처럼 루프백 주소와 전용 포트를 사용합니다.
  • Secret: 짧은 문자열이나 기본값 대신 충분히 긴 무작위 토큰을 지정합니다. 토큰은 설정 파일, 셸 기록, 공개 저장소에 노출하지 마세요.
  • API 버전: 사용 중인 Mihomo 또는 Clash 코어의 문서에 맞춰 경로와 응답 필드를 확인합니다.
  • 방화벽: 외부 접속이 필요하지 않다면 컨트롤러 포트의 LAN 및 WAN 접근을 차단합니다.
안전한 컨트롤러 설정 예시

설정 파일의 문법은 코어와 클라이언트에 따라 다를 수 있지만, 개념적으로 다음과 같은 값이 필요합니다.

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

설정 변경 후에는 Clash를 재시작하거나 프로필을 다시 적용해야 할 수 있습니다. 실제 적용 여부는 API 요청으로 확인하세요.

인증 헤더는 일반적으로 Authorization: Bearer TOKEN 형식을 사용합니다. 토큰을 URL의 쿼리 문자열에 넣으면 셸 기록이나 프록시 로그에 남을 수 있으므로 피해야 합니다. 또한 자동화 프로그램의 로그에는 전체 토큰 대신 앞뒤 일부만 표시하고, 오류가 발생했을 때 응답 본문에 민감한 설정 정보가 포함되어 있는지 확인해야 합니다.

보안 주의사항

External Controller를 0.0.0.0에 바인딩한 채 인증 없이 사용하지 마세요. 관리 포트는 웹 프록시 포트와 다르며, 일반 사용자에게 공개할 이유가 없습니다.

2API 호출 흐름과 프록시 그룹 변경

자동 전환은 “상태 조회 → 후보 수집 → 연결 테스트 → 그룹 변경 → 결과 확인”의 순서로 설계하는 것이 좋습니다. 먼저 컨트롤러가 살아 있는지 확인하고, 현재 프록시 그룹과 포함된 노드 목록을 읽습니다. 그다음 후보 노드의 지연 시간을 측정하고, 기준을 통과한 노드를 선택하여 그룹의 현재 선택값을 변경합니다. 마지막으로 변경 결과를 다시 조회해 요청이 실제로 반영되었는지 확인합니다.

자주 사용하는 API 범주

  • 컨트롤러 상태: API 서버가 응답하는지 확인하는 용도입니다. 연결 실패와 잘못된 인증을 구분해야 합니다.
  • 프록시 목록: 프록시 그룹, 현재 선택된 노드, 그룹에 포함된 후보 이름을 조회합니다.
  • 지연 시간 테스트: 특정 노드가 지정된 URL에 응답하는 데 걸린 시간을 측정합니다. 단순한 ICMP 핑과는 다른 결과가 나올 수 있습니다.
  • 그룹 선택 변경: 선택형 프록시 그룹에 새 노드 이름을 전달합니다. 이름에 특수문자가 있으면 JSON 인코딩을 사용해야 합니다.
curl로 API 흐름 점검

아래 예시는 로컬 컨트롤러와 인증 토큰이 준비되어 있다는 전제의 기본 형태입니다. 엔드포인트는 사용 중인 코어 문서에 맞게 조정하세요.

TOKEN="change-this-to-your-token" API="http://127.0.0.1:9090" # 프록시 그룹 조회 curl -H "Authorization: Bearer ${TOKEN}" \ "${API}/proxies" # 특정 노드의 지연 시간 확인 curl -H "Authorization: Bearer ${TOKEN}" \ "${API}/proxies/JP-01/delay?url=http://www.gstatic.com/generate_204&timeout=3000" # 선택형 그룹의 현재 노드 변경 curl -X PUT \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"name":"JP-01"}' \ "${API}/proxies/Auto-Select"

셸에서 앰퍼샌드가 포함된 URL을 직접 입력할 때는 환경에 따라 따옴표 처리가 필요합니다. 응답 상태 코드와 JSON의 노드 이름을 함께 확인하세요.

그룹 이름과 노드 이름은 YAML에 표시되는 문자열과 정확히 일치해야 합니다. 이름에 슬래시, 괄호, 이모지 또는 공백이 포함된 경우 문자열을 임의로 정리하면 요청이 실패할 수 있습니다. 또한 자동 선택 그룹과 수동 선택 그룹은 동작이 다를 수 있으므로, 변경 전에 해당 그룹의 타입을 확인하세요. 그룹을 잘못 선택하면 사용자가 기대한 트래픽 분기 규칙과 실제 연결 경로가 달라질 수 있습니다.

3지연 시간과 연결 상태 기반 자동 전환 구현

노드 자동 전환에서 가장 중요한 부분은 “가장 낮은 숫자”만 선택하지 않는 것입니다. 측정 URL의 위치, DNS 응답, 순간적인 혼잡, 서버의 캐시 상태에 따라 결과가 크게 달라질 수 있습니다. 실전에서는 최소 지연 시간뿐 아니라 허용 가능한 최대 지연, 연속 성공 횟수, 실패 횟수, 노드의 위치와 프로토콜 같은 조건을 함께 사용해야 합니다.

추천 선택 정책

  1. 후보 노드마다 동일한 테스트 URL과 타임아웃을 사용합니다.
  2. 한 번의 결과가 아니라 2~3회 측정한 중앙값 또는 평균값을 계산합니다.
  3. 응답이 없거나 타임아웃된 노드는 일정 시간 후보에서 제외합니다.
  4. 현재 노드보다 새 노드가 일정 비율 이상 빠를 때만 변경합니다. 예를 들어 20% 개선 조건을 둘 수 있습니다.
  5. 변경 후에는 최소 유지 시간을 둬서 짧은 간격의 핑퐁 전환을 막습니다.

다음은 Python에서 구현할 때의 간단한 구조입니다. 실제 운영 코드에서는 API 경로, 그룹 이름, 예외 처리 방식을 사용 중인 코어에 맞게 확인해야 합니다.

import time import requests API = "http://127.0.0.1:9090" TOKEN = "change-this-to-your-token" GROUP = "Auto-Select" TEST_URL = "http://www.gstatic.com/generate_204" headers = {"Authorization": f"Bearer {TOKEN}"} def proxy_delay(name): endpoint = f"{API}/proxies/{name}/delay" params = {"url": TEST_URL, "timeout": 3000} response = requests.get(endpoint, headers=headers, params=params, timeout=5) response.raise_for_status() return response.json().get("delay") def change_proxy(name): endpoint = f"{API}/proxies/{GROUP}" response = requests.put(endpoint, headers=headers, json={"name": name}, timeout=5) response.raise_for_status() candidates = ["JP-01", "SG-02", "US-01"] scores = {} for node in candidates: try: values = [proxy_delay(node) for _ in range(3)] scores[node] = sorted(values)[1] except (requests.RequestException, TypeError, KeyError): continue if scores: best = min(scores, key=scores.get) if scores[best] < 250: change_proxy(best)

이 예시는 설명을 위한 기본 구조이며, 실제 운영에서는 현재 선택된 노드를 먼저 조회하고 변경 여부를 판단해야 합니다. 또한 delay 값이 누락되거나 문자열로 반환되는 상황을 처리하고, 노드 이름을 외부 입력으로 받을 때는 허용 목록을 사용하는 것이 안전합니다. API 요청이 성공했더라도 Clash 내부에서 실제 연결이 완전히 전환되는 데 시간이 걸릴 수 있으므로, 변경 직후에 곧바로 다시 전환하지 않도록 대기 구간을 두세요.

운영 성공 팁

현재 노드가 180ms이고 후보 노드가 175ms라면 전환하지 마세요. 작은 차이보다 연결의 지속성과 전환 횟수 감소가 실제 체감 품질에 더 큰 영향을 줍니다.

4안정적인 운영을 위한 예외 처리와 모니터링

자동 전환은 처음에는 잘 작동하더라도 네트워크 환경이 바뀌면 과도한 전환을 일으킬 수 있습니다. 특히 모든 노드가 동시에 실패했는데 스크립트가 계속 그룹 변경을 시도하면 API 로그가 불필요하게 늘어나고, 사용자는 인터넷이 복구될 때까지 반복적인 연결 끊김을 경험하게 됩니다. 따라서 “전환할 후보가 없음”을 정상적인 상태로 취급하고, 잠시 후 재시도하는 백오프 전략을 적용해야 합니다.

  • API 오류: 401 또는 403 응답은 인증 토큰을 확인하고, 404는 코어 버전과 엔드포인트를 확인합니다.
  • 연결 거부: 컨트롤러가 실행 중인지, 포트가 변경되지 않았는지, 방화벽이 로컬 접근을 막고 있지 않은지 확인합니다.
  • 모든 후보 실패: 즉시 임의의 노드로 변경하지 말고 현재 노드를 유지한 뒤 30초 또는 60초 후 재시도합니다.
  • 반복 전환: 마지막 전환 시각을 저장하고 최소 유지 시간과 히스테리시스 조건을 적용합니다.
  • 로그 기록: 시각, 현재 노드, 후보별 지연 시간, 변경 사유, 응답 코드를 기록하되 인증 토큰은 절대 저장하지 않습니다.

자동화 작업은 운영체제의 작업 스케줄러나 서비스 관리자를 통해 실행할 수 있습니다. 다만 1초마다 API를 호출하는 방식은 권장하지 않습니다. 대부분의 환경에서는 30초에서 120초 사이의 주기가 적절하며, 영상 회의나 게임처럼 연결 유지가 중요한 작업 중에는 자동 전환을 일시 중지하는 옵션을 제공하는 것이 좋습니다.

전환이 항상 정답은 아닙니다

노드를 바꾸면 기존 TCP 연결과 웹소켓 세션이 재설정될 수 있습니다. 실시간 회의나 파일 업로드 중에는 지연 시간보다 연결 유지가 중요하므로, 자동 전환 정책을 서비스별로 분리하세요.

또한 테스트 URL 하나만으로 노드 품질을 단정하지 마세요. 가까운 지역의 정적 파일 응답은 빠르지만 실제 사용 서비스는 느릴 수 있고, 반대 상황도 발생합니다. 웹 브라우징, 스트리밍, 업무 서비스 등 실제 사용 목적에 가까운 테스트 대상을 선택하고, 특정 도메인의 이용 약관과 서비스 정책을 준수해야 합니다.

자주 묻는 질문

External Controller 인증이 계속 실패하면 어떻게 하나요?

먼저 컨트롤러 주소와 포트가 현재 실행 중인 Clash 코어의 값과 일치하는지 확인하세요. 그다음 Authorization 헤더의 Bearer 표기, 토큰 앞뒤 공백, 설정 변경 후 재시작 여부를 점검합니다. GUI에서 사용하는 API 포트와 코어가 실제로 열어 둔 포트가 다를 수도 있으므로, 로컬에서 상태 요청을 보내 응답 코드부터 확인하는 것이 좋습니다.

지연 시간이 가장 낮은 노드로 바꾸면 항상 빨라지나요?

그렇지 않습니다. 지연 시간은 측정 시점과 테스트 서버에 따라 달라지며, 실제 서비스의 다운로드 속도나 패킷 손실을 직접 보장하지 않습니다. 여러 번 측정한 중앙값, 타임아웃 횟수, 실제 사용 서비스의 접속 성공 여부를 함께 평가하고, 작은 차이에는 전환하지 않는 기준을 두세요.

어떤 프록시 그룹을 자동 전환 대상으로 지정해야 하나요?

규칙에서 실제로 참조하는 선택형 그룹을 대상으로 지정해야 합니다. 노드를 바꾸더라도 규칙이 다른 그룹을 가리키고 있으면 트래픽 경로는 변하지 않습니다. 설정 파일의 rules와 그룹 구성을 확인하고, 변경 후 컨트롤러의 현재 선택값과 실제 접속 경로를 함께 검증하세요.

TUN 모드에서도 External Controller 자동 전환이 작동하나요?

대체로 TUN 모드는 트래픽을 처리하는 기능이고 External Controller는 관리 기능이므로 함께 사용할 수 있습니다. 다만 TUN, DNS, 시스템 권한 설정이 API 요청 자체에 영향을 주는 경우는 드뭅니다. 자동화 프로그램이 실행되는 환경에서 루프백 주소 접근이 가능한지와, 전환 후 DNS 누수나 규칙 오작동이 없는지를 별도로 점검해야 합니다.

마무리 점검

토큰 보호, 후보 목록 제한, 다중 측정, 최소 유지 시간, 실패 시 재시도 간격을 모두 적용한 뒤 자동화를 활성화하세요. 처음부터 무인 운영하기보다 로그를 관찰하며 임계값을 조정하는 방식이 안전합니다.

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