Clash Advanced Configuration Guide

Configuration model, load order and validation baseline

Separate the client, core and configuration source

Desktop and mobile clients in the Clash ecosystem manage subscriptions, edit configuration, request system permissions and render the interface. The core handles connections. Clash Plus, Clash Verge Rev, FlClash and Clash Nyanpasu may use compatible cores, but their subscription overrides, configuration merging and external interfaces can differ. First identify the layer involved: downloading and installation belong to the client layer, unrecognized YAML fields belong to the core or configuration layer, and an unavailable node belongs to the proxy path.

Configuration commonly comes from client-generated base fields, subscription nodes and policies, local user overrides, and runtime state. Runtime state includes the selected policy, cached rule sets and DNS mappings, and may not be written back to YAML. If a client regenerates configuration during subscription updates, direct edits to a temporary generated file may be lost. Long-term changes belong in the client's documented override, merge or script entry point.

Follow the path from ingress to egress

A connection typically passes through ingress detection, domain recovery or sniffing, rule matching, policy-group selection and proxy egress. With TUN enabled, system routes send traffic to a virtual interface first. With Fake-IP enabled, DNS may return a reserved address, after which the core restores the original domain from its mapping table. DOMAIN-SUFFIX, GEOSITE and domain rule providers need domain information, while IP-CIDR and GEOIP handle destination addresses.

Rules are evaluated in order and stop at the first match. Specific domains, service rules and blocking rules should appear before broad regional rules, while MATCH belongs at the end. A policy group is a rule target; it does not match traffic by itself. If a rule contains DOMAIN-SUFFIX,example.com,Work-Traffic, the configuration must define a policy group or proxy with exactly that name.

Build the smallest working configuration

Do not begin with a template containing hundreds of lines. Keep one listening port, one node source, one manual selection group and one fallback rule. Confirm that it loads and connects before adding rule providers, DNS and TUN. The following skeleton shows the references between fields. The reserved example address is structural only and cannot establish a proxy connection.

mixed-port: 7890
mode: rule
log-level: info
allow-lan: false

proxies:
  - name: Example-Node
    type: socks5
    server: proxy.example.com
    port: 1080

proxy-groups:
  - name: Manual
    type: select
    proxies:
      - Example-Node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Manual
  - MATCH,Manual

Check indentation first. YAML uses spaces for hierarchy; tabs, inconsistent indentation and a missing space after a colon can cause parsing failures. Quote names containing colons, hashes, brackets or surrounding spaces. Use one list style consistently within a section. Boolean values are true or false, not interface labels such as “On” or “Off”.

Regression checks after configuration changes

After each change, test direct traffic, proxied traffic, a pure-IP connection and a local network service. A working browser does not prove every application works: browsers may use independent secure DNS or QUIC. Use system commands such as nslookup example.com and curl -I https://example.com to verify resolution and the command-line path. If the system proxy and TUN are both enabled, test with each one disabled separately to rule out duplicate takeover.

Configuration stability depends on rollback. Keep “last known good”, “current test” and “planned release” states instead of continually overwriting one file. When renaming a policy group, search rules, rule providers, nested groups and scripts for the old name. Before removing a proxy provider, confirm that no group references it through use.

Policy group types and practical combinations

select: keep the final choice manual

select is the basic policy-group type. It can contain nodes, DIRECT, REJECT and other policy groups. It does not run latency tests; it records the current choice. Use it for top-level policies such as “Main Egress”, “Work Traffic” and “Streaming”. Clients may save the selected state in runtime storage rather than the original configuration. If selection should survive restarts, enable the supported profile.store-selected option and ensure the client does not reset configuration on launch.

A top-level group should not contain hundreds of nodes directly. Organize latency tests, failover and regional nodes into child groups, then select those groups from the top level. Rules can depend on stable top-level names while subscription membership changes underneath them. Adding DIRECT is useful for temporary direct access, but it bypasses the proxy path.

