How to Write Custom Clash Rules: Rule Types, Matching Order, and Mobile Overrides

Check the rule mode, target policy, and core first

Custom Clash rules determine which outbound connection a request uses; they do not create proxy nodes. A matched rule can send traffic to the built-in DIRECT or REJECT, or to a node or policy group already defined in the configuration. The policy group then selects the actual outbound, so matching a proxy group does not always mean the connection will use a proxy node: that group may be set to direct connection.

Before making changes, check these three things. They determine whether a rule can be loaded, whether it is considered during matching, and where traffic goes when it matches.

1. Mode: Switch to Rule mode, often labeled “Rule” or Rule in the app. Global and Direct modes do not route traffic through the standard rule list below.
2. Policy name: Check the target group name under proxy-groups in your configuration. Match its capitalization, spaces, and Chinese characters exactly. A misspelled name will usually prevent the configuration from loading.
3. Core: Check whether the client is running original Clash, Clash Meta, or mihomo. The Meta branch was later renamed mihomo; do not assume newer rules or rule-set formats also work with older cores.

Common rule types and basic syntax

Most rules use the format “rule type, match value, target policy,” with fields separated by commas. MATCH has no match value, so it takes the target policy directly. In YAML, each rule is a list item indented with spaces; do not use tabs for indentation.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Outbound selection
  - DOMAIN-KEYWORD,example,Outbound selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Outbound selection

This snippet illustrates the syntax; it is not a complete, standalone subscription. When adding it to an existing configuration, keep only one top-level rules field and make sure each rule fits your needs.

Domain rules do not take full URLs

To match https://www.example.com/account, use the domain www.example.com. Do not include https://, a path, or query parameters in DOMAIN. Standard domain rules do not filter URL paths or distinguish pages on the same HTTPS domain.

DOMAIN-SUFFIX,example.com,DIRECT matches the root domain and its subdomains, but not notexample.com. If you only need to handle one login endpoint, use an exact domain rule rather than applying a broad direct or reject rule to the entire domain suffix.

IP rules and the no-resolve option

When a connection has a domain but no destination IP available for matching, IP rules may trigger a DNS lookup. The trailing no-resolve means not to resolve the domain solely for this rule; matching can still proceed if a destination IP is already available. It does not disable DNS globally or guarantee that the rule will always match.

As a result, GEOIP,CN,DIRECT,no-resolve may behave differently from the same rule without that option for a domain-based connection. If a domain in mainland China does not match an IP rule, check the domain and destination IP in the logs, along with DNS behavior, before repeatedly switching nodes.

Matching order: the first match wins, so put specific rules first

For the standard rules covered here, Clash evaluates the list from top to bottom and applies the policy for the first match. It does not continue searching for a “more specific” rule. Rule types have no built-in priority: a later DOMAIN rule will not automatically take precedence over an earlier DOMAIN-SUFFIX rule.

rules:
  - DOMAIN,login.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Outbound selection
  - MATCH,Outbound selection

• login.example.com matches rule 1 and goes direct.
• www.example.com skips rule 1 and matches rule 2.
• example.net matches neither of the first two rules, so rule 3 catches it.

If you swap the first two rules, the login domain matches the suffix rule first, so the later exact direct rule never takes effect. When troubleshooting custom Clash rules that seem ineffective, look for a broader rule above yours instead of focusing only on the new entry.

Why MATCH belongs at the end

MATCH catches every connection that has not matched an earlier rule. Standard rules after it never get a chance to run. A practical order is “specific exceptions → service or app rule sets → general geographic rules → MATCH,” adjusted to your needs. This is a maintainable way to organize rules, not a sequence required by the core.

RULE-SET: check both the provider and where it is referenced

RULE-SET stores a set of match conditions in a separate file and references it from the main rule list. It does not bypass rule order: the set is evaluated where its reference appears. The provider name, behavior type, file format, and file contents must all match.

Here is an example using a local file with mihomo. Place ./rules/local-direct.yaml in a configuration directory the core can access, then add the provider definition. Whether a mobile client can write to that directory depends on the client; do not assume the core can read a file left in the system Downloads folder.

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

