01 · OVERVIEW
이 문서로 할 수 있는 것
사용법 가이드는 '설치와 연결 방법'을, 문서는 '설정 항목의 의미와 변경 방법'을 다룹니다. 두 가지를 함께 활용하면 가장 효율적입니다.
이런 분에게 추천합니다
이미 구독을 가져왔고, 규칙이나 DNS를 직접 수정하거나 TUN을 활성화하고 싶은 분, 또는 프록시 그룹이 작동하지 않는 문제를 해결하려는 분에게 적합합니다.
설정 파일 위치
GUI 클라이언트는 보통 '설정 / Profiles'에서 편집할 수 있습니다. CLI 코어는 기본적으로 작업 디렉터리의 config.yaml을 읽습니다.
코어 안내
본 문서는 주로 mihomo（Clash Meta） 문법을 기준으로 작성되었으며, 일반적인 Clash 설정 방식과도 호환됩니다.
수정 전 백업은 필수
YAML을 수동으로 수정한 후에는 들여쓰기와 콜론 뒤 공백을 확인하세요. 문법 오류가 있으면 코어가 시작되지 않습니다.
구독 가져오기가 익숙하지 않으신가요? 먼저 사용법 가이드를 읽어보신 후 이 페이지의 항목 설명으로 돌아와주세요.
02 · CONFIG
설정 구조 한눈에 보기
완전한 설정은 보통 「기본 포트 → 프록시 목록 → 프록시 그룹 → 규칙 → DNS」의 몇 가지 블록으로 구성됩니다. 아래는 가장 최소한의 읽기 쉬운 골격입니다:
# config.yaml — minimal skeleton
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
proxies:
- name: "예시 노드"
type: ss
server: example.com
port: 8388
cipher: aes-128-gcm
password: "password"
proxy-groups:
- name: "PROXY"
type: select
proxies:
- "예시 노드"
- DIRECT
rules:
- DOMAIN-SUFFIX,kr,DIRECT
- MATCH,PROXY
자주 쓰는 기본 필드
| 필드 | 타입 | 설명 |
|---|
| port | number | HTTP 프록시 포트, 브라우저/시스템 프록시에서 자주 사용 |
| socks-port | number | SOCKS5 포트 |
| mixed-port | number | HTTP·SOCKS 혼합 포트（둘 중 하나면 됩니다） |
| allow-lan | bool | LAN 내 기기의 프록시 접속 허용 여부 |
| mode | string | rule / global / direct |
| log-level | string | silent / error / warning / info / debug |
| ipv6 | bool | IPv6 활성화 여부 |
allow-lan: true를 활성화할 때는 외부 컨트롤러를 보호하기 위해 secret도 함께 설정하세요. 설정하지 않으면 LAN 내 누구나 설정을 변경할 수 있습니다.
03 · PROXIES
프록시 노드（proxies）
각 노드는 하나의 아웃바운드 채널입니다. 구독을 가져오면 보통 자동으로 생성됩니다. 수동으로 추가할 때는 name이 설정 내에서 고유해야 합니다.
ss
ssr
vmess
vless
trojan
hysteria2
tuic
wireguard
http
socks5
공통 필드
| 필드 | 타입 | 설명 |
|---|
| name | string | 표시 이름, 프록시 그룹과 규칙에서 참조됩니다 |
| type | string | 프로토콜 종류, 예: ss, vmess |
| server | string | 서버 도메인 또는 IP |
| port | number | 서버 포트 |
| udp | bool | UDP 릴레이 허용 여부（기본값은 프로토콜에 따라 다름） |
Shadowsocks 예시
- name: "HK-SS"
type: ss
server: hk.example.com
port: 8388
cipher: aes-128-gcm
password: "your-password"
udp: true
프로토콜마다 고유한 필드가 있습니다（예: VMess의 uuid, alterId, Trojan의 password, sni）. 제공업체가 제공한 설정을 그대로 따르고 임의로 변경하지 마세요.
04 · PROXY-GROUPS
프록시 그룹（proxy-groups）
프록시 그룹은 여러 노드를 하나로 묶고 「어떻게 선택할지」를 결정합니다. 규칙에서는 보통 개별 노드가 아닌 그룹 이름을 참조합니다.
select
수동 선택. 「홍콩/일본/미국」 같은 지역별 그룹에 적합합니다.
url-test
지연 시간을 기준으로 자동으로 가장 빠른 노드를 선택합니다. interval과 tolerance를 설정할 수 있습니다.
fallback
목록 순서대로 시도하며, 현재 노드가 실패하면 다음 노드로 전환합니다.
load-balance
사용 가능한 노드 간에 로드 밸런싱을 수행하며, 다중 경로 분산에 적합합니다.
url-test 예시
- name: "자동 선택"
type: url-test
proxies:
- "HK-01"
- "JP-01"
- "US-01"
url: http://www.gstatic.com/generate_204
interval: 300
tolerance: 50
05 · RULES
규칙 문법（rules）
규칙은 위에서 아래 순으로 매칭되며, 처음 일치한 곳에서 멈춥니다. 놓치는 트래픽이 없도록 보통 마지막에 MATCH로 마무리합니다.
자주 쓰는 매칭 타입
| 타입 | 예시 | 설명 |
|---|
| DOMAIN | DOMAIN,api.example.com,PROXY | 정확한 도메인 |
| DOMAIN-SUFFIX | DOMAIN-SUFFIX,google.com,PROXY | 접미사 매칭 |
| DOMAIN-KEYWORD | DOMAIN-KEYWORD,ads,REJECT | 키워드 매칭 |
| IP-CIDR | IP-CIDR,192.168.0.0/16,DIRECT | IPv4 범위 |
| GEOIP | GEOIP,KR,DIRECT | 국가/지역별 |
| MATCH | MATCH,PROXY | 최종 기본 규칙 |
작성 예시
rules:
- DOMAIN-SUFFIX,local,DIRECT
- IP-CIDR,127.0.0.0/8,DIRECT
- DOMAIN-KEYWORD,ad,REJECT
- GEOIP,KR,DIRECT
- MATCH,PROXY
커스텀 규칙은 가능한 위쪽에 배치하세요. GEOIP,KR이나 광범위한 규칙 뒤에 두면 영원히 매칭되지 않을 수 있습니다.
06 · DNS
DNS 설정
DNS는 도메인 이름 해석 방식을 결정합니다. 적절히 설정하면 DNS 오염을 줄이고 분류 규칙과 더 정확하게 연동할 수 있으며, '노드에는 연결되지만 사이트가 열리지 않는' 문제를 해결할 때도 중요한 단계입니다.
dns:
enable: true
listen: 0.0.0.0:53
enhanced-mode: fake-ip
nameserver:
- https://cloudflare-dns.com/dns-query
- https://dns.google/dns-query
fallback:
- tls://1.1.1.1
- tls://8.8.8.8
fallback-filter:
geoip: true
geoip-code: KR
모드 설명
- redir-host: 실제 IP를 해석합니다. 호환성이 좋아 실제 주소가 필요한 일부 앱에 적합합니다.
- fake-ip: 가상 IP를 반환합니다. 해석이 더 빠르고 규칙 기반 분류와 함께 사용하는 경우가 많습니다. 일부 게임이나 LAN 앱은
fake-ip-filter에 추가해야 할 수 있습니다.
07 · TUN
TUN 모드
시스템 프록시는 「시스템 프록시 설정을 따르는」 앱만 커버합니다. TUN은 가상 네트워크 카드를 통해 트래픽을 가로채므로 프록시를 지원하지 않는 앱을 포함해 더 많은 앱을 규칙에 따르게 할 수 있습니다.
tun:
enable: true
stack: system # system / gvisor / mixed
dns-hijack:
- any:53
auto-route: true
auto-detect-interface: true
- Windows: TUN 모드를 활성화하려면 보통 관리자 권한으로 클라이언트를 실행해야 합니다.
- macOS: 처음 활성화할 때 네트워크 확장 설치를 요청하므로 시스템 설정에서 허용해주세요.
- 시스템 프록시와의 관계: 보통 둘 중 하나만 사용하면 됩니다. 동시에 활성화하면 이중 프록시나 오류가 발생할 수 있습니다.
서버나 GUI가 없는 환경에서는 CLI 코어 + 환경 변수 프록시를 우선 사용하세요. 데스크톱에서 「전체 시스템 적용」이 필요할 때만 TUN을 활성화하세요.
08 · API
외부 컨트롤러 API
external-controller로 REST API를 노출하면 대시보드와 스크립트로 노드를 전환하거나 연결을 확인하고 설정을 핫 리로드할 수 있습니다.
| 필드 | 타입 | 설명 |
|---|
| external-controller | string | 리스닝 주소, 예: 127.0.0.1:9090 |
| secret | string | 액세스 시크릿, Authorization: Bearer <secret> 헤더로 전송 |
| external-ui | string | 선택 사항, 외부 대시보드의 정적 리소스 디렉터리 |
자주 쓰는 엔드포인트（예시）
# 현재 설정 버전/상태 확인
GET http://127.0.0.1:9090/version
# 프록시 그룹의 선택 노드 전환
PUT http://127.0.0.1:9090/proxies/{group}
Body { "name": "HK-01" }
# 설정 다시 로드
PUT http://127.0.0.1:9090/configs?force=true
프로덕션이나 공개 인터넷 환경에서는 반드시 secret을 설정하고, 가능하면 127.0.0.1만 리스닝하세요. 컨트롤러 포트를 공개 인터넷에 노출하지 마세요.
설치가 끝났다면, 설정을 다듬어보세요
클라이언트를 다운로드하고 사용법 가이드에 따라 연결한 후, 다시 이 문서로 돌아와 규칙과 DNS를 커스터마이징하면 훨씬 수월합니다.