Build and Host Clash Rule Providers on GitHub: An Advanced Guide
Why host Clash rule providers on GitHub
A growing Clash configuration often becomes difficult to maintain for a simple reason: proxy selection, DNS settings, and every custom routing exception end up in one large YAML file. Adding a new domain then means editing and reloading the main profile, and a small indentation mistake can make an otherwise working setup fail to start. Clash rule providers solve this organizational problem by keeping rule lists in separate files and letting a Mihomo-compatible configuration load them as needed.
GitHub is a convenient place to host those files. A repository gives you readable change history, straightforward editing, and a stable raw-file URL that a rule provider can fetch. You can review exactly which domains changed, revert a bad commit, and keep work, media, or local-network rules separate without repeatedly rewriting the main profile. This approach suits users who want custom rules to survive profile updates, but it is not a substitute for understanding rule order or checking what a public rules repository reveals.
The distinction between a rule provider and a subscription is important. A subscription usually supplies a broad profile, including proxies and proxy groups. A provider supplies a list of rules that your profile references. Your configuration still decides what policy group handles matching traffic, and the order of entries in the top-level rules list still determines which matching rule wins.
Examples below target a Mihomo-compatible core. Client interfaces differ, but the core configuration remains the key: check that your client actually runs a version that supports the provider fields you use. A YAML file accepted by one recent core may not behave identically in an older or different implementation.
How a GitHub-hosted provider fits into a Clash profile
A remote provider setup has three parts: a rule file in a GitHub repository, a rule-providers entry that tells Mihomo how to retrieve and parse that file, and one or more RULE-SET entries that place the provider into your ordered rules. If any part is missing, the provider may not affect traffic even when its URL is reachable.
The behavior field describes the structure of the provider file. Use domain for a list of domain names, ipcidr for IP ranges, or classical for rule lines that include rule types such as DOMAIN and DOMAIN-SUFFIX. Match the behavior to the actual file contents: a file containing DOMAIN-SUFFIX,example.com lines is not a plain domain list.
For a domain provider, a file might contain plain hostnames or domain suffixes, one per line:
example.com
api.example.net
cdn.example.org
For a classical provider, each line includes a rule type and its value:
DOMAIN,login.example.com
DOMAIN-SUFFIX,service.example.net
DOMAIN-KEYWORD,internal-tool
Choose the narrowest rule type that expresses your intent. DOMAIN matches one hostname, while DOMAIN-SUFFIX covers the named domain and its subdomains. DOMAIN-KEYWORD can match more than you expect, so it is best reserved for cases where a stable, distinctive keyword is genuinely needed.
| Provider behavior | File contents | Typical use | Common mistake |
|---|---|---|---|
domain |
Plain domain entries | A compact hostname list | Including rule-type prefixes |
classical |
Typed rules such as DOMAIN |
Mixed domain and other supported rule types | Using bare domains without a rule type |
ipcidr |
IP addresses or CIDR ranges | Explicit network ranges | Putting hostnames in an IP list |
Create and publish a GitHub rule file
Start with a repository you control, or a clearly maintained public repository whose update policy you understand. A public raw URL is convenient because Mihomo can fetch the file directly, but public content is visible to anyone. Avoid putting private hostnames, customer identifiers, internal network ranges, or other information that should not be disclosed into a public repository. If the list must remain private, use a hosting and authentication method that your client and core can actually access; do not assume a browser session or a private GitHub page is equivalent to an unauthenticated raw URL.
- Create a repository and add a dedicated directory, for example
rules/. Give the file a descriptive name such aswork-services.yamlso its purpose is apparent when you return to the project later. - Choose a format before writing entries. For
domain, add plain hostnames; forclassical, add supported rule expressions such asDOMAIN-SUFFIX,example.com. Use one rule per line and avoid adding explanatory prose that the parser might treat as an invalid rule. - Commit the file to the repository’s default branch. Open the file in GitHub and use its raw-file view to confirm that the URL returns the file contents, not an HTML page, sign-in screen, or repository landing page.
- Copy the complete raw URL, including the owner, repository, branch, and file path. Recheck it after moving or renaming the file; a plausible-looking URL can still point to a missing path.
- Review the published content as if you were an outside reader. Confirm that it contains only the intended rules and that the repository’s visibility matches your privacy requirements.
For a repository named clash-rules owned by your-account, a file on the main branch could be fetched from a URL shaped like https://raw.githubusercontent.com/your-account/clash-rules/main/rules/work-services.yaml. Replace every example component with your real repository details; this is a URL pattern, not a working feed.
A branch URL is convenient when you want the provider to follow the latest committed version. The tradeoff is that a commit can change the feed without a corresponding edit to your main Clash profile. For critical policies, consider documenting each change in commit messages and reviewing the diff before merging. Pinning a file to a specific commit can make the content reproducible, but then updates require intentionally changing the URL. Choose the update model that fits your need for convenience versus change control.
Configure the provider and place its rules correctly
Once the raw URL works, define a provider in the main configuration. The following example uses classical rules; replace the URL, local cache path, and proxy group with values that exist in your profile.
rule-providers:
work-services:
type: http
behavior: classical
url: "https://raw.githubusercontent.com/your-account/clash-rules/main/rules/work-services.yaml"
path: ./ruleset/work-services.yaml
interval: 86400
rules:
- RULE-SET,work-services,PROXY
- MATCH,PROXY
The path is a local cache location managed by the core, not the GitHub URL. Keep it distinct for each provider so separate lists do not overwrite one another. The example interval requests an update every 86,400 seconds, or one day; choose an interval appropriate to how often the source changes and how frequently the device is online. A short interval is not automatically better. It can create unnecessary requests and still cannot guarantee an immediate update while the client is offline.
The final field in RULE-SET is a policy target. It must refer to a proxy group or other supported target that actually exists in your configuration. If your group is called Work, use that exact name rather than copying PROXY from the sample. Group names are profile-specific, and a typo can cause a configuration validation error or send traffic to an unintended policy.
Rule order is just as important as provider syntax. Mihomo evaluates the top-level rules in sequence and uses the first matching rule. Put a specific provider rule before broad rules that could already match its traffic, such as a general domain suffix, geolocation rule, or final catch-all. If a provider is listed after a broad rule, it may load successfully while never being reached for the traffic you intended it to control.
RULE-SET entry. Separating these changes makes a YAML error, an unreachable URL, and a rule-order problem much easier to tell apart.Rule providers do not replace DNS configuration. A hostname rule still depends on the core observing and resolving traffic in a way that can be matched. When behavior differs between a browser and an application, inspect Mihomo’s connection records and DNS settings instead of assuming that the GitHub file itself is incorrect.
Validate updates and troubleshoot common failures
Before enabling a new provider on a device you rely on, validate both layers: the main profile and the downloaded rule file. When available, use the validation option in your client or test the configuration with the Mihomo version that the client actually runs. A system-installed binary that is newer than the client’s bundled core can produce misleading results, so record which core performs the test.
- Configuration rejected at startup: check YAML indentation, quotation marks around the URL, and whether
rule-providersis at the top level rather than accidentally nested under another key. Confirm that each provider has the fields required by your core. - Provider cannot be downloaded: open the raw URL independently and verify that it returns plain text with a successful response. Check spelling, repository visibility, branch name, file path, and network access from the device running Clash. A URL that works on your laptop may be blocked or unavailable on a router.
- Invalid rule or parse error: compare the provider’s declared
behaviorwith its contents. Remove Markdown fences, headings, comments not supported by the expected format, and copied web-page markup. Start with one known-good rule, then add entries in small batches. - Provider loads but traffic uses the wrong route: verify the policy name in the
RULE-SETentry, confirm the group exists, and move the provider rule above broader matching rules. Use the client’s connection or rule-match view to see the actual destination and matched policy. - Changes do not appear immediately: the core may be using its local cached copy until its interval expires or the provider is refreshed. Trigger an update through the client if it offers one, then check logs for the result. Restarting the whole client repeatedly is not a reliable substitute for understanding its update behavior.
When a feed works in a browser but fails inside Clash, compare the exact response rather than just the URL. Redirects, access controls, temporary GitHub service errors, DNS failures, and differences in proxy access can all matter. Likewise, a successful provider download proves only that the file was retrieved; it does not prove that the intended application matched the rule or that the chosen outbound is reachable.
Keep a small test plan for changes. Before publishing, note one or two hostnames that should match the provider and the expected policy group. After updating, generate a connection from the relevant application, inspect the matched rule, and confirm the resulting outbound. If the result changes unexpectedly, revert the last repository commit or restore the previous provider URL while you investigate. Version control makes this rollback practical, but only if changes are small enough to identify.
For a public repository, also consider availability and rate limits. GitHub raw content is useful for personal and modest deployments, but it is not a guaranteed configuration service for every network or high-volume use case. Keep a copy of important rules, monitor update errors, and avoid making an untested remote feed the only place where essential routing policy exists.
FAQ: GitHub-hosted Clash rule providers
Can Mihomo fetch a private GitHub repository?
Not simply because you can open it while signed in to GitHub. The core needs a URL and an authentication method it supports, and private repository access can require credentials that should not be embedded in a publicly shared profile. For personal use, use a supported secure delivery method, protect any access token, and understand that a token in a configuration file may be exposed through backups, logs, or profile sharing. If you do not need private hosting, a public repository containing only non-sensitive rules is simpler.
Should the provider file use YAML or plain text?
Follow the format expected by the selected behavior and your Mihomo version. A provider that declares classical should contain rule expressions, while a domain provider uses domain entries. The extension alone does not determine how the contents are parsed; a file named .yaml can still have the wrong structure.
How quickly do GitHub edits reach my Clash client?
That depends on the provider’s configured interval, whether the client is online, local caching, and whether the core or interface offers a manual refresh. A commit does not necessarily trigger an instant fetch. Check the client’s update controls and logs, and use a shorter interval only when the added freshness is worth the extra requests.
Is one large provider better than several smaller providers?
There is no universal answer. One list has fewer configuration entries, but several focused providers are easier to review, assign to different policy groups, and troubleshoot independently. Split lists by purpose or policy rather than creating a separate provider for every hostname; excessive fragmentation adds maintenance without improving routing clarity.
Choose a maintainable rule workflow
Some all-in-one proxy clients make custom routing depend on a long sequence of UI screens, while simple VPN tools may not expose per-domain rules or a reviewable history at all. Those approaches can be convenient for a quick connection, but they become awkward when several devices need the same exceptions, a profile update overwrites local edits, or you need to explain why a domain took a particular route.
Clash with a Mihomo-compatible core offers a more inspectable workflow: keep custom rules in version control, load them as providers, and connect them to named policy groups in a configuration you can validate. GitHub does not eliminate maintenance or guarantee availability, but clear file formats, deliberate rule ordering, and reviewable commits make changes easier to test and reverse. If you are ready to set up a supported client, visit the download page for available platforms and builds.
→ Download Clash for free and enjoy a better internet experience