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

Clash Rule Matching Model

Clash's rule system answers one practical question: which policy group, proxy node, or built-in action should handle the current connection? Once a connection enters the core, rules are checked from top to bottom in the order they appear in the configuration file. The first matching rule takes effect immediately, and later rules are ignored for that connection. Clash does not collect every match and compare its "specificity," nor does it automatically give domain rules precedence over IP rules.

A typical rule consists of a rule type, a match value, and a target policy, with fields separated by English commas. For example:

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Proxy
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,Final

DOMAIN, DOMAIN-SUFFIX, and IP-CIDR are rule types; a domain or network range is the match value; and DIRECT, Proxy, and Final are handling targets. The target name must exactly match a proxy group name in the configuration, including capitalization, spaces, and symbols. DIRECT means connect directly, REJECT denies the connection, and a proxy group name lets that group choose the node to use.

Rules generally process connection metadata such as the destination domain, destination IP, port, network type, and originating process. They do not inspect webpage content to determine a site's category. If an app accesses multiple domains on one page, requests for the main page, images, video, APIs, and analytics may match different rules. To verify whether a rule is working, inspect the specific connection rather than relying only on the main domain shown in the address bar.

Domain Matching Syntax: Exact Matches, Suffixes, and Keywords

DOMAIN: Match an exact domain

DOMAIN is designed for one specific hostname. The following rule matches api.example.com, but not www.example.com, v2.api.example.com, or any other subdomain:

- DOMAIN,api.example.com,Proxy

Use an exact domain rule when one endpoint needs separate routing while other services under the same parent domain should keep their existing policy. Domain comparisons in actual connections are generally case-insensitive, but writing domains in lowercase makes configurations easier to review, search, and deduplicate.

DOMAIN-SUFFIX: Match a domain and its subdomains

DOMAIN-SUFFIX is one of the most frequently used custom rule types. The rule below covers example.com, www.example.com, and cdn.media.example.com:

- DOMAIN-SUFFIX,example.com,Proxy

Enter the domain directly as the suffix value; there is no need to add a leading dot or wildcard. Writing *.example.com may not produce the expected result because the rule type already defines suffix matching. To exclude a subdomain, place the exception rule before the general suffix rule:

- DOMAIN,internal.example.com,DIRECT
- DOMAIN-SUFFIX,example.com,Proxy

DOMAIN-KEYWORD: Match text fragments in a domain

DOMAIN-KEYWORD checks whether a domain contains the specified text. For example, DOMAIN-KEYWORD,example,Proxy may match not only example.com, but also example-cdn.net and notexample.org. Its coverage is broad, making it useful for services whose domain structure changes frequently but retains a stable naming fragment. It should not replace every suffix rule.

The shorter the keyword, the greater the risk of false matches. If unrelated sites are being routed through a proxy during troubleshooting, inspect earlier DOMAIN-KEYWORD rules first. When the full parent domain is known, prefer DOMAIN or DOMAIN-SUFFIX.

GEOSITE: Match domain category sets

Clash Meta, including the mihomo core commonly used today, supports GEOSITE for matching curated domain categories. For example:

- GEOSITE,category-ads-all,REJECT
- GEOSITE,cn,DIRECT

Available GEOSITE categories depend on the GeoSite data files bundled with or downloaded by the client. A missing category, an outdated database, or a core that does not support the rule can cause configuration errors or unexpected matches. Before copying rules from another configuration, verify the current client's core type and data source.

IP, Port, and Network-Type Rules

IP-CIDR and IP-CIDR6

IP-CIDR matches IPv4 destination addresses using CIDR ranges, while IP-CIDR6 is used for IPv6. The number after the slash indicates the network prefix length. A single IPv4 address can use /32, and a single IPv6 address can use /128:

- IP-CIDR,203.0.113.8/32,Proxy,no-resolve
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- IP-CIDR6,2001:db8::/32,Proxy,no-resolve

When a connection initially provides a domain, some IP rules may trigger DNS resolution to obtain the destination IP before continuing the match. The no-resolve option at the end of a rule means not to resolve the domain solely to check that IP rule. For rules covering private LAN ranges or known server addresses that do not need domain-based resolution, adding this option can reduce unnecessary DNS queries.

no-resolve does not disable Clash's DNS function globally, nor does it stop an app from making its own DNS requests. It only controls whether the current rule actively resolves a domain to an IP during matching. Do not add it mechanically when the rule depends on a resolved address range.

