Clash Rule Providers: GitHub Hosting and Advanced YAML Setup

Why Use Rule Providers?

As a Clash configuration grows, its rules list can become difficult to maintain. A handful of domain rules may turn into hundreds of entries for streaming services, work tools, advertising domains, or regional networks. Keeping every rule inside the main profile makes reviews harder and increases the chance that a small edit will break an otherwise working configuration.

Rule providers move rule data into separate files that Mihomo can download and refresh. The main profile keeps the routing logic, while a provider file contains the rules themselves. This separation makes it easier to reuse a ruleset, review changes in GitHub, and roll back a problematic update without rewriting the rest of the profile.

A provider is not a proxy node or a subscription. It is a named collection of matching rules. In the main configuration, a RULE-SET entry connects that collection to a policy such as DIRECT, REJECT, or the name of a proxy group. The provider determines what traffic matches; the policy determines what Mihomo does with that traffic.

1Prepare a Rules Repository on GitHub

Create a repository for rules you own or are authorized to use. A simple layout is enough: place a YAML file such as rules/work.yaml in the repository and commit it to the branch you intend to publish. Keeping rules in a dedicated folder makes the raw URL predictable and separates them from documentation or other project files.

For a public repository, open the file on GitHub and choose Raw to check the direct file address. A raw URL usually follows this pattern:

Replace each path component with the actual owner, repository, branch, and file name. Use a stable branch such as main, rather than a temporary feature branch. The URL must identify the file itself; a normal GitHub page URL, a repository landing page, or a URL that requires an interactive sign-in is not a suitable provider endpoint.

A YAML rules file using the classical behavior can look like this:

The top-level payload key is part of the YAML structure. Each item is a matching rule, not a complete Clash configuration. Do not paste top-level fields such as proxies, proxy-groups, or rules into this provider file. Keep the rule syntax appropriate for the provider behavior that you will declare in the main profile.

2Configure the Provider in Mihomo YAML

Add a rule-providers section at the top level of your Mihomo configuration. The following example registers the GitHub-hosted YAML file and saves a local copy in the configuration directory:

Change OWNER and REPOSITORY to your actual GitHub values, and confirm that the branch and file path match the published file exactly. The type: http setting tells Mihomo to fetch the provider over HTTP or HTTPS. The path is a local cache location; it is not the GitHub URL and it does not need to be exposed as a public web path.

The behavior field tells Mihomo what kind of rules the provider contains. Use classical for entries written in Clash rule syntax, such as DOMAIN-SUFFIX,example.org. Use domain when the file contains domain patterns in the supported domain-provider format, or ipcidr when it contains IP network rules. The declared behavior and the contents must agree. A mismatch can cause a provider to fail to load or produce unexpected results.

For example, a domain-style file uses domain patterns rather than comma-separated classical rules:

Similarly, an IP CIDR provider should contain network ranges in the format expected by Mihomo’s provider implementation. Do not label a file ipcidr if it contains ordinary domain rules. When you use YAML, retain valid indentation and quote values when a character could be interpreted specially by YAML.

The interval value is measured in seconds. In this example, Mihomo checks for an update every 86,400 seconds, or approximately once per day. A longer interval reduces repeated requests and is often appropriate for a ruleset that changes infrequently. A shorter interval can make sense for a frequently maintained list, but checking more often does not make an invalid URL or malformed file work.

3Reference the Provider and Set Matching Order

Defining a provider does not apply it automatically. Add a RULE-SET entry to the main rules list and choose the policy that should handle matching traffic. For example:

Here, work-sites is the provider name declared under rule-providers, and Work is the policy or proxy group to use. If the profile does not contain a policy named Work, create one or change the rule to an existing policy such as DIRECT or Proxy. Provider names and policy names are different things: the first identifies a list of matches, while the second identifies a routing destination.

Rule order matters because Mihomo evaluates the rules from top to bottom and applies the first matching rule. In the example, the explicit company domain rule is checked before the broader provider. The provider then gets a chance to match before the regional and final catch-all rules. A broad rule such as MATCH normally belongs at the end; rules placed after it will never be reached for traffic already matched by it.

• Put exceptions first: Add a specific domain or IP rule above a broad provider when that exception must take precedence.
• Choose the policy deliberately: A provider routed to DIRECT bypasses proxy nodes, while one routed to REJECT blocks matching traffic.
• Keep the final match last: Check that no broad catch-all rule prevents later providers or special cases from being evaluated.
• Use descriptive names: Names such as work-sites or streaming-domains are easier to understand than generic labels such as list1.

