이 글이 해결하는 문제

Clash API 기반 노드 자동 전환은 현재 사용 중인 노드가 느려지거나 연결에 실패했을 때 사용자가 직접 Clash 화면을 열어 다른 노드를 선택하지 않도록 만드는 운영 방식입니다. 여기서 중요한 점은 단순히 여러 노드를 등록하는 것이 아니라, 각 노드의 상태를 일정한 기준으로 확인하고 그 결과에 따라 특정 프록시 그룹의 선택 노드를 바꾸는 구조를 만드는 것입니다.

웹 브라우징에서는 페이지 하나가 조금 늦게 열리는 정도로 끝날 수 있지만, 장시간 다운로드, API 호출, 원격 개발, 스트리밍처럼 연결이 오래 유지되는 작업에서는 불안정한 노드가 큰 문제를 만듭니다. DNS 조회는 성공했지만 TLS 연결에서 멈추거나, 처음에는 빠르다가 몇 분 뒤 패킷 손실이 증가하거나, 특정 지역의 노드만 반복해서 타임아웃을 일으키는 경우가 대표적입니다. 이런 상황에서 수동 전환만 사용하면 장애를 알아차리는 시점과 실제 복구 시점 사이에 긴 공백이 생깁니다.

이 글에서는 Clash 또는 Mihomo 계열 코어의 외부 컨트롤러 API를 활용해 프록시 그룹을 조회하고, 헬스체크 결과에 따라 선택 노드를 변경하는 기본 원리를 설명합니다. Clash Verge Rev 같은 GUI 클라이언트를 사용하더라도 실제 자동화 대상은 대부분 백그라운드에서 실행되는 코어이므로, 먼저 API 주소와 인증 방식을 확인해야 합니다. 클라이언트의 메뉴 이름은 버전에 따라 다를 수 있지만, API 엔드포인트·프록시 그룹·노드 이름을 확인하는 방식은 대체로 비슷합니다.

헬스체크 기준을 먼저 설계하기

자동 전환에서 가장 흔한 실수는 “응답 시간이 가장 짧은 노드가 항상 좋은 노드”라고 판단하는 것입니다. 짧은 ICMP 핑이나 단 한 번의 HTTP 요청만으로 노드의 실제 품질을 확정하기는 어렵습니다. 노드가 테스트 서버까지는 빠르게 도달하더라도, 사용하려는 API 도메인이나 스트리밍 서버에서는 다른 결과를 보일 수 있기 때문입니다. 따라서 헬스체크는 측정 대상, 측정 횟수, 실패 허용 횟수, 전환 조건을 함께 정의해야 합니다.

  • 지연 시간: 동일한 URL에 여러 번 요청해 평균값뿐 아니라 최대값과 변동 폭을 확인합니다. 평균은 낮지만 간헐적으로 크게 튀는 노드는 장시간 연결에 적합하지 않을 수 있습니다.
  • 연결 성공률: DNS, TCP, TLS, HTTP 응답 중 어느 단계에서 실패하는지 구분합니다. HTTP 403이나 429는 네트워크 단절이 아니라 정책 또는 사용량 문제일 수 있으므로 단순 연결 실패로 처리하지 않는 편이 좋습니다.
  • 응답 코드: 테스트 URL이 정상적으로 반환하는 상태 코드를 미리 정합니다. 리다이렉트가 정상인 서비스라면 301 또는 302를 허용할지 결정해야 합니다.
  • 연속 실패 횟수: 한 번의 타임아웃만으로 즉시 전환하면 일시적인 혼잡에도 노드가 계속 바뀌는 플래핑이 발생합니다. 예를 들어 3회 중 2회 실패 또는 3회 연속 실패를 전환 조건으로 둘 수 있습니다.
  • 복귀 조건: 장애 노드가 한 번 성공했다고 바로 원래 그룹으로 복귀시키지 말고, 일정 횟수 연속 성공한 뒤 복귀하도록 설정합니다.

