Why GitHub-hosted rule-providers matter in advanced Clash setups

Searches such as Clash rule-providers GitHub, custom Clash YAML rules, or “how do I route GitHub, OpenAI, and streaming services differently in Clash?” usually appear after a basic profile has stopped being enough. A single subscription may provide proxy groups and a long rule list, but it rarely reflects the exact network policy you need. Developers may want GitHub, package registries, documentation sites, and AI APIs on one reliable group. A family may prefer streaming services on another group while keeping banking, local government portals, and workplace systems on DIRECT. A small company may also need a rule set that can be reviewed, versioned, and updated without manually editing every client.

A rule-provider solves that maintenance problem by moving a group of rules into a separate YAML file. Clash or Mihomo downloads the file from a configured URL, stores it locally, and applies it as part of the active routing policy. Hosting that file in a GitHub repository gives you a familiar workflow: edit rules in a text editor, review a diff, test the syntax, and publish a controlled revision. The important distinction is that GitHub is only the delivery and version-control layer. It does not decide how traffic is routed. Your Clash profile still controls the provider’s behavior, its policy group, its update interval, and its position relative to other rules.

This guide focuses on maintainable configuration rather than blindly copying a large ruleset. You will see how to design a repository, write domain and suffix rules, connect the provider to a Clash-compatible profile, control matching order, avoid common YAML and URL mistakes, and debug the result through Mihomo logs and connection details. The examples use neutral group names such as AI, Code, Streaming, and Proxy; replace them with the exact names exposed by your own profile.

Design a GitHub rule-provider that remains easy to maintain

Start with scope. A provider should answer one routing question clearly instead of becoming a second monolithic configuration file. For example, an ai.yaml provider can contain model APIs and AI web applications, while a separate coding.yaml provider can cover GitHub, GitLab, package registries, and developer documentation. This separation makes review easier and limits accidental policy changes. If a GitHub pull request adds a streaming domain, the reviewer should not have to inspect hundreds of unrelated enterprise rules before understanding the impact.

For a simple domain-based provider, use the following structure:

payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN-SUFFIX,githubassets.com
  - DOMAIN-SUFFIX,api.github.com

The payload array is the part Mihomo consumes as a list of rule lines. Keep one rule per line and avoid adding comments inside the payload unless your target client and parser version are known to support them consistently. Domain suffix rules are useful when a service operates across multiple subdomains. A suffix rule for github.com can cover github.com and its subdomains, but it does not automatically cover every unrelated GitHub-owned domain. That is why assets, raw content, user content, and API hostnames may need explicit entries after you observe them in the Connections view.

Use exact domain rules when the policy should be narrow. For instance, an enterprise environment might want the main GitHub site proxied but leave an internal mirror or a local development hostname untouched. In that case, DOMAIN,github.com is more deliberate than a broad suffix rule. Use keyword rules cautiously because they can match unexpected hostnames. A keyword such as google may catch a legitimate internal hostname or a third-party service that happens to contain the same text. Regular-expression rules are powerful, but they increase review and debugging cost, so reserve them for patterns that cannot be represented clearly with exact or suffix rules.

A practical repository layout could look like this:

clash-rules/
├── ai.yaml
├── coding.yaml
├── streaming.yaml
├── enterprise-direct.yaml
└── README.md

Use the README to document the purpose of each file, its intended policy group, the last review date, and any known exclusions. Do not place subscription tokens, private hostnames, internal IP addresses, or credentials in a public repository. A public rule-provider should contain routing metadata only. If the repository is private, confirm that the raw URL is actually accessible to every client that must download it; a browser session authenticated to GitHub does not mean Clash can authenticate to the same file.

GitHub raw delivery also deserves attention. The URL should point to the raw file rather than the normal HTML page. A typical public address looks like https://raw.githubusercontent.com/example-user/clash-rules/main/ai.yaml. Pinning to a branch such as main is convenient for updates, but it means every commit can change live routing. For a more controlled environment, use a versioned tag or a commit-specific URL and update the profile only after review. Branch-based URLs are suitable for personal experimentation; tagged or pinned revisions are safer for teams, classrooms, and production gateways.

