Clash Advanced Configuration Guide

Proxy Group Types and How They Work

A proxy group determines which node or route handles a connection that matches a rule. When troubleshooting routing, first check the group named in the rule, then see which member is selected. A node appearing available in the proxy list doesn't mean a connection will use it. A common setup puts nodes in a “Manual” group, has groups such as “Auto” and “Failover” reference those same nodes, then directs traffic rules to these higher-level groups. The group name must match the rule's target exactly, including capitalization and spaces. After a subscription update adds nodes, also check that your node filters still match the names you expect.

Four Selection Strategies

select lets you choose a member manually, which works well for logins or remote access that need a fixed exit. It won't switch nodes automatically based on test results. url-test selects a member based on its response time to a test URL, making it suitable for everyday browsing when changing exits is acceptable. fallback uses the first available member in the list, which is useful when you want to prioritize a primary route and switch only if it fails. load-balance distributes connections across members. If a site requires a consistent exit, avoid routing its login traffic through a load-balanced group. A successful test only means the test URL is reachable; it doesn't guarantee access to every site. For failures affecting one site, check the actual connection log.

Put nodes in groups you can verify

Assume the configuration already contains proxies named “Node A” and “Node B.” Replace them with the names provided by your subscription, and don't create two proxy groups with the same name. interval is measured in seconds. For auto selection, tolerance is the latency difference allowed before switching away from the current member, helping prevent frequent changes when results are close. Use a test URL that's reliably accessible on your network and returns a short response; avoid sites that require a login.

proxy-groups:
  - name: Manual
    type: select
    proxies:
      - Node A
      - Node B
      - DIRECT
  - name: Auto
    type: url-test
    proxies:
      - Node A
      - Node B
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
  - name: Failover
    type: fallback
    proxies:
      - Node A
      - Node B
    url: http://www.gstatic.com/generate_204
    interval: 300
rules:
  - DOMAIN-SUFFIX,example.org,Manual
  - MATCH,Auto

One easily missed detail: node tests run against group members, but actual requests are routed by rule matching first. If a DIRECT rule appears before the example domain rule, that request never reaches “Manual.” To diagnose, open “Connections” in the client, find the target domain and matched rule, and check which group the rule points to. Then open “Proxies” and check the group's members and selected member. If an existing connection still shows the old exit after a change, disconnect it and start a new request; established connections usually don't switch routes midstream.

Check the catch-all rule last. MATCH usually belongs at the end of the rule list; it handles traffic that didn't match any preceding rule. Put it earlier and the more specific rules below it won't take effect. To temporarily check whether a rule works, route a clearly identified domain to a manual group, start a new connection, and inspect its log instead of switching all traffic to Global mode. Remove the diagnostic rule afterward and restore the original order and selection so the change remains easy to track.

Manage Rules with Rule Providers

Rule providers move frequently changing domain or IP entries out of the main configuration. rule-providers defines their source, format, and local cache path, while rules uses RULE-SET to reference them. This avoids editing the main configuration every time rule content changes, but adds a loading chain: rules must be downloaded, parsed, cached, and referenced correctly. A failure at any step can prevent traffic from being routed as expected. First decide whether you need remote rules or a few local rules that rarely change. For just a handful of custom domains, adding them directly to rules is easier to maintain.

Match the Rule Set's Content Format

Use behavior: domain for domain entries, behavior: ipcidr for IP ranges, and behavior: classical for full classic rule expressions. format: yaml and format: text must match the downloaded content; the file extension alone isn't enough. A YAML rule set generally lists entries under payload, while a classic rule set can contain type prefixes such as DOMAIN-SUFFIX. Loading classic rule text as a domain rule set, or caching a web error page as a rule file, will cause parsing to fail. Before referencing a remote URL, check in a browser that it returns rule content, not a login page or a redirect to an information page.

This example uses a documentation domain to show how the fields relate; the URL isn't a usable rule source. Replace it with a rule set URL you trust, and set behavior and format to match that file. Use a relative path under the configuration directory for the cache, and give each provider its own file. interval controls how often updates are checked; it doesn't trigger a download for every request.

rule-providers:
  work-domains:
    type: http
    behavior: domain
    format: yaml
    url: https://example.com/rules/work-domains.yaml
    path: ./rules/work-domains.yaml
    interval: 86400
rules:
  - RULE-SET,work-domains,Manual
  - DOMAIN-SUFFIX,example.org,DIRECT
  - MATCH,Auto

A matching work-domains.yaml file could look like this. List domain entries in the domain rule set; don't repeat the proxy group name used in the main configuration's rules list on every line. The RULE-SET rule that references the provider specifies the exit. A rule set can be referenced by multiple rules, but check their order: once an earlier rule matches, later rules aren't considered.

