Advanced Clash Configuration Guide

Proxy Group Types and Practical Use

Proxy groups decide which outbound route a connection uses after a rule matches. They don’t capture system traffic or resolve domain names. When troubleshooting, first confirm that the connection reaches the core, then check which rule matched and which proxy group it targets, and finally inspect the group’s selection. Changing the selection on the Proxies page without checking the rule target may mean you’re adjusting a group unrelated to the connection.

Know when to choose manually and when to automate

select is a manual group, useful when you need direct control over the outbound route. url-test selects automatically based on probe results, making it useful for frequently used routes where connectivity can change. fallback uses the first available member in the list, prioritizing order rather than searching for the fastest option each time. These types differ in how they select a member; none can improve the underlying quality of a proxy node.

load-balance distributes connections across multiple outbound routes; it doesn’t split a single download across routes to combine their bandwidth. Depending on the balancing strategy, a service may see different source IP addresses. If an account requires session persistence, use a fixed route or confirm that the chosen consistency strategy meets your needs. Don’t assume automatic rotation works for every site.

Health checks use the probe URL configured for the group, while real traffic may use different domains, protocols, and ports. A successful probe only confirms that the test path is reachable; it doesn’t mean every site will work. Frequent probes also create extra connections and can wake mobile devices. Set a reasonable interval for your environment rather than shortening it just to keep the interface refreshing.

Start with a small, easy-to-understand configuration

The groups below reference only the built-in DIRECT and REJECT policies to demonstrate naming and references; they don’t provide proxy routes. After loading the configuration, switch selections on the Proxies page and start a new test connection to see the difference between allowed and rejected traffic. Once you understand the flow, add actual node or nested group names from your subscription. Names must match exactly.

proxy-groups:
  - name: Manual Route
    type: select
    proxies:
      - DIRECT
      - REJECT

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

In a real setup, a traffic-specific group can point to an automatic selection group, while DIRECT can remain available as a manual troubleshooting option. Group references must form a one-way chain: group A must not include group B if group B also includes group A. Renaming a node doesn’t update old names in rules or group members. If the configuration fails to load, check the logs for missing targets and circular references.

If members come from proxy-providers, groups usually reference the provider with use; don’t put the provider name in proxies as if it were a node. A provider supplies a set of nodes, while a proxy group provides selection logic over that set. Keeping these roles separate means you can change the source when a subscription changes while business rules continue to reference a stable group name.

Verify the selected route and connection lifecycle

Changing a group selection generally affects new connections. Browsers may reuse existing connections, and active downloads or long-lived apps may continue using the old route. Close the relevant connection before testing, then make a new request; save your work first if you need to interrupt an active task. A page refresh alone doesn’t prove the new route is active. The connection details are more useful than whether the page reloads.

If an automatic group keeps switching, check for too many members, probe URLs affected by special handling, or DNS issues along the test path before adjusting tolerance or intervals. Change one variable at a time and record the original value and result. If every member fails, check shared dependencies such as the local network, subscription validity, and node hostname resolution instead of adding more layers of automatic selection.

Managing Rule Providers

Rule providers move frequently changing domain, IP, or classical rule lists out of the main configuration. The main configuration only needs the source definition, the reference, and the chosen outbound route; the provider handles updates. This avoids editing the entire subscription every time you add a domain and makes it easier to distinguish changes to matching criteria from changes to routing policy.

Separate rule content, format, and references

rule-providers defines rule sources, while RULE-SET adds a source to the matching process. A provider that’s declared but never referenced won’t take effect. The target in the rule that references it must still be an existing proxy group or built-in policy. Rule providers generally shouldn’t specify an outbound route; otherwise, the same list is harder to reuse across configurations.

behavior describes the type of content: domain is for domain lists, ipcidr for IP ranges, and classical for classical rule expressions. format describes how the content is stored. Loading a classical rule file as a domain list may fail even if the file downloads successfully. When choosing a source, check both its content format and behavior type.