Connect the GitHub provider to a Clash or Mihomo profile

After publishing the YAML file, declare it under rule-providers in the profile that will consume it. A common configuration uses the HTTP provider type:

rule-providers:
  coding-rules:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/example-user/clash-rules/main/coding.yaml
    path: ./ruleset/coding-rules.yaml
    interval: 86400
    proxy: Proxy

  ai-rules:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/example-user/clash-rules/main/ai.yaml
    path: ./ruleset/ai-rules.yaml
    interval: 21600
    proxy: Proxy

The provider key, such as coding-rules, is a local identifier. It does not need to match the filename, but using a descriptive and stable name prevents confusion when several profiles share the same provider. behavior: classical tells Mihomo that the payload contains complete rule lines such as DOMAIN-SUFFIX,github.com. Other behaviors exist for different payload formats, so do not select a mode merely because it appears in a copied example. The behavior must match the actual contents of the remote file.

The path value is the local cache location. It allows the client to retain a previously downloaded provider and continue using it when the remote server is temporarily unavailable. The exact path syntax can vary slightly between clients, so preserve the format generated by Clash Verge Rev, Mihomo, or another client that already manages local profiles correctly. Avoid placing cached provider files in a directory that your operating system routinely cleans up.

interval is measured in seconds. A daily update, represented by 86400, is normally adequate for a stable coding ruleset. AI endpoint inventories may change more often, but an aggressive five-minute refresh is usually unnecessary and can create avoidable traffic or rate-limit problems. Choose an interval based on how quickly a rule change must reach users, not on the assumption that frequent polling automatically improves reliability.

The optional proxy field is important when the raw GitHub address is not reachable directly from your network. It defines how the provider itself is downloaded. This is separate from the rules inside the provider. A provider can route GitHub traffic through Code after it has been downloaded, while the download request uses Proxy to reach GitHub. If you omit this field in an environment where GitHub is inaccessible through DIRECT, the provider may remain stale even though the rest of your proxy is working.

Reference the provider in the main rules section:

rules:
  - RULE-SET,ai-rules,AI
  - RULE-SET,coding-rules,Code
  - RULE-SET,streaming-rules,Streaming
  - GEOIP,LAN,DIRECT
  - MATCH,Proxy

The final argument is the policy group used when a provider rule matches. It must exist under proxy-groups or be a valid built-in target such as DIRECT or REJECT. If your profile calls the group AI Services instead of AI, the reference must use the exact spelling. A correctly downloaded provider with a nonexistent target group can produce confusing behavior because the provider appears healthy while its action cannot be applied as intended.

Control rule order before adding more domains

Clash evaluates rules from top to bottom and normally stops at the first match. This makes order more important than the size of your provider. A beautifully curated GitHub provider will not help if an earlier catch-all rule already sends the same request to DIRECT. Likewise, placing a broad reject or private-network rule too low can allow traffic to reach a general proxy rule before the intended exception is considered.

A dependable ordering model is to move from narrow exceptions to broad classifications:

  • Local and private destinations: keep LAN addresses, router interfaces, company intranet names, and local service discovery on DIRECT when that matches your policy.
  • Explicit exceptions: place domains that must never use a proxy before broader provider rules.
  • Specialized providers: add AI, coding, streaming, gaming, or enterprise rule-sets in an order that reflects business priority.
  • Regional rules: use country or geolocation decisions only after the specialized services have been handled.
  • Final fallback: end with MATCH, normally targeting a general proxy group or DIRECT according to your security policy.

Consider a domain that belongs to both a coding platform and a general technology category. If the coding provider appears first, the request goes to Code. If a broad technology provider appears first, it may go to Proxy instead. Neither result is inherently wrong; the key is that the outcome is intentional and documented. When you need one service to override another provider, add a small local exception above the provider reference rather than editing a third-party ruleset. This preserves the separation between upstream data and your local policy.

Do not confuse a provider update with a profile reload. Depending on the client, clicking an update control may download fresh content without immediately rebuilding every active connection. Existing long-lived connections can continue under their old decision until they close. After changing a critical rule, reload the profile, restart the affected application, or close the relevant connection in the Connections panel. Testing only a browser tab that has kept an HTTP/2 session open for an hour can make a correct rule appear ineffective.