url-test: select according to probe results

url-test periodically probes a URL and selects a node with acceptable response performance. The result describes the probe target, not every website or protocol. Use a stable URL with a small response body. A short interval increases background requests and battery use, while a long interval delays failover. tolerance reduces frequent switching between similar nodes; a larger value makes the current node easier to retain.

proxy-groups:
  - name: Auto Select
    type: url-test
    use:
      - main-provider
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true

  - name: Main Egress
    type: select
    proxies:
      - Auto Select
      - Failover
      - DIRECT

lazy: true delays tests until a group is actually used. If every node appears to time out, check whether the test URL is reachable, DNS is working, the system clock is correct and the protocol handshake is allowed before concluding that all nodes are unavailable. See the node timeout troubleshooting order.

fallback: priority order and failover

fallback focuses on availability and list order. It normally uses the first available item and moves to the next when the current item fails. Compared with url-test, it suits fixed primary and backup egress where source-region stability matters. Failover is not session migration: existing TCP connections generally need to be established again after an egress change.

load-balance: distribute connections, not bandwidth

load-balance distributes separate connections across nodes. It does not split one TCP connection across multiple lines to add their bandwidth. Services that require stable login state or source-address behavior should use destination-consistent hashing, select or fallback. Round-robin distribution suits independent short connections but may expose multiple egress addresses to one service.

Use filters to manage subscription nodes

Proxy providers can use filter, exclude-filter or a client regex to create regional groups. Match the naming actually used by the provider instead of assuming that every provider uses the same abbreviations. Inspect original node names first. A result with no matches leaves the group without selectable members. For multiple regional spellings, use a grouped expression such as (Hong Kong|HK). Exclude expiry and traffic-information entries separately so they do not enter test groups.

The core of policy-group design is stable references: rules point to a small set of fixed group names, while groups organize changing nodes. A common structure has “Main Egress” reference “Auto Select”, “Failover”, “Region Select” and “DIRECT”. Keep names meaningful, limit nesting to about three levels and avoid circular references.

Rule-provider management and matching order

Separate rule content from policy decisions

rule-providers loads rule collections from local files or remote URLs. It manages rule content, not node selection. The main configuration connects content to a decision with RULE-SET,Provider Name,Policy Group. The same provider can point to different groups in different configurations without changing the rule file.

Providers suit large domain categories, IP ranges and service lists that need independent updates. A few stable local rules are easier to audit directly in rules. Remote sources add download, cache and format variables, so critical local-network and fallback rules should remain in the main configuration.

behavior defines rule-file semantics

behavior: domain is for domain collections, behavior: ipcidr is for IPv4 and IPv6 ranges, and behavior: classical allows complete rule types such as DOMAIN-SUFFIX, PROCESS-NAME and IP-CIDR. The declared behavior must match the file content. Loading IP ranges as domains or classical rules as a plain domain list can cause parsing errors or missed matches.

Rule files may use YAML, plain text or a supported binary format. Text is easier to inspect and compare; binary formats may load more efficiently. Confirm that the target core recognizes the selected format before migrating a configuration.

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/private-domain.yaml
    url: https://rules.example.com/private-domain.yaml
    interval: 86400

  service-rules:
    type: http
    behavior: classical
    format: yaml
    path: ./rules/service-rules.yaml
    url: https://rules.example.com/service-rules.yaml
    interval: 86400

rules:
  - DOMAIN,router.local,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-rules,Main Egress
  - GEOIP,LAN,DIRECT,no-resolve
  - MATCH,Main Egress

path is the local cache location and must be unique for each provider. The directory needs write permission. interval is measured in seconds; frequent updates are not always better. For slowly changing business rules, daily updates are generally more reliable than refreshing every few minutes.

Rule order matters more than rule count

The core matches from top to bottom. Private networks, LAN domains and required direct-access addresses belong near the top. Specific service rules should precede broad regional collections, and blocking rules must appear before generic rules that might allow the same traffic. MATCH handles only connections that matched nothing earlier.

