How to Write Custom Clash Rules: DOMAIN Syntax and Match Priority Explained

Understand the Structure of a Clash Rule First

Clash routes traffic based on connection characteristics. Most rules consist of a rule type, a match value, and a policy, with fields separated by English commas. For example, this domain rule sends requests to api.example.com through the DIRECT policy:

DOMAIN,api.example.com,DIRECT

DOMAIN is the rule type, api.example.com is the match value, and DIRECT is the target policy. The target can be a built-in action or the name of an existing proxy or policy group. Common built-in actions include DIRECT and REJECT. If the configuration contains a policy group named “Manual Selection,” you can write “Manual Selection” at the end of the rule. The name must match exactly: spaces, capitalization, and symbols are all part of it.

Where the Full Rule List Goes

Traditional Clash YAML places inline rules under the top-level rules field. Each item starts with a hyphen, and the order is the actual matching order:

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Manual Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Manual Selection

In graphical clients that support configuration editing, open the YAML through “Config” → select the active configuration → “Edit.” Button labels vary and may appear as “Edit File,” “View Configuration,” or “Advanced Configuration.” After saving, reload the configuration as well; changing only the file on disk without triggering a reload leaves the running kernel on the old rules.

DOMAIN vs. DOMAIN-SUFFIX vs. DOMAIN-KEYWORD

Domain rules are usually the best first choice for website routing because they use the requested hostname directly, without resolving it to an IP first. The three common DOMAIN-family rules cover different scopes, so similar names do not make them interchangeable.

DOMAIN: Match One Exact Hostname

Use DOMAIN when you want to target one specific hostname. For example, you can send a software update endpoint directly while leaving other services on the same parent domain unchanged:

DOMAIN,updates.example.com,DIRECT
DOMAIN,telemetry.example.com,REJECT
DOMAIN-SUFFIX,example.com,Manual Selection

Requests to updates.example.com match the first rule and stop; requests to telemetry.example.com match the second; only requests to store.example.com continue to the third suffix rule. Put precise rules before broad rules to preserve exceptions.

DOMAIN-SUFFIX: Cover the Parent Domain and Every Subdomain

DOMAIN-SUFFIX,example.com,Manual Selection covers example.com, www.example.com, and cdn.assets.example.com. It does not incorrectly match fakeexample.com as a plain text ending; matching follows domain-label boundaries.

A website often uses separate subdomains for login, APIs, images, and static assets. Once you know those subdomains should use the same policy, one suffix rule is easier to maintain than a list of full hostnames. If a subdomain needs an exception, place its DOMAIN rule above the suffix rule.

DOMAIN-KEYWORD: Broad Coverage Requires Careful Review

DOMAIN-KEYWORD checks whether a domain contains a specified string. It suits services whose hostnames change but retain a stable brand fragment, though it may also catch unrelated domains with similar names. Shorter keywords produce broader matches. For example, the keyword cdn could match many unrelated content-delivery domains.

DOMAIN-KEYWORD,company-service,Manual Selection

When DOMAIN or DOMAIN-SUFFIX can express the intent, prefer the narrower rule type. Keyword rules generally belong after exact-domain and suffix rules, but before IP-based rules.

Rule Priority Has One Core Principle: Top to Bottom, First Match Wins

Clash does not collect every match and then choose the “most specific” one. The kernel checks rules from the first line and immediately applies the policy of the first matching rule; later rules are ignored. In practice, priority is simply the order of rules in the configuration file.

rules:
  - DOMAIN-SUFFIX,example.com,Manual Selection
  - DOMAIN,api.example.com,DIRECT
  - MATCH,Manual Selection

In this configuration, api.example.com matches the first DOMAIN-SUFFIX rule, so the second exact rule can never take effect. Put the exception before the broad rule instead:

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Manual Selection
  - MATCH,Manual Selection

A Maintainable Ordering Strategy

