Clash Custom Rules Syntax Explained: Match Order, Priority, and Rule Overrides

Clash’s rule system answers one specific question: which policy group, proxy node, or direct connection should handle a new connection? Most “rule not working” problems are not caused by completely invalid syntax. Instead, the connection may have matched an earlier rule, the edit may have been made in a file that gets replaced when a subscription refreshes, or the test traffic may never have reached the kernel currently in use.

When reading rules, treat the domain, destination IP, process, port, and network protocol as separate matching conditions. The rule list is not automatically sorted by what “looks more specific,” and a longer rule does not receive higher priority. In practice, Clash usually evaluates the rules list from top to bottom. As soon as the first rule matches, its specified policy is applied and later rules no longer participate in deciding that connection.

Matching model: how a connection reaches a rule

After an application starts a request, the Clash or mihomo kernel needs to obtain the destination information. For browser proxy requests, the kernel can usually see the destination domain directly. With some transparent proxy or TUN traffic, it may receive the destination IP first, then reconstruct the domain using DNS mappings, sniffing results, and connection metadata. Because the available information differs, the same rule set can produce different matches under different traffic-interception methods.

Assume the rule list contains, in order, a direct-connection rule for a full domain, a proxy rule for that domain’s suffix, and a final fallback rule. When the full domain is accessed, the first rule has already matched, so the suffix rule is never evaluated. If the suffix rule is moved above it, the broader subdomain range captures the request first and the later full-domain exception no longer works. That is why narrow exceptions are normally placed before broad rules.

rules:
  - DOMAIN,updates.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Node Selection
  - MATCH,Catch-all

In this example, updates.example.com uses a direct connection, other domains ending in example.com go to “Node Selection,” and the remaining connections are handled by “Catch-all.” “Node Selection” and “Catch-all” must be actual policy group names in the configuration. Their Chinese text, spaces, and capitalization must match the definitions under proxy-groups exactly.

A rule match and node availability are separate stages

A rule match only determines where the connection is sent; it does not guarantee that the selected node in the policy group is usable. For example, logs may show that a connection matched “Node Selection,” while the page still fails to load. The problem could be the group’s current choice, node connectivity, DNS results, the TLS handshake, or the upstream network. Conversely, a successful node speed test does not prove that a custom domain rule matched. Speed tests often use different addresses from the actual request, so verify them separately.

Common rule syntax and when to use it

Classic rules usually use a comma-separated format: the first field is the rule type, the middle fields contain the match criteria, the next field specifies the destination policy, and the final field may contain additional parameters supported by that rule type. Supported rule types vary across kernels and client versions, especially for process, inbound, rule-set, and logical-combination features. Before editing, confirm whether the client uses the traditional Clash kernel or the Clash Meta (mihomo) kernel, then follow that kernel’s configuration documentation and runtime logs.

DOMAIN: exact domain matching

DOMAIN matches only the specified full hostname, making it suitable for a single exception. It does not automatically cover other subdomains. For example:

- DOMAIN,api.example.com,DIRECT

This rule matches api.example.com but not img.api.example.com. If a site uses separate subdomains for its main page, API, images, and downloads, list them individually or use a suffix rule to cover the entire domain range.

DOMAIN-SUFFIX: domain suffix matching

DOMAIN-SUFFIX matches a domain and its subdomains, making it suitable for site-wide routing:

- DOMAIN-SUFFIX,example.com,Node Selection

It covers example.com, www.example.com, and deeper subdomains. Because suffix rules have a broad scope, place a matching DOMAIN exception before them when one update domain should use a direct connection.

DOMAIN-KEYWORD: domain keyword matching

DOMAIN-KEYWORD checks whether a domain contains the specified text. It is concise, but the match range is often broader than expected. For example, the keyword music could match several unrelated domains. Unless the target domain changes frequently while retaining a reliable identifying pattern, prefer an exact domain or domain suffix.

- DOMAIN-KEYWORD,example,Node Selection

