Clash Rule Providers: Advanced YAML Setup and GitHub Hosting

What Rule Providers Do

A long Clash configuration can become difficult to read and maintain when every domain, IP range, and application-specific rule is written directly into the main rules list. Rule providers solve this by letting the configuration load a rule set from a separate file, then refer to that set by name with a RULE-SET rule. The main profile stays compact while the provider file can be updated independently.

In practical terms, the main configuration describes where a rule set comes from, how its contents should be interpreted, and how often the client should check for a newer version. The rules themselves live in a separate YAML file or another supported format. When the configuration is processed, a matching rule set can send traffic to a policy group such as Proxy, DIRECT, or a group defined in your own profile.

Rule providers are useful for users who maintain their own domain lists, share rules across several devices, or want to separate frequently updated rules from stable routing logic. They are not a substitute for understanding rule order: Clash evaluates rules from top to bottom, and the first matching rule determines the action. A provider that is correctly downloaded but referenced after a broader matching rule may never affect the traffic you intended it to control.

1Configure the Provider in YAML

In Mihomo-based clients, provider definitions are commonly placed under the top-level rule-providers: key. Each provider needs a unique name, a source type, a rule behavior, a download URL, a local cache path, and a refresh interval. The following example defines a domain rule set hosted in a public GitHub repository:

The provider name, work-services, is an identifier chosen by you. Use a short, descriptive name and keep it consistent wherever it is referenced. type: http tells the core to fetch the content over HTTP or HTTPS. behavior: domain tells Mihomo that the file contains domain-based entries rather than complete Clash rules. format: yaml indicates the file format for supported Mihomo versions. If your core is older or reports that the field is unknown, check the core’s supported syntax and remove or adjust the field accordingly.

The url points to the raw file, not the normal GitHub page used to browse a repository. The path is where the core keeps its local copy. It is a filesystem path, not a URL; a relative path such as ./ruleset/work-services.yaml is typically resolved within the client’s working or profile storage context. Avoid assuming that the path is relative to the folder where you downloaded the original configuration. If a provider fails to load, inspect the core log for its resolved path and verify that the application can write to that location.

The interval is measured in seconds. For example, 86400 requests a refresh approximately once per day. A shorter interval is not automatically better: refreshing too frequently creates unnecessary requests and may make troubleshooting harder. Pick a value that matches how often the list changes, then use the client’s provider-update action when you need to test a new version immediately.

Select the Right Behavior

The behavior value must agree with the contents of the downloaded file. A mismatch can cause parsing errors or rules that do not match as expected. Common choices include:

• domain: For domain entries such as DOMAIN-SUFFIX,example.com or supported domain-pattern entries, depending on the format and core version. Check the expected provider payload syntax before mixing entry types.
• ipcidr: For IP address ranges written in CIDR notation, such as 192.0.2.0/24. Use this when the provider is intended to match IP networks.
• classical: For complete Clash-style rule expressions, such as DOMAIN-SUFFIX,example.com or IP-CIDR,192.0.2.0/24. The individual rules include their own rule types.

Do not use classical simply because the source file has a YAML extension. File format and rule behavior describe different things: the format describes how the file is serialized, while behavior describes the kind of rule data inside it. In particular, a classical provider generally contains a YAML payload list of complete rule strings, not a second full Clash configuration with top-level keys such as rules or proxies.

Reference It with RULE-SET

After defining a provider, add a matching RULE-SET entry under the main configuration’s top-level rules: list. The provider name must match exactly, and the destination must be a policy group that exists in the active configuration:

Here, traffic matching the provider is sent to the Proxy group. If your group is named Work, Auto, or something else, use that actual name instead. Keep specific rules above broad catch-all rules. A MATCH rule is usually placed at the end because it matches traffic that has not already matched an earlier rule.

2Host Rule Files on GitHub

GitHub is a convenient place to keep a public rule file because it provides version history and a stable raw-content URL. Create a repository, add a provider file, and commit it. For a raw GitHub URL, the usual pattern is https://raw.githubusercontent.com/<owner>/<repository>/<branch>/<path>. Replace each placeholder with the actual owner, repository, branch, and file path. The URL must resolve directly to the file contents; a URL beginning with github.com that displays the repository interface is generally not the raw download address required by an HTTP provider.

For a domain provider using YAML, a minimal file can look like this:

Keep the provider payload focused on the entries expected by the selected behavior and supported format. This example uses domain patterns in a YAML payload. Do not add the surrounding configuration fields rule-providers or rules to this provider file. Those belong in the main Clash configuration, not in the downloaded rule-set payload.

A classical rule provider has a different payload because its entries are complete rules. For example:

Use the structure required by your core version and provider behavior. If you are uncertain whether the endpoint returns valid content, open the raw URL in a browser or request it with a command-line tool, then inspect the response. A successful HTTP status alone is not enough: an HTML error page, a GitHub rate-limit message, or malformed YAML is still unusable as a rule provider.

Choose a Branch or Commit Reference

Using a branch such as main is convenient because updates become available at the same URL. It also means a new commit can change routing behavior without any edit to the main configuration. For personal lists that you actively maintain, this can be a practical balance between convenience and control. Review changes before merging, and avoid giving write access to people or automation that you do not trust.

For a more controlled setup, reference a tagged release or a commit identifier in the URL if your hosting arrangement supports that path. A fixed reference makes the content reproducible, but it will not receive later changes until you update the URL. Whichever approach you choose, keep a known-good copy of the last working file. If a new revision breaks parsing or matches too broadly, you can revert the GitHub commit or point the provider back to the previous version.