GEOIP: Match IP database categories

GEOIP matches according to the destination IP's category in a geographic database. A common form is:

- GEOIP,CN,DIRECT,no-resolve

The result depends on the contents of the GeoIP or GeoData database. IP ownership can change, and cloud services and content delivery networks may route traffic across regions. As a result, GEOIP works best as a near-end range rule rather than as a catch-all for precise domain exceptions. Put explicit domain or IP rules before it when a service requires fixed handling.

Ports and protocols

mihomo supports further connection filtering with types such as DST-PORT, SRC-PORT, and NETWORK. Destination-port rules target server ports, while source-port rules apply to ports used by local connections. Network types are usually written as tcp or udp:

- DST-PORT,22,SSH
- DST-PORT,3478-3481,Realtime
- NETWORK,udp,UDP-Policy

Routing by port alone can affect unrelated programs that use the same port. HTTPS, for example, commonly uses port 443, so sending all port-443 traffic to one fixed policy is usually too broad. A safer approach is to combine the port with domain, process, or logical rules to narrow the scope, then monitor the connection list after making changes.

Process Rules and Logical Combinations

PROCESS-NAME and PROCESS-PATH

PROCESS-NAME matches the executable name that initiated the connection, making it useful for routing an entire app through a specific policy. Windows program names usually include the file extension:

- PROCESS-NAME,example.exe,Application-Proxy
- PROCESS-NAME,curl,DIRECT

PROCESS-PATH matches the full program path and is more precise when multiple executables share a name. However, path syntax depends on the operating system and core implementation. Backslashes, spaces, and YAML quoting in Windows paths must be handled correctly. An app upgrade may also change its installation directory and invalidate an old path rule.

Process detection depends on the platform, permissions, and how traffic is intercepted. Some systems expose process information only with specific permissions, and some forwarding paths cannot recover the original process. When a process rule does not work, first check whether the client's connection details show a process name instead of repeatedly changing the rule text.

AND, OR, and NOT

mihomo supports logical rules that combine multiple conditions. For example, you can proxy only a specific domain when it is accessed by a particular app:

- AND,((PROCESS-NAME,example.exe),(DOMAIN-SUFFIX,example.com)),Proxy
- OR,((DST-PORT,80),(DST-PORT,443)),Web
- NOT,((NETWORK,udp)),TCP-Policy

Logical rules are useful for expressing clear intersections, unions, and exclusions, but maintenance becomes difficult quickly when parentheses are deeply nested. Support for logical rules and child rule types may vary between core versions. If the client reports a parse failure after saving, check the current mihomo documentation for parentheses, commas, and supported rule types.

Rule Order and Priority

Clash's central priority rule is "first match wins." Rule types do not have a universal hidden weighting. Even if a more precise DOMAIN rule appears later, it will not run once an earlier DOMAIN-SUFFIX, GEOSITE, or other broad rule has matched.

A practical ordering strategy is to put exceptions first, range rules in the middle, and the fallback at the end:

1. LAN addresses, internal domains, and exceptions that must connect directly.
2. Exact domains that must use a fixed proxy or be rejected.
3. Rules for specific apps, ports, and logical combinations.
4. Broad rules such as domain suffixes, rule sets, GEOSITE, and GEOIP.
5. MATCH fallback rule.

rules:
  - DOMAIN,login.internal.example,DIRECT
  - DOMAIN,api.example.com,Service-Proxy
  - PROCESS-NAME,example.exe,Application-Proxy
  - DOMAIN-SUFFIX,example.com,Proxy
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,Final

In this configuration, api.example.com matches the exact domain rule first and never reaches the later example.com suffix rule. Other domains under that suffix are sent to Proxy. Connections not handled by any earlier rule ultimately go to Final.

MATCH is an unconditional fallback and should be placed at the end of the rule list. Some older configurations use FINAL for a similar purpose, but actual support depends on the core. For mihomo configurations, follow the current core documentation and prefer MATCH. If the fallback appears in the middle, rules after it will never get a chance to match.

When a rule targets a proxy group, it only determines which group handles the connection; the group type still determines node selection. A manual-selection group uses the node currently chosen by the user, while an automatic latency-testing group selects based on its test results. When troubleshooting routing, distinguish between "the rule matched the wrong group" and "the group selected an unsuitable node."

Subscription Rule Overrides and Persistent Changes

