Clash Advanced Configuration Manual

01Proxy Group Types in Practice

Proxy groups (proxy-groups) are the dispatch hub of the whole configuration. A matched rule usually doesn't point straight to a specific node — it points to a proxy group, and the group's type determines the actual traffic exit. Understanding how each group type behaves differently is the first step toward a config you can maintain long-term. The Clash core supports four common group types: select, url-test, fallback, and load-balance — each solving a different scheduling problem.

select: Manual Selection

select is the most basic group type — the exit is manually chosen by the user in the client UI. It does no speed testing or health checks; whatever you select stays selected until you change it or the node disappears from the subscription. This "does exactly what you tell it" behavior makes it a good fit for the outermost layer of a config, acting as a master switch: gather several functional groups, regional groups, and DIRECT into one select group named something like "Proxy Selector," point all rules at it, and daily switching becomes a single click in the UI.

A select group only requires three fields: name, type, and proxies. The proxies list can mix specific node names, other group names, and two built-in policies: DIRECT for a direct connection bypassing the proxy, and REJECT for outright blocking the connection. When referencing a group by name elsewhere, it must match the definition exactly — including spacing and case — otherwise you'll get a "group not found" error at startup.

url-test and fallback: Automated Scheduling

A url-test group periodically sends a lightweight HTTP request to every node in the group and picks the lowest-latency one as the current exit. Three parameters matter: url is the test target — convention is to use an address that returns a 204 status with an empty body, minimizing the traffic the test itself consumes; interval is the test period in seconds, commonly 300 — setting it too short causes excessive background requests; tolerance is the switch threshold in milliseconds — the core only switches to a new "best" node if it's faster than the current one by more than this margin. Without a tolerance, two nodes with similar latency can flip back and forth due to measurement jitter, causing the exit IP to change constantly.

A fallback group instead checks availability in the order the proxies list is written, and always uses the first node in the list that passes the check; when it fails, traffic moves to the next one, and switches back automatically once it recovers. Its core difference from url-test is what it optimizes for: url-test cares about "who has the lowest latency," while fallback cares about "who's listed first and still alive." That makes fallback a good fit for "primary line + backup lines" — put your most stable, most trusted node first, list backup lines after it, and traffic normally rides the primary node with a seamless switch when it fails.

load-balance: Load Balancing

A load-balance group spreads connections across multiple nodes in the group. When strategy is set to consistent-hashing, requests are hashed by destination domain so that connections to the same site consistently land on the same node — avoiding logged-in sessions breaking due to a changing exit IP. Set to round-robin, exits rotate per connection, spreading traffic more evenly but working poorly for session-sensitive sites. In practice, load balancing suits high-volume downloads or bulk scraping — use cases where the exit IP doesn't matter — and isn't recommended for services that need a stable login state.

Nesting Groups: A Structural Approach

A practical pattern is a two-layer structure of "functional groups referencing regional groups": first set up several url-test groups by region (e.g., "HK Auto," "Japan Auto"), then set up several select functional groups by purpose (e.g., "Streaming," "AI Services," "Fallback Selector") whose candidates are regional group names rather than specific nodes. That way, when subscription nodes are added, removed, or renamed, only the regional-group layer is affected — rules and functional groups don't need to change at all. Switching subscriptions only means rebuilding the regional groups. The one thing to avoid is a circular reference between groups — Group A referencing Group B while B references A back — the core will refuse to load and error out at startup.

proxy-groups:
  - name: Proxy Selector
    type: select
    proxies: [HK Auto, Japan Auto, Fallback, DIRECT]

  - name: HK Auto
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 60
    proxies: [HK-01, HK-02, HK-03]

  - name: Fallback
    type: fallback
    url: http://www.gstatic.com/generate_204
    interval: 300
    proxies: [HK-01, JP-01, SG-01]

  - name: Bulk Download
    type: load-balance
    strategy: consistent-hashing
    proxies: [HK-01, HK-02, JP-01]

02Managing Rules as Subscriptions

Writing thousands of routing rules directly into the main config file creates two long-term problems: the main config becomes bloated and hard to maintain — tweaking one rule means searching through thousands of lines — and rule data (ad domains, regional IP ranges) keeps changing over time, so anything hardcoded into the config is frozen at the moment it was written. rule-providers split rules into separate files that are pulled and refreshed on a schedule, leaving just a single reference line in the main config. This is the standard approach to rule management.