The example below uses a local classical rule set, which is useful for checking paths and references first. Relative paths are resolved from the core’s working directory, not the web page’s directory or necessarily the installation directory. Create the file in a configuration directory managed by the client and readable by the core, then check the logs to confirm where it was loaded from. Working directories can differ between clients.

# Snippet for the main configuration
rule-providers:
  work-sites:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/work-sites.yaml

rules:
  - RULE-SET,work-sites,DIRECT
  - MATCH,DIRECT

# ./rules/work-sites.yaml
payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,example.org

Check the download path separately when using remote rules

When switching from a local file to a remote rule source, follow the source documentation to set type: http, the actual URL, a cache path, and an update interval. Don’t use a web page about the rules as the URL for the raw rule file. A successful response containing HTML is still invalid content to the core. Check the response in a browser, then review the core logs for download and parsing results.

A rule update failure is different from a rule that doesn’t match. For update failures, check the remote URL, connectivity, parsing, and write permissions for the cache directory. For missing matches, check whether the file contains the target, whether the reference exists, and whether an earlier rule matched first. An old cache may still work when the network is down, so traffic routing successfully doesn’t prove the latest update succeeded.

Update intervals are usually measured in seconds, so set them according to how often the source changes. Static business lists don’t need frequent downloads, and excessive requests may trigger rate limits. Give each provider its own cache path to avoid overwriting files. Before changing a source URL, keep a working copy of the previous file. Remove the old definition only after confirming the new content parses correctly.

Order rules by first match

Rules are evaluated in order. Put specific exceptions before broad rules, and place the catch-all MATCH rule last. If a domain appears in two rule sets, the core won’t automatically choose the more specific set; the first matching reference determines the route. When maintaining multiple lists, check for duplicates and document each list’s priority in the main rules section.

IP rules may need a domain lookup to obtain an address to match. no-resolve prevents a particular IP rule from triggering that lookup, but it doesn’t disable DNS globally. Adding it indiscriminately to every IP rule can send traffic that depends on resolved addresses to the catch-all rule. Decide based on whether the app supplies a domain or destination IP and whether an earlier rule already matched.

To test a rule, choose a domain you know is in the set, close any existing connection, and visit it again. Check the match type and target on the Connections page. If there are no loading errors but the connection keeps hitting the catch-all rule, check whether the app uses its own DNS, connects directly to an IP, or is matching another rule first. Don’t rely on a site seeming to work as proof.

DNS Configuration

DNS resolves domain names to addresses, but a proxied connection can be resolved at different points. System DNS, browser-encrypted DNS, Mihomo’s built-in resolver, and resolution by the proxy server are not interchangeable. When troubleshooting Clash DNS leaks or resolution failures, first identify which program makes the query and where it sends it. Then decide whether Mihomo’s DNS settings need to change.

Distinguish application DNS from bootstrap DNS

nameserver defines the regular DNS upstream. If an upstream is specified by hostname, you also need a bootstrap path that can resolve it. default-nameserver primarily serves this bootstrap purpose; it isn’t a universal gateway for every application domain. If the bootstrap resolver and proxy route depend on each other, startup can get stuck: the proxy isn’t ready, but resolving the proxy requires using it.

proxy-server-nameserver can resolve proxy node hostnames separately, avoiding a dependency on the proxy itself for its own connection. nameserver-policy selects an upstream for domains matching specified conditions, which is useful for internal networks and enterprise services that require a particular DNS view. These fields serve different purposes; don’t duplicate every server across every list just to add a “backup.”

The snippet below enables Fake-IP and uses encrypted upstreams for regular queries. It shows how the fields fit together; it doesn’t guarantee that the upstreams are reachable on every network. Check that they work in your environment. If the client has already generated DNS configuration, merge these fields into the existing mapping to avoid duplicate top-level dns keys and ambiguous overrides.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://cloudflare-dns.com/dns-query

Make the resolution and connection paths easy to explain

Encrypted DNS protects queries in transit; it doesn’t automatically route them through the proxy or guarantee that the results suit the connection’s outbound route. Direct connections may need locally reachable addresses, while proxied connections may resolve domains on the proxy side. If a site resolves to an address but the connection fails, check the result, matched rule, and actual route together. The upstream’s name alone doesn’t prove the configuration is correct.

