Clash Advanced Configuration Guide

Proxy Group Types and Practical Use

Proxy groups sit between rules and nodes: rules send a connection to a group, and the group chooses its outbound route. Pointing rules directly at a node is simple, but renaming that node means updating every reference. A more maintainable setup points rules to stable, purpose-built groups, which can then reference manual or automatic selection groups. Grouping should serve real needs; there’s no need to create duplicate layers for every website.

What each of the four types is for

select is a manual selection group, useful when you need a fixed route or want to troubleshoot. url-test automatically picks a route based on probe results and suits routine traffic where the route can change. fallback selects an available option in the configured order; it provides primary/backup behavior, not a guarantee of choosing the fastest route. load-balance distributes separate connections across multiple routes; it does not combine bandwidth for a single download connection.

Choose a probe endpoint that is stable, responds quickly, and is reachable through every candidate node. If the endpoint itself is blocked, every node in the group may appear unhealthy even when actual traffic works. Conversely, connecting to a single test site does not prove that streaming access, work system logins, or other region-specific requirements are met. Track health checks and service-specific tests separately when troubleshooting.

Keep the service entry point stable

The snippet below places an automatic group inside a manual group. include-all includes eligible proxy candidates already present in the configuration, so the full configuration must actually load usable nodes. It is not a source of nodes and does not create proxies. The probe URL is a common connectivity test endpoint; if it is unreachable on your network, replace it with a lightweight endpoint you have verified.

proxy-groups:
  - name: Automatic selection
    type: url-test
    include-all: true
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
  - name: Outbound
    type: select
    proxies:
      - Automatic selection
      - DIRECT

interval is measured in seconds and sets how often probes run; tolerance is measured in milliseconds and helps avoid frequent switching between similar results. A shorter interval is not always better: it increases background requests and makes the group more sensitive to brief fluctuations. On laptops or mobile networks, start with a more conservative interval and review the logs instead of treating probe frequency as a guarantee of connection quality.

For proxy providers, use use to reference an existing proxy-providers name instead of listing every node in a group. A provider name and a node name are different things: the provider manages a source, while a node represents a specific route. When filtering provider nodes, account for upstream renames and the possibility that no nodes match. After making changes, check the candidate list—not just whether the configuration loads.

Switching behavior and recovery

Automatic group changes typically affect new connections; existing long-lived connections may not move immediately. If a refreshed page still uses the old route, close the app’s existing connections and try again before assuming the group is broken. Video playback, terminal sessions, and work systems vary in their tolerance for route changes. Services that require a stable source IP are usually better suited to a manually pinned group than automatic switching between regions.

Groups can reference other groups, but they must not form a loop. For example, if “Outbound” references “Work” and “Work” points back to “Outbound,” there is no clear final route. Follow the reference chain when designing groups and make sure it ends at an actual node or a built-in policy such as DIRECT. Avoid naming groups after nodes as well; it makes both the interface and rule targets harder to interpret.

Validate in this order: confirm the proxy page has candidates, manually select a known working node, then enable automatic selection. If the fixed node works but the automatic group fails, check the probe endpoint, filters, and group references. If the fixed node fails too, investigate node authentication and the underlying network rather than adding more groups. For help finding the relevant interface pages, see Proxy, Configuration, and Log Pages Explained.

DNS Configuration and Resolution Paths

A DNS configuration needs to answer three questions: what receives app queries, what resolves them upstream, and which network route carries those requests. Changing the upstream to encrypted DNS does not mean every app query goes through the core. Browser Secure DNS, system caches, app-specific resolvers, and local network gateways can all bypass it. Before investigating a Clash DNS leak, map the actual query path on your device.

Separate listening, bootstrap, and regular resolution

listen sets the address where the core’s DNS service listens; nameserver lists upstreams for regular queries. default-nameserver handles bootstrap needs, such as resolving the hostnames of upstream DNS servers; it is not a universal fallback for every failed query. A DoH resolver identified by hostname must first resolve its own hostname, so avoid a loop where you need to reach the resolver to find its address.

The DNS snippet below is intended for local diagnosis and uses a dedicated loopback port. It does not automatically change the operating system’s DNS server to this address or capture app traffic. First query the listening port explicitly with a command, then verify traffic interception with TUN or system settings. This helps distinguish a failure in the DNS service itself from an app that never reached it.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    '+.example.com':
      - 223.5.5.5

Example addresses illustrate the configuration structure; choose actual resolvers based on your network operator, location, and access requirements. Use nameserver-policy to direct specific domains to particular resolvers, for example when internal DNS or a specific regional result is required. Don’t send an entire business domain to a public resolver without a reason, or internal addresses may not resolve. Keep match scopes narrow: verify a single domain before expanding to its subdomains.