Use different groups for different risk and performance requirements. AI requests may benefit from a low-latency, stable group with predictable outbound regions. Git operations may need reliable long-lived TCP sessions rather than the fastest node selected by a temporary health check. Streaming may require a region-specific group, while ordinary documentation can use a broader pool. A single “best proxy” group is easy to configure but often creates needless contention and makes failures harder to classify.

Test, update, and troubleshoot the complete routing chain

Validation should cover three separate layers: provider retrieval, rule parsing, and traffic matching. Begin with retrieval. Open the raw GitHub URL in a clean browser window or use a command-line request that does not rely on an existing authenticated session. Confirm that the response is the YAML content itself, not a GitHub login page, a repository HTML page, a 404 response, or a rate-limit message. A successful browser display alone is not proof that the Clash process can reach the URL through its configured provider proxy.

Next, inspect the provider status in your client. Clash Verge Rev and other Mihomo interfaces commonly expose the provider’s last update time, file size, and current state. A zero-byte file, an old timestamp, or a persistent download error indicates a retrieval problem rather than a rule-order problem. Check the URL spelling, branch name, filename capitalization, network path, and local cache path. GitHub paths are case-sensitive in ways that may not be obvious on a case-insensitive desktop filesystem.

Then test a hostname that is definitely present in the provider. Search the Mihomo Connections panel for the full domain and inspect the selected rule or rule source. The useful evidence is not merely that the request succeeded. You want to see whether it matched RULE-SET,coding-rules, whether the selected policy group was Code, and whether the connection used the expected node. If the panel shows MATCH, a higher rule captured the request. If it shows DIRECT, look for a preceding domain, GEOIP, or final policy rule.

Test more than one hostname from the same service. GitHub web pages may load from github.com, while clone operations use github.com over SSH or HTTPS, release downloads may use asset domains, and raw file access may use raw.githubusercontent.com. A provider that includes only the visible homepage can leave API calls, images, package archives, or authentication redirects on a different route. Observe actual connections during the failing operation and add only the domains that the workflow genuinely requires.

For command-line tools, remember that Clash routing and application proxy settings are separate layers. A terminal program may connect through the system network stack and be handled by TUN mode, or it may require HTTPS_PROXY and HTTP_PROXY environment variables when TUN is disabled. Conversely, setting an environment proxy can bypass assumptions made by a desktop profile. Test one mode at a time, document which process inherits the variables, and clear stale lowercase or uppercase values when comparing results. A browser working through system proxy does not prove that a package manager, container, or IDE helper process uses the same path.

When a provider works briefly and then stops, check update behavior and cached content before rewriting every rule. A GitHub branch may have received a malformed commit, the raw endpoint may have returned an error page, or a client may have retained a stale cache after a failed refresh. Keep the last known-good revision available, use tags for important deployments, and validate YAML syntax before merging. If a change affects many users, publish it as a small commit with a clear message rather than combining routing changes, formatting changes, and unrelated cleanup in one revision.

Security and privacy also belong in the troubleshooting process. Public repositories are readable by anyone, so never include provider subscription URLs, access tokens, private corporate domains, or personal IP ranges unless you understand the exposure. A raw GitHub URL is not a secret merely because it is inconvenient to remember. For private rules, use an access-controlled delivery mechanism supported by your client, or keep the file local and distribute it through your organization’s approved configuration channel. Finally, route only traffic that your network policy permits. Rule-providers improve control and auditability; they should not be used to bypass workplace restrictions, licensing controls, or service terms.

Compared with single-switch VPN clients, which often provide limited per-domain control and make a routing mistake difficult to explain, Clash gives you observable Connections, reusable policy groups, ordered rules, cached providers, and a Git-based review trail. Compared with manually editing one large YAML file on every device, GitHub-hosted providers make specialized AI, coding, streaming, and enterprise policies easier to update consistently. If you want that workflow on your own systems, choose the Clash client for your platform and begin with a small, reviewable provider rather than importing an opaque mega-list.

Download Clash →