What Each rule-providers Field Means

Each provider is a named entry; here's what the core fields do. type set to http means the file is pulled periodically from a remote address; set to file means it's read from a local file with no auto-updates. url is the remote rule file's address; path sets the local cache path — if omitted, the core names the cache file automatically based on a hash of the URL; interval is the refresh period in seconds — 86400 is once a day, and since rule data doesn't change that often, there's rarely a need to go shorter.

behavior decides how the file's content is interpreted, and it's the field people misconfigure most often: domain means the file is a plain domain list, one per line (supports the +. wildcard prefix); ipcidr means the file is a list of IP ranges; classical means each line is a complete rule, and it can mix types like DOMAIN-SUFFIX, IP-CIDR, and PROCESS-NAME. If behavior doesn't match the file's actual content, rules can silently fail to match at best, or throw a loading error at worst. format declares the file format: yaml and text are the most broadly compatible; mrs is mihomo's binary format — small and fast to load, but it only supports the domain and ipcidr behaviors.

Referencing Providers in rules

Once a provider is defined, reference it in the rules section with RULE-SET,provider-name,group-name. For ipcidr-type rule sets, it's a good idea to append the no-resolve parameter: IP-based rules need the destination IP to match against, so if the connection target is a domain, the core would first perform a DNS lookup before comparing — no-resolve tells it to skip that lookup and treat domain-based connections as a non-match, moving on to the next rule. This avoids unnecessary resolution overhead and prevents extra real DNS lookups from being triggered under fake-ip mode.

rule-providers:
  ad-domains:
    type: http
    behavior: domain
    format: yaml
    url: https://example.com/rulesets/ad-domains.yaml
    path: ./ruleset/ad-domains.yaml
    interval: 86400
  cn-ip:
    type: http
    behavior: ipcidr
    format: mrs
    url: https://example.com/rulesets/cn-ip.mrs
    path: ./ruleset/cn-ip.mrs
    interval: 86400

rules:
  - RULE-SET,ad-domains,REJECT
  - RULE-SET,cn-ip,DIRECT,no-resolve
  - MATCH,Proxy Selector

Match Order and Update Troubleshooting

Rules are matched top to bottom; the first match wins and no further rules are evaluated — which means a rule set's position in the list is its priority. Put rejection rules (ads) first, precise domain rules ahead of broad IP rules, and always end with a MATCH catch-all — otherwise unmatched traffic behaves unpredictably. The most direct way to confirm which rule a given site actually hit is to open the control panel covered in Chapter 7 and check the rule column on the connection's entry.

Failed rule-set updates are a common issue. To troubleshoot: pulling the rule file itself requires network access — if the fetch URL can't be reached directly on your current network, a cold start (before any proxy is available) will fail to fetch it. The fix is to pick a mirror address that's reachable directly, or make sure the cache file already exists before the first launch. Next, check the core log for provider-related errors — a mismatched behavior or an incorrectly declared format are the usual culprits. As a last resort, manually delete the cache file at the path location and restart the core to force a fresh download.

03DNS Configuration and Optimization

Clash's built-in DNS isn't an optional add-on — it determines whether domain-based rules match correctly, how the fake-ip mapping is generated, and whether DNS queries bypass local interference. The default configuration works for most cases, but getting to "fast local resolution, accurate proxied results, zero leaks throughout" requires understanding what each field does.

Core Fields

enable: true turns on the built-in DNS resolver; listen sets the listening address and port — TUN mode's DNS hijacking forwards system queries here; enhanced-mode is a choice between fake-ip and redir-host, discussed in the next chapter. default-nameserver is an easily overlooked field: if the nameserver list below contains DoH addresses (like https://…/dns-query), those addresses are themselves domain names that need to be resolved first — that's exactly what default-nameserver handles, which is why it must be a plain IP address, never a domain, or you'd create a resolution deadlock.

nameserver is the primary resolver group, handling most domain lookups. Use encrypted DNS addresses that resolve reliably on a direct connection in your current network, to keep direct-traffic resolution fast and accurate. Plain-text DNS on port 53 works too, but on some networks plain queries can be tampered with by intermediary devices, so prefer DoH or DoT.

