홈/설정 레퍼런스

Clash 설정 파일 완전 레퍼런스

config.yaml은 Clash의 유일한 "두뇌"입니다. 이 글에서는 최상위 항목을 하나씩 분석해, 각 항목이 어떤 타입인지, 기본값은 무엇인지, 언제 변경해야 하는지 설명합니다. 사전을 찾듯이 참고하면 소스 코드를 읽는 것보다 훨씬 빠르게 답을 찾을 수 있습니다.

🕒 북마크해두고 필요할 때 참고하세요 🧭 동작 차이에 대해서는 고급 설정을 참고하세요 🔄 최근 업데이트: 2026년 7월

기본 네트워크 항목

이 항목들은 Clash가 로컬에서 어떤 포트를 수신 대기하고 어떤 방식으로 트래픽을 받을지를 결정하며, 거의 모든 설정에서 사용됩니다.

portnumber기본값: 없음

HTTP 프록시 수신 포트, 예: 7890. 시스템 프록시를 설정하면 HTTP/HTTPS 트래픽이 모두 이 포트로 전달됩니다.

socks-portnumber기본값: 없음

SOCKS5 프록시 수신 포트. 일부 도구(다운로드 매니저, 커맨드라인 프로그램)는 SOCKS5만 지원하므로 이 포트를 별도로 설정해야 합니다.

mixed-portnumber기본값: 없음

혼합 포트로, 하나의 포트에서 HTTP와 SOCKS5 연결을 동시에 받습니다. 최신 클라이언트는 보통 이 포트 하나만 설정하면 되므로 port와 socks-port를 따로 작성하는 것보다 간편합니다.

allow-lanboolean기본값: false

같은 네트워크 내 다른 기기가 본기의 IP를 통해 이 프록시 포트에 연결하도록 허용할지 여부입니다. 스마트폰으로 컴퓨터에서 실행 중인 Clash에 연결하고 싶다면 활성화해야 하며, 낯선 기기가 무단으로 사용하는 것을 막기 위해 아래의 authentication과 함께 사용하는 것을 권장합니다.

bind-addressstring기본값: *

프록시 포트가 바인딩되는 네트워크 인터페이스 주소로, *는 모든 인터페이스에서 수신 대기함을 의미합니다. 일반적으로 수정할 필요가 없습니다.

실행 모드와 로그

moderule | global | direct기본값: rule

rule은 rules 목록에 따라 라우팅합니다(일상적인 사용에 권장). global은 모든 트래픽을 동일한 프록시 그룹으로 강제 전달하며 임시 디버깅에 자주 사용됩니다. direct는 모든 트래픽을 직접 연결로 처리해, 프록시를 끈 상태에서 클라이언트만 실행 중인 것과 같은 효과를 냅니다.

log-levelsilent | error | warning | info | debug기본값: info

로그의 상세 수준입니다. 연결 문제를 진단할 때는 일시적으로 debug로 변경해 각 규칙의 구체적인 매칭 과정을 확인할 수 있습니다. 평소에는 info로 유지해 로그 파일이 빠르게 커지지 않도록 하는 것이 좋습니다.

ipv6boolean기본값: false

IPv6 지원 활성화 여부입니다. 사용 중인 네트워크와 일부 노드가 IPv6를 네이티브로 지원한다면 활성화하여 호환성을 높일 수 있습니다. 확실하지 않다면 네트워크마다 IPv6 지원 수준이 크게 다르므로 비활성화 상태로 두는 것이 안전합니다.

외부 컨트롤러와 패널

external-controllerstring예: 127.0.0.1:9090

RESTful API 수신 주소를 엽니다. 함께 제공되는 웹 관리 패널(대시보드)은 이 인터페이스를 통해 프록시 상태, 연결 목록, 실시간 트래픽을 읽어옵니다. GUI가 있는 대부분의 클라이언트는 이 항목을 자동으로 설정해 줍니다.

secretstring기본값: 비어 있음

external-controller 인터페이스에 접근하는 데 필요한 키입니다. allow-lan이 켜져 있고 패널이 LAN에 노출되어 있다면, 반드시 키를 설정해야 합니다. 그렇지 않으면 LAN 내 누구나 프록시 설정을 읽고 수정할 수 있습니다.

proxies: 노드 정의

proxies는 목록 형태이며, 각 항목은 하나의 구체적인 프록시 노드를 설명합니다. 항목은 프로토콜에 따라 달라지지만 다음과 같은 공통 항목을 모두 포함합니다.

항목	설명
`name`	노드 표시 이름으로, 규칙과 프록시 그룹에서 참조하는 것이 바로 이 이름입니다
`type`	프로토콜 유형: `ss` / `vmess` / `trojan` / `socks5` 등
`server`	서버 주소(도메인 또는 IP)
`port`	서버 포트
기타 항목	프로토콜마다 다릅니다. 예를 들어 Shadowsocks는 `cipher`와 `password`가 필요하고, VMess는 `uuid`와 `alterId`가 필요합니다

config.yamlyaml

proxies:
  - name: HK01
    type: ss
    server: hk01.example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

  - name: JP01
    type: trojan
    server: jp01.example.com
    port: 443
    password: "your-password"
    sni: jp01.example.com