1. The most specific reject, direct, or designated-node exceptions, such as a single DOMAIN rule.
2. DOMAIN-SUFFIX, DOMAIN-KEYWORD, or GEOSITE rules covering a group of services.
3. IP-CIDR and IP-CIDR6 rules for LANs, reserved addresses, and known networks.
4. GEOIP rules grouped by country or region.
5. Put the fallback MATCH rule last.

This is a practical ordering guideline to reduce rules being shadowed, not a syntax requirement. Rules that must take precedence should still appear earlier. For example, a network range that must be blocked should not come after a broad direct rule that might match first.

The Practical Role of IP-CIDR, GEOIP, and no-resolve

IP-CIDR matches destination IPv4 addresses or networks, while IP-CIDR6 handles IPv6. The number after the CIDR indicates the network prefix length: 192.168.1.0/24 covers 192.168.1.0 through 192.168.1.255, while 10.0.0.0/8 covers the entire private 10.0.0.0 address range.

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,Manual Selection

GEOIP matches according to the destination IP's country or region in the geographic database. For example, GEOIP,CN,DIRECT sends connections whose database result is mainland China directly. Accuracy depends on the GeoIP data loaded by the kernel; cloud services, Anycast, and address changes can make an individual result differ from the server's physical location.

Why IP Rules May Trigger DNS Resolution

When an application opens a connection, the kernel may receive a hostname or an IP address. To evaluate IP-CIDR or GEOIP, a hostname-only connection may need to be resolved to obtain its destination IP, which can then be checked against a network or region. That is the link between IP rules and DNS queries.

Add no-resolve to the end of an IP-based rule that supports it to prevent an extra DNS lookup solely for evaluating that rule. If the connection already provides a destination IP, the rule can still match normally. If only a hostname is available and no destination IP can be used, the kernel skips the check that requires resolution and continues with later rules.

IP-CIDR,203.0.113.0/24,Manual Selection,no-resolve

no-resolve is not a general performance switch, and it should not be appended to DOMAIN, DOMAIN-SUFFIX, or MATCH. It is mainly for IP-based rules. Whether to use it depends on the goal: LAN ranges can usually include it because the destination is already a private IP; if matching requires the address returned by DNS, do not use it to prevent that lookup.

Keep Domain Rules Ahead of IP Rules in Fake-IP Mode

With Fake-IP DNS mode, the client may receive a mapped address first, while the kernel retains the hostname-to-address relationship and can still route by domain rules. Put explicit domain rules before IP geolocation rules to prevent CDN address changes from sending the same service through different policies. IP-based matching matters more only when usable hostname information is unavailable or no domain rule matches.

Common mihomo Extensions: GEOSITE, Ports, and Processes

The current Clash Meta kernel, mihomo, supports more rule types than early Clash versions. When a configuration must work across kernels, first confirm which kernel the client actually starts. Unsupported rule types may cause the configuration to fail during loading.

GEOSITE matches domain collections in a database; it does not determine the country from the server's IP. GEOIP uses an IP database instead. Their names are similar, but they operate on completely different inputs. Before using GEOSITE, make sure the client is configured to load the required GeoSite data.

Process rules depend on the operating system and the kernel's ability to obtain process information. Support for process identification also varies by platform in TUN mode. For configurations shared across Windows, macOS, and Linux, domain and IP rules are generally more reliable; process rules are better used as device-specific additions rather than the sole decision criterion.

Where to Insert Custom Rules

Whether a custom rule works usually depends less on whether it is “written correctly” than on whether it appears before a rule that matches first. To find the insertion point, locate GEOIP, broad RULE-SET entries, and MATCH near the end, then determine which layer of behavior the new rule should override.

Scenario 1: Bypass the Proxy for One Domain

If the existing configuration routes the entire parent domain with DOMAIN-SUFFIX,example.com,Manual Selection, put the new direct exception above it:

