Clash Advanced Configuration Guide

Proxy Group Types and Routing in Practice

Understand the difference between rules, proxy groups, and nodes

Rules determine where a connection goes; proxy groups determine which route to use next; nodes establish the actual proxy connection. These are separate configuration layers. In rule mode, connections are matched against rules in order and passed to the target proxy group. Groups can reference other groups, ultimately selecting a node or a built-in option such as DIRECT or REJECT. A rule matching PROXY does not mean the connection is using a specific node—expand the proxy group chain to see the final selection.

Configuration names are referenced as strings, so capitalization, spaces, and punctuation must match exactly. If you rename a group from “Auto Select” to “Auto,” update every rule and group that references it. For errors such as proxy not found, look for a missing or mismatched name instead of repeatedly updating the subscription. Some clients retain the last manual selection. After changing a group, that selection may no longer be valid, so check the active route after reloading.

Manual Selection, Automatic Selection, and Failover

Use select when you need to choose a route yourself; it typically won’t switch automatically based on test results. url-test checks candidate proxies and selects one based on test results and settings such as tolerance. fallback prioritizes the configured order, using the first available candidate. load-balance distributes connections according to a specified strategy—it does not split a single file transfer across multiple routes.

This proxy group example assumes “Node-A” and “Node-B” already exist in proxies or a proxy provider. These are sample node names; replace them with names from your running configuration. The test URL is used to check connectivity, not to represent a real service. If your network blocks that URL, automatic selection results may be misleading. Confirm that manual selection works first, then add automatic selection to make it easier to pinpoint issues.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto Select
      - Node-A
      - Node-B
  - name: Auto Select
    type: url-test
    proxies:
      - Node-A
      - Node-B
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

When a stable egress IP matters more than frequent switching

interval sets the test interval in seconds. tolerance adds a switching threshold to automatic selection, preventing minor fluctuations from changing the route. lazy can reduce unnecessary tests for unused groups. Avoid setting very short intervals for every group. Proxy providers may also run their own health checks; running both checks frequently increases request volume and background activity on mobile devices, without guaranteeing faster page loads.

Login services, payment pages, and long-lived sessions usually work best with a fixed route. Automatic switching can make the same account use different egress IPs in quick succession, potentially triggering security checks. Create a dedicated manual group for the service and route its domains to that group for more precise control than disabling automatic selection globally. If you use load balancing, understand how its distribution strategy interacts with session persistence and expect separate connections to use different egress routes.

To verify the route, find the target domain on the Connections page and note the matched rule, proxy group, and final node. Then select another confirmed working node, close the existing connection, and try again. Established TCP connections generally do not migrate when you switch groups. If a connection still shows the old route, distinguish connection reuse from a configuration that did not take effect. If the new route still fails, check the service, node reachability, and DNS rather than blaming the proxy group for every failure.

Manage Rules with Rule Providers

Rule order matters more than the number of rules

mihomo typically evaluates regular rules from top to bottom and applies the policy for the first match. Put specific exceptions before broad rules, and keep MATCH last as a catch-all. If a broad direct rule comes before a proxy rule for a specific domain, the exception will never match. Start troubleshooting with the matched rule shown in the connection details. Confirm the domain or destination IP used by the request, then check rule order—searching the configuration for the website name is not enough.

DOMAIN matches an exact domain. DOMAIN-SUFFIX matches a suffix and its subdomains. DOMAIN-KEYWORD matches any domain containing a string and can have a much broader scope. For known services, prefer an exact domain or a specific suffix. A webpage may also use separate domains for login, static assets, and APIs, so routing only the homepage may not cover the full workflow. Use connection logs to identify actual dependencies instead of switching all traffic to global mode.

Separate rule content from where rules are applied

rule-providers defines the source of rule content; RULE-SET specifies where to apply it and which policy to use. This lets you update rule files independently while keeping execution order clear in the main configuration. The example uses a local file so you can validate the structure first. Save the rules file as rules/local-direct.yaml in the client’s configuration working directory. If the client runs in a sandbox, use its supported file manager to confirm the actual path.

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