IP-CIDR and IP-CIDR6: destination address ranges

IP-CIDR matches IPv4 ranges, while IP-CIDR6 matches IPv6 ranges. They are useful for private networks, fixed service addresses, and clearly published network ranges:

- 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

no-resolve means the domain is not resolved just to obtain an IP while this IP rule is being evaluated. It is commonly used for private address ranges and other cases where only the existing destination IP matters. Whether to add it depends on the rule’s purpose: if domain connections should be resolved and then considered for an IP-range match, do not mechanically append no-resolve to every IP rule.

GEOIP, GEOSITE, and rule data

GEOIP matches according to the geographic database category assigned to the destination IP. Common mihomo configurations also use GEOSITE to classify domain collections. These rules depend on the geographic data files loaded by the client, so their results can change with the data version. They are useful for broad classification, but they do not guarantee that every domain or address will permanently have the same classification. For stable exceptions, add precise rules before the classification rules.

- GEOSITE,category-ads-all,REJECT
- GEOSITE,cn,DIRECT
- GEOIP,CN,DIRECT
- MATCH,Node Selection

Traditional Clash branches may not support the same GEOSITE syntax or data-loading method. If configuration validation reports an unknown rule type, first confirm the kernel’s capabilities instead of repeatedly adjusting indentation.

Port, network protocol, and process rules

DST-PORT routes traffic by destination port, while NETWORK distinguishes TCP from UDP. Process rules can match by program name or path, but they depend on operating-system permissions, kernel implementation, and whether the client supplies the relevant metadata. On mobile systems, in restricted sandboxes, and in some transparent proxy environments, the kernel may not be able to obtain process information reliably.

- DST-PORT,22,Work Line
- NETWORK,UDP,Low-Latency Line
- PROCESS-NAME,example.exe,DIRECT

Place port rules carefully. Common ports such as 443 carry many different services; putting a port rule before domain rules could capture nearly every HTTPS connection. Process rules should likewise not be used to enforce security boundaries based only on an application name, because an app may use another system process to make the connection.

Order and priority: why a more specific rule can still fail

The rule list has no automatically calculated “specificity priority.” DOMAIN does not inherently override an earlier DOMAIN-SUFFIX, and a smaller IP range does not automatically override an earlier larger range. As long as an earlier rule meets the conditions, the current connection stops there. Custom lists are therefore often organized as “explicit exceptions, specific categories, broad collections, geographic categories, and final fallback.”

1. Local and required direct-connection exceptions: LAN addresses, router administration domains, corporate intranet services, or update services that explicitly require a direct connection.
2. Exact domain and process exceptions: used to override later suffix rules, rule sets, or geographic classifications.
3. Site-level suffix rules: route a group of stable subdomains through the same policy.
4. Rule sets: maintain larger collections of domains, address ranges, or service categories.
5. Broad GEOIP, GEOSITE, and similar checks: handle connections not covered by earlier rules.
6. MATCH fallback: receives all remaining unmatched traffic and belongs at the end of the list.

MATCH matches the remaining connections, so ordinary rules placed after it will usually never take effect in practice. Some older configurations use FINAL for a similar fallback meaning, but accepted names vary between kernels. When migrating a configuration, do not simply replace the text; run configuration validation and check the kernel logs first.

A single domain may create multiple connections

Web browsing is not a single request. The main document, static assets, video, analytics endpoints, and third-party login services may use different domains, and HTTP/3 may also use UDP. Seeing the main domain match the expected policy does not mean every connection involved in the page follows the same route. When troubleshooting a site, inspect the actual failed hostname, destination port, network protocol, and matched rule in the connection list or logs instead of adding a rule only for the domain in the address bar.

DNS results affect how IP rules appear