테스트 URL은 실제 서비스의 인증 API나 민감한 엔드포인트보다 가볍고 안정적인 HTTPS 주소가 좋습니다. 다만 특정 지역에서만 차단되는 문제를 확인하려면 일반적인 연결 테스트와 별도로 실제 사용 대상인 API 호스트를 짧게 점검해야 합니다. 두 테스트의 결과가 다르면 노드 자체의 품질보다 목적지별 라우팅, SNI, 지역 정책 또는 규칙 매칭을 의심해야 합니다.

팁: 자동 전환을 시작하기 전 10~15분 동안 여러 노드의 지연 시간과 실패 로그를 수집해 보세요. 테스트 데이터 없이 임계값을 정하면 너무 민감한 전환이나 지나치게 늦은 장애 대응이 생기기 쉽습니다.

Clash API와 프록시 그룹 확인하기

Clash API는 보통 로컬 코어의 외부 컨트롤러 주소와 비밀 키를 통해 접근합니다. 일반적으로 주소는 127.0.0.1 또는 localhost의 특정 포트이며, 설정 파일에는 external-controller와 secret에 해당하는 항목이 있습니다. 실제 키 이름과 포트는 사용 중인 코어와 클라이언트 버전에 따라 달라질 수 있으므로, 예시를 그대로 복사하기보다 현재 프로필의 코어 설정과 로그에서 확인해야 합니다.

API를 LAN에 공개하는 설정은 특히 신중해야 합니다. 외부 컨트롤러가 인증 없이 열려 있으면 같은 네트워크의 다른 기기가 노드 선택, 모드 변경, 연결 종료 같은 작업을 수행할 수 있습니다. 꼭 원격 장치에서 제어해야 한다면 강한 비밀 키를 사용하고, 관리 포트는 방화벽이나 VPN 뒤에 두며, 인터넷 전체에 직접 포트 포워딩하지 않는 것이 안전합니다. 자동화 스크립트에 키를 넣을 때도 공개 저장소나 셸 히스토리에 남지 않도록 환경 변수나 권한이 제한된 별도 파일을 사용하세요.

다음으로 자동 전환 대상인 프록시 그룹의 이름을 확인합니다. 그룹 이름은 구독 제공자나 YAML 작성 방식에 따라 PROXY, 🚀 节点选择, Auto처럼 달라질 수 있습니다. API 요청에서는 화면에 보이는 이름을 정확히 사용해야 하므로, 한글·이모지·공백·대소문자를 임의로 바꾸면 안 됩니다. 그룹이 실제로 노드 선택을 담당하는지, 다른 그룹을 다시 참조하는 상위 그룹인지도 확인해야 합니다.

노드 이름 역시 구독 갱신 때 바뀔 수 있습니다. 따라서 스크립트가 특정 이름 하나만 찾도록 만들면 다음 갱신 뒤 자동 전환이 멈출 수 있습니다. 운영 환경에서는 노드 이름의 고정 접두사, 국가 코드, 태그 규칙 등을 기준으로 후보 목록을 만들고, 예상하지 못한 이름은 로그에 남긴 뒤 안전한 기본 노드를 유지하도록 설계하는 편이 좋습니다.

실제로 자동 전환 구성하기

