Clash Advanced Configuration Guide: Rule Syntax, Providers, DNS & TUN Reference

config.yaml Structure Overview

A complete config file is made up of several top-level fields. Once you understand this table, every section below just expands on how to write one of these fields in detail:

Proxy Protocol Parameters

If you need to add nodes manually (instead of relying entirely on a subscription), here are the core parameters for several mainstream protocols under the proxies field:

Shadowsocks

The core fields are cipher (encryption method, e.g. aes-256-gcm, chacha20-ietf-poly1305) and password. Some nodes also include a plugin (like obfs or v2ray-plugin) for traffic obfuscation.

VMess

Requires uuid and alterId (usually 0 in newer setups); cipher is commonly auto. If the node has TLS enabled, you'll also need to set tls and servername (i.e. SNI).

Trojan

The core fields are password and sni. Trojan forces standard TLS by default, disguising traffic as regular HTTPS, so whether sni matches the certificate domain directly affects usability.

Hysteria2

Based on the QUIC protocol, with password and up / down (upload/download bandwidth hints) as core fields. Typically more stable than traditional TCP protocols on weak or high-latency connections.

WireGuard

The field style differs from the others: it needs a private-key, the peer's public-key, and an ip (this device's address within the WireGuard subnet). Configuration is fairly low-level and providers usually hand you a complete snippet directly.

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

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

  - name: "hy2-node"
    type: hysteria2
    server: example.com
    port: 443
    password: "your-password"
    up: "50 Mbps"
    down: "200 Mbps"

Complete Rule Syntax Reference

Rules follow a unified RULE-TYPE,MATCH-VALUE,TARGET-POLICY format, matched top to bottom, stopping at the first hit. Here's the full list of common rule types:

Provider Mechanics: Proxy Provider & Rule Provider

Providers are Clash's unified mechanism for managing "remote, auto-updatable" resources — a subscription link is essentially a Proxy Provider under the hood, and a rule set is a Rule Provider. Both support automatic periodic updates with no need to manually replace files.

proxy-providers:
  my-sub:
    type: http
    url: "https://example.com/api/v1/subscribe?token=xxx"
    interval: 3600
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 300

rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://example.com/rules/reject.txt"
    path: ./rules/reject.txt
    interval: 86400

Here, interval controls the auto-update period (in seconds), health-check has the client periodically batch-test the latency of nodes under the Provider, and behavior tells the client whether the rule set's content is a domain list (domain), an IP range (ipcidr), or full rules (classical).

Advanced Proxy Group Parameters

Besides the basic type and proxies, proxy groups have a few more advanced parameters worth knowing:

• lazy — When enabled for url-test / fallback groups, latency tests only run in the background once the group is actually in use, reducing resource usage while idle;
• tolerance — Latency tolerance (in ms). A new node only triggers a switch if its latency is lower than the current node's by more than this value, preventing frequent switching caused by latency-test jitter;
• strategy (for load-balance groups only) — the load-balancing strategy, commonly consistent-hashing (the same destination always routes through the same node, good for scenarios needing session persistence) or round-robin (nodes are cycled through in order);
• disable-udp — disables UDP forwarding for nodes in this proxy group; useful when certain nodes or routes don't handle UDP well.

Advanced DNS Configuration

Beyond simply toggling leak protection, DNS settings can also fine-tune resolution behavior:

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.google/dns-query
    - https://1.1.1.1/dns-query
  fallback:
    - https://1.0.0.1/dns-query
    - https://dns.quad9.net/dns-query
  nameserver-policy:
    "geosite:private": [192.168.1.1]
  fallback-filter:
    geoip: true
    geoip-code: US

enhanced-mode: fake-ip is the most common mode — the client assigns each domain a virtual IP, then resolves the real domain at the proxy layer, offering the best compatibility. nameserver-policy lets you specify which DNS group to use based on domain ownership — for example, resolving your home router or other LAN hostnames via your local router instead of a public resolver — while fallback-filter is used to judge whether a resolution result "looks" tampered with, and decide whether to re-query using the fallback list. Replace the placeholder geoip-code (US here) with your own country code, and swap the sample IPs/domains for whichever local DNS resolvers you actually use.

TUN Mode Parameters Explained

The core TUN mode parameters are as follows:

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

stack determines how the virtual adapter is implemented — system offers the best compatibility, while gvisor/mixed perform better in certain scenarios. When auto-route is enabled, the client automatically takes over the system routing table; auto-detect-interface lets the client automatically detect the active physical network interface, avoiding manual configuration; dns-hijack forcibly intercepts DNS requests over UDP port 53, preventing apps from bypassing the system DNS settings to query directly.

External Controller & RESTful API

Once external-controller is set, Clash exposes a RESTful API at the specified address. Paired with a dashboard-style client, you can view connections, switch nodes, and check latency in real time — no client restart required.

external-controller: 127.0.0.1:9090
secret: "your-strong-secret"

Performance & Security Recommendations

• Prefer referencing rule sets via RULE-SET instead of flattening hundreds of DOMAIN-SUFFIX entries directly into rules — the former matches faster and is easier to maintain;
• Place your most frequently hit, most specific rules near the top of the rules list to reduce the average number of match attempts;
• Avoid leaving log-level set to debug long-term — verbose logs continuously consume disk space and memory;
• Always set a secret for external-controller, and never reuse the same secret across multiple devices or platforms;
• Don't set the proxy group's latency-test interval too short — anywhere from tens of seconds to a few minutes is enough to catch node issues promptly; testing too often only adds extra load on nodes and local resources;
• Keep a separate backup of your custom overrides for rules and proxy groups, so you can quickly restore them after a subscription update or client reinstall.

FAQ