구독 링크가 표준 형식이라면 클라이언트가 이 부분을 통째로 자동 해석해주므로 보통 직접 작성할 필요가 없습니다. 다만 구조를 이해해두면 "특정 노드에 연결이 안 될 때" 어떤 항목이 원인인지 파악하는 데 도움이 됩니다.

proxy-groups: 스케줄링 그룹

4가지 유형(select / url-test / fallback / load-balance)의 동작 차이는 고급 설정에서 자세히 다뤘으므로, 여기서는 자주 쓰이는 범용 항목 몇 가지를 보충합니다.

항목	적용 대상	설명
`proxies`	그룹에 포함된 구체적인 노드 또는 하위 그룹의 이름 목록	그룹에 포함된 구체적인 노드 또는 하위 그룹의 이름 목록
`use`	전체	`proxy-providers`의 원격 노드 집합을 참조해 노드 목록을 직접 작성하는 대신 사용
`url`	url-test / fallback / load-balance	헬스 체크에 사용하는 속도 측정용 주소로, 일반적으로 `generate_204` 같은 가벼운 엔드포인트를 사용
`interval`	url-test / fallback / load-balance	헬스 체크 간격(초)
`tolerance`	url-test	지연 시간 허용 오차(밀리초), 비슷한 지연 시간을 가진 노드 간 잦은 전환을 방지
`strategy`	load-balance	`consistent-hashing` 또는 `round-robin` 중 선택해 분배 알고리즘을 결정

rules: 라우팅 규칙

전체 규칙 유형 목록은 고급 설정 · 규칙 유형 상세 설명을 참고하세요. 여기서는 형식만 짚고 넘어갑니다. 각 줄은 쉼표로 구분된 세 부분 유형,값,동작입니다(MATCH만 예외로 두 부분).

config.yamlyaml

rules:
  - DOMAIN-SUFFIX,github.com,Auto
  - GEOIP,CN,DIRECT
  - MATCH,Auto

dns: 도메인 해석

항목별 상세 설명과 Fake-IP / Redir-Host 두 모드의 선택 기준은 고급 설정 · DNS와 Fake-IP를 참고하세요. 핵심 항목 빠른 참조:

항목	타입	설명
`enable`	boolean	내장 DNS 모듈 활성화 여부 (TUN 모드에서는 반드시 활성화해야 함)
`enhanced-mode`	fake-ip / redir-host	도메인 해석 전략, 고급 설정 비교 참고
`fake-ip-range`	string	Fake-IP가 사용하는 가상 주소 대역으로, 본기의 LAN 대역과 충돌하지 않아야 함
`nameserver`	string[]	기본으로 사용하는 상위 DNS 서버
`fallback`	string[]	결과가 신뢰할 수 없다고 판단될 때 사용하는 보조 DNS
`fallback-filter`	object	`fallback`을 언제 활성화할지 결정하는 조건, 예를 들어 `geoip-code` 기준 판단

tun: 가상 네트워크 어댑터

내부 동작 원리는 고급 설정 · TUN 모드 내부 동작 원리를 참고하세요. 핵심 항목:

항목	타입	설명
`enable`	boolean	TUN 모드 활성화 여부
`stack`	system / gvisor	네트워크 스택 구현 방식, 고급 설정 비교 참고
`auto-route`	boolean	시스템 라우팅 테이블을 가상 어댑터로 자동 설정할지 여부
`auto-detect-interface`	boolean	물리 네트워크 인터페이스를 자동 감지해 출구 인터페이스를 수동 지정할 필요가 없도록 함
`dns-hijack`	string[]	가로채 처리해야 할 DNS 요청 주소 범위

profile: 캐싱 전략

profile.store-selectedboolean기본값: false

활성화하면 select 유형 프록시 그룹에서 수동으로 전환한 노드가 기억되어, 다음에 클라이언트를 시작하거나 구독을 업데이트해도 설정 파일에 적힌 기본 노드로 초기화되지 않고 마지막 선택이 유지됩니다.

profile.store-fake-ipboolean기본값: false

Fake-IP의 도메인-IP 매핑 관계를 캐싱할지 여부입니다. 활성화하면 재시작 후 매핑을 다시 만드는 오버헤드를 줄일 수 있지만, 아주 드물게 매핑과 실제 해석 결과가 일시적으로 일치하지 않을 수 있습니다.

최소 사용 가능 설정 예시

위 내용을 종합하면, 실제로 작동하는 최소 설정은 대략 다음과 같습니다(실제 사용 시 proxies는 보통 구독을 통해 자동 생성되므로 직접 작성할 필요가 거의 없습니다).

config.yamlyaml

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

proxies:
  - name: Node01
    type: ss
    server: example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: Auto
    type: url-test
    proxies: [Node01]
    url: "https://www.gstatic.com/generate_204"
    interval: 300

rules:
  - GEOIP,CN,DIRECT
  - MATCH,Auto

이 파일을 config.yaml로 저장하고 클라이언트에 가져오면 정상적으로 라우팅되는 최소 시스템이 완성됩니다. 이후 필요에 따라 dns, tun, rule-providers 등의 모듈을 하나씩 추가하면 됩니다.