fallback and fallback-filter

The fallback group targets domains whose result from the primary resolver group might be tampered with. When both nameserver and fallback are configured, the core queries both concurrently, and fallback-filter decides which result to trust: geoip: true with geoip-code: CN means — if the IP returned by nameserver belongs to mainland China, the domain is treated as a domestic one whose result is trustworthy, and the nameserver answer is used; otherwise the domain is assumed to need resolution outside mainland China, and the fallback answer is used instead. The ipcidr sub-field lists known tampered-result ranges (such as the reserved block 240.0.0.0/4) — if nameserver returns an IP within these ranges, it's flagged as tampered and the fallback result is used instead.

The net effect: domains in mainland China get resolved by nearby domestic DNS, returning CDN-optimal IPs; domains outside mainland China get their results via the fallback group's encrypted channel, unaffected by local interference. Just make sure the encrypted DNS addresses in fallback are reachable whenever the proxy is available — otherwise the fallback side of the concurrent query keeps timing out, slowing down resolution overall.

nameserver-policy: Domain-Specific Resolution

nameserver-policy lets you assign specific domains to specific upstream resolvers, taking priority over the general nameserver/fallback logic. Two typical uses: corporate internal domains that must be resolved by an internal DNS server or they won't resolve at all; and certain major domestic sites sensitive to CDN scheduling, which get pinned to a specific domestic DoH provider to avoid uncertainty introduced by the concurrent-query mechanism. Keys support the +. wildcard prefix, matching both the domain itself and all subdomains.

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
  nameserver-policy:
    "+.corp.example.com": 10.0.0.53

Leak Verification

Once configured, actually verify it: connect through the proxy, visit a DNS leak test site, and check where the detected resolver is located — if domains outside mainland China still show up as resolved by your local ISP's DNS, that's a leak. Common causes are a manually set system DNS lingering somewhere, or a browser's built-in DoH setting bypassing Clash entirely. You can also bump the log level to debug and watch exactly which upstream each domain actually uses. For the full verification walkthrough and a breakdown of when to use each DNS mode, see the blog article "Clash DNS Configuration and Leak Prevention: A Practical Guide."

04TUN Mode and Fake-IP

How the Two Take-Over Approaches Differ

A system proxy essentially announces an HTTP/SOCKS port to the OS — whether anything actually uses it is up to each individual app: browsers and most GUI apps respect it, but plenty of command-line tools, some game clients, and system services never read that setting, and their traffic goes straight out unproxied. TUN mode takes a different route: the core creates a virtual network interface and points the system's default route at it, so every app's traffic gets intercepted at the network layer, with no cooperation required from any app. In short: a system proxy is "opt-in," TUN is "everything, no exceptions." For the full comparison of how the two work, see "How Clash TUN Mode and System Proxy Actually Work: A Comparison."

tun Section Fields

stack selects the protocol stack implementation: system reuses the OS network stack for the best performance; gvisor is a userspace stack with better compatibility and less system intrusion; mixed combines both — TCP over system, UDP over gvisor — and is a sensible default for most setups. auto-route automatically writes routing table entries to direct default traffic to the virtual interface; auto-detect-interface automatically identifies the real physical uplink interface — this one is critical, since it ensures the proxy node's own traffic exits through the physical interface rather than looping back into the virtual one. If detection fails or picks the wrong interface, traffic loops back on itself, showing up as an immediate loss of network connectivity right after enabling TUN. strict-route tightens routing rules to prevent some traffic from bypassing the virtual interface. dns-hijack intercepts queries sent to port 53 on any address and redirects them to the built-in DNS resolver — commonly written as any:53 — ensuring all system and app DNS queries flow through the resolution pipeline described in Chapter 3.

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

How Fake-IP Works, and fake-ip-filter

In fake-ip mode, when the built-in DNS receives a query, it doesn't perform a real lookup — instead, it hands out a fake IP allocated from fake-ip-range (the reserved block 198.18.0.1/16 by default) and internally records a "fake IP ↔ domain" mapping. When the app connects using that fake IP, the core reverse-looks-up the mapping the moment the connection arrives, instantly recovering the original domain and matching domain rules directly — skipping a real resolution round trip, so connections establish faster and domain rules match more reliably. Real resolution only happens when a direct connection is confirmed, or when it's handled remotely by the proxy server itself.