rules:
  - RULE-SET,local-direct,DIRECT
  - MATCH,Outbound selection

The rule file should contain the following. The classical entries retain their rule types but do not specify a target policy; the main configuration sets the target for all of them with RULE-SET,local-direct,DIRECT.

payload:
  - DOMAIN,example.com
  - DOMAIN-SUFFIX,example.org
  - IP-CIDR,192.168.0.0/16,no-resolve

• behavior: domain: For domain collections. Entries must follow the syntax for the corresponding domain collection; do not paste the classical entries above as-is.
• behavior: ipcidr: For a collection of IP ranges, not for mixing in domain rules.
• behavior: classical: For entries that include rule types, such as the mixed domain and IP conditions in this example.

Remote providers also need a download URL, cache path, and update interval. Subscription updates and rule-provider updates are separate: a successful subscription refresh does not mean every external rule file was refreshed. If you only need a couple of mobile-specific exceptions, standard rules are usually easier to troubleshoot than adding a provider.

Override subscriptions on mobile: keep the remote source and manage local rules separately

A remote subscription is a configuration source; a client override makes local changes when the configuration loads. Editing the generated subscription YAML directly can mean losing your changes on the next update. A safer approach is to keep the original subscription and save local rules through the client’s configuration override, rule management, or extension settings.

Android client: steps to check

1. Open the details for the configuration you are using and confirm which subscription is active. Do not change a backup configuration and then test a different one.
2. Find the client’s rule management or override settings and check whether it supports rules inserted at the top, list merging, or only full replacement. Menu names vary across Android clients.
3. Start with one exact rule, such as DOMAIN,example.com,DIRECT. Do not change DNS, TUN, and a dozen rules at the same time.
4. Save and reload the configuration. Check for unknown policies, YAML parsing errors, or failed rule-provider loads.
5. Refresh the original subscription once, then check that the local rule is still near the top of the final rule list. Saving it once does not guarantee it will survive future subscription updates.

If the client asks for “merge YAML,” first check how it handles arrays. rules is an array: some merge tools replace the entire array, while others prepend or append entries. Pasting a rules: section with a single rule may overwrite the subscription’s entire rule list. Override syntax is client-specific; there is no universal field for prepending rules on every mobile client.

On iOS, check the configuration format before migrating rules

Proxy clients on iOS differ in their configuration syntax, modules, and local rule mechanisms. Subscription support alone does not mean a client can run Clash YAML directly. First confirm which formats the client explicitly supports. If it uses a different rule syntax, add the equivalent conditions through its native rule settings instead of pasting in a full rules: section.

System VPN permission lets a client route traffic; it does not convert Clash rules to another configuration format. If you need to choose an installation method, start with the mobile client comparison guide, then check the selected client’s configuration and override support.

Troubleshooting rules that do not work: check connection logs, not just the page

Whether a page loads depends on DNS, node availability, server status, and existing connections. To verify a rule, check the client’s connection or log screen for the destination domain, matched rule, policy group, and final outbound. A page getting faster or slower does not prove that a particular rule matched.

TUN / VPN routing and rule matching are separate steps

Enabling TUN or the system VPN only makes traffic routing possible; it does not guarantee that every app’s traffic enters the core. Android per-app settings, bypass lists, and client routing options can let specific apps bypass it. A connection that never reaches the core cannot match a rule in the configuration.

Another common issue is that the core sees an IP address but not the domain. An app’s built-in encrypted DNS, direct connections to fixed IP addresses, and differences in DNS interception settings can all affect domain visibility. mihomo domain sniffing may help identify domains for supported protocols, but it cannot identify every encrypted connection. Understand your current DNS setup before enabling related features. See the DNS technical reference for more details.

Change one thing at a time, then start a new connection

After a rule change, existing connections may keep using the outbound selected when they were established. Save and reload the configuration, then close the app’s existing connections or reopen the app before checking new connection logs. Test in this order: add one exact rule → verify the match → refresh the subscription → verify again. If something goes wrong, restore the last working configuration instead of clearing the app’s data.