rules:
  - DOMAIN,example.com,DIRECT
  - RULE-SET,local-direct,DIRECT
  - MATCH,PROXY

PROXY in the main configuration above must already be defined. Here is the corresponding local rules file. example.org demonstrates suffix matching; replace it with a domain that should use a direct connection. A domain-type rule set is not a regular rules list, so don’t include a policy name on each line. Get this small rule set matching correctly before migrating a larger collection to separate path, format, and content issues.

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

Choose the right behavior and update method

Use behavior: domain for a set of domains, ipcidr for a set of IP ranges, and classical for traditional rules that include rule types. The provider’s format must also match the file format; the extension alone does not tell you what the file contains. Putting DOMAIN-SUFFIX,example.org in a domain-type set, or adding full rules with policy names to a classical set, can cause parsing errors or unexpected matches.

For remote rule maintenance, set the provider to type: http, then enter the actual url from a trusted source, a unique path, and a suitable interval. Don’t let multiple providers share a cache file—a refresh could overwrite another rule set. Inspect a sample of any changed source to make sure it still contains domain lists, not a webpage or error message, before updating the provider in the client. Reloading the configuration does not necessarily download every remote file again.

Troubleshoot rule providers by tracing the match

If a rule isn’t taking effect, first confirm that the client is in Rule mode. Then check that the provider loaded, its name matches the RULE-SET reference, and no earlier rule matched first. For IP rules, no-resolve prevents that rule from triggering a DNS lookup just to obtain an IP address. It does not turn a domain rule into an IP rule or stop all DNS queries. Connections that already have a destination IP can still match IP rules; interpret the result using the details for that connection.

GEOIP depends on the relevant geolocation database, so a working rule set does not guarantee the database is available. For GeoIP errors, check the file path and download failure details in the logs, then use the client’s database update option. Don’t repeatedly delete the entire configuration directory. If your rules keep growing and getting harder to troubleshoot, organize them into four layers: local exceptions, service-specific groups, shared rules, and a final catch-all. See the glossary for basic concepts and the help center for troubleshooting.

Optimize DNS Settings and Trace Resolution

Map out which components are querying which resolvers

When troubleshooting DNS, distinguish the app, operating system, mihomo, and upstream resolvers. Your browser may use its own secure DNS, the OS may retain manually configured servers, and TUN may intercept some DNS requests. If changing nameserver has no visible effect, the setting may be valid but the requests may not be going through mihomo. Check the client logs for queries to the target domain before changing system DNS, browser settings, or traffic interception.

A domain-based encrypted DNS upstream needs its server address resolved first; this is called bootstrap resolution. default-nameserver is used for relevant bootstrap lookups, not necessarily as the first resolver for every request. If a proxy node uses a hostname, also check proxy-server-nameserver to avoid a dependency loop: you need the proxy to resolve the node, but need the node resolved to connect to the proxy. Verify that the proxy can start separately from whether business domains resolve correctly.

Start with a small set of known resolvers

This DNS example separates bootstrap resolution, regular DNS queries, and node hostname lookups. It is not a universal setup: test whether public resolvers are reachable and supported on your network. The example does not set a local listening address. If the OS or another device needs to query mihomo DNS, configure listen separately and check port availability, permissions, and firewall rules. Don’t expose DNS to your local network by simply adding a listen address.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'

dns.ipv6: false affects how the DNS module handles AAAA queries. It does not disable IPv6 in the operating system or guarantee that all IPv6 traffic is intercepted. If the system still has an IPv6 route, apps may use IPv6 through cached results or other resolution paths. Also check the top-level IPv6 settings in the running configuration, TUN routes, and connection logs; one DNS toggle does not explain the behavior of the entire network stack.

Set DNS policies by domain; avoid stacking fallbacks

nameserver-policy routes queries for specific domains to designated resolvers. This is useful for internal company domains or services with specific resolution requirements. Corporate DNS servers are often reachable only while connected to the office network; using one as the resolver for every domain may cause widespread timeouts when you’re away. A safer approach is to limit it to internal domains and confirm queries still use the right network interface. Decide separately whether those domains also need direct-connection rules, based on the reachability of their destination addresses.

