The biggest pain point of writing Clash rules by hand is maintenance: as the rule list grows, the config file becomes bloated, and updating domain lists for a service means manual YAML edits every time. Rule Provider is Clash's modular rule management system — rule lists live in external files, Clash fetches and updates them automatically, and your config file simply references them without inlining every entry. This article covers the full usage and best practices.

Rule Provider Structure

A Rule Provider consists of two parts: a rule set file (domain/IP list) and a declaration in your config file. Rule set files support two formats:

  • YAML format: each rule is on its own line, like DOMAIN,example.com or IP-CIDR,8.8.8.8/32, with explicit type prefixes. Good for complex mixed rule sets.
  • text format: each line is just a domain or IP (no type prefix). Clash infers the type from the behavior field. Simpler and more compact, ideal for pure domain or pure IP lists.
YAML Format Rule Set (proxy-list.yaml)
payload:
  - DOMAIN,google.com
  - DOMAIN-SUFFIX,youtube.com
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-KEYWORD,openai
  - IP-CIDR,8.8.8.8/32,no-resolve
text Format Rule Set (direct-domains.txt)
example-internal.com
corp.local
192.168.1.0/24
10.0.0.0/8

Declaring Rule Providers in Your Config

Use the rule-providers field to declare rule set sources. Both http (remote URL) and file (local path) types are supported.

rule-providers Declaration Example
rule-providers:

  proxy-list:
    type: http
    behavior: classical   # Rule format: classical / domain / ipcidr
    url: https://raw.githubusercontent.com/yourrepo/rules/proxy.yaml
    path: ./ruleset/proxy-list.yaml
    interval: 86400          # Auto-update interval in seconds (24 hours)

  direct-list:
    type: http
    behavior: domain
    url: https://raw.githubusercontent.com/yourrepo/rules/direct.txt
    path: ./ruleset/direct-list.txt
    interval: 86400

  private-ip:
    type: http
    behavior: ipcidr
    url: https://raw.githubusercontent.com/yourrepo/rules/private-ip.txt
    path: ./ruleset/private-ip.txt
    interval: 604800         # IP lists change less often (7 days)

The behavior Field Explained

behavior tells Clash how to parse and index the rule set, directly affecting matching performance:

  • classical: each entry has a full type prefix (e.g., DOMAIN-SUFFIX,google.com). Can mix different rule types. Flexible, but slightly slower matching.
  • domain: each line is just a domain name. Clash builds a domain trie (prefix tree) supporting wildcard matching (e.g., +.google.com matches all subdomains). Best performance for pure domain lists.
  • ipcidr: each line is a CIDR IP range. Clash builds a radix tree index for extremely fast lookups. Ideal for large IP-based routing decisions.
Split your rule sets by type: use domain behavior for domain rules and ipcidr behavior for IP rules. Avoid using classical for everything. The specialized behaviors use data structures optimized for their types, which can be several times faster at lookup.

Referencing Rule Providers in rules

Once rule-providers are declared, reference them in your rules section using the RULE-SET keyword:

rules Reference Example
rules:
  - RULE-SET,direct-list,DIRECT      # Direct-connect domains → DIRECT
  - RULE-SET,proxy-list,Proxy         # Proxied domains → proxy group
  - RULE-SET,private-ip,DIRECT        # Private/LAN IPs → DIRECT
  - GEOIP,US,DIRECT                   # Local country IPs → DIRECT (adjust to your country)
  - MATCH,Proxy                        # Catch-all → proxy

Rule Priority and Ordering

Clash evaluates rules top to bottom and stops at the first match. Rule ordering is critical. A recommended order:

  1. LAN / local domains first (DOMAIN-SUFFIX,.local, IP-CIDR,192.168.0.0/16) — prevents internal traffic from being accidentally proxied.
  2. Known direct-connect domains (internal services, local resources).
  3. Known proxy domains (external services you want to route through the proxy).
  4. GEOIP,<YOUR_COUNTRY>,DIRECT as a catch-all for local IPs.
  5. MATCH as the final catch-all — typically routes unmatched traffic to the proxy.
Avoid using MATCH,DIRECT as your final rule — this sends all unrecognized traffic directly, meaning external services you haven't explicitly listed will bypass the proxy entirely.

Local file Type: Offline Rule Sets

When you need offline access or custom rules, use type: file pointing to a local file. Paths are relative to Clash's home directory (typically ~/.config/clash/ or ~/.local/share/mihomo/).

Local Rule Set Configuration
rule-providers:
  my-custom-rules:
    type: file
    behavior: domain
    path: ./ruleset/my-custom.txt