Subscription configurations are usually generated by the service server. Editing the expanded subscription YAML in the client may work temporarily, but those changes can be replaced the next time the subscription updates. For custom rules that must persist, use the client's override, configuration merge, script extension, or local configuration features.

Clients use different names for merge features, but they generally fall into three categories:

• Prepend rules: Insert rules at the beginning of the subscription list, ideal for high-priority exceptions.
• Append rules: Add rules to the end of the list, but if the subscription already contains MATCH, the appended rules may never match.
• Full replacement: Replace all subscription rules with a custom list. You must retain any necessary LAN, DNS, direct-connection, and fallback logic yourself.

Therefore, "adding a rule" does not necessarily mean "raising its priority." To override an existing subscription result, the new rule must appear before the relevant broad rules and final fallback. In a graphical client, inspect the merged or active configuration rather than relying only on the order shown in the override editor.

RULE-SET and rule-providers

When there are many rules, use rule-providers to load rule sets, then reference them with RULE-SET in the main rule list. The provider loads the rule content, but the position of RULE-SET in the main list still determines its priority:

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

rules:
  - DOMAIN,exception.example.com,DIRECT
  - RULE-SET,private-services,Proxy
  - MATCH,Final

behavior must match the contents of the rule set. Common behaviors include domain, ipcidr, and classical. Domain behavior suits domain collections, IP behavior suits network ranges, and classical behavior can contain complete typed rule entries. The exact file format also depends on format and the core version; do not treat a complete main-configuration rules section as a rule-provider file of any arbitrary format.

When a remote rule set fails to load, verify that the URL is accessible, the file format is valid, the save path is writable, and the client logs show no errors. If critical routing depends on a remote rule set, keep a sensible final fallback so connections still have a clear destination when the set is temporarily unavailable.

Troubleshooting Rules That Do Not Take Effect

Approach rule problems by working backward from the runtime result instead of changing large amounts of configuration at once. The sequence below helps distinguish syntax, ordering, resolution, and client-capability issues.

1. Confirm that the active configuration is enabled. The client may store multiple configuration files. After editing, save, reload, or switch configurations, then verify that the active version is the one you just changed.
2. Inspect connection details. Record the destination domain, destination IP, network type, process name, matched rule, and final policy group. The connection list reflects the core's actual decision and is more reliable than guessing from the webpage domain.
3. Check broader rules earlier in the list. Search specifically for DOMAIN-KEYWORD, DOMAIN-SUFFIX, GEOSITE, GEOIP, RULE-SET, and MATCH.
4. Check the policy name. The target at the end of the rule must exist. After a group is renamed, an old rule may still point to a name that has been removed.
5. Confirm what DNS reveals. An app may connect directly to an IP, use cached results or encrypted DNS, or perform its own resolution. Without domain information, domain rules may not participate in matching.
6. Confirm core support. Process, logical, GEOSITE, and some port rules depend on core and platform capabilities. Check startup logs for unknown rules or configuration parsing messages.
7. Clear old connections and retry. Existing long-lived connections are not usually rematched immediately after a rule change. Close the app's connections, clear the client's connection records, or restart the app before testing again.

Why an Exact Domain Still Does Not Match

Common causes include a request going to another subdomain, connection details showing only an IP, the exact rule appearing after a broad rule, or the change being overwritten by a subscription update. Modern websites often separate login, API, static assets, and video across different domains. Start by filtering the connection list by process, then check each destination host.

Why the Rule Matches but the Result Does Not Change

A correct match only means that the connection entered the specified policy. Also check the policy group's current selection, node connectivity, DNS responses, app cache, and any separate IPv6 connection. If the group uses automatic selection, its node may change after testing; if a domain returns both IPv4 and IPv6 addresses, the two connections may match different rule types.

Minimal Test Configuration

When a complex configuration makes the source of a conflict unclear, temporarily add a sufficiently specific rule at the very top and point it to an easy-to-identify policy group. Once the test succeeds, restore the rule order step by step. Do not change DNS, TUN, proxy groups, and large numbers of rules at the same time, or it will be difficult to identify the real cause of any change.

If the client needs TUN mode to intercept apps that do not follow the system proxy, first confirm that TUN has started correctly and that routing and DNS hijacking settings meet the requirements of the current platform. TUN sends traffic into the core; rules decide how traffic is handled after it enters the core. These are separate stages. Connections not intercepted by TUN will naturally not appear in the rule-matching records.