The trade-off: a handful of scenarios genuinely need a real IP to work. Local network device discovery, NTP time sync, some game launchers, and Windows' network connectivity probe will all misbehave if handed a fake address from the 198.18 block. fake-ip-filter is the whitelist built for exactly this — domains listed there fall back to real resolution and are excluded from the fake-ip mapping.

dns:
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - time.windows.com
    - "+.ntp.org"
    - "+.msftconnecttest.com"

Permission Differences by Platform

05Domain Sniffing

Why Sniffing Is Needed

Two kinds of traffic reach the core without any domain attached: apps that resolve DNS themselves and connect straight to an IP (some browsers with built-in DoH, and plenty of mobile apps with their own resolution logic, fall into this category); and forwarding paths under redir-host where domain info gets lost along the way. Without a domain, every domain-based rule simply falls through, leaving these connections to be handled by IP rules or the MATCH catch-all — noticeably hurting routing precision. Domain sniffing (sniffer) reads the domain back out of the traffic itself: the SNI field in a TLS handshake, the Host header in an HTTP request, and the handshake info in QUIC all carry the target domain. The core parses these protocol headers before forwarding, recovering the domain so it can participate in rule matching.

Configuration Fields

sniffer.enable turns sniffing on; under sniff, each protocol is configured separately: ports restricts which target ports get sniffed (443 is common for TLS, 80 for HTTP, and port ranges are supported), and override-destination set to true replaces the connection target with the sniffed domain for rule matching. force-domain lists domains that are always re-sniffed for confirmation even if the connection already carries a domain; skip-domain lists domains excluded from sniffing — the most common use is excluding mobile push-notification long-lived connections, since sniffing can interfere with keeping those connections alive and delay push delivery.

sniffer:
  enable: true
  sniff:
    TLS:
      ports: [443, 8443]
    HTTP:
      ports: [80, 8080-8880]
      override-destination: true
    QUIC:
      ports: [443]
  skip-domain:
    - "+.push.apple.com"

Working Alongside the Two DNS Modes

Under fake-ip mode, most domains are already recovered through the mapping reverse-lookup, so sniffing is a supplementary mechanism that specifically covers "app connects straight to IP" edge cases. Under redir-host mode, domains get lost much more often, making sniffing nearly mandatory — otherwise rule-match rates drop noticeably. Sniffing adds a small protocol-header-parsing cost to each new connection, negligible on typical hardware; if you have genuinely extreme performance requirements, you can narrow the ports range to only sniff standard ports. To check whether sniffing is working, use the connections page from Chapter 7 the same way: if the connection target shows up as a domain rather than a plain IP, sniffing successfully recovered it.

06Local Overrides and Multi-Subscription Merging

Why Overrides Matter

Refreshing a subscription essentially replaces your local file wholesale with the latest remote config — any rules you added by hand, DNS tweaks you dialed in, or TUN settings you enabled all get wiped out on the next update. Overrides separate "personal customization" from "subscription content": the subscription only supplies nodes, while rules, DNS, and TUN policy live in the override layer, which is automatically reapplied every time the subscription updates — the two sides never interfere with each other. The mainstream GUI clients listed on the Downloads page (Clash Plus, our top pick, along with Clash Verge Rev and others) all offer a graphical override interface, usually split into two forms: Merge and Script.

Merge Overrides: Declarative Merging

A Merge override is a block of YAML merged into the subscription config with fixed semantics: dictionary-type fields (like dns, tun, sniffer) fully replace the matching field from the subscription; list-type fields use the prepend- and append- prefixes to control where items go — prepend-rules inserts rules at the very top of the rule list (highest priority), while append-rules adds them to the end. Personal direct-connect exceptions and corporate internal domains go in prepend; your own catch-all fallback policy goes in append. This approach is declarative and easy to reason about, covering the vast majority of "add a few rules, tweak a DNS block" needs.

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - PROCESS-NAME,ssh,DIRECT
append-rules:
  - MATCH,Proxy Selector
dns:
  enable: true
  enhanced-mode: fake-ip
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

Script Overrides: Programmatic Modification