Align DNS requests with routing policies

To route DNS connections according to routing rules, consider respect-rules and configure proxy-server-nameserver correctly to resolve proxy server hostnames. Otherwise, resolving a proxy node may require the proxy, while connecting to the proxy requires the node’s address—a startup loop. There is no universal combination of switches for every subscription. The key is to ensure at least one bootstrap path does not depend on a proxy that has not been established yet.

direct-nameserver can handle resolution for direct outbound connections. If you also use domain policies, decide whether those lookups should follow nameserver-policy. Don’t configure several sets of nameservers, fallbacks, and policy mappings all at once without checking the results. Complex configurations can trigger multiple queries for the same domain and make it harder to trace where an answer came from.

The traditional fallback and fallback-filter settings control how DNS responses are selected; they do not simply mean “try the second DNS server only if the first one times out.” Filters, geolocation checks, and candidate responses all affect the final answer. If explicit domain policies already meet your needs, keep the configuration simple. Add filtering only when you have reproducible cases of DNS pollution or unexpected responses.

Verify the response and request route separately

Use the command below to query the local listener on systems with dig installed. Windows tools vary in their support for custom ports, so make sure you are querying the local core rather than system DNS. Record the query time, response type, and upstream shown in the logs, then compare them with the app’s connections.

dig @127.0.0.1 -p 1053 example.com A

In Fake-IP mode, returning a virtual address is expected; a difference from a public DNS result does not by itself indicate a resolution error. For IPv6, distinguish the core’s main setting, whether DNS returns AAAA records, the system’s IPv6 routes, and the proxy node’s transport support. The example disables IPv6 DNS responses only to reduce variables during initial diagnosis; it is not a recommendation to disable IPv6 permanently on every network.

Leak test sites usually show the DNS sources involved in one web request; they cannot cover every app and protocol. If a browser has its own Secure DNS setting enabled, check that separately. Managed devices may also have organization policies. Don’t repeatedly change system settings just to pass a particular test page. First define what you need to protect and which queries should be intercepted, then cross-check logs, routes, and app behavior.

Domain Sniffing and Its Limits

Domain sniffing extracts the target host from the initial data of some protocols after a connection has entered the core. Common sources include the HTTP Host header and the server name in a TLS handshake. It can help apply domain rules to connections that have only a destination IP, but it is not a replacement for DNS and cannot identify all encrypted traffic. Think of it as an additional clue, not a complete application identification system.

Traffic must reach the core before it can be identified

Sniffing only handles connections the core has received. If an app bypasses the system proxy and does not enter TUN, enabling sniffing will not bring its traffic in. Conversely, sniffing may add little when a connection already has reliable domain information. First confirm the connection appears on the client’s connections page, then check its domain, matched rule, and final route. Don’t start by expanding the sniffed port range.

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

The example limits sniffing to common protocol ports and preserves the original destination so you can first check whether identification is reliable. A port is only a place where a protocol may appear, not a guarantee about its contents; port 443 can carry other protocols too. Sniffing every port adds unnecessary processing and makes compatibility issues with nonstandard services harder to isolate. Expand gradually based on actual use.

Identifying a domain is not the same as rewriting the destination

override-destination determines whether the sniffed result replaces the connection destination. Services that rely on a specific IP may reach a different server after it is rewritten; for a site using a CDN, resolving again may also change the selected address. If you only want to improve rule matching, keep the original destination and check the connection records first. Enable destination override only when you have a specific need for it.

Enabling parse-pure-ip lets some connections with IP-only destinations be considered for sniffing, but identification depends on whether the protocol contains a readable domain. An HTTP request sent directly to an IP may not include the domain you expect, and TLS may not include a server name. An app’s proprietary encrypted protocol may not follow HTTP, TLS, or QUIC parsing either. If identification fails, don’t assume it must work just because the connection uses HTTPS.

Use settings such as force-domain and skip-domain to define specific cases where sniffing is required or skipped. Exceptions should address reproducible service behavior; don’t copy an unexplained domain list into your configuration. With shared IPs, reverse proxies, or internal gateways, an identified name may not reflect the original intent of the connection. Consider the original destination as well.

Encrypted protocols and privacy limits

Some TLS deployments use Encrypted ClientHello and may prevent traditional server name extraction. QUIC runs over UDP, so it is handled differently from TCP and is also subject to node UDP support, routing, and network policy. If a browser can reach a site but the client cannot identify its domain, the configuration may still be correct. If rules work using other reliable information, there is no need to display a domain for every connection.

