Configuration November 9, 2026

Clash Rule Providers: Build and Manage Custom Rules on GitHub

Turn scattered Clash routing entries into reusable rule sets. Explore rule-providers YAML, matching order, GitHub hosting, version control, update practices, and practical checks for rules that fail to load or match traffic.

Docker Proxy GitHub Acceleration Advanced Config YAML

1. Why rule providers are useful for a growing Clash profile

A small Clash configuration can keep every routing decision in one rules list. That is easy to understand at first: a few domains go through a proxy group, local services stay DIRECT, and a final catch-all rule handles everything else. The list becomes harder to maintain when it grows to cover work applications, cloud APIs, streaming services, test environments, and exceptions that change at different speeds. Editing one large profile then risks changing unrelated behavior, and subscription updates may overwrite manual edits.

A rule provider moves a related set of rules into a separate file and lets Mihomo load that file by reference. The main profile keeps the policy structure—what a rule set is called, how it is obtained, and which policy should handle it—while the provider file contains the matching entries. This separation makes rules reusable across profiles and easier to review in GitHub. It also lets you update a frequently changing list without rewriting the rest of your configuration.

Providers are not a separate proxy mode, and they do not choose an exit node by themselves. A provider supplies matching rules; a corresponding RULE-SET entry in the main rules section assigns matching traffic to a policy such as DIRECT, PROXY, or a named selector group. If the provider is absent, malformed, or placed after a broader matching rule, the intended route may never be used. Treat the provider as one component in a routing chain rather than as an independent switch.

This approach is especially practical when you maintain a personal list of internal domains, need a project-specific exception set, or share a consistent routing baseline across several Mihomo profiles. It is less useful for a handful of stable entries: placing every domain in a separate file adds indirection without reducing meaningful maintenance work. Before introducing providers, decide which rules genuinely belong together and who will own updates. A concise set with a clear purpose is easier to test than a collection of files split solely to make the profile look modular.

There is also an important compatibility boundary. Rule-provider syntax and supported options depend on the Mihomo core version embedded in the client, not only on the client’s interface. Clash Verge Rev and other Mihomo-based applications may expose provider status differently, and older or third-party cores may not support every field shown in current documentation. Check the core version and its supported configuration before copying an example. A profile that parses in one installation is not automatically portable to every application that happens to use the Clash name.

2. Design the provider format and preserve matching order

Start by defining one narrow purpose for each provider. Names such as work-direct, lab-proxy, or media-domains explain intent better than generic names such as list1. Keep a provider’s matching behavior consistent with the content it contains. Mihomo commonly distinguishes domain-oriented providers from classical providers: the former uses domain entries such as a domain suffix, while the latter can hold full rule expressions. Do not mix formats casually. A line that is valid in a classical rule list may not be a valid entry in a domain-only payload.

The following example shows the shape of an HTTP provider that downloads a YAML payload. Replace the example URL and local path with values you control, and ensure that the payload uses the format expected by its declared behavior. The remote file is data, not a complete Clash profile; it should not contain unrelated top-level settings such as listeners or proxy definitions.

rule-providers:
  work-direct:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/your-account/clash-rules/main/work-direct.yaml"
    path: ./ruleset/work-direct.yaml
    interval: 86400

rules:
  - RULE-SET,work-direct,DIRECT
  - MATCH,PROXY

A matching domain-style payload might look like this:

payload:
  - '+.intranet.example'
  - '+.code.example'
  - 'packages.example'

The exact entries should reflect the hosts you have observed and the matching behavior you intend. A suffix can cover a family of subdomains, while a bare domain entry may cover only the specified hostname depending on the rule syntax and core implementation. Avoid adding a broad parent domain merely because one application failed to connect: that can redirect unrelated services and make a narrow exception unexpectedly large. When a provider needs rule types such as IP ranges, process names, or more complex logical expressions, choose a compatible classical format and validate it against the Mihomo version you actually run.

The order in the main rules list matters. Mihomo evaluates rules from top to bottom and uses the first matching rule. Put deliberate exceptions before broad rules that could consume the same traffic. For example, if a general provider routes an entire service family through a proxy group but one internal host should remain direct, place the specific direct rule first. Likewise, a catch-all MATCH belongs at the end; rules below it will not handle traffic that has already matched. A provider can be perfectly valid and still appear ineffective because an earlier rule took precedence.

Think of rule ordering as a policy decision, not a formatting detail. Grouping several providers in a visually tidy block does not establish priority by itself; priority comes from their positions in rules. Write a short comment near each important provider reference explaining why it precedes or follows another rule. This helps a future maintainer distinguish intentional precedence from accidental ordering. After changing the order, test both a hostname expected to match and a nearby hostname expected not to match. Negative tests catch overly broad suffixes that positive tests alone can hide.

3. Host rule files on GitHub with reviewable updates

GitHub is a convenient place to host a provider because it offers version history, pull requests, and a simple raw-file URL. Create a repository or a dedicated directory for routing data, then keep each provider in a file with a descriptive name. Use the format expected by the provider declaration, commit the file, and test its raw URL in a browser or with a command-line HTTP client before adding it to a live profile. A repository page URL is not the same as a raw content URL: the provider must retrieve the actual file body, not GitHub’s HTML interface.