Merge can't handle "conditionally modify things in bulk" — that's where Script overrides come in: the client passes the parsed config object to a JavaScript function, which returns the modified object. Typical uses: auto-generating regional groups from a regex match on node names, so newly added region nodes in a subscription get auto-classified; adding a uniform interval and tolerance to every url-test group at once; or bulk-removing "fake nodes" a subscription sneaks in as expiry reminders. The script can use full JS syntax, but the function must ultimately return config and must not break the field structure, or the core will fail to load it.

function main(config) {
  config["proxy-groups"]
    .filter((g) => g.type === "url-test")
    .forEach((g) => {
      g.interval = 300;
      g.tolerance = 60;
    });
  return config;
}

proxy-providers: Merging Multiple Subscriptions

If you have several subscriptions, there's no need to switch configs back and forth in the client. proxy-providers works the same way as the rule providers from Chapter 2: declare each subscription as a node provider, have proxy groups reference one or more providers via the use field, and use filter to select nodes from the merged pool with a regex (say, only keeping nodes with "Hong Kong" in the name). This way one config schedules multiple subscriptions, and any single one failing doesn't affect the rest; the health-check sub-field lets each provider run its own periodic health checks, automatically skipping dead nodes.

proxy-providers:
  provider-a:
    type: http
    url: https://example.com/sub-a
    path: ./providers/a.yaml
    interval: 43200
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: HK Auto
    type: url-test
    use: [provider-a, provider-b]
    filter: "(?i)hk|hong ?kong|香港"

07External Controller API and Dashboards

Enabling the External Controller

The Clash core ships with a built-in RESTful control API — nearly every GUI client's interface and every web dashboard is really just calling into it under the hood. external-controller sets the listening address — use 127.0.0.1:9090 for local-only access; secret sets an access token that every request must carry in an Authorization: Bearer header; external-ui points to a static dashboard directory, which the core will serve directly — just open the listening address in a browser.

external-controller: 127.0.0.1:9090
secret: "replace with a sufficiently long random token"
external-ui: ./ui

Common API Calls

curl -H "Authorization: Bearer <secret>" \
  http://127.0.0.1:9090/proxies

curl -X PUT -H "Authorization: Bearer <secret>" \
  -d '{"name":"HK Auto"}' \
  "http://127.0.0.1:9090/proxies/Proxy Selector"

Using the Dashboard Day to Day

The connections page and logs page are where a web dashboard earns its keep. To figure out "why did this site go out the wrong exit," find the connection on the connections page and check its matched-rule and proxy-chain columns — which rule it hit, which group it went through, and which node it finally exited from, all at a glance. That's far faster than guessing your way through a config file. Bump the log level to debug on the logs page and you can watch each domain's DNS resolution path and rule-matching process in real time — a direct way to observe the DNS issues covered in Chapter 3.

One behavior detail worth knowing: switching proxy mode (Rule/Global/Direct) through the dashboard or client doesn't automatically close already-established connections — they keep running on whatever path they were set up with. If a mode switch seems to have "not taken effect," go to the connections page and close all connections, or restart the app in question. For how traffic flows differently under each of the three modes, see "Clash Rule Mode vs. Global Mode: Differences and When to Switch."

08Config Validation and Quick Troubleshooting

Validate Before You Reload

Validating a config before reloading it saves a lot of trial-and-error time. The CLI core provides syntax and semantic checks via mihomo -t -f config.yaml — success prints a confirmation, failure points to the exact line and reason. A few high-frequency YAML pitfalls: indentation must use spaces, and mixing in tabs breaks parsing; there must be a space after every colon; node or group names containing :, #, emoji, or other special characters need to be quoted; and there must be a space between a list item's - and its content. GUI clients usually run an equivalent check automatically when saving, and the resulting error message is worth reading carefully too.

mihomo -t -f config.yaml

Common Issues at a Glance

What's Next

This page covers the systematic, configuration-level knowledge. More conversational, high-frequency Q&A is organized in the FAQ, grouped into basics, setup, usage tips, and troubleshooting; proxy protocol, core, and rule terminology that comes up throughout this page can be looked up in the Glossary; and deep dives into single topics are published continuously on the blog. For the full step-by-step path starting from zero, head back to the Getting Started Guide.