Domain rules rely on the hostname known to the kernel, while IP rules rely on the destination address. If an application performs encrypted DNS resolution, connects directly to a cached IP, or TUN sniffing fails to recover the domain, the logs may show only an IP address. In that case, a domain rule may not have enough information to match. In fake-IP mode, by contrast, the kernel maintains a mapping between virtual addresses and domains, so the address shown in the connection view alone cannot identify the real upstream IP. Analyze the DNS mode, domain fields in the logs, and final rule name together.

Rule sets and RULE-SET: splitting large configurations

When there are many rules, kernels such as mihomo can define external rule collections with rule-providers and reference them from the main rule list using RULE-SET. This separates domain categories, address ranges, and the main configuration for easier maintenance. A rule set does not automatically receive higher priority; its position when referenced in the main rules list still determines when it participates in matching.

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

rules:
  - DOMAIN,intranet.example.com,DIRECT
  - RULE-SET,work-services,Work Line
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

behavior describes how the collection is organized. Common values include classical, domain, and ipcidr. A classical collection can contain typed rule entries, while domain and address-range collections must follow their respective formats. If a collection is declared as domain but contains full classical rule strings, the provider may download successfully but fail during parsing, or configuration validation may report an error immediately.

Remote collections also involve update intervals, cache paths, and network reachability. On the first launch, if a collection has not been downloaded and the current configuration depends on it, the client may report an initialization failure. Check the provider status, last update time, and parsing errors instead of only testing whether the collection URL opens in a browser. An accessible URL proves only that the file can be downloaded, not that its contents match the format required by the current kernel.

How to resolve overlapping rule sets

Two rule sets may contain the same domain or overlapping address ranges. The result is determined neither by the update time nor by the number of entries in each set, but by the order of the two RULE-SET references in the main rule list. To override a public collection, place local precise exceptions first, then reference your smaller collection, and reference the broader public collection last.

rules:
  - DOMAIN,build.example.com,DIRECT
  - RULE-SET,my-exceptions,Dedicated Line
  - RULE-SET,public-services,Node Selection
  - MATCH,Catch-all

This structure is easier to maintain than copying and modifying a large public collection directly: exceptions remain visible, and public updates do not require merging an entire file again.

Subscription updates, overrides, and configuration persistence

Many desktop and mobile clients download remote subscriptions as local configuration files. Editing the generated file directly may take effect immediately, but the changes are often replaced during the next automatic update, manual refresh, or subscription switch. The reliable approach is to use the client’s override, merge, extension-script, or local-configuration feature so custom rules are stored separately from the subscription file.

Clients handle “prepend rules,” “append rules,” and “merge rules” differently. Prepend rules are generally best for precise exceptions because they need to run before subscription rules. If append rules are added after the subscription’s MATCH, they will have no practical effect. After using an override interface, open the final generated configuration or runtime logs to confirm that the rules were inserted where expected.

Policy group names are dependencies too

If a custom rule references “Work Line,” the final configuration must contain a policy group with that exact name. If the subscription provider renames the group, the client transforms the configuration, or a merge script renames it, the rule may point to a nonexistent target and cause loading to fail. A safer approach is to inject custom policy groups through the same persistence mechanism and avoid relying on display names that change frequently.

Reload the runtime configuration after editing

Saving a YAML file does not necessarily make the running kernel adopt the new rules immediately. Some clients reload automatically; others require clicking Apply, selecting the configuration again, or restarting the kernel. To confirm a successful reload, check the configuration timestamp, kernel logs, and rule changes in the connection details. Existing long-lived connections may continue using the route established when they were created, so close the relevant app connections, refresh the page, or wait for old connections to end during testing.

A layered check for custom rules that do not work

Start troubleshooting by asking “What is actually running right now?” and then check the matching conditions step by step. Frequently changing DNS, switching TUN modes, changing nodes, and reinstalling the client introduces multiple variables at once, making the cause harder to identify. The sequence below works for most problems involving domain rules, IP rules, and rule sets.

1. Confirm that the correct configuration is in use.

   Check the subscription or configuration currently selected in the client and its last load time. If multiple configuration copies exist, make sure the file you edited is the one the kernel is currently reading.

