Clash Custom Rules Syntax Explained: Match Types, Order, and Priority

PROOF / 01

Rule Matching Model: Top Down, First Match Wins

Clash rules form a line-by-line traffic routing table. Each rule usually consists of a type, a match target, and a policy, with some types accepting additional parameters. When processing a connection, the core checks the list from the top and immediately applies the policy on the first matching line; later rules are not evaluated.

Rule priority is not determined automatically by the rule type. DOMAIN is not inherently more specific than DOMAIN-SUFFIX, and IP-CIDR does not automatically override an earlier domain rule. The line position is what determines priority. A broad rule placed too early can therefore hide a more precise exception later in the list.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Proxy Selection
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Selection

This order sends api.example.com directly, then routes other subdomains under that domain through “Proxy Selection.” If the first two lines are swapped, the exact host is caught by the suffix rule first and the direct-connection exception no longer works. The final MATCH rule is the fallback for connections that matched nothing earlier; it is normally placed once, at the end.

PROOF / 02

Domain Rules: Exact Hosts, Suffixes, and Keywords

Domain rules are ideal when the destination hostname is clear and are among the most commonly used rule types for custom routing. When a connection retains its domain information, the core can match it directly without first resolving the destination to an IP address. Common types include:

rules:
  - DOMAIN,login.example.net,DIRECT
  - DOMAIN-SUFFIX,example.net,Work Services
  - DOMAIN-KEYWORD,streaming,Media Nodes
  - GEOSITE,cn,DIRECT
  - MATCH,Proxy Selection

DOMAIN,login.example.net matches only this exact host; it does not match static.login.example.net. DOMAIN-SUFFIX,example.net generally covers both example.net and subdomains at any level, making it suitable for site-wide routing. DOMAIN-KEYWORD is the least constrained: any target domain containing the specified fragment may match. Use a distinctive keyword and place it after exact rules.

GEOSITE uses dataset-driven matching. Its availability and category names depend on the core, client, and geographic data files in use. When migrating a configuration, do not assume that a category recognized by one client is supported by every Clash-derived core. Check the core type and confirm that the data files have loaded correctly.

PROOF / 03

IP, Source Address, and Network Protocol Rules

Use IP-based rules when a service can only be identified by address ranges, or when routing must depend on a LAN source or destination region. IPv4 ranges generally use IP-CIDR, while IPv6 ranges use IP-CIDR6. GEOIP classifies the destination IP using a geographic database.

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fd00::/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Selection

no-resolve prevents an IP rule from actively triggering domain resolution for matching. When the connection already provides a destination IP, the rule can still check that address. If the target is only a domain and the core has not obtained its real address, the rule will not force an additional DNS lookup. This parameter is often added to LAN-reserved address rules because ordinary domain resolution is unnecessary for them.

Whether to add no-resolve depends on the target. If GEOIP needs the resolved address to decide between direct connection and proxying, disabling resolution may leave it without the data it needs. Conversely, when domain rules already cover the main services and IP rules only handle direct-address connections, adding the parameter avoids unnecessary DNS lookups.

In Fake-IP mode, an application may first see a reserved address assigned by the core, while Clash maintains the mapping between the domain and the real destination. Domain rules can usually still use the original hostname, but troubleshooting IP rules requires distinguishing the “Fake-IP seen by the application,” the “domain mapping stored by the core,” and the “real IP returned by the upstream resolver.” Looking only at the destination shown by a browser or application can easily lead to a wrong conclusion about whether a rule matched.

Source Addresses and Network Types

SRC-IP-CIDR matches the address of the device that initiated the connection, which is useful on routers and LAN gateways. For example, a test device can be assigned its own policy. NETWORK distinguishes TCP from UDP and works well when combined with more specific port conditions. Sending all UDP traffic to one policy too early, however, usually affects far more traffic than intended.

rules:
  - SRC-IP-CIDR,192.168.50.25/32,Test Policy
  - NETWORK,UDP,Proxy Selection
  - MATCH,DIRECT

When a desktop client proxies only local traffic, source-address information may be less useful for differentiation than in a router-based transparent proxy setup. Before using these rules, confirm the client mode, the scope of TUN capture, and the connection metadata actually available to the core.

PROOF / 04

Process, Path, and Port Matching

Process rules route traffic according to the application that initiated the connection. PROCESS-NAME generally matches the executable name, while PROCESS-PATH matches the full path. They are useful when several applications share a domain but only one program should use a particular policy.

rules:
  - PROCESS-NAME,example-client.exe,Work Services
  - PROCESS-PATH,C:\Apps\Example\example-client.exe,Work Services
  - DST-PORT,22,Development Nodes
  - DST-PORT,123,DIRECT
  - MATCH,Proxy Selection

Process identification depends on operating-system permissions, client implementation, core version, and capture mode. Windows, macOS, and Linux represent process names and paths differently, and mobile systems generally cannot use desktop executable rules as-is. If logs show only a destination address and no process field, changing the process name repeatedly is unlikely to help; first confirm that the current platform can provide process metadata.

DST-PORT matches the destination port, while SRC-PORT matches the local source port. Destination ports are more stable than source ports, but neither identifies a service by itself. TCP 443, for example, is shared by countless HTTPS services; routing it all to one proxy policy would capture most web connections. Port rules are better suited to clearly defined protocols, or to mihomo logical rules that combine them with domains and network types.

PROOF / 05

Practical Rule Ordering and Priority

