Advanced Clash Configuration Guide

Chapter 01 / Baseline

Configuration skeleton and debugging baseline

A Clash configuration is not a list of independent settings; it is an ordered processing chain. The client first reads basics such as listening ports, operating mode, and DNS, then loads proxy nodes and proxy groups, followed by rules and rule providers. Finally, the system proxy or TUN sends traffic into the core. A reference to a name that does not exist at any layer can affect everything that follows. A common example is a rule pointing to a proxy group that has been renamed: the configuration may still parse, but matching traffic cannot select the intended exit. The first step in advanced tuning is therefore not adding more parameters, but creating a baseline that can be explained, verified, and rolled back.

Separate client settings from core configuration

Graphical clients such as Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu typically divide settings into two layers. The first belongs to the application itself: launch at startup, the system proxy toggle, profile update intervals, themes, and service installation status. The second is the YAML passed to the mihomo core. The system proxy button usually does not rewrite the subscription file; it changes the operating system's proxy entry point. The TUN toggle may generate a runtime override, so the exact same fields may not appear in the original subscription. When troubleshooting, inspect both the active configuration and the subscription source instead of focusing only on the downloaded YAML.

Keep the baseline section deliberately small for debugging. Start with the info log level, which is enough to show connections, rule matches, and DNS errors; switch to debug only when tracing a specific request. Whether ports need to be specified explicitly depends on how the client manages them—desktop clients may inject their own ports at startup. If you maintain a raw configuration by hand, you can use the structure below, but confirm that the port is not already occupied by another proxy program.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
unified-delay: true

profile:
  store-selected: true
  store-fake-ip: true

mode: rule selects direct, proxied, or rejected traffic according to the rules; unified-delay makes latency measurements closer to the full connection process, but it does not improve actual network quality; store-selected saves proxy-group selections so you do not have to choose them again after restarting; store-fake-ip preserves Fake-IP mappings and reduces short-lived connection fluctuations after a restart. Persistence is especially important on mobile when the system may reclaim the app process, but the client must still be allowed to run normally in the background.

Build the shortest verification loop

After each change, first confirm that the core can load the configuration, then verify that a proxy node can establish a connection. Next, check which rule matched one test request, and only then inspect the target application. If parsing already fails, switching nodes will not help. If the node handshake fails, investigate the subscription and network before changing DNS. If the browser works but one application does not, check whether that app bypasses the system proxy, uses its own DNS, or uses QUIC. This sequence keeps the problem within a single layer.

Use spaces only for indentation in configuration files; do not mix in tabs. Text containing colons, hash signs, or special characters can be quoted, and proxy-group names should remain stable once referenced by rules. If you need to change clients, start from the download page and choose the appropriate platform; Clash Plus is the first choice for cross-platform use, followed by other clients based on your system and workflow. During migration, import the same subscription first and verify the basic connection, then move over local overrides. Do not copy runtime fields generated by the old client as if they were universal configuration.

Chapter 03 / Rules

Manage rules as subscriptions

Once a rule list grows from a dozen entries to several hundred, keeping everything in the main configuration quickly becomes unmanageable. rule-providers separates themed rules into independent resources and lets the main configuration declare their URLs, formats, update intervals, and matching behavior. The main file keeps only the invocation order while each provider maintains its own content. This allows ad-blocking, LAN, developer-service, or streaming rules to be updated independently and disabled quickly when one provider fails, without rewriting the entire subscription.

Provider definitions and RULE-SET calls

A rule provider's name is only a local reference identifier; parsing depends on behavior, format, and the resource content. behavior: domain suits collections containing only domain entries; ipcidr is for IP networks; classical can hold classic rules with type prefixes. The format must match the remote file. Common text rules can use text, while YAML rules use yaml. Do not declare classical content as domain: successful loading does not mean the matching semantics are correct.

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/private-domain.yaml
    url: https://example.com/rules/private-domain.yaml
    interval: 86400

  developer:
    type: http
    behavior: classical
    format: text
    path: ./ruleset/developer.list
    url: https://example.com/rules/developer.list
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,developer,Developer Services
  - GEOIP,LAN,DIRECT,no-resolve
  - MATCH,Main Selection

The example domain only shows the field structure. In practice, replace it with a confirmed, reachable, and trusted rule source. path is the local cache location; different providers should not share the same path. interval is measured in seconds, and public rules usually do not need updates every few minutes. Excessive frequency only adds requests and writes. When an update fails, the core generally continues using the existing cache, so distinguish an initial download failure from an update failure where the old rules remain active. Deleting the cache and retrying removes this fallback and should not be the first step.

Rule order is priority