payload:
  - example.net
  - '+.example.org'

Troubleshoot the Loading Chain

After an update, check whether the client reports a rule set download or parsing error, then confirm the cache file exists and still uses the expected format. If the file downloads but the rules don't take effect, check the provider name in RULE-SET, the referenced proxy group name, and the rule's position in rules. Domain rules need domain information to match; a connection identified only by IP may not match a domain rule as expected. For IP rules, also consider DNS resolution and how options such as no-resolve affect matching. Don't change all your DNS settings just to make one rule match.

Subscriptions may provide rules and rule sets of their own. If the client overwrites the main configuration every time a subscription is updated, editing the downloaded file is only a temporary fix. Use the client's override feature or maintain a configuration with a fixed rule source. When migrating rules, start with one domain you can verify. After reloading, confirm in “Connections” that it matched the new RULE-SET, then migrate the remaining entries. Don't enable two overlapping remote rule sets with unclear priority at the same time; first determine which takes precedence and which handles unmatched traffic.

DNS Configuration and Resolution Paths

DNS settings affect two different things: how target domains are resolved and how the proxy server's own domain is resolved. First establish whether the client's DNS handling sees the queries sent by your browser, then review the resolver list. A system proxy typically handles an application's HTTP or SOCKS traffic, but that doesn't mean it handles every DNS query on the system. TUN mode and DNS hijacking provide a separate path. If a domain resolves but won't connect, also check rule matching, node reachability, and connection logs. “The page won't load” alone isn't enough to diagnose a DNS problem.

Know the Key DNS Server Fields

default-nameserver is mainly for bootstrap lookups, such as resolving the domain names of DNS servers themselves; use IP addresses that are directly reachable. nameserver lists servers for regular queries. proxy-server-nameserver lets you choose a separate resolver for proxy node domains, so their resolution isn't affected by domain-based routing settings. nameserver-policy selects resolvers by domain. Don't confuse server URLs, plain IP addresses, and addresses with ports. The protocol format you enter must be supported by the current core, and the upstream must be reachable from the relevant network.

This snippet shows a minimal division of responsibilities; you don't need to replace all your resolvers with the example addresses. Before enabling it, check that these addresses are reachable on your network, especially on restricted networks or where internal DNS is needed for work domains. Evaluate options such as respect-rules, which further affect DNS routing, only after basic resolution is working. This helps avoid circular dependencies between resolvers and proxy node lookups.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  proxy-server-nameserver:
    - 1.1.1.1
  fake-ip-filter:
    - '*.lan'
    - localhost.ptlogin2.qq.com

ipv6: false is an example setting, not a recommendation to disable IPv6 on every network. If your device, upstream resolvers, and proxy route all support IPv6, decide based on your actual needs. fake-ip-filter returns real DNS results for selected domains, which can help with LAN discovery or apps that don't work with Fake-IP. The more entries you add, the more important it is to make sure they don't bypass your intended matching path. Internal domains should be resolved by an internal DNS server that knows those domains, not by a public resolver expected to return LAN addresses.

Trace the Problem with One Request

First confirm that the client's DNS feature is enabled. Reload the configuration and check the logs for errors indicating an unreachable upstream. Then start a new connection to the target domain and note whether it gets a real address, a Fake-IP, or no response. If the query doesn't appear in the client logs, check whether the app uses its own secure DNS, whether the system still points to a different resolver, and whether the current proxy mode handles that kind of request. If the query is logged but the result is unexpected, check the matching nameserver-policy entry, Fake-IP filters, and local cache. After changing the configuration, clear the cache using the client's supported method before testing again so an old result isn't mistaken for the new one.

A successful DNS response doesn't guarantee that the connection will work. Test with a domain and exit policy you know, then check the final rule in “Connections.” If the connection matches DIRECT, continue troubleshooting the direct network path. If it matches a proxy group, check that group's nodes. Work networks often need to preserve internal domain resolution: note the current DNS settings first and change them one at a time. Don't change DNS, rules, and TUN simultaneously; that way, you can identify which change introduced the problem.

Using TUN Mode with Fake-IP

System proxy and TUN cover different traffic. A system proxy relies on apps following the operating system's proxy settings. TUN creates a virtual network interface that can route more traffic through the client, including traffic from apps that don't use those settings. TUN won't automatically solve every problem: route installation, DNS hijacking, other VPNs, LAN access, and system permissions all affect the outcome. Before enabling TUN for the first time, confirm that connections work through the regular system proxy and note the current DNS and routing state. If something breaks after enabling TUN, you'll be able to tell whether it was an existing issue or a problem with the new traffic path.

