Advanced Clash Configuration Guide

Proxy Group Types and Use Cases

Proxy groups decide which outbound connection to use after a rule matches; they do not decide which requests should use a proxy. A rule sends a connection to a group, which then selects the next hop based on manual choice, health checks, or an allocation algorithm. When troubleshooting, find the matched rule in the connection details first, then check the selected proxy. Adjusting the health-check interval is pointless if the request never reached the intended group. Group names are also configuration references, so after renaming one, check rules, nested groups, and the selection state saved by the client.

Choose a Group Type for the Job

Use select when you want explicit control over the outbound connection; a group can contain proxies or other proxy groups. url-test selects a candidate based on probe results, but a probe only reflects connectivity to its test URL—it does not mean every service will be faster. fallback prefers the first available candidate in the list, making it suitable when outbound priority is fixed. load-balance distributes separate connections across candidates; it does not combine their bandwidth for a single download.

Start with a manual selection layer you can trace

Keep a top-level manual group and place automatic groups inside it, rather than having every traffic rule point directly to an automatic group. If something goes wrong, you can pin traffic to a specific outbound and tell whether the issue is caused by automatic switching or a bad rule. The example below only demonstrates references: both candidates are built-in policies, not working proxy nodes. Replace them with imported, tested proxies or groups, and make sure the names match exactly.

mode: rule

proxy-groups:
  - name: Outbound
    type: select
    proxies:
      - DIRECT
      - Block on failure
  - name: Block on failure
    type: select
    proxies:
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.org,Outbound
  - MATCH,DIRECT

Key parameters for automatic groups include the test URL url, check interval interval, and switching tolerance tolerance. Choose a URL that responds reliably and is reachable on your current network. Short intervals generate more probe requests; long intervals can leave a failed candidate marked as available for longer. Tolerance helps prevent frequent switching when candidates perform similarly. Check the documentation for your core to confirm the units and exact behavior. A failed health check does not necessarily mean the proxy is offline: DNS resolution, restrictions on the test site, or the proxy route itself may be responsible.

Check Whether Switching Affects New Connections

After switching groups, make a new request before checking the result. Browser connection pools, persistent HTTP/2 connections, and ongoing downloads may continue using an existing connection, so an unchanged outbound does not necessarily mean the switch failed. Close the test page, start a new connection, and check the full policy chain in the connection details. If you need to terminate an old connection, use the client’s connection management tools rather than restarting the entire system and losing useful logs.

A fixed outbound is often a better fit for sign-ins, payments, and long-lived sessions. Load balancing can send separate connections to the same service through different IP addresses, affecting session checks or location-based decisions; route this traffic to a manual group instead. Avoid circular references between groups—for example, group A references group B, and group B references group A. Loading the configuration is only the first step: also check the selected outbound, failover behavior, and priority after recovery. For a detailed comparison of parameters, see Proxy Group Types: Automatic Selection and Configuration.

Managing Rule Providers

Rule providers let you maintain frequently changing match lists separately from relatively stable outbound policies. Keep provider declarations, reference order, and the final catch-all in the main configuration; store domain or IP range lists separately. This lets you update business domains without changing the overall policy structure, and makes changes easier to review. Remote rule providers are still configuration inputs: check their source, format, and update scope. A downloadable list should not automatically take precedence over local rules.

Understand Declarations, Content, and References

rule-providers declares the source and parsing method; RULE-SET references a provider in the rules list; the actual file contains the match entries. behavior determines whether content is interpreted as domains, IP ranges, or classical rules, while format specifies the file format. These are separate settings: for example, a YAML file can contain either a domain list or classical rules. A file extension alone does not prove that its contents are valid for the core.

Start with a local file to validate the basic chain without introducing network download issues. Place the rule file in the appropriate location under the core’s working directory, then merge its declaration into the existing configuration. Paths are usually relative to the core’s working directory, not necessarily the file you are editing. GUI clients may use a separate configuration directory; check the logs or configuration management page to confirm. Sandboxing and service settings can also limit which paths are accessible.

rule-providers:
  Local domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,Local domains,DIRECT
  - MATCH,Outbound

