Clash 외부 컨트롤러 API 보안 설정과 프록시 노드 자동 전환 방법

Clash 외부 컨트롤러 API란 무엇이며 언제 필요한가

Clash 외부 컨트롤러 API는 실행 중인 Clash 또는 Mihomo 인스턴스의 상태를 확인하고, 프록시 그룹에서 사용할 노드를 바꾸는 HTTP 인터페이스입니다. Clash Verge Rev 같은 클라이언트의 대시보드에서 직접 클릭하는 대신 스크립트나 모니터링 도구가 같은 작업을 요청할 수 있습니다. 예를 들어 현재 선택된 노드를 기록하거나, 특정 노드의 지연 시간을 확인한 뒤 정책 그룹의 선택을 갱신하는 식입니다.

다만 API가 켜져 있다고 해서 자동 전환이 저절로 완성되는 것은 아닙니다. API는 제어 통로이고, 실제 장애 감지와 전환 정책은 url-test·fallback 같은 프록시 그룹이나 별도 스크립트가 담당합니다. 사용자가 원하는 것이 “정해진 주소에 빠르게 연결되는 노드 자동 선택”뿐이라면 먼저 내장 그룹을 검토하세요. 커스텀 알림, 업무 스케줄, 외부 상태 확인과 묶어야 할 때 API 연동이 유용합니다.

이 글은 로컬 PC에서 실행 중인 Clash 호환 코어를 제어하는 상황을 기준으로 설명합니다. 설정 키나 API 동작은 코어와 버전에 따라 차이가 있을 수 있으므로 실제 프로필을 적용하기 전에 사용 중인 Mihomo 또는 클라이언트 문서와 런타임 로그를 확인하세요. 특히 API 주소를 외부에 노출하기보다 로컬에서 먼저 시험하고, 필요한 경우에만 방화벽과 인증을 포함한 제한된 네트워크 경로를 구성하는 것이 기본입니다.

외부 컨트롤러 API 보안: 바인딩 주소와 secret을 먼저 제한

가장 먼저 확인할 항목은 API가 어느 인터페이스에서 수신 대기하는지입니다. 개인 PC에서 사용할 때는 일반적으로 127.0.0.1에 바인딩해 같은 기기의 스크립트만 접근하도록 합니다. 0.0.0.0은 모든 네트워크 인터페이스에서 연결을 받을 수 있는 설정이므로, 편리함만 보고 적용하면 같은 LAN의 다른 기기나 잘못 구성된 포트 포워딩 경로에서 제어 요청을 받을 가능성이 생깁니다.

기본 YAML 구성은 다음처럼 시작할 수 있습니다. secret 값은 예시 문자열 그대로 사용하지 말고, 추측하기 어려운 별도 값으로 바꾸세요. 공개 저장소에 올리는 프로필이나 화면 공유에 API 키가 보이지 않도록 주의해야 합니다.

external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

포트 번호를 바꾸는 것은 접근 통제의 대체 수단이 아닙니다. API 요청을 보내는 클라이언트는 보통 다음과 같이 인증 헤더에 토큰을 전달합니다. 토큰은 비밀번호와 같은 민감 정보이므로 명령을 공유할 때 헤더 부분을 지우고, 자동화 스크립트에 넣을 때도 공개 저장소에 평문으로 커밋하지 마세요.

curl -sS \
  -H "Authorization: Bearer $CLASH_SECRET" \
  http://127.0.0.1:9090/version

API 응답이 오지 않는다면 먼저 코어가 실행 중인지, 포트가 실제 설정과 일치하는지, 요청을 실행한 환경이 같은 네트워크 네임스페이스에 있는지 확인합니다. 인증 오류가 발생하면 secret에 공백이나 줄바꿈이 붙지 않았는지, 요청 헤더 이름과 형식이 맞는지 점검하세요. 토큰을 바꾼 뒤에는 실행 중인 프로필에 변경 사항이 반영됐는지도 확인해야 합니다.