Sniffing does not decrypt HTTPS content, and ordinary domain identification does not require installing a self-signed root certificate on your device. It does not read login passwords or webpage content. Domains can still reveal browsing intent, so share logs and dashboards cautiously. Before sharing troubleshooting details, remove private domains, subscription information, and node credentials; include only what is needed to reproduce the rule issue.

To test, use a known domain and create a new connection with sniffing both disabled and enabled. Compare the domain field and matched rule. Don’t judge only by whether the page loads: the same catch-all policy may succeed either way. If enabling sniffing causes access problems, first disable destination override and narrow the port range. If the issue remains, temporarily turn sniffing off and check the DNS mapping and rules.

For financial logins, corporate intranets, and services accessed by fixed IP, stability is usually more important than broader identification. Keep explicit address or domain rules and add narrow exceptions for known incompatible services. The acceptance test for sniffing should be that the intended traffic is routed correctly without causing problems—not that every connection displays a name. That avoids sacrificing usability for a complete-looking interface.

External Dashboards and Security

An external dashboard uses mihomo’s control interface to read runtime status, switch policies, and view connections. It is neither a proxy entry point nor a subscription server. The mixed port handles app traffic; the control port handles management. They are not interchangeable. If a dashboard will not open, check separately whether its static page loads, whether the control interface is reachable, and whether authentication succeeds. Don’t change the mixed port used for internet access.

Start local management with a loopback listener

If you use the desktop client’s built-in interface, you usually don’t need to open another control port. If you do need a local dashboard, start with a loopback address to avoid exposing the management interface to devices on your LAN. The credentials below are examples only. Replace them before use with a strong password you generate and store locally; never use the sample value for a service accessible from other devices.

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

external-ui points to a prepared directory of dashboard files, resolved relative to the core’s working directory; it does not generate those files. If the directory exists but has no entry file, the interface may work while the page returns an error. Get dashboard files from a trusted project and deploy them locally according to its instructions. Don’t treat control credentials entered on an unfamiliar webpage like an ordinary website login.

Binding to 127.0.0.1 allows access from the local machine through that address only. Listening on all interfaces may expose the port to devices on your LAN or other reachable networks; actual reachability also depends on the firewall and network topology. allow-lan mainly controls the proxy listener’s access scope; it is not a master switch for the control interface. Turning it off does not replace limits on control port binding and access.

Separate connectivity, authentication, and browser restrictions

If a connection to the interface is refused, first check that the core is running, the listening address is correct, and the port is not occupied. If the connection succeeds but returns unauthorized, check the control password saved in the dashboard instead of changing firewall rules. If the page loads but cannot retrieve data, browser cross-origin restrictions or a mismatch between the page and interface addresses may be involved. Use the browser’s developer tools to inspect the specific request.

An HTTPS page connecting to an HTTP control interface may be blocked as mixed content. Prefer a local deployment on the same machine and origin to avoid cross-origin configuration. If a reverse proxy is necessary, decide which layer handles TLS, authentication, and origin restrictions. Don’t allow arbitrary origins just to clear a browser error, and don’t put control passwords in public URLs; they may end up in browser history, logs, or shared content.

For management across devices, prefer a controlled secure tunnel or access limited to a trusted management network, and use the system firewall to restrict which devices can connect. Exposing the control interface directly to the public internet increases risk: it can show status and change active policies and configuration. Setting a password alone does not address encryption in transit, brute-force attempts, or whether the dashboard itself is trustworthy.

Complete the validation loop after a configuration change

After switching a group in the dashboard, confirm that the client interface and the route used by new connections both reflect the change. After changing the runtime mode, check whether it affects the current rule test. Dashboard state, configuration files, and runtime state do not always stay in sync: some choices are saved by the client, while others are overwritten on reload. For persistent settings, edit the configuration layer that owns them instead of changing them only through the control interface.

Keep logs to the minimum needed for troubleshooting. Temporarily increase the log level for debugging, then restore your usual level after reproducing the issue; avoid recording large volumes of visited domains over time. Before sharing materials, check for node credentials, subscription URLs, control passwords, and personal browsing records. If management credentials are exposed, change the actual credentials and remove the old value saved in the dashboard; deleting text from a screenshot is not enough.

Use a consistent final checklist for the whole guide: the configuration loads, node sources work, proxy group references resolve without loops, rules match as intended, the DNS path is clear, TUN captures the expected traffic, sniffing causes no compatibility issues, and the control interface is reachable only where needed. Change one variable at a time and keep a rollback point; it is usually easier than piling on more settings. If you cannot isolate the issue, share redacted logs and check each symptom under the Troubleshooting category.