Here is the content for rules/local-domains.yaml. It uses a reserved example domain only to check whether the file loads and the rule matches. It does not replace production rules or add proxy nodes.

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

Rule order determines what gets matched

Rules are generally evaluated from top to bottom, and the first match determines what happens next. Put precise exceptions before broad categories, and keep the catch-all MATCH last. If a broad direct-connection rule comes before a business proxy rule, the latter may never match. Overlap between rule providers is common. The goal is not to make every list mutually exclusive, but to be able to explain why an earlier rule captured a given request.

Domain rules rely on domain information available on the connection, while IP rules may trigger DNS resolution. For IP matching rules that support it, no-resolve means not to resolve a domain solely to match that rule; it does not prevent DNS queries elsewhere in the connection. Whether to use it depends on the rule’s purpose. An exception for a private network range usually does not need an extra lookup, while a policy based on the destination IP’s geographic location needs you to consider where the resolved address comes from.

When switching to type: http, add the rule provider URL and set the update interval and cache path explicitly. First confirm that the source is reachable on your current network, then decide which outbound to use for update requests. Otherwise, you can create a circular dependency: the rules are needed to reach the rule source. After an update failure, a cached copy may remain available; on first launch, there may be no cache. Test both startup conditions instead of relying on a single successful update.

Check for Update Failures in Order

Start with the logs: did the download fail, did the file fail to load, or did parsing fail? For download failures, check source resolution, TLS connectivity, and outbound routing. For read failures, check directory permissions and paths. For parse failures, inspect the payload structure, indentation, and behavior type. Entries in a classical rule provider generally do not include a final policy, since the outer RULE-SET specifies it. Moving full main rules into a provider can result in the wrong number of fields or confusing semantics.

After updating, test one domain that should match and one that should not. Start new connections, check the match results, and look for an earlier rule that may have taken precedence. The rule name in the client’s connection panel is more useful than simply checking whether a website loads: it may be loading through the catch-all. Keep the last working rule file and a note of its source. If a domain is misclassified, add a narrow local exception first and investigate the upstream change; do not immediately switch the entire ruleset to global proxying.

DNS Configuration

When troubleshooting DNS, distinguish two questions: which resolver the application queries, and which resolver the core uses to look up the final address. An application may use system DNS, browser-based encrypted DNS, or its own resolver. Proxy server hostnames also need to be resolved. Changing only nameserver does not mean every application’s queries will pass through the core. First check whether the issue affects just one application, then examine the query entry point, upstream resolver, and connection outbound. Avoid replacing every address as soon as you see a DNS error.

Break the Resolution Chain into Checkable Steps

default-nameserver is mainly used to resolve the hostnames of DNS upstreams, providing the initial lookup; nameserver specifies regular upstream resolvers; and nameserver-policy can route specific domains to particular resolvers. If proxy server hostnames need separate handling, check whether your core supports proxy-server-nameserver. Do not make proxy hostname resolution depend on an outbound that is not yet available, or configure encrypted DNS so its hostname can only be resolved through itself.

This snippet listens on a loopback address and test port, using upstreams specified as IP addresses so you can verify the chain first. It does not automatically change the operating system’s DNS settings or enable DNS hijacking. The example enables redir-host so you can inspect the real IP returned. If your client already manages DNS, check the final configuration to avoid duplicate listeners.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver-policy:
    'example.org':
      - 223.5.5.5

If dig is installed, query this listener directly and compare the result with the system’s default resolver. This verifies that the core’s DNS service is reachable; it does not prove that your browser is using it. If the query times out, check the listener, port conflicts, and upstream connectivity. If an address is returned but the website still fails, continue with connection rules, the TLS handshake, and application proxy settings.

dig @127.0.0.1 -p 1053 example.org A
dig @127.0.0.1 -p 1053 example.org AAAA

Choosing Upstreams and Routing by Domain

How multiple upstreams are queried and their results used depends on the core implementation and its fields; do not assume a list automatically means primary and backup. Choose upstreams based on network reachability, support for internal domains, and whether the returned addresses make sense for the actual outbound. Company intranet domains should usually use the company resolver, since public resolvers do not know internal zones. Sending internal domains to public resolvers can cause lookup failures and expose more domain information.

