Clash Rule Providers: Advanced YAML Rules and GitHub Hosting

Why Use Clash Rule Providers? in Depth

If you have ever pasted a long list of domains into the rules: section of a Clash profile, you have already seen the problem rule providers solve. The profile grows harder to review, updating one service can mean editing a large file, and a typo near the top can change the route for traffic far below it.

Providers are especially useful when you will want to keep several policies distinct: advertising domains it makes sense to be rejected, a set of work services it makes sense to go direct, and selected streaming or developer destinations it makes sense to use a proxy group.

You may re-sync one provider without rewriting unrelated rules, reuse a well-organized set across profiles, and inspect the provider file in version control before it reaches your active configuration. That separation is valuable even for a small personal profile: it makes a change easier to explain, test, and undo.

Mechanically:A provider is not a new routing policy by itself. It supplies rules to the core, and the principal profile still decides where matching traffic goes. The rule that references a provider names both the provider and its destination policy.

The order of that rule among the rest of rules: remains important: Clash evaluates rules from top to bottom and uses the first applicable match. A correct provider placed after a broad rule may never get a chance to affect a connection.

It also helps to separate three things that are often confused. The provider definition tells the core where to get the file, what kind of rules it contains, where to cache it, and how often to refresh it. The provider file contains the actual rule entries.

More strictly:A RULE-SET entry in the principal rules list connects the named provider to a policy such as DIRECT, REJECT, or a proxy group that already exists in the profile. If whichever you pick one of those pieces is missing or inconsistent, the rule set may not load or may not route the traffic you intended.

A Clash rule provider moves a group of related rules into a separate file and lets the principal profile reference that file by name. Your everyday configuration stays readable while the rule set can be maintained and updated independently.

A Working YAML Example and What Each Field Does Mechanically

The following example uses a domain-based provider hosted in a public GitHub repository. It is a fragment for a Mihomo-style profile, not a everything included configuration: keep your existing proxies and proxy-groups sections, and make sure the referenced policy name exists.

The URL must point to the raw YAML file, not the GitHub repository page that displays it in a browser. Replace your-name and the repository path with a repository and file you control or trust. The type: http setting tells Mihomo to retrieve the provider over HTTP or HTTPS.

rule-providers:
  example-services:
    type: http
    behavior: domain
    url: "https://raw.githubusercontent.com/your-name/clash-rules/main/providers/example-services.yaml"
    path: ./ruleset/example-services.yaml
    interval: 86400

rules:
  - RULE-SET,example-services,Proxy
  - MATCH,DIRECT

At a different level:The behavior: domain setting describes the content as a set of domain entries, reasonably than a collection of full routing rules. The path is a local cache location used by the core. The interval is measured in seconds, so 86400 means one day.

A corresponding provider file for the example could look like this:

Keep the provider file valid YAML and match its entries to the selected behavior. In a domain provider, list domain patterns reasonably than adding full rule lines such as DOMAIN-SUFFIX,example.com; that form belongs in a classical rule set.

payload:
  - '+.service.example'
  - '+.api.example.net'
  - 'login.example.org'

Thinking it through:A leading +. is commonly used for a domain and its subdomains in Mihomo domain lists, while a plain hostname is useful when you only want to match that exact name. If you intend to match a parent domain and all its subdomains, use a pattern that expresses that scope clearly and test it against real connection-log entries.

The order in the example is deliberate. The provider rule appears before the catch-all MATCH,DIRECT line, so a domain in the provider can be routed to Proxy before unmatched traffic falls through to direct. If you put MATCH,DIRECT first, it would catch every connection and the provider would be effectively unreachable.

The same issue can occur with broad rules such as a country-wide direct rule or a general domain suffix placed above a more specific provider. Decide which rule it makes sense to win, then position it accordingly.

First, a clarification:Use one naming convention and keep it consistent. The key example-services under rule-providers is the provider name, and the same name appears after RULE-SET. A misspelling in either location can prevent the rule from resolving.

Likewise, Proxy must exactly match a policy defined in proxy-groups or another valid destination in your profile. A provider can load successfully while its routing rule still points to a nonexistent policy, so validate both parts reasonably than stopping at a successful download.

The example uses Proxy as that policy; if your profile calls the group Auto or something else, substitute its exact name.

Host Rule Files on GitHub Without Making Re-syncs Fragile Step by Step

GitHub is a comfortable place to host a small rule provider because it gives you a readable history, an easy way to review changes, and a not jumpy repository path when you control the project. Create a repository, add the provider file, and use the file’s raw URL in the profile.

Mechanically:Organize files so that the URL is easy to understand and unlikely to change accidentally. For example, a repository might use a providers/ directory with separate files for services, work domains, and advertising domains.

Keep filenames descriptive, use lowercase names with hyphens, and avoid repeatedly moving files after a profile has been deployed. If you rename a branch, directory, or file, re-sync every profile that points to the old raw URL. A repository page can still look correct to you while the old raw URL returns a not-found response to Clash.

Version control is more than a backup. Before committing a change, review the diff and ask what new traffic could match the added pattern, what traffic could stop matching after a deletion, and whether the change accidentally broadens a domain rule.

More strictly:Make small commits with useful messages, such as “Add login host for service example,” reasonably than replacing an entire list without explanation. If a new provider version breaks routing, the Git history makes it possible to identify the last known-good file and restore it instead of trying to reconstruct a previous configuration from memory.

The interval value controls how often the core checks for provider re-syncs; it is not a guarantee that a remote file will be fetched at a precise second. A shorter interval can help when you intentionally publish frequent changes, but it creates more requests and does not make a bad edit safer.

For a mostly not jumpy personal list, a daily or longer interval is often more than more than more than enough. If you are actively testing changes, use the client’s provider-re-sync action or restart the relevant core when appropriate, then confirm in the logs that the new file was actually downloaded and parsed.