A maintainable rule table usually follows the structure “exceptions first, normal traffic next, fallback last.” Start with exact hosts that must connect directly or be rejected, then add business domains and process rules, followed by address ranges and geographic categories, and finish with MATCH. Adjust the order to your actual targets rather than applying a fixed template mechanically.

1. Local and administrative addresses: Router admin panels, LAN ranges, and local services should usually connect directly first so broad proxy rules cannot capture them.
2. Exact exceptions: Use DOMAIN, a single-address CIDR, or a specific process name for special cases.
3. Service rules: Assign traffic to the appropriate policy group by domain suffix, rule set, or application process.
4. Broad categories: Place geographic databases, keywords, and large rule sets after more precise rules.
5. Final fallback: Point MATCH to the intended default policy.

rules:
  # LAN
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve

  # Exact exceptions
  - DOMAIN,update.example.org,DIRECT
  - DOMAIN,blocked.example.org,REJECT

  # General services
  - DOMAIN-SUFFIX,example.org,Work Services
  - PROCESS-NAME,media-player.exe,Media Nodes

  # Regions and fallback
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Selection

Comments do not change rule behavior, but they can significantly reduce future validation work. Label each group by its purpose rather than merely recording its source. After a subscription update or manual merge, you can quickly verify that custom sections remain where expected. Pay particular attention to client overrides: some clients insert custom rules at the top, some append them at the bottom, and others regenerate the entire configuration when updating a subscription.

PROOF / 06

Rule Providers and mihomo Logical Rules

When there are many rules, use rule-providers to move them into separate files, then reference them from the main rule table with RULE-SET. The provider stores the match entries, but its position in the main configuration still determines overall priority. Defining a provider near the top of the configuration does not make it execute before other rules automatically.

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

rules:
  - DOMAIN,internal.example.net,DIRECT
  - RULE-SET,service-domains,Work Services
  - MATCH,Proxy Selection

The behavior must match the rule file contents. A domain collection can use domain, an IP-range collection can use ipcidr, and a collection containing multiple classic rule types generally uses classical. Core versions may differ in their support for format, behaviors, and data-file formats. Before importing an existing rule set, check the actual core used by the client rather than relying only on the client’s product name.

mihomo also supports logical combinations. Use AND, OR, and NOT to combine multiple conditions into one rule. For example, a condition that matches only UDP 443 can be written as:

rules:
  - AND,((NETWORK,UDP),(DST-PORT,443)),REJECT
  - MATCH,Proxy Selection

Logical rules are useful for expressing complex conditions that must all be true or where any one condition is sufficient, but parentheses, commas, and nesting levels are easier to get wrong. They are extension features of compatible cores such as mihomo and may not be recognized when migrated to an older original Clash core. For readability, do not force a deeply nested expression when two or three clear standard rules will solve the problem.

PROOF / 07

A Practical Order for Troubleshooting Rule Failures

A rule failure is rarely caused by syntax alone. A more effective approach is to verify, step by step, whether the configuration loaded, the connection entered the core, the metadata matches expectations, and an earlier rule captured the traffic.

1. Confirm the active profile: Reload the configuration after editing and verify the profile name currently enabled in the client. Editing an inactive copy will not change the running result.
2. Check the matched rule in the connection view or logs: Record the destination domain, destination IP, process, network type, and final policy. If an earlier rule matched, reorder the rules or narrow its scope.
3. Check the YAML structure: rules must appear at the correct top-level position, and list items need hyphens. Full-width commas, incorrect indentation, and invisible characters can all cause parsing failures.
4. Verify the policy group name: The name referenced by a rule must actually exist. When a proxy group is renamed, update the target name in older rules as well.
5. Distinguish domains from IPs: When an application connects directly to an IP address, domain rules have no hostname to match. After enabling encrypted DNS, TUN, or Fake-IP, use core logs to determine the actual connection metadata.
6. Check client overrides: Subscription updates, merge scripts, and GUI rule overrides can change the final order. Treat the runtime configuration as the source of truth.
7. Confirm core support: GEOSITE, logical rules, some process fields, and rule-set formats are not supported consistently across all core versions.

Reproduce the Issue with a Minimal Rule Set

When the original configuration contains thousands of rules, temporarily create a minimal configuration containing only test rules and MATCH. First verify that the target domain matches the exact rule, then add suffixes, rule sets, GEOIP, and process conditions step by step. Add one group at a time so it is clear which line changes the result.

rules:
  - DOMAIN,test.example.com,DIRECT
  - MATCH,Proxy Selection

If the minimal configuration matches but the full configuration does not, the cause is usually an earlier rule, override order, or rule-set scope. If the minimal configuration also fails to match, check whether the traffic is entering Clash, whether the target actually includes that domain, and whether the client has loaded the test configuration.

Pre-Submission Validation Checklist

• Are exact exceptions placed before broad suffix, keyword, and rule-set entries?
• Do all policy names match the proxy group names?
• Are IPv4, IPv6, and LAN address ranges using the appropriate rule types?
• Is no-resolve used only with IP rules that do not need active resolution?
• Do the process rules match the identification method used by the current operating system and core?
• Does each rule provider’s behavior match its content format?
• Does the end of the list contain only the intended fallback logic?

A stable Clash custom rule set depends less on the number of rules than on clear boundaries, explainable ordering, and results that can be verified at runtime. Express exceptions with exact rules first, expand the match scope layer by layer, and use logs to confirm the first match. This is usually more reliable than continually adding keywords.