DoH and DoT can protect DNS queries in transit, but they do not fix incorrect routing or outbounds, or make target traffic bypass routing rules. Before enabling rule-based DNS routing, understand how respect-rules interacts with proxy hostname resolution, and define a clear path for resolving proxy hostnames. Review any existing fallback settings and filters as well. Pasting in a new upstream list alone does not guarantee that resolver selection has changed.

Choose whether to enable IPv6 based on the network, rather than always turning it on or off. IPv6 works end to end only when addresses resolve, the system has a usable route, and the client’s traffic interception supports it. If a page occasionally hangs, test A and AAAA lookups and IPv4 and IPv6 connections separately to see whether one address family consistently fails. Disabling AAAA responses in the DNS section does not guarantee that applications cannot get an IPv6 address from cache or an independent resolver.

Caches, Browser DNS, and Retesting

After changing DNS policies, old results may remain cached by the core, operating system, or browser. First confirm the new result with an explicit query, then clear the DNS cache using the client’s supported method, restart the test application, and open a new connection. Repeatedly refreshing the same page may not trigger a new DNS request at all, since the connection pool can reuse existing connections. For browser-only issues, check secure DNS settings and extensions, and note the difference before and after disabling them.

For each test, record the queried domain, record type, returned address, response time or timeout, and the corresponding connection log. NXDOMAIN, an empty response, and a timeout are different failures: the first means the domain does not exist, an empty response may mean there is no data for that record type, and a timeout usually points to a problem with the network path or upstream. For application-level checks, see Frequently Asked Questions. Adjust Fake-IP or DNS interception only after you have identified the DNS step that is failing.

TUN and Fake-IP

TUN handles the traffic entry point; Fake-IP maps domains to virtual addresses. They are often used together, but they are not the same setting. TUN receives traffic through a virtual network interface, making it useful for apps that do not follow the system proxy. Fake-IP returns a virtual address first, then the core uses its mapping to recover the domain and route the connection. Applications typically opt in to the system proxy, while TUN involves system routes, permissions, and the network stack. Enable it only if a specific application is not being intercepted.

First, Identify What Is Intercepting Traffic

When multiple VPNs, accelerators, or virtual network tools run on the same device, they may override each other’s routes and DNS settings. Note the system proxy status, existing virtual interfaces, and default route, then test with just one interception method enabled. Desktop clients may get permissions through a service process or require explicit authorization. Mobile systems generally use the built-in VPN interface. The UI on one platform does not necessarily correspond to the same underlying routing behavior on another.

This snippet demonstrates only a mihomo setup combining TUN, DNS interception, and Fake-IP; it does not include proxy nodes. The client may already generate some of these fields, so check the final configuration. Before enabling TUN, make sure you can disable it from the local interface and keep a copy of the original configuration that does not depend on network access.

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
  fake-ip-filter:
    - '*.lan'
    - '*.local'
  nameserver:
    - 223.5.5.5

auto-route sets up traffic interception routes, auto-detect-interface helps select the actual outbound interface, and stack determines how traffic is handled. Support and compatibility for system, gVisor, and mixed stacks depend on the platform and core build. Do not switch simply to use a particular stack name. First test basic connectivity with the client’s recommended defaults, then compare one setting at a time for the protocols that have issues. Record the logs before and after each change.

Know the Limits of Virtual Addresses

A Fake-IP address is not the real address of the destination server, so it cannot be used to test public reachability directly. After an application receives a virtual address, its connection must pass back through the core that holds the mapping. If the application bypasses TUN, the mapping is lost, or traffic enters another proxy instance, the destination domain may not be recoverable. A cached virtual address can also cause brief failures after interception is disabled. Clear the relevant cache and let the application resolve the domain again.

Domains listed in fake-ip-filter generally resolve to real addresses instead, but that does not automatically send them direct; rules still determine the outbound. Consider a narrowly scoped exception for LAN discovery, apps that validate real addresses, or communication with specific devices, then check whether it actually fixes the issue. Do not add every domain to the filter to hide an interception problem: that changes the entire resolution model and removes a useful baseline for troubleshooting.