Clash searches rules from top to bottom and stops at the first match. Specific rules should come before broad ones: private domains and LAN traffic usually go direct first, service domains then enter their designated policies, IP rules belong where address resolution is required, and MATCH catches everything else at the end. If a broad proxy rule is placed at the top, later direct exceptions will never run. When troubleshooting incorrect routing, the log entry showing which rule matched is more reliable than guessing which category a domain belongs to.

no-resolve tells IP-based rules not to trigger DNS resolution just to obtain an IP address. It can avoid unnecessary lookups, but should not be added mechanically to every rule. If a domain request matches no domain rule and a later GEOIP decision depends on resolution, blocking resolution entirely may leave that rule without the address it needs. Decide whether to add it based on the rule type and DNS mode. Connections that already provide a destination IP can still match IP rules normally.

A small number of local exceptions can be written directly at the top of rules; there is no need to create a remote provider for three or five entries. For example, if a work domain must go direct or an application endpoint must always use “Developer Services,” place those rules before subscribed providers. If the exception list keeps growing, move it to a local provider. This keeps the main configuration readable without requiring a remote file release for every small adjustment.

rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - DOMAIN-SUFFIX,github.com,Developer Services
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,developer,Developer Services
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,Main Selection

How to locate rule-provider failures

First check whether the provider has finished loading, then confirm that the remote response matches the declared format. Next verify that the provider name matches the RULE-SET reference, and finally inspect its position in the rule list. If the status is normal but nothing matches, common causes include the wrong behavior type, a broad earlier rule capturing the request, or a target connection exposing only an IP while the provider contains only domains. If an update suddenly causes widespread misrouting, restore the previous local cache or temporarily comment out the provider to confirm whether the problem came from an upstream content change.

The more rule sources you add, the harder it becomes to standardize update schedules and naming. A more reliable structure uses a small number of providers selected by purpose, with one primary source per service and local exceptions at the highest priority. Do not import multiple broad providers with nearly identical coverage and expect ordering to resolve every conflict. For multi-device management, see the multi-device configuration sync guide and keep the main configuration, subscription links, and local rules separate.

Chapter 05 / Network stack

Coordinating TUN mode and Fake-IP

The system proxy covers only applications that actively follow proxy settings. Command-line tools, some games, apps with independent network stacks, and programs that send UDP directly may bypass it completely. TUN mode uses a virtual network interface to take over system routes and send this traffic into the Clash core, providing broader coverage. Fake-IP returns a mapped address during DNS resolution so that, when the application connects to it, the core can restore the original domain and apply domain rules. They are often used together, but serve different roles: TUN brings traffic in, while Fake-IP preserves domain semantics.

TUN fields and system permissions

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: true
  mtu: 1500

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

stack selects the network-stack implementation used by TUN. mixed balances compatibility and performance in supported cores; if a particular platform behaves unexpectedly, test system or gvisor separately instead of switching repeatedly without a comparison. auto-route writes routes automatically, while auto-detect-interface attempts to identify the current egress interface. This reduces manual interface maintenance when a device switches between Wi-Fi, mobile data, and Ethernet. strict-route more aggressively prevents traffic bypasses, but may expose routing conflicts with other VPNs, virtual machines, and container networks.

TUN startup requires system-level VPN or network-extension permission. A Windows client may use service mode to elevate network-operation permissions; macOS requires approval for the network extension; Android and iOS show a system VPN authorization prompt. When permission is denied, the interface toggle may turn on briefly and then revert, while logs show device-creation or route-writing errors. Reimporting the subscription repeatedly will not help; handle system authorization first. For macOS-specific prompts and recovery steps, see the network extension and Keychain guide.

How Fake-IP mappings work

When Fake-IP mode receives a domain query, it does not immediately give the real address to the application. Instead, it assigns a mapped address from a reserved range. When the app connects to that address, the core restores the domain from the mapping table and matches DOMAIN, DOMAIN-SUFFIX, or a rule provider. This allows Clash to retain the original domain even when an application passes only the destination address to the network layer. A mapped address is not the address of a remote server and should not be used for public-network routing tests. Results in the 198.18.0.0/16 range usually indicate that Fake-IP is participating normally in resolution.

Some LAN discovery, time-sync, printer, gaming-platform, or real-DNS-dependent applications do not work well with Fake-IP and need to be added to fake-ip-filter. Keep exclusions as specific as possible. Excluding an overly broad domain set sends many requests back to real-address mode, weakens domain restoration, and may force rules to depend on IP matching. When compatibility fails, identify the domain in the logs, add one suffix at a time, and retest instead of copying an unexplained, oversized filter list.

MTU, UDP, and network switching