Adding more resolvers does not necessarily make DNS more reliable. fallback and its filter conditions both affect resolver selection, so list order alone does not mean “try the second resolver only if the first fails.” If respect-rules makes DNS connections follow routing rules, account for dependencies involving node hostname resolution and rules, and keep a separate working path for resolving nodes. Unless you have a specific need, start with a few reachable upstream resolvers, confirm they work, and then add domain-specific policies to avoid hard-to-understand dependencies.

Distinguish DNS errors from connection errors

Troubleshoot in three steps: did a query arrive, did it return a result, and can the destination be reached? For query timeouts, check resolver reachability first. If an address was returned but the TCP connection times out, check the policy, egress route, and routing. If only one browser fails, check its independent DNS settings, proxy configuration, and cache. In Fake-IP mode, seeing a reserved address is expected behavior; it does not by itself indicate DNS poisoning. Don’t manually pin a domain to that address.

After changing settings, close existing connections from the affected app, then clear DNS and Fake-IP caches using the method supported by your client. Clear the system cache if needed, but don’t reset the entire network stack every time. A certificate error is not something to fix by switching DNS: check the system clock, certificate issuer, and domain, and keep browser certificate validation enabled. If the issue occurs only through one egress route, test the same domain both directly and through that route, record the difference, and then decide what to change.

Using TUN with Fake-IP

Intercepting traffic and returning an address are separate functions

TUN uses a virtual network interface and routes to receive traffic, which helps with apps that ignore system proxy settings. Fake-IP is a DNS response and domain-mapping mechanism: it returns reserved addresses so the core can associate later connections with their domains. They’re often used together, but they are not the same thing. If the system proxy works but one app doesn’t, that app may be bypassing the proxy. If TUN is enabled but access still fails, check permissions, route conflicts, or the app’s network behavior before changing DNS mode.

Before enabling TUN, check whether your Clash client supports it and whether it requires service mode or administrator privileges. Windows may require a service or elevated permissions; macOS requires system authorization and support from the client; Linux requires permission to create a virtual interface and manage routes. Android generally uses the system VPN interface, so desktop service-mode instructions don’t apply. Follow the client’s own setup and authorization screens. If the feature is unavailable, check your client choice in the download center.

Start with a basic configuration you can roll back

This desktop TUN example should be checked alongside the DNS settings in the previous section. auto-route requests automatic route configuration; auto-detect-interface identifies the outbound interface; and dns-hijack intercepts matching DNS traffic. any:53 does not mean every encrypted DNS request can be detected. An app’s own DoH request over HTTPS is not the same as a regular query on port 53.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

Available stack options depend on the environment and kernel capabilities. Common values include system, gvisor, and mixed. Don’t change the network stack, adjust MTU, and enable strict routing all at once, then try to identify the cause from a single test. Start with the client’s recommended setting and confirm that browsing, downloads, and local network access work. If you can reproduce a specific issue, compare network stacks one at a time while keeping the node, rules, and test app the same.

Handle Fake-IP compatibility and local network access

Device discovery, local network services, and apps that require real IP addresses may not work well with Fake-IP responses. Add specific domains to fake-ip-filter to use their normal resolution path instead of switching DNS modes entirely. The filter only changes DNS behavior; it does not automatically create direct routes. For local services, also check the rules, system routes, and network interface. A domain resolving to a private IP does not mean that address is reachable from the current network.

Don’t add every domain to the filter list; that defeats much of the purpose of Fake-IP and makes behavior harder to understand. After changing Fake-IP mode, its address range, or filter rules, cached entries may still send apps to old reserved addresses. Close the affected connections and clear the relevant caches before testing again. If a corporate VPN, container network, or lab environment already uses an address range that overlaps with Fake-IP, choose a different range and clear the caches; changing one route alone won’t resolve the conflict.

Troubleshoot permissions, routes, DNS, and connections in order