Do not add a second provider merely to change the routing policy for a few exceptions. In many cases, a specific rule before the provider is simpler to understand and debug. Conversely, if the same set of matches is reused with different policies in different configurations, a shared provider can help keep the rule data consistent while each profile retains its own routing decisions.

4Validate Changes and Review Updates with Git

Before committing a rules change, review the diff and confirm that each addition is intentional. Check spelling, duplicate entries, domain scope, and the action that the provider will receive through its RULE-SET reference. A suffix rule can match many subdomains, so use it only when that broad scope is intended. If the rule is meant for one host, a DOMAIN match is more precise.

After publishing, test the configuration in a controlled sequence. First verify that the raw URL opens and returns the file contents rather than an HTML page or an error message. Next, validate the main YAML and confirm that the provider name, behavior, format, path, and interval are correctly indented under the appropriate top-level keys. Then reload the configuration in a Mihomo-based client and inspect its provider or log view for fetch and parse errors.

Once the provider has loaded, test a domain or address that is present in the rules file. Use the client’s connection or routing view, if available, to confirm that the request matched the expected rule and policy. A successful download alone does not prove that the provider is referenced correctly or that its rule appears before a conflicting rule.

GitHub history provides a practical review and rollback path. Keep changes small enough to explain, use commit messages that say what changed, and review the file diff before merging. If a new list causes unwanted routing, revert the commit or restore the previous content, publish the correction, and refresh or reload the provider. For collaborative repositories, require another person to review broad blocking rules or rules that affect critical work services.

5Troubleshoot Fetch, Parsing, and Matching Errors

When a provider does not behave as expected, identify which stage is failing: the client cannot fetch the file, Mihomo cannot parse it, or the parsed rules are not matching the traffic you intended. These are different problems and should be checked separately.

• Fetch or HTTP error: Open the exact raw URL in a browser. Confirm the repository visibility, branch name, file path, and spelling. If the client is offline or cannot reach GitHub, test again after connectivity is restored. A normal GitHub page URL may return HTML rather than the rules file.
• Provider not found: Compare the name in RULE-SET,work-sites,Work with the key under rule-providers. These names must match. Also verify that the provider is defined in the active configuration, not an inactive profile.
• YAML or parse error: Check indentation, the payload key, quoting, and rule syntax. YAML uses spaces rather than tabs for indentation. Remove accidental Markdown fences such as ```yaml; those belong in documentation, not in the raw provider file.
• Behavior mismatch: Make sure classical, domain, or ipcidr matches the actual contents. A valid YAML document can still be invalid for the selected provider behavior.
• Rules load but do not match: Check the target domain or IP, the pattern’s scope, and whether an earlier rule already matched. Confirm that the relevant traffic is visible to the client and that the selected policy name exists.
• Changes do not appear: Check that the latest commit is on the branch used in the URL. Then trigger a provider update or reload according to the client’s interface. The configured interval is not necessarily an immediate refresh command.

If the error persists, simplify the test: use one known rule in a small provider file, confirm that Mihomo can fetch and load it, and then add the remaining entries in batches. This helps distinguish a broken URL or YAML structure from a single unsupported or malformed rule. Keep a copy of the last known-good configuration so you can restore working routing while investigating.

Frequently Asked Questions

Does a rule provider have to be hosted in a public GitHub repository?

No. Mihomo needs to be able to retrieve the configured URL from the environment where it runs. A public raw URL is convenient, but a private repository may require authentication or a delivery method that the client cannot use. Do not assume that a browser session’s GitHub login will also authenticate Mihomo’s HTTP request.

Can I keep some rules in the main profile and others in a provider?

Yes. Keep specific exceptions or frequently adjusted rules in the main profile, and place larger or reusable collections in providers. Put each rule where it is easiest to review, and arrange the combined rules list so that the intended first match wins.

Does a shorter interval make GitHub-hosted rules more reliable?

No. The interval controls how often Mihomo checks for updates; it does not validate the file or repair a network, URL, YAML, or behavior problem. Choose a reasonable interval based on how often the list changes, then update manually when you need to test a new commit promptly.

Will every Clash client support these settings?

Rule-provider capabilities depend on the core bundled with the client and its version. Confirm that the client is using Mihomo and supports the provider options in your configuration. A client interface may expose provider updates differently, but the underlying YAML still needs valid Mihomo syntax.

With a stable raw URL, a correctly formatted provider file, and a carefully ordered RULE-SET entry, GitHub can provide a transparent and reviewable home for custom Clash rules. Keep the repository organized, test changes before relying on them, and treat provider updates as configuration changes worth reviewing.

Download Clash for Free – Get Started Now →