The DNS interception shown in the example targets traditional requests to destination port 53; it does not directly decrypt an application’s own DoH or DoT. Browser-based DNS, corporate VPN resolution, and traffic on special network interfaces need separate checks. LAN broadcasts, multicast, and some local services are not ordinary internet connections, so a single TUN switch cannot be assumed to route them correctly. If a router or printer is unreachable, check LAN routes and DNS before blindly changing proxy nodes.

Roll Back in the Least Disruptive Order

If the entire device loses connectivity, disable TUN first and check whether the default route and system DNS have recovered, then restore the original configuration. If the client exits unexpectedly and leaves routes behind, use its repair feature or restart the network interface. If you are unfamiliar with system routing commands, do not copy commands that delete routes in bulk. Once basic network access is back, test the system proxy and TUN separately instead of adding more rules while the network is still broken.

Once the connection is stable, test separately with a browser, command line, and an app that does not normally follow the system proxy. Check whether each connection reaches the core, includes a domain, and matches the intended rule. For UDP traffic, also verify that the proxy protocol and server support the required transport; TUN receiving traffic does not mean the outbound supports it. For a full comparison, see How TUN and System Proxy Work. Distinguish traffic interception from outbound capabilities before making the next change.

Domain Sniffing

Domain sniffing adds domain information to a connection; it is not a tool for decrypting web traffic. When an application uses its own DNS, a cached address, or a direct IP connection, the core may see only the destination address and be unable to apply the intended domain rule. Sniffing can try to extract visible host information from HTTP requests or TLS and QUIC handshakes for later matching. It can only use information the protocol actually exposes. It cannot guarantee a domain when the client hello is encrypted, the protocol is non-standard, or the service uses only an IP address.

First, Confirm That the Domain Is Missing

Find a request in the connection panel that you can reproduce reliably. Confirm that the destination shows only an IP address and that the domain rule did not match. If the panel already shows the correct domain but the wrong rule was selected, check rule order and policy references first; enabling sniffing is unlikely to help. If the browser uses its own encrypted DNS, first decide whether that behavior is expected, then choose whether to change the browser’s DNS settings or have the core add domain information through sniffing.

The example uses a conservative port range and demonstrates HTTP and TLS sniffing only. Setting override-destination to off reduces the chance that sniffed information will rewrite the connection destination. Check your core for the exact information available and behavior supported. Merge this snippet into an existing configuration; it is not a standalone connection setup.

sniffer:
  enable: true
  parse-pure-ip: true
  force-dns-mapping: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080
    TLS:
      ports:
        - 443
  skip-domain:
    - '+.lan'
    - '+.local'

parse-pure-ip allows attempts to sniff connections made directly to IP addresses, while force-dns-mapping affects sniffing behavior in certain DNS mapping scenarios. Neither guarantees that every connection will produce a domain. Port ranges determine which connections are checked, not whether their traffic actually uses the expected protocol. If an application uses TLS on a non-standard port, expand the range only if your use case requires it. Avoid including every port just to cover one issue.

Separate Domain Recovery from Destination Override

A sniffed domain can help restore business-rule matching, while destination override may also change the meaning of the target the connection was originally going to reach. Some services rely on a fixed IP, a custom Host header, or a specific reverse proxy; blindly enabling overrides can break requests that worked before. Test whether a domain is being sniffed separately from whether destination overrides are allowed. Check logs and rule matches first, then verify that the application handshake still succeeds.

One IP address may host many domains, so a reverse lookup cannot reliably tell you which host this request is for. A server name visible in a TLS handshake may not represent every resource the application later requests. A webpage may also connect to separate domains for content delivery, login, images, and APIs. A correctly matched homepage does not prove that the whole site uses the same policy. Check related requests in the connection list by application or time range, especially when sign-in redirects or resource loading fail.