If TUN fails to start, check the logs for permission errors, device creation failures, or route addition failures, then address the corresponding OS-level issue. If it starts but traffic cannot get through, first rule out another VPN or network accelerator taking over the default route. Make sure the outbound interface is detected correctly, then check whether DNS queries reach the core. Don’t disable all security software and the system firewall. Check the specific processes, interfaces, and rules involved, and grant only the minimum required permissions.

If webpages work but games, voice chat, or other UDP apps fail, confirm that the node and upstream route support UDP forwarding, then check whether the rules send traffic through the right route. TUN receiving UDP does not guarantee the remote endpoint can handle it. If only large responses or specific transfers fail, investigate MTU and path issues using the same scenario before and after the change. Judge the result using both connection logs and the app itself: seeing TUN enabled only confirms that interception is on, not that every app is routed as expected.

Domain Sniffing and Rule Matching

When connections need domain information

Domain rules need usable domain information from the connection. If an app connects directly to an IP, uses its own resolver, or sends DNS queries outside mihomo, the connection list may show only a destination address. Domain sniffing attempts to extract a domain from some protocol handshakes for use in subsequent processing. It can provide missing context in some cases, but it is not a fix for every DNS issue and cannot recover a domain from every app connection.

HTTP host information, the server name in a TLS handshake, and some QUIC handshake data may help identify a domain. TLS sniffing does not decrypt HTTPS content; it does not require installing a TLS interception certificate and cannot reveal encrypted data. Encrypted Client Hello and similar mechanisms may limit the domain information available. For such connections, accept the limits of domain detection and use known IP ranges, app-specific rules, or a reliable DNS path instead of expanding sniffing indiscriminately.

Start with specific ports and limited coverage

This example shows a sniffing configuration for common protocols. The HTTP and TLS port ranges limit which traffic is inspected, rather than applying sniffing to every port. With override-destination disabled, you can first check whether domain detection improves without changing how destination addresses are handled. Some clients generate the same settings from GUI toggles. Before enabling them, check whether the subscription already defines sniffer so a local change isn’t overwritten by another configuration layer.

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

parse-pure-ip allows sniffing to be attempted on connections to raw IP addresses; it does not mean those connections necessarily contain a domain. force-dns-mapping affects handling of DNS mapping scenarios; it is not a substitute for correct DNS settings. override-destination controls whether the sniffed domain overrides destination handling, so verify its effect with your app. If protocol-specific override settings are also present, check the final effective value rather than inferring behavior from the top-level toggle alone.

Verify domain detection separately from route changes

Choose a reproducible request that previously showed only an IP. Enable sniffing, establish a new connection, and check whether its details now include a domain and whether the matched rule changed. If the domain appears but traffic still goes direct, check rule order and proxy group selection. If no domain appears, check whether the protocol, port, and handshake are within the detectable range. One unchanged connection does not prove the entire configuration failed to load; different resources on the same page may use different protocols.

A sniffed domain should not be treated as unquestionably accurate. Some apps reuse a connection for different services, while others connect by IP but include a different name. If enabling destination override breaks a particular service, compare the results with override disabled while keeping sniffing on. If you confirm a compatibility issue, exclude specific domains with settings such as skip-domain. Keep exceptions limited and easy to explain instead of adding unverified service names.

Compatibility, privacy, and performance limits

Sniffing inspects initial connection data, and its value depends on your DNS path and the type of traffic. If Fake-IP already associates most connections with the right domains, broader sniffing may not help. For long-lived sessions or custom protocols, preserve the original destination behavior where possible. Don’t risk working connections just to make domains appear more completely in logs. When troubleshooting is done, turn off temporary debug logging to avoid retaining unnecessary domain and browsing-path data.

If you see a certificate warning, first confirm that the certificate belongs to the site, then compare results with destination override enabled and disabled. Sniffing is not a reason to ignore certificate warnings, and allowing insecure connections is not a valid way to “verify the fix.” If the domain and rule match correctly but the issue occurs only on one node, investigate the egress route and remote service. For protocols that cannot be identified, checking the app’s proxy support, DNS resolution, and IP rules is usually more effective than adding more sniffing settings.

