Clash External Controller API로 프록시 노드 자동 전환하기
Clash External Controller API란 무엇이며 자동 전환에 왜 필요한가
Clash External Controller API는 실행 중인 Clash 또는 Mihomo 코어의 상태를 외부 프로그램에서 조회하고 제어할 수 있게 해 주는 HTTP 인터페이스입니다. 웹 대시보드에서 현재 연결 상태와 프록시 그룹을 확인하는 것뿐 아니라, 스크립트로 노드 지연 시간을 측정하고 특정 정책 그룹의 선택 노드를 바꾸는 작업도 API를 통해 수행할 수 있습니다. 따라서 단순히 화면에서 가장 빠른 서버를 한 번 고르는 방식보다, 일정한 조건에 따라 장애를 감지하고 다른 노드로 넘기는 자동화 구성이 가능합니다.
예를 들어 업무 시간에 사용하는 WORK-PROXY 그룹의 현재 노드가 응답하지 않거나 지연 시간이 기준값을 초과하면, 모니터링 스크립트가 후보 노드에 테스트 요청을 보냅니다. 정상 응답을 돌려주는 노드가 있으면 API에 선택 명령을 전달하고, 이후 새 연결부터 해당 노드를 사용하게 만들 수 있습니다. 이 방식은 영상 재생, 개발 패키지 설치, 원격 저장소 접근처럼 장시간 연결이 필요한 환경에서 수동 전환 횟수를 줄이는 데 유용합니다.
다만 API가 네트워크 장애를 마법처럼 해결하는 것은 아닙니다. 노드 자체가 만료되었거나 구독 프로필의 규칙이 잘못되었거나, DNS·TUN·방화벽 설정이 충돌하면 다른 노드를 선택해도 같은 문제가 반복될 수 있습니다. 자동화의 핵심은 무조건 빠른 노드를 고르는 것이 아니라 측정 대상, 실패 판정, 전환 대상, 복구 조건을 명확히 정의하는 데 있습니다.
127.0.0.1에만 바인딩한 뒤 인증 비밀번호를 설정하세요. 회사·학교 네트워크에서는 자동화 스크립트 실행과 프록시 사용 정책도 먼저 확인해야 합니다.External Controller 주소와 인증을 안전하게 설정하기
API를 사용하려면 먼저 Clash 설정의 external-controller 값을 확인해야 합니다. 일반적인 로컬 구성은 다음처럼 지정합니다. 실제 설정 파일의 키 이름과 들여쓰기는 사용 중인 Clash 클라이언트와 Mihomo 버전에 맞춰 확인하세요.
external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-secret"
127.0.0.1:9090은 같은 컴퓨터에서만 접근할 수 있는 주소입니다. 반대로 0.0.0.0:9090으로 설정하면 모든 네트워크 인터페이스에서 연결을 받을 수 있어, 공유기·공용 Wi-Fi·사내 네트워크에 API가 노출될 위험이 커집니다. 다른 장비에서 관리해야 하는 특별한 이유가 있다면 방화벽에서 관리 장비의 IP만 허용하고, 평문 HTTP를 신뢰할 수 없는 네트워크에 그대로 노출하지 않는 편이 안전합니다.
인증이 필요한 요청에는 보통 Authorization 헤더에 Bearer 토큰을 넣습니다. 브라우저에서 대시보드를 열 수 있더라도, 스크립트에서는 인증 누락 때문에 401 Unauthorized가 발생할 수 있습니다. 토큰을 셸 명령에 직접 적어 두면 셸 기록이나 프로세스 목록에 남을 수 있으므로 환경 변수나 별도 권한의 설정 파일에서 읽도록 구성하세요.
- 컨트롤러 포트: 다른 서비스가 이미 사용하는 포트와 겹치지 않는지 확인합니다.
- secret: 짧은 단어보다 충분히 긴 무작위 문자열을 사용하고 저장소에 커밋하지 않습니다.
- 접근 범위: 자동화 스크립트가 실행되는 호스트와 포트만 로컬로 제한합니다.
- 로그 관리: 토큰, 구독 URL, 개인 식별 정보가 모니터링 로그에 기록되지 않도록 마스킹합니다.
클라이언트 UI에서 Controller 설정을 직접 제공하는 경우에는 설정 저장 후 코어를 다시 시작해야 값이 적용될 수 있습니다. 변경 직후 API가 응답하지 않는다면 포트가 실제로 열렸는지와 선택한 프로필이 현재 활성 프로필인지부터 점검하는 것이 좋습니다.
노드 상태 검사와 정책 그룹 자동 전환을 단계별로 구성하기
자동 전환은 한 번에 복잡한 데몬을 만드는 것보다, 먼저 API 요청을 수동으로 확인한 뒤 검사 로직을 추가하는 순서가 안정적입니다. 아래 예시는 로컬 Controller가 9090 포트에서 실행 중이고, 정책 그룹 이름이 Proxy라고 가정합니다. 그룹 이름은 프로필마다 다르므로 API에서 실제 이름을 먼저 확인하세요.
- 컨트롤러 연결 확인: 대시보드 또는 API 클라이언트로
http://127.0.0.1:9090/version에 요청을 보내 코어 버전과 HTTP 응답을 확인합니다. 응답이 없으면 Clash 프로세스, 포트, 방화벽을 먼저 확인합니다. - 정책 그룹 목록 조회:
/proxies엔드포인트를 조회하고Proxy와 같은 실제 그룹 이름, 현재 선택된 노드, 후보 노드 목록을 기록합니다. 보이는 이름과 YAML 내부의 이름이 다를 수 있으므로 응답 JSON을 기준으로 삼습니다. - 후보 노드 검사: 각 노드에 대해 지연 시간 테스트 API를 호출합니다. 테스트 URL은 자주 접속하는 HTTPS 주소를 사용하되, 특정 사이트의 응답 시간만으로 전체 인터넷 품질을 단정하지 않습니다.
- 실패 판정: 예를 들어 HTTP 오류, 연결 시간 초과, 지연 시간 800ms 초과가 연속 두 번 발생하면 실패로 기록합니다. 단 한 번의 일시적인 지연만으로 즉시 전환하면 불필요한 플래핑이 발생합니다.
- 노드 선택 변경: 정상 후보 가운데 지연 시간과 연속 성공 횟수를 함께 비교한 뒤, 해당 그룹의 선택 API에 노드 이름을 전달합니다. 이름에 특수문자나 한글이 포함되어도 JSON 인코딩이 깨지지 않는지 확인합니다.
- 전환 후 검증: 선택 변경 응답만 확인하지 말고 실제 업무용 URL을 다시 요청합니다. 규칙이 다른 그룹을 가리키거나 연결이 기존 세션에 남아 있으면 화면상 선택과 실제 트래픽이 다를 수 있습니다.
개념적인 요청 흐름은 다음과 같습니다. 엔드포인트와 요청 방식은 사용하는 코어 버전의 API 문서를 확인하고, 실행 전 테스트 환경에서 검증해야 합니다.
curl -H "Authorization: Bearer $CLASH_SECRET" \
http://127.0.0.1:9090/proxies
curl -H "Authorization: Bearer $CLASH_SECRET" \
"http://127.0.0.1:9090/proxies/Proxy"
curl -X PUT \
-H "Authorization: Bearer $CLASH_SECRET" \
-H "Content-Type: application/json" \
-d '{"name":"JP-01"}' \
http://127.0.0.1:9090/proxies/Proxy
자동화 스크립트는 먼저 후보 목록에서 DIRECT, 다른 정책 그룹, 이미 실패한 노드를 제외해야 합니다. 이후 각 후보에 순서대로 테스트 요청을 보내고, 가장 빠른 결과 하나만 고르기보다 최근 성공률과 최소 유지 시간을 함께 반영하세요. 30초마다 전환하는 구조는 사용자가 체감하는 안정성을 오히려 떨어뜨릴 수 있습니다. 일반적으로 전환 후 일정 시간 동안은 새 검사 결과가 나빠도 즉시 되돌리지 않는 쿨다운을 두는 것이 좋습니다.
장애 조치와 복구를 분리하는 것도 중요합니다. 현재 노드가 실패하면 예비 그룹으로 이동하고, 원래 노드가 다시 살아났을 때 바로 복귀시키는 대신 2~3회 연속 성공한 경우에만 복귀하도록 설정하면 반복 전환을 줄일 수 있습니다. 여러 컴퓨터에서 같은 정책 그룹을 동시에 제어하면 서로 다른 스크립트가 선택값을 덮어쓸 수 있으므로, 잠금 파일·실행 주기·관리 주체를 하나로 정해야 합니다.
자동 전환이 실패할 때 확인할 항목과 FAQ
401 또는 403 오류가 발생하면 어떻게 하나요?
401은 대부분 Authorization 헤더가 없거나 Bearer 뒤의 secret이 일치하지 않을 때 발생합니다. 공백과 따옴표가 환경 변수에 포함되지 않았는지 확인하고, 현재 활성 코어가 읽은 설정의 secret과 비교하세요. 403이 발생하면 요청 메서드, 경로, 코어가 지원하는 API 버전이 맞는지 확인해야 합니다. 브라우저 대시보드에서 성공했다고 해서 모든 API 작업 권한이 동일하다고 단정해서는 안 됩니다.
지연 시간은 낮은데 실제 접속은 왜 불안정한가요?
지연 테스트는 보통 짧은 HTTPS 요청 하나의 결과입니다. 큰 파일 다운로드, WebSocket 유지, UDP 통신, 특정 서비스의 TLS·지역 제한까지 모두 반영하지는 않습니다. 따라서 업무용 도메인이나 자주 쓰는 SaaS를 별도 테스트 대상으로 추가하고, 성공률·응답 코드·연결 유지 시간도 함께 수집하세요. DNS가 직접 연결되고 HTTP만 프록시를 타는 구성이라면 결과가 왜곡될 수 있으므로 rule hit 로그도 같이 봐야 합니다.
정책 그룹을 찾을 수 없다는 오류는 왜 발생하나요?
프로필마다 그룹 이름이 다르고, 구독 갱신 과정에서 이름이 바뀌거나 그룹이 제거될 수 있습니다. 스크립트에 Proxy를 고정하기 전에 /proxies 응답에서 그룹 타입과 이름을 확인하세요. 이름이 바뀌었을 때 자동으로 비슷한 그룹을 선택하도록 만들면 오작동할 수 있으므로, 허용 목록에 등록된 정확한 그룹만 제어하는 편이 안전합니다.
노드가 계속 바뀌는 현상을 어떻게 줄이나요?
단일 측정값을 기준으로 삼지 말고 연속 실패 횟수, 최소 전환 간격, 복귀 조건을 함께 사용하세요. 예를 들어 3회 연속 실패 후 전환하고, 전환 뒤 5분 동안은 재전환하지 않으며, 복귀 후보가 3회 연속 성공했을 때만 원래 노드로 돌아가도록 할 수 있습니다. 서비스별로 필요한 품질이 다르므로 영상·개발 API·일반 웹의 임계값을 동일하게 적용하지 않는 것도 도움이 됩니다.
일부 동급 프록시 클라이언트나 단순 VPN 도구는 노드 선택 화면은 제공하지만, 정책 그룹의 현재 상태를 외부에서 읽고 조건부로 바꾸는 기능이 제한적이거나 플랫폼별 설정 방식이 크게 다릅니다. 자동 장애 조치를 구현하려면 별도 플러그인과 복잡한 GUI 매크로가 필요하고, 실패 원인을 확인할 로그가 부족한 경우도 있습니다. 반면 Clash와 Mihomo는 External Controller API, 정책 그룹, 지연 시간 검사, 상세 로그를 조합할 수 있어 개발자와 네트워크 엔지니어가 자신의 운영 기준에 맞춰 자동 전환 로직을 설계하기 좋습니다. 로컬 바인딩과 secret 인증을 지키면서 작은 스크립트부터 검증하고 싶다면 다운로드 페이지에서 지원 클라이언트를 확인해 보세요.