To route DNS connections according to routing rules, you can look into respect-rules. Before enabling it, set up a separate path for resolving proxy node hostnames and check which rules apply to the DNS upstreams. Otherwise, DNS may require the proxy while resolving the proxy hostname requires the same DNS query, leaving no usable route during startup.

Be especially careful with enterprise and local network domains. Public resolvers may not know internal addresses, and replacing system DNS can break workplace apps. Confirm internal suffixes, the designated DNS servers, and the routes needed to reach them, then scope policies accordingly. Don’t send every domain to an internal-only server or inadvertently send internal queries to an external resolver.

Troubleshoot by cache, source, and address family

After changing DNS, consider application, system, and core caches separately. Clearing the system cache may not trigger a new query if the browser reuses an existing connection. Close the target connection first, and restart the test app if needed, then check the logs. A command-line lookup only proves which resolution path that tool used; it doesn’t show that browsers, games, and other apps use the same path.

ipv6: false controls related response behavior in the core’s DNS; it doesn’t disable IPv6 across the operating system or stop every app from trying IPv6. If IPv6 is available on your network, decide explicitly whether to route that traffic. If only some connections fail, compare the domain’s address results with the routes instead of treating protocol disablement as a universal long-term fix.

Before checking for DNS leaks, define what you expect: which apps must use the core for DNS, which internal queries should stay local, and whether the browser can use its own encrypted DNS. A test page showing a resolver name is only a clue. A more reliable assessment combines system DNS settings, app configuration, connection records, and, when needed, packet captures to distinguish intentional direct queries from unexpected routing.

TUN and Fake-IP

TUN receives traffic through a virtual network interface; Fake-IP uses synthetic addresses to preserve domain mappings. They serve different purposes. Enabling TUN doesn’t mean all DNS goes through the core, and enabling Fake-IP doesn’t mean every app is captured. Check the virtual interface, system routes, DNS query path, and rule matching together. Missing any one of these can make a setup appear to work only partially.

Set up traffic capture with a rollback plan

System proxy settings work for apps that respect them; apps that ignore them may need TUN. You don’t have to enable both as a fixed combination. For the first test, keep your current working setup and record the existing system proxy and DNS settings before enabling service mode and TUN. If even basic connectivity fails, turn off the new traffic capture first, restore the connection, and then review the logs.

Clash Verge Rev’s TUN support depends on service permissions and platform support. On Windows, check that the service is running, the virtual interface can be created, and security software isn’t blocking it. On macOS, grant the required permissions. On Linux, check permissions, routes, and firewall rules. Routing behavior can differ across operating systems even with the same YAML, so an enabled toggle alone doesn’t prove traffic is being captured.

The snippet below shows a common traffic-capture setup. Merge its DNS fields with the mapping from the previous section. auto-route asks the core to configure routes, auto-detect-interface helps identify the outbound interface, and dns-hijack redirects matching traditional DNS requests to the built-in resolver. Test these settings with appropriate permissions and a clear understanding of your network layout.

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

Understand synthetic addresses and exclusions

Fake-IP returns synthetic addresses that let the core associate a connection with its original domain; they aren’t the website’s real server addresses. When an app connects to one, the core can recover the domain and apply domain-based rules. Seeing a synthetic address in a diagnostic tool doesn’t by itself indicate a DNS error. What matters is whether the subsequent connection reaches the same core and whether the mapping is still available.

Connections can fail if an app gets a synthetic address but bypasses TUN, or if it retains a stale mapping after waking from sleep. Check routes and cache lifetimes before adding every domain to the exclusion list. For apps that genuinely need real addresses, perform special connectivity checks, or use LAN discovery, set fake-ip-filter as narrowly as possible.

Exclusion behavior depends on the filtering mode, so check the current semantics before adding entries. In the standard exclusion mode, matching domains receive real DNS results. Other filter modes can change what the list means. Don’t mix snippets from different guides that use opposite semantics. After changes, clear relevant caches and test the app’s actual workflow.