Domain rules usually do not need an IP lookup. IP rules may trigger resolution; use no-resolve where supported when the target address is already known. Do not apply it mechanically: if a connection provides only a domain and the rule needs the resolved IP, disabling resolution removes the match condition.

Local rule-provider structure and testing

YAML rule providers commonly use payload as the list entry. A domain provider stores domain patterns, while a classical provider stores complete rules. Before updating, validate one file and then test it through the main configuration. If a provider downloads successfully but never matches, check its name, behavior, rule order and whether the connection still includes domain information.

payload:
  - DOMAIN,api.example.com
  - DOMAIN-SUFFIX,assets.example.com
  - PROCESS-NAME,example-client
  - IP-CIDR,192.0.2.0/24,no-resolve

When a remote source fails, the core may keep an existing cache or may have no rules on first load. Important access-control rules need a local baseline. For subscription URL and configuration parsing recovery, see the recovery procedure.

Maintainable names and change records

Provider names should describe their content, such as work-domain and private-cidr, rather than “rule1” or “latest”. Group names may target interface users; provider and path names are better kept as stable ASCII to reduce cross-platform and script differences. Treat changes to a remote URL, behavior or format as structural changes: clear the related cache and test again.

The objective is not the largest rule count but clear responsibility at every layer. When a match is unexpected, locate the first matching rule in the log and then inspect its provider. For complete routing between direct, proxied, blocked and fallback traffic, continue with the rule-routing guide.

DNS optimization and split resolution

DNS determines what the rule engine can see

DNS configuration is more than changing resolvers. It affects the resolution path, whether domains remain available for rules, Fake-IP mappings and how proxy server addresses are resolved. When a node works but pages do not, the browser works while command-line tools fail, or one domain repeatedly selects different policies, inspect DNS as an independent path.

nameserver handles normal queries; default-nameserver resolves encrypted DNS server names and usually uses directly reachable IP resolvers; proxy-server-nameserver can resolve proxy node hostnames separately; nameserver-policy selects resolvers by domain. Support depends on the core, and clients may expose only part of it.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  respect-rules: true

  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8

  nameserver:
    - https://dns.google/dns-query
    - https://cloudflare-dns.com/dns-query

  proxy-server-nameserver:
    - 1.1.1.1
    - 8.8.8.8

  nameserver-policy:
    "geosite:private":
      - system

  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "stun.*.*"

The example shows relationships, not a universal resolver recommendation. Confirm reachability and privacy requirements on the current network. If an encrypted DNS endpoint is a hostname, the core still needs an initial resolver, which is the role of default-nameserver. With respect-rules, DNS follows routing rules; avoid creating a loop where choosing a policy depends on a DNS result that is not available yet.

redir-host and fake-ip

redir-host returns real IP addresses and behaves like traditional DNS. It is friendlier to applications incompatible with Fake-IP, but after resolution the domain may be lost and a pure-IP TUN connection may no longer match domain rules. fake-ip returns a mapped address from a reserved range. When the application connects to it, the core restores the domain and applies domain rules.

Fake-IP is neither a proxy address nor a public address. It represents a domain in the local mapping table. The application must return the connection to Clash. If system routing, a side router or security software captures the reserved range, the connection fails. Validate Fake-IP and TUN routing together.

When to use fake-ip-filter

LAN discovery, printers, casting, time synchronization, some voice applications and STUN-dependent software may need real addresses or special DNS responses. Add only the actual query domains to fake-ip-filter. Broad wildcards send too much traffic back to real resolution and weaken domain recovery. Identify the queried domain from logs before adding a narrow exception.

IPv6, caches and browser DNS

ipv6: false normally prevents the built-in DNS from returning AAAA records, but it does not completely disable IPv6 in the operating system. Browsers may also use independent secure DNS and bypass Clash DNS. Temporarily disable independent resolution, query the configured listener directly and clear system and browser caches when testing changes.