A public repository is easy for a client to fetch, but public visibility means the rules and commit history are visible to everyone. Do not put account details, private hostnames, access tokens, subscription URLs, or personal network information in a public rule file. A private repository may require authentication that the client’s provider downloader cannot supply, so do not assume a private URL will work simply because it opens in your signed-in browser. For private infrastructure, consider a controlled hosting method supported by your deployment, or keep the relevant rules in a local provider file when remote delivery is unnecessary.

Git history gives you a useful audit trail. Make small commits that describe the intent of a change, such as adding a newly observed API hostname or removing a retired service. For a team, review changes through pull requests and ask the reviewer to check both the domain scope and the position of the matching rule in consuming profiles. This catches a common operational mistake: a rule entry may be correct in isolation but too broad for the policy it will affect. Keep a note of where each domain was observed, such as application logs or a documented vendor endpoint, so later cleanup is evidence-based.

A branch URL such as main is convenient because it serves the latest committed version, but that also means the returned content can change without a local profile edit. Choose an update interval that reflects how often the list is expected to change and how quickly clients should receive updates. A long interval reduces repeated downloads but delays corrections; a very short interval creates unnecessary requests and can make transient hosting problems more visible. For important environments, test a proposed update in a staging profile before merging it into the branch used by everyday devices.

Version control is not the same as version pinning. When a profile fetches from a moving branch, GitHub’s history can help you inspect or restore a previous commit, but the client still follows the file currently served at that URL when it next updates. If reproducibility is more important than automatic updates, use a release or commit-specific URL only if your hosting setup and provider downloader support that URL reliably. Document the trade-off: a fixed revision improves repeatability but requires a deliberate configuration change to receive later rules.

Do not treat a successful HTTP response as proof that a change is safe. Before publishing, check YAML indentation, quoting, line endings, expected payload keys, and whether each entry belongs to the selected provider behavior. Review additions for accidental wildcards or catch-all patterns. Then validate the file with the target core and inspect the provider’s loaded status in the client. The main profile and the remote payload are separate pieces of configuration; test them together, because a valid payload can still be connected to a missing provider name or an unsuitable policy.

4. Update safely and diagnose providers that fail

A reliable update process starts with a known-good baseline. Keep a copy of the current profile or commit it before changing provider settings. Make one meaningful change at a time, reload the configuration, and inspect the client’s logs or provider panel for download and parse errors. If the core reports a provider update failure, separate the possible causes instead of changing several fields at once: confirm the URL is reachable from the machine running Mihomo, check that the response is the raw file rather than an error page, verify the file’s syntax, and confirm the provider type and behavior are supported by that core.

When a provider loads but traffic takes the wrong route, work through the matching chain in order. First verify that the request actually reaches the Clash or Mihomo core; applications outside the system proxy or TUN path cannot be fixed by a domain rule. Next, inspect the real destination hostname in connection logs rather than assuming the visible website’s main domain is the only host involved. Then confirm that the hostname matches an entry in the payload, that the correct provider name appears in a RULE-SET rule, and that the selected policy exists in the active configuration. Finally, look for an earlier rule that may already have matched.

DNS behavior can complicate this investigation. A browser may connect to a hostname different from the one you expected, reuse a cached address, or open a connection to an auxiliary asset or API domain. Fake-IP mode, IPv6, and application-level DNS behavior can also make a test look inconsistent if you compare different clients or different connection attempts. Use a repeatable test: note the application, destination hostname, timestamp, active profile, and observed rule or policy. If one hostname routes correctly while a related API hostname does not, add only the missing observed entry rather than broadening the provider to an entire unrelated domain family.

If updates fail intermittently, check network access to the hosting endpoint, HTTP status, DNS resolution, and the client’s last successful update time. A timeout may indicate a temporary route or hosting problem rather than invalid YAML. If the payload was renamed or moved, the provider URL can remain syntactically valid while returning a not-found page that the parser cannot use. A cached local copy may keep older behavior active, so compare the loaded provider contents or update timestamp with the version you intended to publish. Restarting the client without checking status can conceal the cause rather than solve it.

Keep the rule set maintainable after the initial setup. Remove entries only after confirming they are obsolete, and retain a short explanation for exceptions that look unusual. Review providers when an application changes its endpoints, when a team’s network policy changes, or when a core upgrade alters supported syntax. Avoid copying large third-party lists without understanding their source, scope, and update process: excessive or stale entries make matching harder to reason about and can direct more traffic than intended. A small, tested provider with explicit ownership is often more dependable than a large list that nobody feels responsible for.

Some GUI clients make a global proxy toggle feel simpler, but that convenience can be limiting when one application needs a proxy while internal services, repositories, or local resources should remain direct. A manually maintained monolithic rule list has the opposite problem: it can be precise, yet difficult to review and reuse as it grows. Rule providers give Mihomo users a middle ground—separate, versioned rule data combined with explicit policy and ordering in the profile. If you want to apply the same careful approach across platforms, compare the available Clash-compatible clients and choose one that exposes the core and provider status you need to troubleshoot confidently.

Explore downloads →

Ready to get started?

Choose a Clash-compatible client, import your Mihomo profile, and verify rule-provider status before relying on a new routing set.