이제 헬스체크와 API 제어를 하나의 작업으로 연결합니다. 먼저 Clash 코어가 실행 중이고 프로필이 활성화되어 있는지 확인합니다. GUI에서 현재 모드가 규칙 모드인지, 대상 그룹이 실제 트래픽에 사용되는지 살펴보세요. 글로벌 모드에서 다른 그룹을 사용하고 있다면 API로 대상 그룹을 바꿔도 브라우저 트래픽에는 아무 변화가 없을 수 있습니다.

  1. API 주소와 인증 확인: 외부 컨트롤러의 호스트, 포트, 인증 키를 확인하고 로컬 장치에서만 간단한 상태 조회를 수행합니다. 응답이 없으면 포트가 잘못되었거나 코어가 API를 열지 않은 상태일 수 있습니다.
  2. 그룹 목록 조회: 프록시 그룹 목록에서 자동 전환할 그룹의 정확한 이름과 현재 선택된 노드를 확인합니다. 그룹이 존재하지 않으면 노드 선택 요청을 보내지 않고 오류를 기록해야 합니다.
  3. 후보 노드 수집: 그룹에 포함된 노드 가운데 실제로 사용할 수 있는 후보를 추립니다. 만료된 노드, 설정 파일에 남아 있지만 현재 프로필에 없는 이름, 특별한 테스트 전용 항목은 제외합니다.
  4. 순차 헬스체크: 각 후보에 대해 같은 목적지와 같은 타임아웃으로 요청합니다. 동시에 너무 많은 검사를 보내면 로컬 코어와 노드 모두에 부하가 생길 수 있으므로, 처음에는 순차 실행이나 작은 동시성으로 시작합니다.
  5. 점수 계산: 성공률, 평균 지연, 최근 실패 여부를 조합해 점수를 계산합니다. 지연이 조금 낮더라도 최근 연속 실패가 있는 노드는 후보에서 제외하는 방식이 안정적입니다.
  6. 전환 요청: 현재 노드와 새 후보가 다르고 전환 조건을 충족할 때만 API로 그룹의 선택 노드를 변경합니다. 같은 노드를 반복해서 선택하는 요청은 로그와 코어에 불필요한 작업을 만듭니다.
  7. 결과 검증: 변경 요청의 HTTP 성공 코드만 믿지 말고, 그룹 조회 API를 다시 호출해 실제 선택 노드가 바뀌었는지 확인합니다. 이후 짧은 실제 연결 테스트를 실행해 규칙과 시스템 프록시가 정상적으로 적용됐는지 확인합니다.

구현 언어는 Python, Go, Node.js 등 무엇을 사용해도 됩니다. 중요한 것은 HTTP 요청마다 연결 타임아웃과 전체 실행 시간 제한을 두는 것입니다. 요청이 무한정 대기하면 다음 주기의 작업과 겹쳐 여러 전환 요청이 동시에 발생할 수 있습니다. 또한 작업이 중복 실행되지 않도록 잠금 파일, 프로세스 락 또는 스케줄러의 단일 실행 옵션을 사용하는 것이 좋습니다.

전환 후에는 바로 다음 노드로 다시 바꾸지 않도록 쿨다운 시간을 둡니다. 예를 들어 전환 후 2~5분 동안은 새 장애가 명확하지 않은 한 추가 전환을 막을 수 있습니다. 장시간 연결이 많은 환경에서는 새 노드로 바뀐 뒤 기존 연결이 즉시 이동하지 않는다는 점도 기억해야 합니다. 이미 열린 TCP 연결은 기존 노드에 남을 수 있으므로, 새 연결을 만들어 실제 상태를 확인해야 합니다.

# Example request structure
GET http://127.0.0.1:PORT/proxies/GROUP_NAME
Authorization: Bearer YOUR_SECRET

PUT http://127.0.0.1:PORT/proxies/GROUP_NAME
Content-Type: application/json
Authorization: Bearer YOUR_SECRET

{"name":"NODE_NAME"}

위 예시는 API 구조를 이해하기 위한 형태이며, 실제 엔드포인트와 요청 형식은 사용 중인 Clash 코어의 API 문서를 확인해야 합니다. 그룹 이름이나 노드 이름에 특수 문자가 포함되어 있다면 URL 인코딩이 필요할 수 있습니다. 응답 본문에 비밀 키나 전체 구독 정보가 포함될 가능성도 있으므로, 디버그 로그를 그대로 외부 수집 시스템에 전송하지 않도록 주의하세요.

주기 실행, 장애 로그와 안정화

주기 실행 간격은 네트워크 환경과 목적에 맞춰 정합니다. 일반적인 웹 사용이라면 1~5분 간격으로도 충분하지만, 짧은 간격이 항상 더 좋은 것은 아닙니다. 너무 자주 검사하면 노드 제공자의 제한에 걸리거나, 일시적인 지연 변동을 장애로 오인할 가능성이 커집니다. 처음에는 3분 간격과 연속 실패 기준을 사용하고, 실제 로그를 본 뒤 조정하는 방식이 안전합니다.

