Build Custom Clash Rule Providers on GitHub: YAML Setup Guide

Why move reusable rules into a rule provider?

A Clash rule provider lets you keep a set of routing rules outside your main profile and refer to that set by name. Instead of copying a long list of AI, coding, or documentation domains into rules, you maintain the list in a separate file and let Mihomo load it when the profile starts or reaches its configured update interval. The main profile stays easier to review, while the reusable list can be updated without editing every profile that depends on it.

This is particularly useful when different devices share the same routing policy. You might use a Windows desktop, a laptop, and a router with separate Mihomo configurations, but want requests to selected developer tools to follow the same proxy group on all of them. A GitHub-hosted rule file gives you one place to maintain that list. Each client still needs its own provider declaration, but you no longer have to paste every individual domain into each profile.

A rule provider is not the same thing as a proxy provider. A proxy provider supplies proxy nodes that can be members of a proxy group. A rule provider supplies matching conditions, such as domains or IP ranges, which a rule can send to a policy group. If a browser request matches a provider rule, the policy named in the main profile determines how the request is handled. The provider does not create nodes, choose a server, or guarantee that a particular website will be reachable.

GitHub can be a convenient place to host a small public rules file, but it is not a dedicated configuration service. A public raw file may be cached, temporarily unavailable, or inaccessible on a particular network. Treat the hosted file as a dependency: keep a working local profile, test changes before relying on them, and avoid putting subscription links, tokens, private hostnames, or other secrets in a public repository. If the rules are sensitive, choose a hosting method and access arrangement that your client can actually authenticate to; a private repository’s raw URL is not automatically accessible to Mihomo.

Create a GitHub-hosted rule file

Create a repository or use an existing one, then add a dedicated file for one coherent purpose. For example, a file named rules/ai-tools.yaml can contain AI service domains, while a separate rules/developer-tools.yaml can cover code hosting and package documentation. Separate files make review and rollback easier: you can change one category without unexpectedly changing another.

For a YAML provider using the domain behavior, Mihomo expects a YAML document with a payload list. Domain entries can use a suffix pattern such as +.example.com to cover the base domain and its subdomains. A small file could look like this:

payload:
  - +.openai.com
  - +.chatgpt.com
  - +.anthropic.com

Use real domain names that you intend to route, and verify them against the services you actually use. Do not assume that one brand uses only one domain: login flows, APIs, static assets, and download services may use different hostnames. At the same time, avoid adding broad parent domains simply to make a test pass. A suffix that matches more than you expect can send unrelated traffic through the same policy group.

After committing the file, open it on GitHub and use the raw-file view to check that it returns the file contents rather than an HTML page. A raw URL commonly follows this pattern:

https://raw.githubusercontent.com/OWNER/REPOSITORY/BRANCH/rules/ai-tools.yaml

Replace the placeholders with the actual owner, repository, branch, and path. The path and capitalization must match the repository exactly. For a stable configuration, reference a branch intended for released rules, such as main, and make changes through commits that you can inspect or revert. Referencing a moving branch is convenient because new commits become available without changing the profile, but it also means an unreviewed commit can alter routing behavior. If you need reproducible builds, consider referencing a versioned release or commit-specific URL and update that reference deliberately.

Choose the file format based on how you want to maintain the list. YAML is readable and supports a clear payload structure; text providers can be useful for line-oriented rule lists when the provider behavior and file contents are compatible. Keep the provider’s format setting aligned with the actual file format, and confirm that the Mihomo version used by each client supports the fields in your profile. A configuration accepted by one recent core may not be accepted by an older or differently bundled core.

Configure the provider and connect it to a policy group

Add a rule-providers section at the top level of the Mihomo configuration. The provider name is a local identifier: it is not the GitHub repository name, and it must match the name used later in the RULE-SET rule. The following example shows a domain provider and a rule that sends its matches to a proxy group named AI-Tools:

rule-providers:
  ai-tools:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/OWNER/REPOSITORY/main/rules/ai-tools.yaml"
    path: ./ruleset/ai-tools.yaml
    interval: 86400

rules:
  - RULE-SET,ai-tools,AI-Tools
  - MATCH,PROXY

Replace OWNER and REPOSITORY with your values, and ensure that AI-Tools is the exact name of a proxy group defined in proxy-groups. If your group is named Proxy, AI, or something else, use that exact label instead. The final MATCH rule is only an example of a catch-all policy; retain the final routing behavior that makes sense for your existing profile.

The type: http field tells Mihomo to fetch the provider file over HTTP or HTTPS. The behavior: domain field describes what kind of rules the provider contains. For network ranges, use an appropriate IP-CIDR behavior and compatible entries; for full Clash-style rules such as domain suffixes, ports, or process conditions, use a compatible classical provider and write the file accordingly. These behaviors are not interchangeable. If the provider behavior and the entries disagree, the configuration may fail validation or rules may not match as expected.