Local Overrides and Merging Subscriptions

Know which changes will survive a reload or update

Subscription source files, local configuration copies, override rules, and the final running configuration are different things. Direct edits to a downloaded subscription file may be overwritten the next time it updates; edits to the running configuration may be lost when it reloads and regenerates. Put persistent rules in a local override, extension configuration, or scripting entry point supported by your client. Menus and processing order vary between Clash clients; a script interface for one client is not a universal mihomo setting.

In the client, confirm the current configuration source and whether global or per-subscription overrides are enabled. Try a minimal change with an easy-to-identify rule: save, reload, inspect the running configuration, update the subscription, and inspect it again. Move larger customizations over only after the rule survives every stage as expected. If an update removes it, identify which configuration layer needs the change instead of repeatedly pasting it back by hand; that only makes the source harder to track.

Tell full subscriptions apart from proxy providers

A full Clash YAML file usually contains proxies, proxy groups, rules, and other settings. A node subscription may not include any of these, and a Base64-encoded list of nodes is not a complete YAML configuration. Before merging subscriptions, confirm the format of each input. For help understanding the differences, see subscription formats and conversion. Keep access credentials in subscription URLs on your own device—never include them in public logs, screenshots, or online conversion tools.

If the existing content follows the mihomo proxy provider format, use proxy-providers to separate node sources from the main configuration. This example uses a local node file containing a valid proxies list. It is not a drop-in alternative for any full subscription. If the input is a webpage or encoded text, first process it into the correct format through a trusted local workflow, then give it to the provider.

proxy-providers:
  office:
    type: file
    path: ./providers/office.yaml
  travel:
    type: file
    path: ./providers/travel.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - office
      - travel

For remote proxy providers, assign each source a unique name and cache path, then enter the URL and update interval provided by the source. Don’t share paths between node files and rule sets. If the client manages subscriptions through its own import process, you can keep using the GUI for updates and reference the generated nodes in a local override. Make sure those references still work after updates; don’t rely on temporary filenames or unstable internal directories.

Arrays, duplicate names, and precedence

Array behavior is a common source of merge problems. When you add a rules array in an override, some clients replace the original array, some offer prepend or append options, and others require a script to concatenate the arrays explicitly. Mapping fields may not be merged recursively either. Don’t assume that everything is preserved just because the interface says “merge”—inspect the complete generated configuration. In particular, confirm that the original MATCH rule is still last and that local exceptions actually precede shared rules.

Subscriptions often contain proxy and group names that are identical, so merging them directly can create ambiguous references, name conflicts, or import failures. In a controlled merge workflow, add a source prefix to node names and update every group reference to match. If you use provider filters, check whether renaming affects their results. Don’t change only the display name and leave old rule targets in place. After merging, trace each rule to an existing proxy group, then to a valid node or built-in policy.

Validate, roll back, and migrate

You can use mihomo’s configuration test mode to check syntax and references. Run the command below in an environment where the executable is available; config.yaml is the file to test. Relative resources depend on the working directory, which may differ from the GUI client’s. Even if the command-line test passes, reload the configuration in the client and check whether providers load successfully. Valid syntax only means the configuration can be parsed; it doesn’t guarantee the subscription source is reachable or every node can connect.

mihomo -t -f config.yaml

To roll back, disable the new override first, restore the last working configuration, then reload and verify it. A short record of the change, affected fields, test domain, and rollback location is more useful than multiple unlabelled copies. When moving to another client, migrate the subscription first, then rules and DNS, and finally GUI-level scripts. Startup settings, TUN permissions, and override interfaces usually need to be configured again in the new client; copying a YAML file alone does not complete the migration.

External Controller and LAN Sharing

Configure proxy access separately from management access