인증이 설정되지 않은 API를 인터넷에 직접 공개하지 마세요. 원격 관리가 꼭 필요하다면 외부 바인딩만으로 해결하지 말고 방화벽의 허용 출발지 제한, VPN 또는 SSH 터널 같은 보호 경로를 함께 사용하세요. 관리 화면의 CORS 허용 목록도 필요한 출처만 지정해야 하며, CORS 설정은 API 인증을 대신하지 않습니다.

자동 전환을 위한 프록시 그룹과 YAML 구성

API로 노드를 바꾸려면 먼저 바꿀 대상이 선택형 그룹에 들어 있어야 합니다. 그룹 이름과 노드 이름은 YAML에 적힌 값이 API에서 사용하는 식별자와 일치해야 합니다. 아래 예시는 구성을 이해하기 위한 뼈대이며, Node-A와 Node-B를 실제 프로필에 존재하는 노드 이름으로 교체해야 합니다.

proxy-groups:
  - name: "AUTO-MANUAL"
    type: select
    proxies:
      - "Node-A"
      - "Node-B"
      - DIRECT

  - name: "AUTO-HEALTH"
    type: url-test
    proxies:
      - "Node-A"
      - "Node-B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

select 그룹은 API나 사용자가 지정한 노드를 유지하기 좋고, url-test 그룹은 주기적으로 지정 URL을 검사해 조건에 맞는 노드를 고르는 데 적합합니다. fallback은 등록 순서에 따라 사용 가능한 노드를 찾도록 구성하는 방식입니다. 어느 유형이든 검사 URL이 실제 환경에서 접근 가능해야 하며, 검증 주기를 지나치게 짧게 잡으면 불필요한 연결 테스트가 늘거나 일시적인 지연 변화에 민감하게 반응할 수 있습니다.

내장 자동 선택과 외부 스크립트를 동시에 같은 그룹에 적용하면 서로 선택을 덮어써 예측하기 어려운 상태가 될 수 있습니다. 예를 들어 url-test가 노드를 바꾼 직후 외부 스크립트가 다른 노드를 선택하면 로그상으로는 전환이 반복되는 것처럼 보입니다. 따라서 자동 선택은 그룹 하나에 맡기거나, 외부 스크립트가 선택할 그룹은 select 유형으로 분리하는 식으로 역할을 명확히 나누세요.

API는 YAML의 원본 프로필을 수정하는 도구가 아니라 실행 중인 코어의 상태를 제어하는 인터페이스입니다. 프로필을 다시 불러오거나 그룹 구성이 바뀌면 스크립트가 기억한 노드 이름이 사라질 수 있으므로, 매번 API에서 현재 그룹과 노드 목록을 확인하는 편이 안전합니다.

프록시 그룹 조회부터 노드 전환까지 단계별 테스트

자동 전환을 만들기 전에는 조회, 지연 측정, 선택 변경 순서로 API를 검증하세요. 첫 단계에서 /proxies 응답을 확인하면 그룹 이름이 정확히 무엇인지, 그룹 안에 어떤 노드가 있는지 확인할 수 있습니다. 응답은 JSON이므로 jq를 사용하면 필요한 부분만 읽기 쉽습니다.

  1. 인증 헤더를 포함해 /proxies를 조회하고, 응답에 예상한 그룹과 노드가 있는지 확인합니다. 그룹 이름에 공백이나 특수 문자가 있다면 URL 경로에 맞게 인코딩해야 합니다.
  2. 지연 측정 API에 그룹과 노드 이름을 넣어 검사합니다. 사용하는 코어가 지원하는 경로와 매개변수 형식은 버전에 따라 확인하고, 요청 제한 시간과 검사 URL을 명시합니다.
  3. 선택형 그룹의 API 경로에 PUT 요청을 보내고 JSON 본문에 선택할 노드 이름을 전달합니다. 성공 응답만으로 판단하지 말고 다시 그룹 정보를 조회해 현재 선택이 바뀌었는지 확인합니다.
  4. 마지막으로 실제 대상 앱이나 도메인에 접속해 트래픽이 기대한 규칙과 그룹을 통과하는지 확인합니다. API에서 노드가 선택됐다는 사실은 애플리케이션 연결까지 성공했다는 뜻은 아닙니다.