If pages load but some images, uploads, or a particular app stall, the path MTU may be unsuitable. TUN encapsulation adds overhead, and an underlying VPN, PPPoE link, or mobile network may already impose limits, so 1500 bytes can cause fragmentation or packet loss. Keep the rest of the configuration unchanged and lower the MTU gradually—for example, test around 1400 first—while watching whether the issue consistently disappears. Smaller is not always safer: an MTU that is too low increases packet count and processing overhead. Once confirmed, choose the largest value that remains stable.

Separate UDP problems into three layers: whether the application sends UDP, whether TUN intercepts it, and whether the node protocol and network support that transport. DNS queries, QUIC, games, and voice traffic may all use UDP. If disabling QUIC restores browser access, that only localizes the fault to the UDP path; it does not mean DNS or the node is generally unavailable. After a mobile device switches between Wi-Fi and cellular data, an old session may still be bound to the previous interface. Reconnect TUN when necessary instead of immediately clearing the entire configuration.

The recommended order is: use the system proxy first to confirm that nodes and rules work; enable TUN separately and verify routing and permissions; then enable Fake-IP and handle a small number of compatibility exceptions. If enabling TUN cuts off the entire device, turn it off to restore connectivity, then check the default route, DNS hijacking, and other VPNs. For Windows service mode, port conflicts, and system-proxy steps, see the complete Windows installation and configuration guide.

Chapter 07 / Merge

Local overrides and merging multiple subscriptions

A subscription supplies remotely maintained nodes and a baseline configuration; local overrides preserve adjustments specific to a device or personal environment. Editing both directly in one file means the next subscription update may overwrite local changes, while copying everything into a static configuration loses node updates. A better structure treats the subscription as upstream input and puts ports, DNS, added proxy groups, rule ordering, and TUN settings into a repeatable override layer. Clients use different names for this mechanism—Merge, Mixin, Script, or global extensions—but the goal is the same: regenerate the active configuration after updates.

Distinguish replacement, appending, and deep merging

YAML objects can be merged by key, but arrays have different semantics. Changing dns.enable usually replaces one field; handling rules requires deciding whether to prepend rules, append them, or replace the entire array. If a merger directly overwrites the old array, an override containing only three local rules may remove every rule from the subscription. Before using a client's built-in merge function, inspect the final active configuration rather than checking only whether the override fragment was saved.

prepend-rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,corp.example,DIRECT

append-rules:
  - MATCH,Main Selection

override:
  mode: rule
  log-level: info
  ipv6: false

The structure above illustrates three intentions—prepend, append, and replace. The exact keys depend on the client's merge implementation and must not be loaded directly as native mihomo configuration without confirmation. mihomo still receives one complete configuration in the end. To verify it, open the runtime configuration generated by the client and confirm that local rules appear in the expected position, proxy groups are not duplicated, and only one MATCH remains. If the client provides a configuration checker, run it after every update.

Merge multiple subscriptions at the node layer

When using several subscriptions, the most stable approach is usually to declare them as separate proxy-providers and import them into local proxy groups with use, rather than concatenating multiple complete configuration files. Complete profiles often contain their own ports, DNS, proxy groups, and rules; identical keys overwrite one another, identical groups conflict, and the outcome depends on the merger. Providers should handle node collections, while the local main configuration handles unified policies and rules. The responsibilities remain clear.

proxy-providers:
  primary:
    type: http
    url: https://example.com/subscription/primary
    path: ./providers/primary.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

  backup:
    type: http
    url: https://example.com/subscription/backup
    path: ./providers/backup.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 900

proxy-groups:
  - name: Main Selection
    type: select
    use:
      - primary
      - backup
    proxies:
      - DIRECT

The subscription URLs in the example show structure only. Replace them with your own valid URLs, and never expose links containing access credentials in documents, screenshots, or shared repositories. The two providers must use different cache paths. Adjust health-check intervals according to the device and node count; mobile devices should not poll large node lists too frequently. If upstream node names collide, the interface may make their sources difficult to distinguish. Use a client-supported prefix feature at the merge layer or place each provider in a separate regional group instead of mixing everything into one long list.

Update failures and configuration drift

In multi-subscription setups, the common problem is not a configuration that fails to load once, but one that gradually drifts from expectations. An upstream provider may rename nodes and invalidate filters; removing a region may leave a proxy group empty; adding a duplicate node name may make manual selection point to another source. After an update, check provider status, whether group member counts are reasonable, and whether key service rules still point to existing groups. Do not monitor fictional fixed node counts. Watch whether groups are empty, references exist, and important requests still match as expected.

When syncing across devices, do not sync the entire client data directory. Desktop and mobile systems differ in permissions, paths, TUN interface names, and cache locations. Sync subscription sources, a local main-configuration template, rule providers, and override logic instead, while keeping device-specific settings in each client. For differences between WebDAV, subscription distribution, and manual imports, continue with the Clash multi-device configuration sync guide.