rules:
  - DOMAIN,office.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Manual Selection
  - GEOIP,CN,DIRECT
  - MATCH,Manual Selection

Scenario 2: Always Route One Network Through the Proxy

If the range could be caught first by GEOIP,CN,DIRECT, insert the network rule before GEOIP:

rules:
  - IP-CIDR,198.51.100.0/24,Manual Selection,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Manual Selection

Scenario 3: Keep Rules Across Subscription Updates

Directly editing subscription-generated YAML often lasts only until the next update. When the subscription refreshes, the client typically replaces the local copy with the remote content. A more reliable approach is to use the client's configuration override, merge configuration, or extension script to insert custom rules before the subscription rules. The exact entry point depends on the client; common paths include “Settings” → “Configuration Management” → “Override,” or “Advanced Configuration” from the current subscription's menu.

For collections of dozens of rules or more, use rule-providers. The rule set can be updated separately, while the main configuration references it through RULE-SET:

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

rules:
  - RULE-SET,private-sites,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Manual Selection

behavior: domain means the rule-set payload contains domain entries. If it includes complete rules such as DOMAIN and IP-CIDR, use the classical behavior intended for full rules. The provider type, file format, and actual contents must correspond; do not place complete Clash rules in a collection that accepts only domain payloads.

How to Confirm That a Rule Really Matched

Rule verification should not rely only on whether a webpage opens. A successful page load may come from a direct connection, proxy, cache, or another network path. Check the configuration status, connection logs, and the rule that actually matched.

1. Save the configuration and reload it, then confirm that the interface shows no YAML parsing or unsupported rule-type errors.
2. Close existing connections from the target application; if necessary, fully quit and reopen it.
3. In the client's “Connections” page, filter the target requests by domain.
4. Check the connection's displayed rule type, rule content, and final policy group.
5. Test the parent domain, a subdomain, and a similar domain that should not match to confirm the scope is as expected.

For example, when testing DOMAIN-SUFFIX,example.com,DIRECT, check example.com, api.example.com, and example.com.test in turn. The first two should match; the third should not. When testing an exact rule, also try v2.api.example.com; DOMAIN,api.example.com,DIRECT should not treat it as the same hostname.

Troubleshoot in This Order When a Rule Does Not Take Effect

• First, check whether an earlier rule caught it: Find the rule that actually matched in the connection details instead of repeatedly moving the custom entry at the end.
• Next, check the policy name: The value at the end of the rule must exactly match the policy-group name.
• Check the active configuration: The file you edited may not be the configuration currently used by the client.
• Check existing connections: Rule changes usually do not reroute already-established TCP connections.
• Check DNS and the destination type: The application may connect directly to an IP, use a different subdomain, or use a QUIC UDP connection.
• Check kernel compatibility: GEOSITE, logical combinations, and some process rules require mihomo support.

A Rule Example You Can Use to Check Ordering

The structure below demonstrates the order of “single-domain exceptions, domain sets, private networks, regional rules, and the final fallback.” Policy-group names must match those in your configuration:

rules:
  - DOMAIN,login.example.com,DIRECT
  - DOMAIN,ads.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,Manual Selection
  - GEOSITE,category-ads-all,REJECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,::1/128,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Manual Selection

In this example, the login hostname is sent direct first, the advertising subdomain is rejected first, and the remaining example.com services use “Manual Selection.” Generic advertising categories, private addresses, and regional IP rules are checked afterward. Finally, all unmatched connections go to MATCH. When adding a rule, answer “Which existing rule should it override?” and the insertion point is usually clear.

Effective rule maintenance is about controlling scope, not accumulating entries. Prefer exact domains; use suffixes only after confirming that an entire subdomain group shares one policy; decide explicitly whether IP rules may resolve DNS; and keep broad categories and fallbacks later. After editing, verify the matched rule in the connection details—this is usually faster for troubleshooting than simply watching the webpage result.