Handle multiple adapters, other tunnels, and wake-from-sleep issues

With multiple network adapters, automatic detection may choose a default route you didn’t expect. If a work network, mobile hotspot, and another VPN are active at once, identify which connection carries internet traffic and which provides access to enterprise resources. More routes don’t necessarily mean better coverage. Multiple tools changing default routes and DNS can create loops or send traffic to the wrong interface.

strict-route can enforce stricter routing behavior on certain platforms, but it isn’t a universal first-time setup fix. It may affect LAN access and compatibility with other software. Test it one change at a time, and only after confirming that ordinary automatic routing is leaking traffic and you understand the platform’s implementation. Test websites, LAN services, enterprise apps, and wake-from-sleep behavior.

DNS hijacking primarily targets matching traditional DNS requests; it doesn’t automatically turn every encrypted DNS connection inside an app into a traditional query. Browser and app resolvers may still need separate configuration and routing rules. If a program never appears in the expected records, check its network permissions, proxy settings, and independent DNS before adding more hijack entries.

If enabling TUN leaves you offline, check in order: whether the core started, the service is available, the interface was created, the default route makes sense, DNS returns results, and the proxy route works. Compare with TUN disabled to narrow down the cause. Don’t change the node, DNS, network stack, and rule sources all at once; even if connectivity returns, you won’t know which change fixed it.

Domain Sniffing

Domain sniffing attempts to extract hostnames from protocol data at the start of a connection, adding domain information when only a destination address is available. This can improve domain-rule matching, but it doesn’t decrypt traffic and can’t recover the domain from every connection. Before enabling it, determine whether the missing piece is domain information, a matching rule, or the traffic-capture path. Don’t blame every unrelated connection issue on the sniffing toggle.

Know what sniffing can and can’t see

An ordinary HTTP request may include a host field, and some TLS handshakes expose a server name; QUIC has its own identification method. What’s visible depends on the protocol, implementation, and encryption. With mechanisms such as encrypted client hello, a name that would otherwise be visible may no longer be available. Don’t assume sniffing can recover the correct domain from every HTTPS connection.

A sniffed name may not represent every service an app accesses. One app can connect to multiple service domains, content delivery networks can share addresses, and connection reuse may mean later requests don’t repeat the handshake. Check individual connections; one successful sniff doesn’t prove all of an app’s traffic will use the same business-specific proxy group.

The example below attempts identification only on specified HTTP and TLS ports and preserves the original destination instead of forcing a rewrite. Start by checking whether identification improves rule matching, then decide whether to expand the scope. Interface options and generated configuration can vary by client. After saving, inspect the runtime configuration rather than assuming a checked box corresponds to a complete YAML block.

sniffer:
  enable: true
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: false
    TLS:
      ports:
        - 443
        - 8443
      override-destination: false

Test domain identification and destination rewriting separately

override-destination controls whether a sniffed domain replaces the connection target. This affects more than the displayed hostname; it can change subsequent resolution and how the connection is made. Some services depend on the original address, region, or dedicated entry point, and replacing the destination may break them. Start with conservative settings and expand only where needed.

If an app already sends the domain through its proxy protocol, or a Fake-IP mapping provides domain information, sniffing may add little. Enabling it for more protocols and a wider range of ports can add processing overhead and complicate troubleshooting. When domain information is already complete, a limited scope is easier to maintain than enabling everything.

If a specific site stops working with sniffing enabled, create a repeatable test using the same route and rule with a new connection. Compare the destination, matched rule, and error with sniffing on and off. Only after confirming that sniffing causes the difference should you use skip-domain to add a narrow exception. Don’t exclude an entire public suffix to hide a local compatibility issue.

Troubleshoot alongside DNS, rules, and logs

If a connection record shows only an IP address, first check whether its protocol and port are within the expected scope, then see whether the app reused an existing connection. Sniffing generally relies on information available when a connection starts; turning it on mid-connection may not recover the hostname. Close the connection and make a new request to create clear test conditions instead of repeatedly toggling the setting.