로그에는 최소한 검사 시각, 그룹 이름, 노드 이름, 테스트 대상, 지연 시간, 응답 코드, 실패 단계, 전환 전후의 선택 노드를 기록합니다. 단, API 비밀 키, 구독 URL에 포함된 토큰, 인증 헤더 전문은 절대 기록하지 않아야 합니다. 로그를 시간순으로 정렬하면 “노드가 나빠서 전환된 것인지”, “규칙이 다른 그룹으로 빠진 것인지”, “API 요청 자체가 실패한 것인지”를 구분하기 쉬워집니다.

전환이 반복되는 플래핑은 자동화 시스템에서 가장 위험한 증상 중 하나입니다. A 노드가 한 번 실패한 뒤 B로 바뀌고, B의 첫 요청이 느려 다시 A로 돌아가는 상황이 이어지면 사용자 체감 품질이 오히려 떨어집니다. 이를 막기 위해 최소 유지 시간, 연속 성공 조건, 노드별 실패 백오프를 함께 사용하세요. 장애 노드에는 다음 검사까지 불이익을 주되, 모든 노드를 영구적으로 제외하지 않도록 일정 시간이 지나면 다시 검증해야 합니다.

구독을 갱신한 뒤에는 노드 목록이 변경될 수 있으므로 자동화 작업이 정상적으로 후보를 다시 읽는지 확인합니다. 그룹이 삭제되었거나 이름이 바뀌었을 때는 가장 빠른 노드로 임의 전환하는 대신, 현재 설정을 유지하고 관리자에게 경고하는 편이 안전합니다. 잘못된 노드로 자동 전환하면 업무 트래픽이 예상하지 못한 지역이나 정책을 통과할 수 있기 때문입니다.

자주 묻는 질문

지연 시간이 가장 짧은 노드로 항상 바꿔도 되나요?

그렇지 않습니다. 짧은 테스트 요청에서는 빠르지만 패킷 손실이나 긴 연결에 약한 노드가 있을 수 있습니다. 최소 성공률과 연속 성공 조건을 함께 적용하고, 실제 사용하는 목적지에 가까운 HTTPS 테스트를 병행하는 것이 좋습니다.

Clash API를 외부에서 접근할 수 있도록 열어도 되나요?

가능하면 로컬호스트에만 바인딩하세요. 원격 제어가 필요하다면 VPN이나 안전한 관리망을 사용하고, 강한 인증 키와 방화벽 규칙을 적용해야 합니다. 인터넷에 컨트롤러 포트를 직접 공개하는 방식은 노드 선택과 프록시 설정을 외부에서 조작당할 위험이 있습니다.

노드가 계속 바뀌는 이유는 무엇인가요?

헬스체크 임계값이 지나치게 민감하거나, 검사 대상 서버의 일시적인 지연을 노드 장애로 판단하는 경우가 많습니다. 전환 쿨다운, 연속 실패 횟수, 최소 유지 시간을 추가하고, 전환 전후의 실제 로그를 비교해 원인을 확인하세요.

Clash Verge Rev를 종료해도 API 자동 전환이 계속되나요?

API는 GUI가 아니라 Clash 또는 Mihomo 코어가 실행 중일 때만 동작합니다. 클라이언트를 종료하면서 코어도 함께 중지되는 구성이라면 자동화 작업은 성공 응답을 받을 수 없습니다. 백그라운드 코어의 실행 상태와 자동 시작 설정을 별도로 확인해야 합니다.

일부 단순 프록시 앱은 수동 노드 선택은 쉬워도 그룹 상태 조회, 인증된 API 제어, 실패 기록과 쿨다운 같은 운영 기능이 제한적일 수 있습니다. 반면 Clash는 프록시 그룹과 규칙을 분리하고, 코어 API를 통해 현재 선택 노드와 연결 상태를 확인하면서 환경에 맞는 자동화 로직을 붙일 수 있다는 장점이 있습니다. 여러 노드를 직접 비교하며 바꾸는 시간이 부담스럽거나 장애 대응을 체계화하고 싶다면, 이 글의 구조를 기준으로 먼저 로컬 자동 전환을 구성해 보는 것이 자연스러운 다음 단계입니다.

지금 Clash를 무료로 다운로드하고 자유로운 인터넷 경험 →