TUN takeover, Fake-IP mapping and platform limits

TUN and the system proxy cover different traffic

The system proxy depends on applications reading the operating-system proxy setting. TUN creates a virtual interface and routes more TCP, UDP and proxy-unaware application traffic to the core. Games, command-line tools and store applications that bypass the system proxy may not enter Clash at all. TUN expands coverage but introduces route, permission, DNS hijacking and LAN-access variables.

Verify ordinary system-proxy mode before enabling TUN. The recommended order is to confirm the node and policy, enable TUN without complex routing changes, verify normal web and command-line traffic, and then handle LAN, IPv6, application exclusions and strict routing.

tun:
  enable: true
  stack: mixed
  device: Clash
  auto-route: true
  auto-detect-interface: true
  strict-route: true
  dns-hijack:
    - any:53
    - tcp://any:53
  mtu: 1500

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

stack, auto-route and strict-route

stack selects the network stack used to process TUN packets. System, user-space and mixed modes can behave differently across operating systems, client packages and protocols. Change only this setting at a time when testing UDP, LAN discovery or application failures. auto-route writes routes to send traffic to the virtual interface, auto-detect-interface identifies the real egress interface, and strict-route restricts bypass paths but may affect multi-homed systems, virtual machines and enterprise networks.

DNS hijacking and the Fake-IP range

dns-hijack sends common port-53 queries to the built-in DNS. It cannot automatically capture encrypted DNS inside an application. Other VPNs, filters and virtual-interface tools may compete for DNS and the default route; keep one takeover component active while testing. The Fake-IP range must be captured by TUN and must not conflict with a real enterprise, laboratory or virtual network range.

MTU and stalled transfers

An MTU that is too large can cause fragmentation or path-MTU problems: handshakes succeed but large pages, uploads or certain protocols stall. An MTU that is too small adds overhead. Test small requests, large responses, uploads and UDP, and adjust gradually rather than choosing an extreme value immediately.

Platform differences

Windows and macOS commonly require administrator permission or a network-extension authorization for TUN. Android and iOS use system VPN interfaces and often allow only one such connection at a time. Linux requires a TUN device, route permissions and compatible firewall rules. Remote servers should retain an out-of-band management path so a route change cannot lock out administration.

Client capabilities determine whether application exclusions, route bypasses and automatic recovery are available. See the download page for platform entries; Clash Plus is a broad cross-platform option, while desktop users can compare Clash Verge Rev, FlClash and Clash Nyanpasu. Clash for Windows and ClashX Meta may help with legacy environments but should not be relied on for new core features.

LAN, virtual machines and containers

Private networks generally need early direct rules and matching system routes. GEOIP,LAN,DIRECT alone may not be enough if the operating-system route sends traffic to the wrong interface before rule evaluation. Check routes, TUN exclusions and Clash rules together. When allow-lan is enabled, restrict trusted networks with the firewall and keep a management path outside the changed route.

Domain sniffing, configuration and false-match control

Use sniffing to recover domain information

Some connections enter the core with only a destination IP. Domain sniffing extracts a name from HTTP Host, the TLS ClientHello server name or recognizable QUIC handshake metadata, then uses it for rule evaluation. It is not DNS and does not decrypt HTTPS content; it reads metadata visible during connection setup. Sniffing can improve domain-rule matching in TUN and transparent-proxy scenarios, but it cannot reliably recover a name from every protocol.

Limit protocols and ports and exclude known-incompatible services. More sniffing is not always better: special encapsulation, encrypted client greetings and pure-IP services can produce no reliable domain, while an incorrect override can send a working connection to the wrong rule.

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true

  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: true
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443
        - 8443

  force-domain:
    - "+.example.com"

  skip-domain:
    - "Mijia Cloud"
    - "+.push.example.com"