If a domain appears but traffic uses the wrong route, review rule order rather than broadening sniffing. Recovering a domain only fills in missing information; it doesn’t create a rule that doesn’t exist. If a domain rule matched but the request still fails, check the selected node, DNS, and destination reachability. Record successful identification and successful connectivity as separate outcomes.

QUIC uses UDP, so check that the outbound route and traffic-capture path support it. An app may fall back to another protocol after a failure, making connectivity seem inconsistent. Don’t disable a protocol globally just to prove sniffing works. Gather connection details first, then decide whether you need protocol-level routing, an app setting change, or an exception for a specific service.

Raise the log level temporarily when diagnosing an issue, then restore it after reproducing the problem. Logs and connection details may contain domains, process paths, and destination addresses; remove unnecessary information before sharing screenshots. When documenting a configuration change, include the relevant fields and error type, not your full subscription, node credentials, or unrelated browsing history.

Local Overrides and Combining Subscriptions

Subscriptions provide remote configuration; local overrides preserve device-specific and personal settings. Direct edits to a remote subscription may be overwritten on the next update, while edits to the runtime configuration can disappear when the client regenerates it. For long-term maintenance, distinguish the source subscription, override inputs, and runtime output, and know which layer is responsible for saving each change.

Check the override entry point and scope first

In Clash Verge Rev, manage local changes through the extension entry associated with a subscription or through the global extension entry; names may vary by client version. Global overrides suit shared device settings, while subscription-level overrides are for exceptions that apply to one source. If both layers modify the same field, check their actual processing order. The editor where you last saved a change doesn’t necessarily determine the final result.

Merge overrides follow conventions defined by the client; not every extension field is native Mihomo configuration. In the corresponding Merge mechanism, prepend-rules places rules at the beginning, and the processed result should appear in the final rules list. Add this field directly to ordinary core configuration and it won’t automatically have the same merge behavior.

# Add this to a Merge override entry that supports these fields
prepend-rules:
  - DOMAIN-SUFFIX,example.com,DIRECT

dns:
  ipv6: false

This example adds a single business rule and changes a field in an existing DNS mapping; it doesn’t define a complete DNS setup. After saving, inspect the runtime configuration to make sure other DNS upstreams remain and the prepended rule is in the expected position. If the client merges differently than expected, test one field at a time rather than adding more settings to the same override.

Lists and mappings need different merge checks

YAML mappings are organized by key, while lists involve ordering, duplicates, and replacement. Rule order and placement directly affect first-match behavior. If a proxy-group list is replaced wholesale, groups referenced by remote rules may disappear. Extension mechanisms handle lists differently, so confirm “successful merge” against both the final configuration and what the core actually loaded.

Extension scripts are useful when you need to rename, deduplicate, filter, or transform configuration, but they add complexity. First clarify the expected input and return objects, and preserve fields you don’t modify. For a fixed rule or boolean setting, prefer a Merge snippet that’s easy to review. A script running successfully doesn’t guarantee its output matches the core’s requirements.

After a subscription update, check that custom groups can still find their members. Providers may rename or remove nodes or restructure groups, breaking local overrides that depend on specific node names. A more robust approach is to have business rules reference stable local groups and manage source changes within those groups. Still check for empty groups and name conflicts; no configuration can stay compatible with every source indefinitely.

Multiple subscriptions aren’t just files to concatenate

Having multiple subscriptions in the client doesn’t mean they’ll all be included in one runtime configuration by default. A common workflow is to select one as the active configuration. To use multiple sources together, consider proxy providers or a clearly defined aggregation mechanism. First confirm that the client supports the required inputs; pasting two complete YAML files together won’t make them coordinate automatically.

Combining sources requires at least handling duplicate node names, duplicate group names, rule priority, and conflicting global fields. If both sources define DNS, listening ports, and catch-all rules, there must be a clear final choice for each. In practice, keep one main configuration and let other sources contribute only node sets, referenced through distinct provider names. This is easier to review than combining two complete sets of business rules.