QUIC usually uses UDP. Before enabling sniffing for it, confirm that the core supports it, check the actual port, and verify UDP support on the outbound. If disabling QUIC in the browser changes the behavior, that only shows the protocol path is different; it does not prove the UDP proxy is unusable. Sniffing cannot recover domain information that is hidden in a TLS handshake. A better fix may be to route the application’s DNS through the core, add a known rule for the service, or split traffic by process if necessary—not to keep widening the sniffing scope.

Set Exclusions and Keep Retest Notes

For LAN services, device management pages, and a few compatibility-sensitive apps, you can add explicit exclusions. Keep them as specific as possible: start with one reproducible domain or destination and assess the result before expanding. Supported fields for skipping domains, source addresses, and destination addresses vary between cores. If configuration validation reports an unknown field, do not keep adding parameters. Confirm the core and its supported options first, then decide which settings to keep.

To test, disable sniffing and make a request. Record the destination domain, rule, and outbound. Then enable sniffing, start a new connection, and compare all three. If the request fails only with sniffing enabled, verify after rolling back that the application cache and old connection have been cleared; otherwise, stale state may make rollback appear ineffective. Redact internal hostnames, request addresses, and application identities from logs before sharing them. Sniffing is best used as an information supplement; stable long-term configurations should rely on a clear DNS path and explainable rules.

Local Overrides and Subscription Merging

For long-term configurations, keep remote inputs separate from local settings: subscriptions provide proxies and updateable content, while local overrides define persistent rules, DNS, proxy group structure, and device-specific options. Directly editing a temporary configuration generated by the client usually means your changes will disappear after a subscription update or configuration switch. First find out whether the client offers persistent overrides, configuration merging, or script processing, then inspect the final generated file. The text in an editor alone does not prove the running core has applied the change.

Understand Merge Order and Array Behavior

YAML is a data format; it does not define a standard way to merge files. A client may recursively merge mappings, replace arrays wholesale, or support prepending, appending, or updating entries by name. Replacing the rules array versus appending to it can produce very different results: replacement may drop subscription rules, while appending may put local exceptions after MATCH. Before applying an override, use a narrowly scoped test rule to check the resulting order.

This example shows a local configuration intent. Its proxy group has only a direct candidate to demonstrate a stable name and rule placement. It is not a universal override format for all clients. Adapt or apply it through the merge interface documented by your client; do not import it by itself as a complete proxy subscription.

proxy-groups:
  - name: Daily Outbound
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,Daily Outbound

When merging in practice, make “Daily Outbound” reference existing proxies, proxy providers, or a lower-level automatic group. Keep the main rules dependent on this stable entry point, so you do not need to rewrite business rules when proxy providers change. If a subscription also defines a group with the same name, make clear which definition takes precedence; duplicate names are not a reliable merge strategy. A client may also retain an old selection that points to a deleted proxy, so check that the selected group member is still valid after an update.

Isolate Sources Before Combining Subscriptions

You can combine subscriptions with a client’s merge feature or use core mechanisms such as proxy-providers, but proxy subscriptions, full configuration subscriptions, and rule providers are different kinds of input. A proxy provider generally needs to contain the expected proxy list structure. Do not put a URL for a full configuration with DNS, rules, and a controller into a proxy provider and expect everything to merge automatically. Check the content returned by the subscription and, if needed, use a trusted local conversion process that you can review.

Use separate names, cache paths, and recognizable proxy names for each source. If two sources both have a proxy called “Hong Kong,” they are hard to tell apart in logs and selection history, and name conflicts may occur. Prefixes should identify the source or purpose; do not put subscription credentials in proxy names. When filtering candidates, first check whether the filter returns anything. Regex changes or updates to names and region labels can suddenly leave a previously working group empty.

Remote subscription URLs often contain access credentials and should be stored in the client’s local configuration manager. Screenshots, support requests, synced repositories, and online conversion tools can all expose them. Before sharing a configuration, check URL query parameters, proxy passwords, controller secrets, and full URLs in logs. Hiding only the proxy list may still reveal the subscription URL. Store backups containing these details somewhere controlled and limit which accounts can access them.

Validate Generation, Checks, and Reloads Separately

