Clash / Mihomo 컨트롤러 API 문서 - RESTful API 전체 개요

요청 예시

대시보드/스크립트가 코어에 보내는 모든 요청에는 다음과 같은 형식의 인증 헤더를 포함해야 합니다:

curl Shell

curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true \
  -d '{"path": "", "payload": ""}' -X PUT

${secret}은 설정 파일에서 지정한 secret 키입니다
${controller-api}는 설정 파일에서 지정한 external-controller 리스닝 주소입니다
?force=true는 쿼리 파라미터로, 일부 엔드포인트에서 필요합니다
'{"path": "", "payload": ""}'는 업데이트할 리소스 데이터입니다

요청에 파일 경로를 전달해야 하는데 해당 경로가 mihomo 작업 디렉터리 밖에 있다면, SAFE_PATHS 환경 변수를 수동으로 설정해 안전 경로에 추가해야 합니다. 문법은 운영체제의 PATH 변수와 동일합니다(Windows는 세미콜론, 다른 시스템은 콜론으로 구분).

로그

GETWS/logs

실시간 로그를 가져옵니다.

선택 파라미터 ?level=log_level, log_level은 info/warning/error/debug 중 선택 가능
선택 파라미터 ?format=structured를 붙이면 구조화된 로그를 출력합니다(time/level/message/fields 포함)
표준 모드는 한 줄에 하나의 JSON을 전송: type 로그 레벨, payload 로그 내용
구조화 모드: time(HH:MM:SS), level, message, fields(추가 필드 배열)

트래픽 정보

GETWS/traffic

실시간 트래픽을 가져옵니다. up/down의 단위는 바이트/초, upTotal/downTotal의 단위는 바이트이며, 1초마다 전송됩니다.

up 현재 업로드 속도　down 현재 다운로드 속도
upTotal 누적 업로드 바이트 수　downTotal 누적 다운로드 바이트 수

메모리 정보

GETWS/memory

실시간 메모리 사용량(바이트)을 가져옵니다. 1초마다 전송됩니다.

inuse 현재 메모리 사용량　oslimit 시스템 메모리 제한(항상 0)

버전 정보

GET/version

코어 버전 정보를 가져옵니다.

meta Meta 버전 여부　version 버전 문자열

캐시

POST/cache/fakeip/flush

fakeip 캐시를 지우고 HTTP 204를 반환합니다.

POST/cache/dns/flush

DNS 캐시를 지우고 HTTP 204를 반환합니다.

실행 설정

GET/configs

현재 실행 설정을 가져오며, port, socks-port, mixed-port, mode, log-level, allow-lan, ipv6, tun 등의 필드를 포함한 JSON 객체를 반환합니다.

PUT/configs

기본 설정을 다시 불러옵니다. 파라미터 ?force=true를 붙이며, HTTP 204를 반환합니다.

PATCH/configs

기본 설정을 일부 업데이트합니다. 예: '{"mixed-port": 7890}', HTTP 204를 반환합니다.

POST/configs/geo

GEO 데이터베이스를 업데이트합니다. '{"path": "", "payload": ""}'를 붙이며, HTTP 204를 반환합니다.

POST/restart

코어를 재시작합니다. '{"path": "", "payload": ""}'를 붙이며, HTTP 204를 반환합니다.

업데이트

POST/upgrade

코어를 업데이트합니다. ?channel=xxx로 업데이트 채널을 지정하거나 ?force=true로 강제 업데이트할 수 있으며, {"status": "ok"}를 반환합니다.

POST/upgrade/ui

대시보드를 업데이트합니다(설정에서 external-ui를 먼저 지정해야 함). {"status": "ok"}를 반환합니다.

POST/upgrade/geo

GEO 데이터베이스를 업데이트하고 HTTP 204를 반환합니다.

프록시 그룹

GET/group

모든 프록시 그룹 정보를 가져오며, proxies 배열을 반환하고 각 항목의 형식은 /proxies/{name}과 동일합니다.

GET/group/{group_name}

지정한 프록시 그룹 정보를 가져오며, 형식은 /proxies/{name}과 동일합니다.

GET/group/{group_name}/delay

프록시 그룹 내 모든 노드에 대해 속도 테스트를 수행하여 새로운 지연 데이터를 반환하고, 해당 자동 프록시 그룹의 현재 fixed 고정 선택을 초기화합니다.

파라미터 ?url=xxx&timeout=5000을 붙임
선택 ?expected=xxx, 기대하는 HTTP 응답 상태 코드로, 범위 표기(예: 200/204, 200-299)를 지원합니다
노드 이름을 키로, 지연 시간(밀리초)을 값으로 하는 객체를 반환합니다. 예: {"노드A": 120, "노드B": 350}

프록시

GET/proxies

모든 프록시/프록시 그룹 정보를 가져오며, 이름을 키로 하는 proxies 객체를 반환합니다. 공통 필드는 다음과 같습니다:

name/type(예: Shadowsocks, VMess, DIRECT, Selector, URLTest 등)
udp/uot/xudp/tfo/mptcp/smux 지원 플래그
alive 현재 생존 여부, history 지연 시간 기록(time+delay), extra 테스트 URL별로 그룹화된 추가 기록
interface/routing-mark/provider-name/dialer-proxy
프록시 그룹에는 추가로: now 현재 선택된 항목(LoadBalance에는 이 필드 없음), all 멤버 목록, testUrl, hidden, icon, emptyFallback, expectedStatus(Selector에는 없음), fixed(URLTest/Fallback에만 있음)가 포함됩니다

