1. Why use Mihomo rule-providers?
If you maintain a Clash profile, custom rules often begin as a short list pasted directly into rules:. That is fine for a handful of exceptions, but it becomes difficult to review once several people add domains, the list grows, or the same rules need to be reused across devices. A Mihomo rule-provider moves that list into a separate file and lets the running core load it as a named ruleset.
Hosting the file in a GitHub repository adds a practical change history: you can see who changed a rule, compare revisions, review a proposed edit before publishing, and roll back a bad update without reconstructing the previous list from memory. Mihomo can periodically request the remote file while the core is running, so a deliberate update to the repository can reach clients without requiring every user to paste a new block of rules into their main configuration.
This is useful for personal domain exceptions, team-maintained internal services, advertising or tracking filters, and small service-specific routing lists. It is not a replacement for understanding the rules already in your profile. A provider only supplies matching criteria; the rules in your main configuration still decide which policy group or action handles a match. A correctly downloaded ruleset can therefore appear ineffective if its reference is missing, its rule is shadowed by an earlier catch-all, or it points to a policy name that does not exist.
The examples below use Mihomo-compatible YAML and a public GitHub repository. Check the documentation and logs for the exact Mihomo core version bundled with your client: Clash Verge, Clash Verge Rev, and other clients may expose different update controls, and their interface labels can change. Treat a client’s successful configuration parse as the first validation step, not proof that every provider has downloaded and matched traffic as intended.
2. Choose the right provider behavior
A provider’s behavior tells Mihomo how to interpret the entries in its file. Choose it to match the content you intend to maintain, rather than selecting a type based only on the filename. The three common behaviors are domain, ipcidr, and classical.
domainis for domain-oriented entries such as a root domain and its subdomains. It is usually the simplest choice when your list is a collection of hostnames to route or reject.ipcidris for IP address ranges in CIDR notation. Use it when the traffic decision is based on destination address ranges rather than requested domain names.classicalis for complete rule expressions, such as domain suffixes, keywords, IP ranges, or combinations that need Mihomo’s usual rule syntax. It is more flexible, but also easier to make inconsistent if contributors do not follow a shared format.
For a focused domain provider, a file can contain a YAML payload like this:
payload:
- "+.example.net"
- "+.service.example"
The leading plus-dot notation is useful when the intent is to cover a domain and its subdomains. Check the behavior you selected and the syntax accepted by the core version you deploy; do not mix full rule expressions into a domain-only payload. For an IP provider, entries should instead be valid network ranges, for example 198.51.100.0/24. The addresses in that example are reserved for documentation and are not service endpoints.
A classical provider stores ordinary Mihomo rules under payload. For example:
payload:
- DOMAIN-SUFFIX,example.net
- DOMAIN-KEYWORD,internal-tool
- IP-CIDR,198.51.100.0/24,no-resolve
Use the narrowest behavior that describes the file. If the list is only domains, a domain provider makes the intent easier to review. If you need several rule types in one file, classical behavior avoids splitting related conditions across multiple files, but it also means reviewers should inspect each rule expression carefully.
3. Host a versioned ruleset on GitHub
Create a repository for the rules you own, or use a clearly named directory in an existing repository. Keep the provider file in a stable path, such as mihomo/rules/work-services.yaml. The URL configured in Mihomo must point to the raw file contents, not to GitHub’s HTML page for browsing the repository. A typical raw URL has this shape:
https://raw.githubusercontent.com/OWNER/REPOSITORY/main/mihomo/rules/work-services.yaml
Replace the owner, repository, branch, and path with values that actually exist. A typo in any one of them can produce an HTTP error even when the repository page opens normally in a browser. A public raw file is the simplest option for clients: Mihomo does not need interactive GitHub login credentials to retrieve it. Do not put access tokens or other secrets in a public profile or provider URL. If the rules are private, first confirm that your chosen distribution method can authenticate safely; a public link should never be treated as private merely because it is hard to guess.
Keep the branch and path stable. Renaming main, moving the file, or changing capitalization in a path can break updates on systems that treat paths as case-sensitive. For everyday work, edit the file through a branch and review the diff before merging. A small, descriptive commit such as “Add billing portal domain” is much more useful later than a series of unexplained edits. If a release must be reproducible, use a URL tied to a specific commit rather than a moving branch, then update that pinned revision intentionally when the rules are approved.
Establish a lightweight review policy before several people contribute. Agree on one entry per line, a naming convention for files, and whether comments are allowed in the chosen format. Ask contributors to describe the reason for a new rule and the expected scope: for example, whether the exception covers one hostname, all subdomains, or an IP range. Broad patterns are convenient, but a rule that matches an entire shared hosting domain can affect unrelated services. Review what the rule matches, not just whether its spelling looks plausible.
You can inspect the remote file directly before wiring it into a profile. Confirm that the response contains the expected YAML and that the filename and branch match the configuration. GitHub’s normal file view is useful for review, but it is not a substitute for testing the raw URL that Mihomo will request. If you publish changes frequently, keep a short changelog or use commit messages to record the reason for each addition, removal, or correction.
4. Configure the provider and place its rule correctly
Declare the provider under the top-level rule-providers: key, then reference its name from rules: with RULE-SET. The following is a compact example for a public domain list:
rule-providers:
work-services:
type: http
behavior: domain
format: yaml
path: ./ruleset/work-services.yaml
url: https://raw.githubusercontent.com/OWNER/REPOSITORY/main/mihomo/rules/work-services.yaml
interval: 86400
rules:
- RULE-SET,work-services,Proxy
- DOMAIN-SUFFIX,local.example,DIRECT
- MATCH,Proxy
Here, type: http tells Mihomo to retrieve the provider over HTTP or HTTPS, behavior describes the entries, format: yaml declares the file format, and interval is the refresh interval in seconds. The local path is where the core stores its provider data. Use a path that is writable and appropriate for the client’s configuration layout. Relative paths are resolved in the context of the running core and profile; if a client manages profiles in a protected or temporary location, check its documentation rather than assuming the path is relative to the folder you opened in your file manager.
The value after RULE-SET must match the provider’s key exactly, including spelling and capitalization. The policy name must also exist in the active configuration. In the example, Proxy is only a placeholder for a group available in your profile. If your group is named 🌐 Select or Work, use that exact name instead. A valid provider does not create a proxy group on its own.
Rule order is consequential because Mihomo evaluates the main rules from top to bottom and uses the first matching rule. Put the provider reference above broad rules that would otherwise capture the same traffic, such as a general GEOIP line or MATCH. A provider reference below an earlier catch-all may be downloaded successfully and still never influence the route. Conversely, placing a broad provider too early can redirect traffic that should have matched a more specific direct or local rule. Arrange exceptions first, then targeted provider references, then broader regional or final fallback rules according to the policy you actually want.
The provider’s own contents also deserve review. A classical ruleset may contain multiple entries, and their ordering can matter to the intent of the list. Avoid appending a provider reference after MATCH; it is unreachable there. After editing YAML, use the client’s configuration check or Mihomo’s configuration validation before switching profiles. This catches indentation mistakes and missing keys early, but you should still inspect provider download status and test a known matching domain.
5. Make updates predictable and easy to audit
An interval value sets the provider refresh cadence while Mihomo is running. For example, 86400 requests an update about once per day; it does not mean that GitHub pushes an instantaneous change into every client. Offline devices cannot fetch a new file, and a core that is stopped cannot perform its scheduled request. After publishing an edit, allow for the configured interval or use the client’s provider update control, if available, to request a refresh sooner.
Do not set an extremely short interval just to make a change appear immediately. Frequent requests add avoidable traffic and make it harder to distinguish expected refreshes from a broken update loop. For a personal list that changes occasionally, daily refreshes are often a reasonable starting point. For a team list with a planned release cycle, choose a cadence that reflects how quickly users need approved changes. Document the interval so teammates know whether a delay is expected or a symptom worth investigating.
A Git-based workflow gives you a useful separation between editing and distribution. Make a change on a branch, review the diff, validate the YAML, and merge only after confirming the intended matching scope. Then test the raw URL and ask one client to refresh the provider. If that client downloads the file and routes a test domain as expected, you have evidence for each part of the chain: the repository contains the change, the URL serves it, Mihomo loads it, and the main rules select the desired policy.
Keep a rollback path. If a newly added entry sends a service through an unsuitable route, revert the commit or publish a correction, then refresh the affected clients. The provider file is part of the active network policy, not just a text list. For organizations, record who approves changes and what kind of services the list is allowed to cover. Avoid placing sensitive hostnames or internal network details in a public repository if that information should remain confidential.
When multiple profiles use the same provider, make the policy outcome explicit in each profile. One team may route a provider through a work relay, while a personal profile may use a different group or action. Share the ruleset only when its matching purpose is genuinely common; keep profile-specific routing decisions in the main configuration. This makes the GitHub file reusable without pretending that every user has the same proxy groups, DNS settings, or network constraints.
6. Diagnose loading and matching failures
When a provider does not work, separate retrieval, parsing, and routing into distinct checks. First inspect the client’s core log or provider panel for the provider name and update result. An HTTP status error points toward the URL, branch, path, repository visibility, or network access. A parse or format error points toward the file contents, YAML indentation, the selected behavior, or an unsupported format in the bundled core. A successful download with no visible routing change usually points toward rule order, an incorrect provider name, or a test request that does not match the list.
- Provider not found: Compare the key under
rule-providerswith the name used inRULE-SET. Check indentation and ensure both are in the correct top-level sections. - Download fails: Open the raw URL, verify that it returns the file rather than an HTML page, and check that the repository is public or otherwise reachable by the client. Confirm the device can access GitHub through its current network path.
- YAML parse error: Check spaces, colons, quotes, and the
payloadstructure. YAML indentation is significant; tabs can produce confusing errors. Validate the file before publishing it. - Rules load but do not match: Confirm the domain or address is actually present, the behavior fits the entry syntax, and no earlier rule captures the request. Use connection logs to inspect the matched rule and selected policy.
- New GitHub content is not visible: Check the configured interval and the last update time, then trigger a manual update if the client offers one. Verify that the remote branch contains the commit you expect.
Use a deliberately chosen test hostname that is included in the provider and is safe to test. Generate a fresh connection after refreshing the provider, since an existing connection may keep its current route. In the client’s connection or rule log, look for the rule name and policy associated with that request. This is more reliable than judging by whether a page loads: the application may have cached content, reused a connection, or reached the same service through another hostname.
If the profile parses but the provider reports an error, avoid changing several variables at once. Test the raw URL first, then check file syntax, then verify the provider declaration, and finally inspect rule order. Keep the old working configuration available until the new provider has passed those checks. That small discipline makes it easier to identify whether the fault is in GitHub hosting, the provider definition, the client’s core, or the policy logic.
7. Frequently asked questions
Does a GitHub change update every client immediately?
No. Mihomo checks according to the configured interval while the core is running, and an offline client cannot retrieve the change. Use a manual provider update control when you need to test sooner, then confirm the update result in the client rather than assuming a repository commit has already reached every device.
Can I use a private GitHub repository?
Do not assume that a private repository’s raw URL will work without authentication. A typical Mihomo HTTP provider request does not automatically inherit your browser’s GitHub login session. Use a distribution method that supports authentication safely, and never embed a personal access token in a profile that may be shared or published.
Should I choose domain or classical behavior?
Choose domain for a list of domain entries and ipcidr for network ranges. Choose classical when the file needs full Mihomo rule expressions or several rule types. Keep each file consistent with its declared behavior, and verify the supported format against the core version bundled with your client.
Why does the provider load but traffic still use the wrong policy?
A loaded provider only makes its entries available to the rules engine. Check that a RULE-SET line references the correct provider and policy, appears before any matching catch-all, and actually matches the hostname or address used by the application. Confirm the result in connection logs with a fresh test request.
Compared with copying rules manually into every profile, a GitHub-hosted list can be reviewed, shared, and rolled back with a clear history; compared with an opaque third-party rules subscription, a self-maintained provider lets you inspect exactly what will match and decide when clients refresh it. The trade-off is that you own the file format, review, and availability of the hosting path. Mihomo’s named providers, configurable refresh interval, and visible rule matching make that maintenance manageable when you keep the list focused and test changes before rollout. If you are setting up a compatible client for this workflow, you can Download Clash or review the Browse Tutorial.
Ready to get started?
Choose a Mihomo-compatible client, import your profile, and manage custom rulesets with a clear update workflow.