Public raw URLs are intended for content that can be read publicly. Do not place credentials, private network details, or sensitive internal hostnames in a public repository. Private repositories require authentication, and a plain unauthenticated provider URL will not gain access merely because you can view the repository while signed in to a browser. Avoid embedding access tokens in a configuration that may be synced, shared, or exposed in logs.

3Refresh and Maintain Providers Safely

Once the main profile is loaded, the core retrieves the provider and stores a local copy at the configured path. The interval controls periodic refresh checks; it does not mean every matching connection downloads the file. If you have just pushed a change, use the provider update or refresh control in your client to request an update rather than waiting for the next interval. Button names differ between Clash Verge, Clash Verge Rev, and other front ends, but provider management is commonly available from the profile or rule-provider view.

After requesting an update, check both the provider status and the core log. A status indicator that says “updated” is useful, but confirm that the timestamp changed and that the core loaded the content without parse errors. If the client offers an option to reveal or inspect the provider file, verify that it contains the expected revision. Some clients manage configuration files and caches in application-specific directories, so editing a similarly named file elsewhere may not change the copy the core actually uses.

Maintain rule sets as carefully as the main configuration. Keep names stable so existing RULE-SET references do not break. Remove duplicates, document unusual entries, and divide unrelated purposes into separate providers rather than putting every rule into one large file. For example, separating work domains from streaming domains makes it easier to apply different policy groups and to identify which list caused an unexpected route.

• Validate before publishing: Check YAML indentation, quoting, list structure, and the rule syntax expected by the selected behavior.
• Make small changes: A focused commit makes it easier to locate a bad entry and revert it without discarding unrelated updates.
• Choose a realistic interval: Update daily or less often for stable lists; use a shorter schedule only when there is a real operational need.
• Keep a fallback: Preserve a known-good revision or local copy so a broken remote edit does not leave you without a working policy.
• Watch repository limits: Large files, frequent requests, and public hosting policies can affect availability. Keep rule lists reasonably sized and avoid needless refreshes.

Remember that a remote provider introduces an external dependency. If GitHub or the network path to it is unavailable, the core may continue using a previously cached copy, depending on the client and core behavior. Do not assume that every client handles failed updates identically. For critical routing, test what happens when the URL cannot be reached and keep a local alternative or a dependable recovery path.

4Troubleshoot Download, Parsing, and Matching Failures

When a provider does not work, separate the problem into three stages: fetching the remote file, parsing its contents, and matching traffic with the loaded rules. This approach is faster than changing several YAML fields at once.

The Provider Cannot Be Downloaded

First, copy the provider URL into a browser or test it with a command-line HTTP request. Confirm that the response is the raw rule file and not a GitHub HTML page, a 404 response, a permission error, or a temporary rate-limit response. Check spelling, capitalization, repository name, branch, and file path. Git paths are case-sensitive, so Rules/Work.yaml and rules/work.yaml may refer to different locations.

Next, verify that the client has network access to the host and that the URL uses HTTPS. A proxy or DNS issue may prevent the core from reaching GitHub even if the browser can load the page through a different network path. Review the core log for the HTTP status and error details. If the raw URL works manually but fails in Clash, confirm that the running core is reading the profile you edited and that the configured local path is writable.

The File Downloads but Fails to Parse

YAML is indentation-sensitive. Use spaces, not tabs, align list items consistently, and quote values that contain punctuation where appropriate. Confirm the top-level payload structure expected by the provider format. A common mistake is to paste a complete Clash configuration into the provider file or to place full rule expressions in a provider declared with a domain-only behavior. Another is to declare format: yaml while serving plain text or a different serialized format.

Check the exact core error rather than guessing. Errors mentioning an unknown field may indicate a core version that does not support that option. A syntax error may point to an invalid line, indentation level, or unexpected character. Fix the file, commit the correction, then trigger a provider refresh and confirm that the timestamp and loaded contents have changed.

The Provider Loads but Traffic Is Routed Incorrectly

Verify the provider name in the RULE-SET entry character by character. Then make sure the target policy group exists in the active profile and appears under the expected name. Review rule order: more specific rules generally belong above less specific rules, and catch-all rules such as MATCH belong near the bottom. Also consider whether the traffic is identified by a domain at all; an IP-only connection, DNS behavior, or an application’s own routing may affect which rule is available to match.

For a controlled test, use a single, clearly identifiable domain in a small provider and route it to a distinct existing policy group. Update the provider, generate a fresh request to that domain, and inspect the client’s connection details or rule-hit display if available. Testing one case at a time helps distinguish a matching problem from a proxy-group or connectivity problem. Once verified, add the remaining rules in small batches.

5Deployment Checklist

Before relying on a GitHub-hosted provider, review the complete path from source file to routing decision. The provider should be publicly reachable if it does not use authentication, and the raw URL should return the expected content. Its behavior and format should match that content, its cache path should be valid for the client, and its refresh interval should fit the update schedule. Finally, the main configuration should reference the exact provider name and send matches to a real policy group.

• Confirm the GitHub raw URL opens the intended file, not a repository page or an error response.
• Validate the provider YAML and make sure its payload matches domain, ipcidr, or classical behavior.
• Keep provider names, local paths, and RULE-SET references consistent.
• Place the provider rule before any broader rule that would otherwise match the same traffic.
• Refresh the provider, inspect the core log, and test with a known domain or IP before depending on it.
• Keep a backup or reversible Git revision, and never publish secrets in a public rule repository.

Rule providers make a large Clash configuration easier to organize, but they also add a remote source and another layer of configuration to maintain. Start with one small provider, verify download and matching behavior, and expand only after the basic workflow is reliable. With clear naming, careful rule ordering, and a reviewable Git history, GitHub-hosted YAML rule sets can be a practical way to maintain routing rules across profiles without repeatedly editing a long main configuration.

Download Clash