parse-pure-ip attempts protocol parsing for pure-IP targets. force-dns-mapping cooperates with DNS mappings, while override-destination allows a successful sniff result to influence the destination used for later decisions. Field details vary by core, so inspect the final generated configuration when both interface settings and hand-written sections exist.

HTTP, TLS and QUIC visibility

Plain HTTP commonly exposes its domain in the Host header, while TLS normally exposes the server name during the handshake. IP-only connections, hidden server names and non-standard handshakes may provide no usable domain. QUIC uses UDP, so TUN and the node path must support the required UDP traffic. Port lists should reflect actual services; adding every port increases false positives and processing cost.

force-domain and skip-domain

force-domain prioritizes sniffing for selected domain patterns. skip-domain excludes unstable or incompatible connections whose destination should not be overridden. A pattern such as +.example.com commonly includes the root domain and its subdomains. Add exceptions only when a reproducible failure justifies them.

If an application fails after sniffing is enabled, compare behavior with sniffing disabled and inspect the extracted domain in the connection log. If the result is wrong, add a narrow skip entry. If no domain was extracted, return to DNS, rules and IP routing; adding more forced domains cannot create missing information.

Coordinate sniffing with rule order

A successful sniff only gives the rule engine a domain; it does not guarantee the desired policy. Earlier IP, process or broad rules may still match first. Inspect the destination domain, address, matched rule and policy in the log rather than looking only for “sniff success”. Process-rule support differs by platform, so use domain rules as the stable foundation.

Enable protocols gradually

Start with TLS on port 443 and observe common websites and applications. Add HTTP and QUIC only after the baseline is stable. Test direct, proxied, LAN and long-lived connections after each addition. Sniffing is most valuable when transparent takeover has lost domain information; it should not be used to guess every destination.

Local overrides and multiple subscriptions

Confirm the client's merge layers

Multiple subscriptions are usually merged by the client rather than by one universal Clash field. A client may provide base configuration, global and subscription-specific overrides, JavaScript preprocessing or a visual merger. Execution order matters: later scalar values usually replace earlier ones, mappings may merge recursively, and arrays may replace, append or deduplicate by name.

Export the configuration delivered to the core and test a small merge before migrating a complete setup. Clash Plus is a broad cross-platform option; Clash Verge Rev, FlClash and Clash Nyanpasu provide different desktop subscription workflows. When moving between clients, migrate standard YAML first and rebuild client-specific merge logic afterward.

Scalars, mappings and arrays

mixed-port, mode and log-level are scalars. dns and tun are mappings. proxies, proxy-groups and rules are arrays and are the most error-prone. A short override can accidentally remove every subscription rule if the merger replaces arrays. A fallback rule appended after the subscription's MATCH may never run.

# Local baseline override: stable scalars and mappings only
mode: rule
log-level: info
ipv6: true

profile:
  store-selected: true
  store-fake-ip: true

dns:
  enable: true
  enhanced-mode: fake-ip

tun:
  auto-route: true
  auto-detect-interface: true

This fragment is suitable for a client that supports recursive mapping merge, but the final YAML must confirm whether other DNS fields remain. Any merge tool that cannot show the final result should not be used for production configuration.

Separate node sources

Two subscriptions may contain identical node names. Direct merging can confuse selection, health checks and saved state. Add stable source prefixes during merging and update group references with them. Avoid expiry dates and traffic counters in prefixes, because every update would create new node identities.

Keeping multiple proxy-providers is often clearer than expanding everything into one large array. Groups can reference each source with use, while update intervals, health checks and filters remain independent.

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

  backup:
    type: http
    url: https://sub.example.com/backup.yaml
    path: ./providers/backup.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: Primary Subscription
    type: select
    use:
      - primary
  - name: Backup Subscription
    type: fallback
    use:
      - backup
    url: https://www.gstatic.com/generate_204
    interval: 600

Sensitive fields and configuration distribution