Proxy ports carry app traffic; the controller API reads status, switches proxy groups, and manages connections. Sharing a proxy with devices on the same network does not require exposing the controller API. mixed-port is the shared HTTP and SOCKS proxy port; external-controller is the management API address. They serve different purposes and have different security risks. If a phone cannot connect to a computer’s proxy, opening the management port is not the solution.

For single-device use, listen on the loopback address only. This local management example uses an explicitly fake password for illustration; generate a unique, long random password on your device before enabling the controller. secret authenticates the controller API and is separate from node passwords and subscription credentials. If the client already manages controller settings, change them in its settings to avoid startup processes replacing manually configured values.

mixed-port: 7890
allow-lan: false
external-controller: 127.0.0.1:9090
secret: "your-password"

Check the listener and authentication before connecting a panel

A control panel usually needs the controller address and password. It can read proxy groups and connections only if the controller is running, reachable, and accepting the credentials. A panel that won’t open and one that opens but cannot connect to the core are different problems: check panel assets for the first, and the API address, port, authentication, and browser network restrictions for the second. If the logs show address already in use, find the process using the port instead of changing every listener to bind to all interfaces.

To host a panel locally, place trusted static panel files in a dedicated directory under the configuration working directory, then set the path with external-ui. Don’t use your entire home directory as the static asset directory, or unrelated files could be exposed. Also consider the page protocol when accessing the panel in a browser: an HTTPS page calling an HTTP API may be blocked as mixed content. Cross-origin requests may also require the appropriate allowed-origin settings; neither issue means the subscription has failed.

A panel can control the core; it is not just a read-only dashboard. Don’t put the controller password in public link query parameters, screenshots, or shared bookmarks, and don’t remove authentication just to avoid entering it. For remote management, route requests through a controlled private network or secure tunnel and restrict their source. Reverse proxy settings, authentication, and TLS must each be configured correctly; a complex password is no substitute for network boundaries.

Share only the proxy access needed on your LAN

Before sharing, confirm that both devices can reach each other on the network, the computer’s LAN address is stable, and the router does not have client isolation enabled. Then turn on “Allow LAN connections” in the Clash client and check the actual listening address and firewall. Allow only trusted network ranges that need access to the proxy port. On the phone, enter the computer’s LAN address, not 127.0.0.1; that address points to the phone itself, not the computer.

This proxy-sharing example keeps the controller listening on loopback. bind-address takes effect according to its semantics when the relevant LAN access setting is enabled; verify the actual listening address. The example credential is still a fake value for illustration; replace it with a unique credential for your device. Some devices’ system proxy settings do not support authentication. In that case, consider the device’s capabilities and the security of the network rather than exposing the proxy port to an untrusted network.

mixed-port: 7890
allow-lan: true
bind-address: '*'
authentication:
  - "lan-user:your-password"
external-controller: 127.0.0.1:9090
secret: "your-password"

The HTTP proxy setting in a phone’s Wi-Fi network usually affects only apps that honor it; it does not route every app or UDP connection. Enabling TUN on the computer also does not automatically turn it into a transparent gateway for the phone. To route an entire device, you need an explicit gateway, routing, and DNS setup. Don’t confuse “Allow LAN connections” with “Share TUN.” In a typical home network, an explicit proxy supported by the app is easier to control and troubleshoot.

Finish setup with a minimal test

To verify sharing, first confirm the proxy works on the computer itself. On the second device, check that it can reach the computer’s address, then configure the proxy and watch the computer’s connection list. If no new connection appears, check the address, port, authentication, and firewall. If a connection appears but access fails, check the matched rule, final node, and DNS. If only some apps work, confirm that they honor the system proxy instead of changing the controller. Public Wi-Fi and guest networks may isolate devices, even when they use the same network name.

When setup is complete, close temporarily opened ports, turn off debug logging, and confirm the controller is visible only to the intended network. Make sure subscription updates have not overwritten local security settings. Keep a brief handoff note with the proxy port, listening scope, credential storage location, override entry point, and rollback steps—never include the password itself. To repeat the basic setup, return to the user guide. For common issues such as import failures or leftover system proxy settings, check the help center instead of stacking the entire advanced configuration again.