2. Run configuration validation first.

   Review the client’s configuration validation result and kernel startup log. Pay particular attention to YAML indentation, comma-separated fields, unknown rule types, duplicate keys, rule-set parsing failures, and missing policy groups.

3. Confirm that traffic is entering Clash.

   When the system proxy is disabled, an app bypasses the proxy, an app-specific proxy setting overrides the system configuration, or TUN is not running, the connection will not pass through the rule engine. If the test traffic is completely absent from the connection list, check the interception method first.

4. Inspect the rule that actually matched.

   In the connection details or logs, find the destination domain, destination IP, process, port, network protocol, rule type, and policy name. If an earlier broad rule matched, adjust the order instead of repeatedly adding the same domain.

5. Check whether domain and IP conditions are visible.

   If the logs show only an IP address, the domain rule may not have enough information to match. If the domain has already matched, there is no need to keep suspecting later IP rules. Use the DNS mode, sniffing settings, and application behavior as additional context.

6. Check the policy group’s current selection.

   After the rule sends traffic to the correct policy group, confirm whether the group currently selects a specific node, an automatic testing group, a direct connection, or a reject action. A wrong policy-group selection and a wrong rule order can look identical at the surface.

7. Rule out existing connections and caches.

   Close existing connections in the test application and, if necessary, clear the app’s DNS cache before starting a new connection. Rules are mainly evaluated when a connection is established; an existing session is not automatically re-evaluated when the list changes.

8. Verify the result after refreshing the subscription.

   Manually update the subscription once and confirm that the custom rules are still present and in the same positions. If they disappear after the refresh, move them to an override or merge feature supported by the client.

Minimal tests are easier to diagnose than a full configuration

When dealing with thousands of rules, temporarily add a sufficiently precise test rule with an obvious policy result and place it near the top of the list. For example, assign a test domain to a dedicated policy group and observe the match record for a new connection. Remove the rule after testing so a diagnostic-only routing entry is not left in the long-term configuration.

rules:
  - DOMAIN,test.example.com,Diagnostic Line
  - RULE-SET,main-services,Node Selection
  - GEOIP,CN,DIRECT
  - MATCH,Catch-all

If the precise rule at the top still produces no match record, first check whether traffic is passing through the current kernel, whether the domain matches the actual request, and whether the configuration has reloaded successfully. If it matches but the original rule does not, compare rule position, type, and destination information instead of changing the underlying network settings first.

A maintainable rule list: from working to easy to review

Long-term configurations should not optimize only for the number of rules. Every broad rule should document what it covers, why it is in its current position, and whether it overlaps with an existing collection. For users with only a few exceptions, a set of precise domains plus a stable fallback is usually easier to understand than several large collections from similar sources.

• Place LAN, corporate intranet, and device-management addresses in a clearly defined direct-connection section.
• Place single-domain exceptions before the corresponding suffix, keyword, and rule-set rules.
• Do not use generic port rules as a substitute for domain classification, especially not early matches for common ports such as 80 and 443.
• Choose a behavior that matches the rule set’s contents, and regularly check its update and parsing status.
• Ensure that MATCH is at the end and that its target policy group actually exists.
• Save personalized rules through the client’s override feature instead of relying directly on subscription-generated files.
• Reload the configuration after editing and use a new connection to verify the actual match in the logs.
• When migrating to mihomo or switching clients, reconfirm support for the rule types and extended syntax you use.

A clear rule configuration should explain each stage from top to bottom: which exceptions are handled first, which categories come next, and what catches the remaining traffic. As long as you check these four points—first match, information visibility, final configuration, and policy-group status—most rule-override problems leave direct clues in the logs.

If you are still learning how subscription imports relate to the system proxy, TUN, and DNS, continue with the site’s user guide and configuration tutorial. Rules make routing decisions, but full connectivity also depends on the client’s interception method, DNS settings, and policy nodes working together.