Start with a Minimal Configuration

auto-route asks the core to configure routes, while auto-detect-interface identifies the active outbound interface. Devices whose network interfaces change often should check that detection is accurate. any:53 under dns-hijack handles eligible traditional DNS queries, but it can't guarantee interception of encrypted DNS connections created directly by an app. Some clients write these fields through UI switches; others require permission to create a network extension or virtual interface. Check the effective configuration shown by the client, not just the switch state.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

stack: mixed is one network stack option you can test. If an app's handshake or LAN access fails, note the symptoms and compare other stacks supported by the client rather than changing every routing option at once. On devices with a corporate VPN, another transparent proxy, or a virtual machine bridge, watch for route priority and interface conflicts. If two tools both try to take over the default route, connections may keep dropping or traffic meant for the LAN may use the wrong exit. Temporarily disable the other routing tool for comparison, then decide whether to exclude routes or change interfaces.

Understand How Fake-IP Mapping Works

Fake-IP doesn't immediately resolve a domain to its real address. Instead, it gives the app a synthetic address and keeps a mapping between the domain and address in the core. When the connection arrives, the core uses that mapping to recover the domain so domain rules can be matched. This depends on the DNS query and subsequent connection following paths the client can associate. If an app uses a different DNS route or has cached an old address, the domain and connection may not line up. If an app shows only an IP and fails to match domain rules, first compare its DNS queries with its connections in the logs.

LAN device discovery, printers, screen casting, and some apps that require real addresses may not work well with Fake-IP. Add filter entries for specific domains first, then test discovery and connectivity; avoid broadly excluding entire domain suffix lists. If LAN IPs remain unreachable, check whether rules send private addresses through a proxy group, and review the operating system's firewall and local network permissions. Fake-IP filters only affect DNS results; they don't replace routing rules. Once troubleshooting is complete, test a browser, an app that ignores the system proxy, and a LAN service to confirm that TUN handles the traffic you need without breaking local access.

Domain Sniffing and Rule Matching

When the client sees only a destination IP but needs a domain to choose a route, domain sniffing can try to extract the domain from the connection handshake. It mainly checks information visible in HTTP requests or TLS and QUIC handshakes; it doesn't read web page content and can't reveal the original domain for every encrypted connection. Whether a sniffed domain replaces the connection target or affects routing depends on the relevant options. Before enabling sniffing, check “Connections.” If the full domain is already visible and rules match correctly, there's no need to broaden sniffing just to display more domains.

Limit Protocols and Ports

This example covers common HTTP, TLS, and QUIC entry points. ports limits the ports to inspect, and override-destination determines whether the destination is replaced with the sniffed result. Keep only ports used by the app, then test connections that are failing. QUIC uses UDP; if your network or client doesn't handle the relevant UDP traffic, adding a QUIC sniffing entry alone won't route those connections through the core. The same applies to HTTP on nonstandard ports: check each actual service port.

sniffer:
  enable: true
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: true
    TLS:
      ports:
        - 443
    QUIC:
      ports:
        - 443
  skip-domain:
    - '+.lan'

The example skips LAN domains to avoid extra checks for destinations that should clearly stay on the local network. Adapt the configuration to your apps. Some connect to a server by IP but include a different domain in the TLS handshake; forcing the sniffed domain to replace the destination may change the original routing behavior. If a particular service fails only after sniffing is enabled, compare the destination, matched rule, and error log before and after. Then add an exclusion for that destination instead of disabling all rule-based routing.

Include Sniffing in the Full Troubleshooting Flow

For a connection to be routed by domain, check at least three things: whether DNS provides a domain that can be matched to the connection, whether sniffing obtains and uses a domain, and whether the rule list matches the relevant domain before its catch-all rule. If “Connections” shows only an IP, first check whether the app normally uses a fixed IP. If a domain appears but traffic still uses the wrong exit, check rule order and the proxy group before adding more sniffing protocols. For Fake-IP traffic, also make sure the app's DNS query and connection follow the same intercepted path.

Sniffing isn't a universal switch for turning every IP into a domain. Not all protocols expose a recognizable hostname, and protocol updates can change which handshake fields are visible. No sniffing result in the logs doesn't mean the client didn't process the connection; check verifiable details instead: the connection target, matched rule, and final exit. Test changes one app at a time, changing only one protocol or exclusion per test. Disconnect existing connections before trying again. If the issue only occurs in a browser, check whether it uses its own DNS or QUIC and whether its traffic follows a different path from other apps.

Local Overrides and Merging Multiple Subscriptions

