1. Why rule-providers instead of giant inline rules
Inline rules: arrays are fine for a few dozen lines, but real-world split routing often depends on community lists that add or retire domains daily. Pasting those thousands of lines into your main profile makes diffs noisy, upgrades fragile, and collaboration awkward. Rule-providers move ownership of the list to an HTTPS URL while your YAML keeps only a short name, a cache path, and policy wiring. The Clash Meta family (often shipped under the Mihomo name in downstream clients) treats those providers as first-class objects you can refresh on a timer or on demand, similar in spirit to proxy-providers but aimed at rule payloads.
From an operations mindset, remote lists behave like package dependencies: you pin the URL, let the core fetch artifacts into a known directory, and version-control the small wrapper file that describes how the list connects to your policy groups. When a maintainer fixes a false positive, your next auto-update picks it up without you hand-merging text. That separation also clarifies incidents—if routing regresses, you inspect whether the cache file changed, whether the upstream returned an HTML error page, or whether your local edits reordered matchers.
rule-providers block and every RULE-SET line. Renaming without updating both sides produces an empty reference or a silent skip depending on client validation.
2. Baseline: Meta core and profile layout
Not every Clash fork exposes identical keys. Rule-providers and RULE-SET are Meta-era features; if your build predates them, the parser may ignore unknown sections or reject your file outright. Confirm the about panel or startup log names a Meta-compatible core before copying snippets from anonymous gists. Desktop GUIs such as Clash Verge and mobile ports of Clash Meta typically bundle the right engine, but alpha APKs and repackaged installers sometimes lag behind.
Your profile remains a single effective document after merging overrides. If a subscription generator injects its own rule-providers block, blending two files without understanding merge semantics can duplicate keys or lose your manual additions. When debugging, export the running configuration from the client rather than assuming the on-disk file matches memory. For adjacent topics—empty nodes from bad subscriptions versus rule issues—our subscription troubleshooting guide covers provider URLs separately from rule lists.
For broader documentation on top-level keys, start from the site configuration guide; this article focuses narrowly on wiring remote rule artifacts.
3. Declare rule-providers in YAML
Add a top-level rule-providers: map parallel to proxies, proxy-groups, and rules. Each child key is the provider name you will reference later. A typical HTTP list entry includes type: http, a url that returns raw rule text or structured data the core understands, path for the cached copy, optional interval (seconds) for automatic updates, plus metadata fields such as behavior and format that tell the parser how to interpret bytes.
The example below is illustrative—replace the URL with a list you trust, align behavior with that list’s semantics, and choose a path that fits your client’s working directory conventions:
rule-providers:
reject-trackers:
type: http
behavior: classical
format: text
url: "https://example.com/lists/trackers.txt"
path: ./ruleset/reject-trackers.txt
interval: 86400
streaming-suffix:
type: http
behavior: domain
format: yaml
url: "https://example.com/rule-sets/streaming.yaml"
path: ./ruleset/streaming.yaml
interval: 43200Some environments also support type: file for purely local lists; that pattern skips network fetch while preserving the same RULE-SET indirection, which helps when corporate policy forbids pulling third-party URLs on servers but still allows checked-in artifacts.
Headers, proxy, and fetch path
When the remote host demands a specific User-Agent or auth header, Meta-class cores usually let you attach header: maps under the provider. If the list must be retrieved through an upstream proxy rather than direct egress, consult your client documentation for the exact key—implementations differ between desktop and embedded builds. Misconfigured fetch transports mimic “stuck” lists: the cache remains old while you assume interval elapsed.
4. Path, cache files, and interval strategy
The path field anchors predictable storage. Relative paths resolve against the core’s working directory, which desktop GUIs sometimes relocate per profile. If two providers accidentally share a path, last-writer wins and you will see bizarre rule interactions that resist log correlation. Establish a namespace such as ./ruleset/<name>.<ext> and keep it unique.
First boot typically triggers an immediate download so RULE-SET references are usable; afterward interval governs background refresh. Shorter intervals are not automatically “more secure”—they amplify traffic, wear flash storage on routers, and can anger maintainers who rate-limit aggressive clients. Daily or longer cadences suit many static deny/allow lists; faster refresh might be justified for threat feeds or rapidly shifting CDN maps, provided you understand provider expectations.
In many Mihomo configurations, an interval of 0 (or omission interpreted similarly) disables periodic fetch except for manual refresh or core restart behaviors—check the exact semantics for your build in release notes. When debugging, delete the cache file deliberately and reload to force a clean download; this clears truncated files left after a dropped connection.
Automation-minded users mirror lists through internal object storage and point url at an internal HTTPS mirror. That adds availability but also operational responsibility: your mirror must honor conditional requests if you care about bandwidth, and you should monitor staleness when upstream publishes critical revocations.
5. Reference lists with RULE-SET
Declaring a provider loads metadata; traffic still follows the explicit rules: array. Insert lines using the RULE-SET keyword, the provider name, and the policy target—often a proxy group tag or DIRECT. Variants exist for IP rules with ,no-resolve where applicable. The core expands the remote set into matchers with behavior implied by the provider definition.
rules:
- RULE-SET,reject-trackers,REJECT
- RULE-SET,streaming-suffix,PROXY-MEDIA
- DOMAIN-SUFFIX,office.local,DIRECT
# … GEOIP, MATCH, etc.Pair this with meaningful proxy groups: a list that only names streaming domains should land on a group tuned for throughput, not on a latency-sensitive banking path. If you operate multiple regions, duplicate RULE-SET lines with different policies only when the underlying list explicitly matches consistent semantics—otherwise maintain separate providers per policy to avoid accidental coupling.
Manual refresh buttons in GUIs typically re-fetch proxy-providers and rule-providers together or per section depending on implementation. Learn your client’s UI path so you are not waiting passively for interval ticks during an outage.
6. Ordering vs GEOIP, IP-CIDR, and FINAL
Clash evaluates rules top-down; first match ends the search. Remote lists belong above coarse matchers such as continent-wide GEOIP shortcuts and absolutely before MATCH / FINAL catch-alls. Beginners frequently append RULE-SET at the file tail, then wonder why GEOIP,CN,DIRECT already sent the flow domestically. Move sensitive splits upward and keep documentation in Git so the next editor preserves intent.
Interactions with DNS can mask ordering issues. Fake-ip modes resolve differently than redir-host; a domain-only list may never engage if your traffic arrives pre-resolved as an address that matches an earlier IP rule. When adopting complex DNS stacks, revisit our nameserver and fallback guide alongside GEOIP-focused write-ups like GeoIP direct routing so resolver policy, rule order, and tunnel mode stay aligned.
Large rulesets that include private IP literals deserve scrutiny near corporate split tunnels; a borrowed list might direct RFC1918 ranges through proxies unintentionally. Diff new drops before trusting automation.
7. behavior and format choices
The behavior and format pair tells the core whether rows should be treated as classical Clash rules, domain lists, IP-only buckets, or other supported encodings. Mismatch produces empty logical sets or parser warnings that only appear at fetch time. When upstream documents “yaml rule provider” versus “text domain list,” mirror their vocabulary—do not assume interoperability across behaviors.
Some ecosystems publish binary- or schema-packed artifacts for performance; ensure your core version implements those parsers before switching formats for marginal speed wins. When in doubt, stay on human-readable text until you profile a real bottleneck.
Finally, remember that rule-providers carry policy only indirectly. They never replace proxies definitions; they merely decide which existing outbound group applies. If your target tag points to a missing group, validation fails fast—another reason to keep naming consistent across merges.
8. Troubleshooting quick map
Use the matrix below as a first-pass triage before diving into packet captures:
| Symptom | Likely cause | What to check |
|---|---|---|
| Provider never downloads | TLS interception, wrong URL, or blocked path | curl the URL; verify write permissions for path |
| File updates but rules feel stale | Order overshadowed by earlier matchers | Move RULE-SET above GEOIP / broad IP rules |
| Parser error after fetch | format/behavior mismatch |
Read first lines of cached file; align metadata |
| Only some clients break | Merge layers differ per platform | Compare effective config exports device by device |
| Spiky bandwidth usage | interval too aggressive on huge lists |
Raise interval; enable ETag-friendly hosting if possible |
Logging verbosity varies; enable rule-tracing or connection logging temporarily when you need to prove which matcher fired. Rotate logs off afterward on storage-constrained routers.
9. Frequently asked questions
What should I put in path for a rule-provider?
Use a dedicated relative path under the core working directory—commonly a ruleset subdirectory—with a filename extension that hints at encoding (.yaml, .txt, .mrs if applicable). Avoid collisions between providers.
Does interval zero disable auto-updates?
On typical Mihomo builds, non-positive intervals mean you are not scheduling periodic downloads; you refresh manually or rely on other triggers. Confirm against your exact release string because behavior evolved across minors.
Why does my RULE-SET seem ignored?
Validate ordering, provider health, DNS path, and that the cached artifact actually contains rule rows. Empty files and HTML error pages are the usual culprits after CDN outages.
Can I stack multiple lists for the same policy?
Yes—declare multiple providers and add multiple RULE-SET lines, or combine logically upstream. Keep readability: dozens of one-line providers can become harder to audit than a curated handful.
10. Summary
Clash Meta and Mihomo make remote maintenance of large matcher sets practical: define each artifact under rule-providers with a trustworthy url, stable path, explicit behavior/format, and a refresh interval aligned with operational reality, then wire traffic with RULE-SET lines high enough in rules: to beat blunt GEOIP or MATCH entries. Verify downloads by inspecting cache files after changes, and treat parser errors as signals to reconcile list type metadata—not excuses to disable validation.
Compared with opaque one-size-fits-all VPN apps that hide how traffic is classified, a YAML-driven core with rule-providers gives you inspectable artifacts, reproducible ordering, and the ability to roll forward or back when a list maintainer ships a regression. The trade-off is ownership: you must understand merge order, DNS coupling, and fetch hygiene—but that visibility is what makes enterprise-style split routing supportable without myths about “magic servers.” Clash clients on maintained release channels pair that transparency with polished UIs for manual refreshes and profile editing, so you are not hand-editing files on every phone just to retry a failed download.
When you are ready to standardize on that workflow, use our official download page for builds that track Meta-class features, then layer provider-driven lists on top of a baseline policy you can explain to teammates.