After making changes, inspect the final configuration for rule order, group members, and DNS fields, then run the core’s configuration check. In a command-line environment, you can use the check shown below; config.yaml must be the final file that will be run. For GUI clients, prefer the built-in check to avoid inconsistent paths caused by different working directories. Passing validation means the structure and references are acceptable; it does not mean that a proxy can reach the target service.

mihomo -t -f config.yaml

After reloading, test a local exception, regular proxy traffic, and the final catch-all separately. Then check whether the settings remain after the next subscription update. If the old behavior returns, the override may not be part of the persistent generation process, or a later layer may be replacing it. To roll back, restore the local override and the corresponding subscription snapshot; do not treat a copy of a temporary generated file as a permanent fix. For complex merge failures, reduce the setup to one subscription and one top-level group, then restore sources one at a time until you find the layer causing the difference.

External Controllers

An external controller reads status, switches policies, and manages connections through the core’s control API; it does not forward traffic. A panel that will not open and a proxy that cannot connect to the internet may be two separate issues. First check that the core is running, then check the control API, authentication, and page origin. Most everyday tasks can be handled in the client’s built-in interface. Open additional control access only if you need a separate view or remote management, and avoid exposing an unnecessary management endpoint.

Restrict Access to the Local Machine First

external-controller sets the control API listen address, secret authenticates API requests, and external-ui points to the local static panel directory. This example is for local management only. The example secret is a dummy value for demonstration; replace it with a strong random secret generated on the machine, and do not put it in a public file. Static panel files must already exist in a trusted local directory; setting this field does not create a UI.

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"
external-ui: ./ui

A loopback listener is only accessible from the local machine. Do not expose the API on all interfaces and disable authentication just because another device cannot connect. If remote management is necessary, first plan authentication, access controls, and secure transport, then restrict access to approved sources. System firewalls, container port mappings, and client settings can all affect what is exposed. Check the actual listening state and test access instead of relying on the configuration text alone.

Proxy Ports Are Not Management Ports

Proxy listeners such as mixed-port accept application traffic; the control API manages the core. They are not interchangeable. Setting a browser’s proxy server to the control port will not create a working proxy connection, and pointing a panel’s API URL to a proxy port will not return proxy groups. The API URL must use the correct protocol, host, and port, and the secret must match the running instance. This is especially important when multiple core processes are running on the same device.

You can start by checking whether the local API responds. The command below uses the same dummy secret as the example and is for local demonstration only. Be careful with terminal history and screen sharing; do not expose the authorization header. An unauthorized response means the API responded but authentication did not match. A refused connection usually points to the address, port, or process state; for a timeout, also check the access path and firewall.

curl --fail --silent --show-error \
  -H 'Authorization: Bearer your-controller-secret' \
  http://127.0.0.1:9090/proxies

If the API responds but the page is blank, check that the static files are complete, the directory path is correct, and the browser console has no failed requests. Accessing an unencrypted API from a secure page may trigger mixed-content restrictions; different page and API origins can also involve CORS. Do not allow every origin or remove authentication just to silence a browser error. Prefer a compatible, controlled access method for the local panel and API.

Use the Panel to Build a Complete Troubleshooting Record

In the connections view, check the destination, rule, policy chain, and connection status together. The final proxy name alone does not tell you whether a business rule selected it or the traffic happened to reach the catch-all. After switching policies, start a new connection. If needed, close a specific old connection after checking the impact. Do not clear all connections at once: that can interrupt sign-in sessions, downloads, and remote terminals, and destroy evidence of the issue.

Set the log level high enough to explain the issue, then restore it after testing. Detailed logs can contain internal domains, destination addresses, process information, and request paths. Before submitting a report, keep only the relevant time window and redact sensitive data. A panel shows data from the instance it is connected to. If the client is working but the panel’s rule list looks very different, check the API address and process before assuming the subscription failed to update.

Summarize troubleshooting as a reproducible chain: which application made the request, whether it entered the core, how the domain was obtained, which rule matched, which outbound the group selected, and whether the failure occurred during resolution, connection, or the service response. If browser and terminal behavior differ, see the System Proxy and Terminal Troubleshooting Checklist. If you are still setting up for the first time, return to Getting Started and complete the core setup. That is more likely to produce a reliable result than adding more advanced options.