Subscription providers update their files, so direct edits to a downloaded copy often last only until the next refresh. Local overrides keep settings you maintain over time—such as ports, DNS, rules, and proxy groups—separate from the nodes that change. Override behavior varies by client: some apply a patch after importing the configuration, some merge fields, and others generate the final YAML with a script. Find “Override,” “Config Merge,” or a similar option in the client, and understand its processing order before testing with an easy-to-check field. Don't assume arrays are always appended; replacing rules or proxy groups outright can remove existing routing behavior.

Identify the Effective Configuration First

The configuration to inspect is the full file loaded by the client, not a snippet in an editor. Check that mixed-port, mode, dns, proxy-groups, and rules contain only what you expect. This example shows top-level settings you could use in a configuration you maintain yourself. If the client's override interface accepts only a specific patch format, convert the example to match it; this isn't a universal override file. If a port is already in use, identify the process using it before changing the configuration, then update any apps that use that port.

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

Merging subscriptions also involves node names. Two subscriptions may both provide groups named “Auto” or “Default,” or nodes with the same region name. If the merge tool overwrites by name, the final configuration may point to a member from a different subscription. Keep the original subscriptions and note their node names and update schedules before merging. Afterward, check the name references in the final proxies, proxy-providers, and proxy-groups. A node list is only raw material: you still need to decide which group selects nodes, which group the rules target, and how new nodes enter groups after subscription updates.

Keep a Consistent Post-Update Test

Update each subscription separately and confirm that its original configuration parses. Then apply the local override and check that the final configuration loads. Next, test one DIRECT rule, one proxy rule, and the final MATCH rule with new connections, and confirm each match. Finally, refresh the subscriptions and test again. If it works initially but fails after an update, check whether the override was reapplied and whether group member filters still match the updated node names. Note whether a failure occurs during download, merge, parsing, or connection so you don't conflate four different problems.

Assign final rule ordering to one place. If subscription A's MATCH rule comes before subscription B's specific rules, B's rules will never run. If the merge tool concatenates groups with duplicate names, references may also become ambiguous. Keep a working copy of the original configuration and back up the current override before major changes. To understand whether a subscription link provides a complete YAML file or just a node list, see Subscription Formats and Conversion. Converting formats doesn't guarantee that the original rules and proxy groups will be preserved.

External Controllers and Configuration Checks

An external controller lets compatible dashboards read connection, rule, and proxy group status, and may also allow you to switch groups or reload the configuration. It isn't the same service as the mixed proxy port: mixed-port accepts app traffic, while external-controller provides a management API. For troubleshooting, a dashboard can help verify the selected group and inspect actual connections and rules, but what it shows reflects the core currently running. If the client's built-in UI already provides this information, use it first rather than exposing another management endpoint.

Bind to the Local Address First

If you only access the dashboard from the same computer, bind the controller to 127.0.0.1. Don't listen on every network interface just to connect to a local dashboard. An empty secret is only suitable for isolated local testing. If LAN access is necessary, set a dedicated management password, restrict which networks can connect, and check the system firewall. Never paste subscription URLs, management passwords, or a full configuration containing node credentials into an online dashboard you don't trust.

external-controller: 127.0.0.1:9090
secret: ""
mixed-port: 7890
mode: rule

The core provides the controller address, but the dashboard also needs to know where to connect. Some built-in dashboards detect it automatically; standalone dashboards may require you to enter it. If the connection fails, confirm that the core loaded this configuration, the port isn't in use by another process, the dashboard is connecting to the same device, and the browser or system proxy isn't sending local controller requests to a remote server. Update the saved address in the dashboard whenever you change the port. For authentication errors, check the controller's secret setting; don't enter your subscription password as the dashboard password.

Verify the Configuration Behind the Dashboard

Seeing a group in the dashboard doesn't mean a rule references it, and being able to switch a group doesn't guarantee that new connections will use it. To verify each step, check “Config” for the loaded file and its update status, “Rules” for the target domain's rule, and “Connections” for the match on a new request. If the dashboard still shows old groups after the client switches configurations, refresh it and check whether its controller is connected to a different running core instance. Don't edit the configuration based solely on cached dashboard data.

When a configuration fails to load, check the log for the field and line number, then inspect YAML indentation, duplicate top-level keys, referenced group names, and provider file paths. YAML uses spaces for nesting, and list-item dashes must be at the correct level. Tabs or full-width punctuation copied from a web page can also cause parsing errors. Restore a saved working configuration first, then add examples from this page one section at a time and reload. That's safer than repeatedly guessing at a broken file. If you just installed a client and need help connecting, return to the Quick Start. To switch graphical clients, choose one for your platform on the Downloads page; Clash Plus is our top pick.