GET/proxies/{name}

지정한 프록시/프록시 그룹 정보를 가져오며, 필드는 위와 동일합니다(일반 프록시는 공통 필드만 가짐).

PUT/proxies/{name}

해당 프록시 그룹의 현재 선택된 노드를 전환합니다. '{"name":"일본"}'을 붙이며, HTTP 204를 반환합니다.

DELETE/proxies/{name}

해당 프록시/프록시 그룹의 fixed 고정 선택을 초기화합니다(Selector 타입 제외). HTTP 204를 반환합니다.

GET/proxies/{name}/delay

지정한 프록시의 속도를 테스트합니다. ?url=xxx&timeout=5000(선택 ?expected=xxx)을 붙이며, {"delay": 120}을 반환합니다.

프록시 프로바이더

GET/providers/proxies

모든 프록시 프로바이더 정보를 가져오며, 프로바이더 이름을 키로 하는 providers 객체를 반환합니다. 각 프로바이더에는 메타 정보와 프록시 목록이 포함됩니다.

GET/providers/proxies/{name}

지정한 프록시 프로바이더 정보를 가져오며, 설정 정보와 proxies 프록시 목록을 포함합니다.

PUT/providers/proxies/{name}

해당 프록시 프로바이더를 업데이트하고 HTTP 204를 반환합니다.

GET/providers/proxies/{name}/healthcheck

해당 프록시 프로바이더의 헬스체크를 실행하고 HTTP 204를 반환합니다.

GET/providers/proxies/{name}/{proxy_name}

프로바이더 내 지정한 프록시 정보를 가져오며, 필드는 /proxies/{name}과 동일합니다.

GET/providers/proxies/{name}/{proxy_name}/healthcheck

프로바이더 내 지정한 프록시의 속도를 테스트합니다. ?url=xxx&timeout=5000을 붙이며, {"delay": 120}을 반환합니다.

규칙

GET/rules

모든 규칙을 가져오며, rules 배열을 반환하고 각 항목에는 다음이 포함됩니다:

index 인덱스(0부터 시작)　type 규칙 유형　payload 매칭 내용　proxy 대상 프록시/프록시 그룹
size 규칙 항목 수(GEOIP/GEOSITE에만 유효, 그 외는 -1)
선택 extra: disabled/hitCount/hitAt/missCount/missAt

PATCH/rules/disable

인덱스를 지정해 규칙을 임시로 비활성화/활성화합니다(재시작 후 무효). '{"0": false,"1": true}'를 붙이며, HTTP 204를 반환합니다.

규칙 프로바이더

GET/providers/rules

모든 규칙 프로바이더 정보를 가져오며, 이름을 키로 하는 providers 객체를 반환합니다.

PUT/providers/rules/{name}

지정한 규칙 프로바이더를 업데이트하고 HTTP 204를 반환합니다.

연결

GETWS/connections

활성 연결 정보를 가져옵니다. 선택 파라미터 ?interval=milliseconds(갱신 간격, 기본값 1000ms).

downloadTotal/uploadTotal 누적 트래픽　memory 현재 메모리 사용량
connections 활성 연결 배열: id, metadata(소스/대상 주소, 프로토콜, 프로세스 이름 등), upload/download, start, chains/providerChains 프록시 체인, rule/rulePayload 적용된 규칙

DELETE/connections

모든 연결을 종료하고 HTTP 204를 반환합니다.

DELETE/connections/{id}

지정한 연결을 종료하고 HTTP 204를 반환합니다.

DNS 조회

GET/dns/query

지정한 이름과 유형의 DNS 조회 결과를 가져옵니다. ?name=example.com&type=A를 붙입니다.

Status DNS 응답 코드　Question 조회 질문 배열
TC/RD/RA/AD/CD 각종 DNS 플래그 비트
선택 Answer/Authority/Additional: 모두 레코드 배열이며, 각 항목에는 name/type/TTL/data가 포함됩니다

저장소

GET/storage/{key}

지정한 key의 저장 값을 가져오며, 존재하지 않으면 null을 반환합니다.

PUT/storage/{key}

지정한 key에 값을 씁니다(유효한 JSON이어야 하며 최대 1MB). '{"foo": "bar"}'를 붙이며, HTTP 204를 반환합니다.

DELETE/storage/{key}

지정한 key의 저장 값을 삭제하고 HTTP 204를 반환합니다.

DEBUG

/debug 계열 엔드포인트는 코어 시작 시 로그 레벨을 debug로 설정해야 사용할 수 있습니다.

PUT/debug/gc

GC를 한 번 실행하고 HTTP 204를 반환합니다.

GET/debug/pprof

브라우저에서 http://${controller-api}/debug/pprof를 열면 원본 DEBUG 정보를 확인할 수 있습니다:

allocs: 함수 호출별 메모리 할당 상황(스택/힙 크기와 횟수)으로, 메모리 누수나 빈번한 할당 등의 문제를 조사할 때 사용합니다
heap: 힙 메모리 사용 상세 정보로, 할당 블록의 크기, 개수, 주소를 포함하며 크기순으로 정렬하여 메모리 사용량이 높은 부분을 찾는 데 사용합니다

Graphviz를 설치하면 그래픽 리포트를 볼 수 있습니다:

Shell pprof

go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

브라우저에서 http://${controller-api}/debug/pprof/heap?raw=true에 접속하면 리포트 파일을 다운로드할 수 있으며, 문제가 발생했을 때 issue에 업로드하면 조사에 도움이 됩니다.