When migrating from an older client, first import the subscription and confirm basic connectivity. Then move ports, rules, and DNS, and handle script logic last. Legacy Parsers fields and execution environments aren’t interchangeable with Merge. Use the Clash for Windows Migration Guide to review settings one by one; don’t replace the new client’s configuration wholesale with outdated settings.

Keep a local record of each change, including its purpose, scope, and rollback steps. If something breaks, disable the new override, reload the original subscription, and confirm that service returns before re-enabling changes one at a time. Store backups securely and keep subscription URLs and credentials out of public repositories. Shared examples should include only the fields needed to show the structure.

External Controllers

External controllers use Mihomo’s control API to read status, change proxy selections, and perform some management tasks. They’re different from the mixed proxy port and aren’t an internet access point for apps. Keep proxy traffic and management traffic separate: apps connect to the proxy port, while a panel connects to the controller. Using one address for both usually results in a connection error or an unexpected response.

Prefer a local API with explicit authentication

external-controller sets the listening address. Binding it to 127.0.0.1 accepts connections only from the local IPv4 loopback interface. secret authenticates API requests; set a strong, unique value. The password below is for illustration only and must not be used in a deployment. The client may already manage these fields, so check whether its built-in interface depends on the current controller before overriding them.

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

Don’t expose the controller on every interface or remove authentication just to fix a panel connection error. That could expose proxy controls and runtime status to a much larger network. If remote management is necessary, first set up a controlled access path and restrict its source with a firewall. Desktop users should generally keep management local; everyday proxy use doesn’t require remote control access.

A controller address typically consists of a protocol, host, and port. The panel’s authentication setting must match the core’s current secret. A port conflict, a stopped core, or a secret changed after the client restarted can all disconnect the panel. Check the core’s startup logs and listening status first, then review any outdated settings saved in the panel. Don’t mistake a failed management connection for a broken proxy route.

Distinguish panel files, the API, and browser restrictions

external-ui points to a local directory containing static panel files, not an arbitrary web URL. The directory must contain the panel’s entry point and assets, and the core needs permission to read it. Specifying a directory name doesn’t create a panel. If the client’s built-in interface already handles management, you can skip the static panel and avoid extra file updates and API exposure.

An independent browser-based panel may also encounter cross-origin restrictions, mixed content, or browser limits on local network access. A browser may block an HTTPS page from requesting a local HTTP API, regardless of whether the password is correct. Check whether the browser reports a network failure, cross-origin block, or authentication error. Don’t loosen all origin restrictions as a guess.

The panel’s origin is part of the trust boundary. A page that can access management credentials may be able to send requests to the controller, so don’t enter the secret on an untrusted site. If cross-origin access is needed, allow only the exact origin supported by the core and check the protocol and port the browser actually uses. Fix a specific origin mismatch instead of authorizing every site.

Separate temporary control from persistent configuration

A panel changes the current runtime state. Some settings may be persisted by the client; others may revert when the configuration reloads. Manage DNS, rules, and traffic-capture settings that need to last in the client’s configuration or override entry. Don’t assume a temporary panel change modified the source file. Check the result again after restarting, switching subscriptions, or applying an update.

Before sharing screenshots or exported connection records, check for domains, process paths, device addresses, and controller credentials. A useful bug report usually needs only the error type, relevant fields, and steps to reproduce. Keep the configuration structure and remove sensitive business details. Don’t send a full subscription to prove a rule didn’t match, or expose the controller to others as a routine support method.

Choose a client separately from the core configuration. To compare cross-platform options, start with Clash Plus, then consider Clash Verge Rev and other clients based on your desktop override needs. Interfaces and extension mechanisms vary, so don’t assume the same setting is in the same place everywhere. Find installation and platform information in the Download Center, and migrate existing configuration field by field based on what the current core supports.

A complete troubleshooting process should answer four questions: Did the traffic reach the core? How was the domain resolved? Why did the rule match? Which outbound route was used? The controller gives you a way to inspect what’s happening, but it doesn’t replace that sequence of reasoning. Once the setup is stable, restore the normal log level, close any temporary management access, and keep a record of the verified override changes for the next update.