구체적인 요청 모양은 다음과 같습니다. 아래의 그룹명과 노드명은 예시이므로 실제 /proxies 응답에 표시된 이름으로 바꿔야 합니다. 한글이나 공백이 있는 이름은 셸에서 URL을 직접 이어 붙이지 말고 안전하게 인코딩하거나 URL 인코딩 기능을 사용하세요.

curl -sS \
  -H "Authorization: Bearer $CLASH_SECRET" \
  http://127.0.0.1:9090/proxies

curl -sS -X PUT \
  -H "Authorization: Bearer $CLASH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Node-B"}' \
  http://127.0.0.1:9090/proxies/AUTO-MANUAL

스크립트에서 자동 전환을 구현할 때는 “가장 낮은 지연 시간” 하나만 기준으로 삼지 않는 편이 좋습니다. 일시적인 측정 편차로 계속 바뀌는 것을 막으려면 최소 지연 개선 폭, 연속 실패 횟수, 전환 후 대기 시간 같은 조건을 둡니다. 또한 현재 선택된 노드가 이미 정상이라면 매 주기마다 재선택하지 않도록 하고, 후보 노드가 그룹에 존재하는지 확인한 뒤 요청을 보내세요. 이런 방어 로직이 없으면 구독 갱신 후 이름이 바뀐 노드를 선택하려다 자동화가 계속 실패할 수 있습니다.

로그와 상태 코드로 자동 전환 문제를 좁히기

API 호출 실패는 네트워크 문제, 인증 문제, 잘못된 그룹 이름, 코어의 기능 차이를 분리해 살펴야 합니다. 연결 자체가 거부되면 주소·포트·프로세스 상태를 확인하고, 응답은 오지만 권한 오류가 나면 secret과 헤더를 확인합니다. 요청 형식 오류는 JSON 본문과 HTTP 메서드, 경로의 그룹 이름을 다시 살펴보세요. 그룹 조회는 되는데 전환만 안 된다면 대상 그룹이 선택형인지, 노드가 해당 그룹에 포함되어 있는지 확인하는 것이 빠릅니다.

Clash 클라이언트의 연결 로그에서는 실제 요청이 어느 프록시 그룹으로 분류됐는지, DNS 조회가 성공했는지, 연결 오류가 특정 노드에서 반복되는지 확인합니다. API 응답의 지연 값은 검사 URL에 대한 결과일 뿐, 모든 사이트의 체감 속도를 보장하지 않습니다. 특정 업무 서비스만 느리다면 규칙 매칭, DNS, 목적지별 네트워크 경로도 함께 점검해야 합니다. 여러 항목을 한꺼번에 바꾸기보다 한 번에 하나씩 수정하고 같은 주소로 재시험하면 원인을 구분하기 쉽습니다.

운영 환경에서는 토큰을 셸 히스토리나 오류 로그에 남기지 않도록 하고, 자동화가 실패했을 때 무한 재시도하지 않도록 횟수 제한과 대기 시간을 설정하세요. 노드 전환 기록에는 시각, 그룹, 이전 노드, 새 노드, 전환 이유 정도만 남기면 사후 분석에 도움이 됩니다. 반대로 전체 API 응답이나 민감한 연결 정보를 장기간 저장하면 예상하지 못한 정보 노출이 생길 수 있으므로 로그 보관 범위를 최소화하세요.

일부 범용 VPN 앱이나 단순 프록시 도구는 노드 전환을 앱 화면에서만 제공하거나 자동화 인터페이스가 제한적이라, 상태 감지와 선택 변경을 별도 작업으로 이어 붙이기 어렵습니다. Clash와 Mihomo는 선택형 그룹, 지연 검사 그룹, 실행 중 제어 API를 조합할 수 있어 사용자가 정책을 관찰하고 자동화 수준을 조절하기 좋습니다. 다만 편리한 API일수록 접근 범위를 좁히고 secret을 안전하게 다루는 것이 중요합니다. 아직 클라이언트를 설치하지 않았다면 다운로드 페이지에서 플랫폼에 맞는 클라이언트를 확인하고, 로컬 API와 내장 자동 전환부터 작은 범위로 시험해 보세요.

→ 지금 무료로 Clash를 다운로드하고 빠른 인터넷을 경험하세요

다운로드 페이지로 이동