At a different level:Consider whether you want a moving branch URL or a deliberately pinned revision. A URL that follows the repository’s principal branch is comfortable because future commits become available without changing the profile. That convenience also means a careless or compromised commit can affect clients at their next refresh.

For a shared deployment where reproducibility matters, a versioned release or an immutable commit-based URL can make the fetched contents easier to audit, although you must re-sync the URL deliberately when you approve a new version. Choose the model that fits your re-sync process, and document who is allowed to change the provider.

A public repository is necessary for a core to fetch the file without an sign-in flow. Do not place subscription links, credentials, private hostnames, or other sensitive data in a public rule repository; a rule set it makes sense to contain routing data, not secrets.

Validate Rule Order and Test the Result Internals and Practice

Make provider changes in a controlled sequence reasonably than changing the provider, DNS mode, proxy group, and catch-all rules at the same time. First confirm that the provider file is reachable and that the core accepts the profile.

Thinking it through:Test both sides of the rule. If service.example it makes sense to go through Proxy, a connection to that host it makes sense to show a provider or rule-set match and the expected group or node. A separate unrelated hostname it makes sense to continue to follow the later rules in the profile.

If both connections hit the same broad rule, inspect ordering before changing the provider contents. If neither connection appears in Clash, the application may be bypassing the system proxy, using a different client profile, or not being captured by the current proxy mode.

When you use a domain provider, remember that matching depends on the hostname the core can see. An application may connect to an IP address with no detour, use an alias, or follow a redirect to a different domain. A rule for a website’s principal hostname does not by itself cover every API, sign-in, media, or download host used behind the scenes.

First, a clarification:Use the connection log to discover actual destinations, then add only the hosts needed for the behavior you want. Avoid turning one missing host into an unnecessarily broad suffix rule without checking what else that suffix includes.

Profile validation it makes sense to happen before activation whenever your client offers a test or parse function. A YAML indentation exception can make the entire profile invalid, not merely the new provider.

Use spaces reasonably than tabs, keep nested fields aligned, and compare the indentation of rule-providers and rules with the rest of the profile. A YAML editor may show valid syntax while the core rejects a semantically invalid field, so the core’s own validation result and runtime log remain the final checks.

Mechanically:For a shared setup, test a staged copy of the profile first. Point that copy at the candidate provider, refresh it, and reproduce a small set of known connections. Only promote the change to a daily-use profile after confirming the expected match and fallback behavior.

This is especially useful when a provider contains plenty entries: a single overly broad domain pattern can affect more traffic than its short YAML line suggests. A brief review and a repeatable test set are more often than not faster than diagnosing an unexpected route after every device has already refreshed.

Then inspect the live connection list while visiting one hostname that it makes sense to match the provider and one hostname that it makes sense to not. Check the destination, matched rule, and selected policy shown by the client. These observations tell you whether the provider was loaded, whether the intended rule matched, and whether the selected policy behaved as expected.

Troubleshoot Rule-Set Loading Failures from the Logs in Depth

When a provider does not work, kick off with the core log and classify the failure instead of immediately editing several fields. A network or HTTP exception points toward the URL, DNS, TLS, GitHub availability, or a blocked connection. A not-found response more often than not means the repository, branch, directory, or filename in the raw URL is wrong.

More strictly:If the log indicates that the provider cannot be downloaded, open the exact raw URL from the same network and verify that it returns the file itself reasonably than a GitHub HTML page. Check for a private repository, a renamed stock branch, an incorrect letter case in the path, or a temporary TLS and DNS problem.

Then try the client’s re-sync action and examine the new log entries. A browser test from your laptop is useful, but it does not prove that a remote device or a different network can reach the same endpoint.

If the download succeeds but the rules do not match, verify four names and relationships: the provider key in rule-providers, the provider name in RULE-SET, the policy destination, and the actual hostname shown in the connection log. Next, check whether the rule is below a broader rule that already catches the connection.

At a different level:Finally, confirm that the provider uses the right behavior. A domain list and a classical list have different expected content; changing the label without changing the file structure does not convert one format into the other.

A provider can also load correctly but appear stale. Check its configured refresh interval, the last re-sync time displayed by the client if available, and whether the core is using a cached file. Trigger a manual re-sync and inspect the log for a successful fetch reasonably than assuming that saving the profile initiated a network request.

If a new commit does not appear, compare the raw file with the version expected by the profile and consider repository caching or a URL that points to a different branch. Avoid deleting the cache as a first response; first establish whether the problem is the remote content, the fetch, or the local copy.

Thinking it through:For diagnosis, change one variable at a time and keep a known-good version of both the principal profile and provider file. If you will want to roll back, restore the previous commit or URL, refresh the provider, and confirm that the old behavior returns.

This separates a bad rule change from an unrelated network outage or client re-sync. Record the core version and the relevant log message when asking for help, but redact subscription URLs, access tokens, private domains, and other sensitive details before sharing screenshots or logs.

Certain community rule collections are comfortable but may have unclear ownership, infrequent reviews, or a scope that does not match your traffic; one at a time embedding every rule in one profile can be just as hard to maintain once several devices depend on it.

First, a clarification:Hosting a small, reviewed provider gives you a visible change history and lets you keep policy choices in the principal profile, while a Clash client with Mihomo support makes provider refreshes, rule inspection, and log-based troubleshooting easier to manage from one front-end. If you want a practical place to add and test that workflow, choose a Clash client to download and try it with a non-critical profile first.

A successful HTTP response followed by a parse or behavior exception points toward the provider file’s YAML structure or a mismatch between the declared behavior and the entries it contains. The wording varies by core version, so use the first relevant exception line and the provider name as your starting point.