Subscription URLs, external-control secrets and node credentials should not be copied into public repositories, screenshots or online formatting tools. Keep reusable rules and overrides separate from local subscription and authentication data. Use controlled private storage for device synchronization. Example addresses only show structure.

External rules should define which targets belong to a category, while local configuration defines which policy handles that category. Separating these responsibilities reduces conflicts when changing subscriptions or clients.

Post-update checklist

After every subscription update, check provider status and node count, confirm that top-level groups still have members, verify saved selections point to existing nodes, and ensure all rule references remain complete. Then confirm that DNS, TUN and the external control interface still match local expectations. If preprocessing fails, the client should reject the new configuration instead of applying a partial merge.

External control, dashboard access and security boundaries

The control interface is not a proxy port

external-controller provides runtime status, policy switching, connection management, logs and configuration reloads. It is not an HTTP or SOCKS proxy port. Dashboards use it to read groups and send control actions, so it should be exposed only to trusted networks.

Listening on 127.0.0.1 limits access to local programs. Listening on 0.0.0.0 binds every available interface and requires a strong secret plus firewall restrictions. Without a remote-management need, keep the interface local.

external-controller: 127.0.0.1:9090
secret: "change-this-secret"

# Enable when dashboard files are supplied by a client or local deployment
external-ui: ./dashboard

profile:
  store-selected: true
  store-fake-ip: true

The example secret is structural only. Generate an unpredictable local value and do not reuse it for subscriptions, system logins or other services. If a dashboard returns unauthorized, check its credentials and confirm that another configuration is not overwriting secret at startup.

Dashboard connection flow

A dashboard needs the control address and authentication secret. If the page loads but shows no data, separate static-page loading from API access. The latter depends on the address, authentication, browser origin restrictions and network reachability. From another device, 127.0.0.1 refers to the browser's device, not the host running Clash. Use the trusted LAN address and firewall restrictions instead; do not expose the control port directly to the public Internet.

Read-only status checks

Start with read-only information: configuration mode, policy groups, core logs, active connections and listening ports. Multiple clients or cores may compete for a port, and a dashboard may connect to an old instance. Confirm the target through process information, listener state and log start time. Existing connections do not all migrate after a policy change.

Reloads and runtime state

Validate configuration before reloading it through the interface. Whether policy selection, Fake-IP mappings and provider caches survive depends on core state and configuration. profile.store-selected saves policy selection, while profile.store-fake-ip saves mappings. Changing the Fake-IP range or configuration directory should be expected to rebuild these states.

After a reload, verify proxy ports, control address, DNS and TUN. Changing the control address disconnects the current dashboard. Changing a proxy port may leave the system proxy pointing at the old port. A complete restart is often more deterministic than repeated hot reloads when listeners, virtual interfaces and routes are involved.

Log levels and diagnosis

silent, error, warning, info and debug provide different detail levels. Keep info for daily use and switch temporarily to debug for DNS, sniffing or rule diagnosis. Logs may contain domains, LAN addresses and node names; remove sensitive information before sharing them.

Follow one connection through time: ingress, target domain or address, matched rule, policy chain, actual node and final error. A final “timeout” line alone is not enough; the failure may be in DNS, node handshake, proxy-to-target transport, UDP forwarding or application response handling. See Troubleshooting for classification by ingress, resolution, rules and egress.

Minimum safe exposure

Bind the control interface only where needed, expose proxy ports only to required devices, and evaluate allow-lan separately from control access. A device allowed to use the proxy does not necessarily need to switch policies or inspect connections. Restrict the control port by source address and use a separate secret for the dashboard.

Repeatable change process

Export the working configuration, change one functional area, validate YAML and references, start a test configuration, verify direct access, proxying, DNS, TUN and control access, then replace the production configuration. Repeat the key checks after subscription updates and keep a rollback copy. Return to the user guide for first connection steps and the download page for clients and platforms.