The format: yaml field identifies the provider file format in Mihomo versions that support it. The path field is a local cache location used by the core. It is not the GitHub URL and does not need to match the repository path, but it should be a sensible writable location for the client that runs Mihomo. On systems where the client manages configuration paths, use a path convention that the client supports rather than assuming it can write anywhere on disk.

The interval value is measured in seconds. In the example, 86400 is one day. A longer interval can be appropriate for a stable domain list and avoids unnecessary requests; a shorter interval can make sense while actively testing changes. An interval is not a guarantee that GitHub will be fetched at that exact moment: the client must be running, the network must be available, and the core must be able to reach the URL. After editing a provider, use the client’s provider update or profile reload control to test the new content rather than waiting for the scheduled refresh.

Order matters in the main rules list. Mihomo evaluates rules from top to bottom, and the first matching rule determines the policy. Put a specific RULE-SET rule before broader rules that would otherwise catch the same traffic. If a broad domain rule or an earlier catch-all already matches a request, adding a provider lower in the list may have no visible effect. Keep the provider reference in the same section and format as your other rules, and avoid duplicating the same domains in both the provider and a long inline list unless there is a clear reason.

Validate updates and troubleshoot common failures

Start by checking the Mihomo core log and the provider status in your client. Client interfaces differ, but many expose provider health, the last update time, or a manual update action. If the provider is marked unavailable, investigate the fetch before changing the routing rule. If it loaded successfully but a domain still uses an unexpected policy, investigate matching and rule order instead. Separating these two questions prevents a common troubleshooting loop in which users repeatedly edit valid YAML to solve a network or policy-group problem.

If the provider fails to download, copy the exact configured URL into a browser or use a command-line HTTP client from the same network. Confirm the response is successful and contains the expected YAML. Check for a misspelled owner, repository, branch, or path; a renamed default branch; incorrect capitalization; an extra space; or a URL that points to the normal GitHub page instead of the raw file. Corporate networks, DNS filters, captive portals, and temporary access problems can also prevent the core from reaching GitHub even when the URL works on another connection.

If Mihomo reports a parse or format error, compare the file body with the declared behavior and format. A YAML file should have valid indentation and a correctly named payload list. Check for tabs, smart quotes, accidental Markdown fences, or a pasted error page. For a classical provider, make sure the entries are valid Clash rules rather than bare domain suffixes intended for a domain provider. Also check that the client is using a Mihomo core version compatible with the provider options in your profile.

If the provider loads but a test domain does not use the expected group, confirm that the domain actually matches one of the entries. A suffix entry for +.example.com is intended for that domain family; it will not automatically match a separate service domain such as example-cdn.net. Check the request in the client’s connections or logs and read the matched rule and selected policy, when available. The request may be using a different hostname than the one you tested, or the destination may be an IP address governed by another rule.

Then inspect rule order and group names. The provider reference must come before any broader rule that would take the request first, and the policy label must match a real proxy group. A typo in the group name can prevent configuration validation or leave the policy behavior different from what you intended. If the relevant group itself selects DIRECT, a successful provider match can still produce a direct connection; the provider classifies traffic, while the group decides the action.

When GitHub changes are not appearing, remember that there may be more than one copy of the data in play: the committed file, an HTTP cache, the core’s local provider cache, and the client’s active profile. Confirm that the latest commit contains the expected file, manually update the provider, and then check its update status. If you are testing a change, make a small, observable modification and verify it through the provider status or a controlled connection test. Do not delete cache files or repeatedly restart the client before confirming which layer is stale.

Keep a simple rollback path. Commit changes in small, understandable batches, review the diff before pushing, and preserve a copy of the last known-good profile. A malformed provider can affect every profile that references it, so a quick rollback is more useful than trying to patch several clients independently. If multiple devices use the same provider, test the change on one client first and confirm that its core version and configuration behavior match the others before treating the update as successful everywhere.

Finally, treat domain lists as routing hints, not as a permanent inventory of every service endpoint. Services can add domains, move assets to a content delivery network, or change login flows. Review the list occasionally, remove entries you no longer need, and test important applications after meaningful changes. A focused provider is easier to audit, less likely to capture unrelated traffic, and simpler to maintain than a broad list copied from an unverified source.

Some GUI-only proxy tools make small routing changes quick, but can be awkward when you need the same reviewed domain set across several profiles or want a clear history of edits. Mihomo rule providers pair a readable YAML file with policy groups, scheduled updates, and GitHub’s commit history, so each change can be checked and rolled back. If you want to test that workflow in a Clash client, Download Clash.