Advanced Clash Rule-Providers: GitHub YAML Setup Guide

Why Use Custom Clash Rule-Providers?

Clash rule-providers let you move a large, reusable set of routing rules out of the main configuration file. Instead of placing hundreds or thousands of DOMAIN, DOMAIN-SUFFIX, IP-CIDR, and PROCESS-NAME entries directly under rules, you publish those rules as separate YAML files and let Clash download them on a schedule. The main profile stays readable, while application-specific routing can evolve independently.

This approach is especially useful when your configuration serves more than one purpose. You may want one provider for developer tools, another for streaming services, another for artificial intelligence websites, and a fourth for local services that should always use DIRECT. Each provider can be reviewed, tested, and reused without rewriting the whole profile. When a domain changes, you update one file in GitHub rather than editing every client manually.

A GitHub repository also gives your rules a practical maintenance workflow. Commits provide a change history, pull requests make review possible, and a raw file URL gives Clash a predictable endpoint. You can test a change in a branch, merge it after checking the syntax, and allow clients to fetch the updated provider at their next interval. This is much safer than copying rule snippets from chat messages or maintaining several slightly different local files.

Rule-providers are not a replacement for correct rule ordering. They are only a way to package rules. Clash still evaluates the final rules list from top to bottom, and the first matching rule wins. A perfectly written provider can appear ineffective if a broader rule is evaluated before its RULE-SET reference. Understanding that separation between provider content and rule order is the foundation for reliable advanced configuration.

Design a Maintainable GitHub Rule Project

Before writing YAML, decide how the repository will be organized. A small project can use one repository with a simple directory structure. For example, keep files under providers/, place documentation in README.md, and reserve a separate directory for test fixtures. Clear names are more valuable than clever names because they appear in client logs and configuration files.

Use filenames that describe intent rather than a temporary event. A file called new-sites.yaml becomes confusing after several months, while ai-services.yaml continues to communicate its purpose. Keep category boundaries clear. If one provider contains unrelated rules for gaming, work tools, and local government services, future debugging becomes difficult because a change for one group can unexpectedly affect another.

Choose a publication strategy before connecting the repository to your clients. A raw GitHub URL that points to the default branch is convenient, but it changes whenever that branch changes. A tagged release or a dedicated stable branch provides more predictable updates. For a personal configuration, a default-branch URL may be acceptable if you review every commit. For a team or a shared configuration, consider using pull requests and a release process so that untested changes do not reach every device immediately.

GitHub is not the only possible host, but it is convenient because raw files are easy to publish and inspect. Make sure the final URL returns the file itself rather than an HTML page. A browser view at github.com is designed for humans; Clash needs a raw URL such as raw.githubusercontent.com. If the downloaded response begins with HTML, a YAML parser will usually report an unhelpful error near the first character.

Write a Valid and Reusable Provider YAML

A rule-provider file normally contains a payload list. Each item is a Clash rule expression, and the provider type determines how the client interprets it. The most portable starting point is a classical provider containing complete rules such as DOMAIN-SUFFIX or DOMAIN-KEYWORD. Keep the file focused and avoid adding a catch-all rule such as MATCH inside a provider, because a catch-all entry can hide later rules when the provider is referenced.

payload:
  - DOMAIN-SUFFIX,openai.com
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-KEYWORD,copilot
  - DOMAIN,api.example.dev

For domain-oriented collections, a domain provider can be more compact. The exact supported format depends on the Clash-compatible core and client version, so check the documentation for the implementation you use. Mihomo-based clients generally support several provider behaviors, while older clients may accept a smaller subset. If compatibility matters, use a classical provider with explicit rule types and test it on every target client.

When the provider contains IP networks, add the appropriate options in the main profile. For private or regional ranges, IP-CIDR rules commonly need no-resolve when you do not want Clash to perform a DNS lookup for an IP literal. IPv6 ranges use IP-CIDR6. Do not assume that a domain rule and an IP rule are interchangeable: an application may resolve a hostname before Clash sees the connection, and a direct IP connection may never match a domain-only provider.

payload:
  - DOMAIN-SUFFIX,internal.example
  - IP-CIDR,10.0.0.0/8,no-resolve
  - IP-CIDR,192.168.0.0/16,no-resolve
  - IP-CIDR6,fd00::/8,no-resolve

Keep formatting conservative. Use spaces rather than tabs, quote a value only when YAML requires it, and do not add a document header unless your client accepts it. A trailing comma, an accidental colon inside an unquoted value, or inconsistent indentation can make the entire provider unavailable. YAML is whitespace-sensitive, so the difference between a list item beginning with - and a plain indented string is meaningful.

Each rule should answer one routing question. Prefer DOMAIN-SUFFIX,example.com when all subdomains should share a policy. Use DOMAIN,api.example.com for one exact hostname. Use DOMAIN-KEYWORD sparingly because it can match more hosts than expected. A keyword such as cloud may affect unrelated services, so an explicit suffix is usually easier to audit. If a provider grows too broad, split it into smaller files instead of compensating with an increasingly complicated exception list.

Connect the GitHub Provider to Clash

After publishing the file, declare it under rule-providers in the main Clash configuration. The provider name is a local identifier; it does not have to match the filename, but using the same readable name reduces mistakes. The behavior value must match the content format, and format should match the file type. The interval controls how often the client checks for an updated copy.

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

  direct-local:
    type: http
    behavior: classical
    format: yaml
    url: https://raw.githubusercontent.com/example-user/clash-rules/main/providers/direct-local.yaml
    path: ./ruleset/direct-local.yaml
    interval: 86400

The path value is the local cache location. It is useful because the client can continue using the last successfully downloaded provider when the remote server is temporarily unavailable. Choose a simple relative path and avoid two providers writing to the same file. Some clients create the directory automatically, while others expect the parent directory to exist; if the provider fails immediately, inspect the client documentation and logs for path-related errors.

Reference the providers in the main rules list with RULE-SET. The policy name at the end must match an existing proxy group, such as Proxy, DIRECT, or a group you created yourself. The final MATCH rule should normally remain at the bottom, because it is the fallback for traffic that matched nothing earlier.

rules:
  - RULE-SET,direct-local,DIRECT
  - RULE-SET,ai-services,Proxy
  - DOMAIN-SUFFIX,example-work.com,Work
  - GEOIP,LAN,DIRECT
  - MATCH,Proxy

Order the references from the most specific policy to the broadest policy. If GEOIP,LAN,DIRECT appears before an application-specific IP provider, the LAN rule may win before the provider gets a chance to classify the connection. Likewise, placing MATCH,DIRECT above every provider makes all later entries unreachable. When two providers overlap, decide which category has priority and place that RULE-SET first.

Do not confuse a proxy group name with a provider name. The provider stores matching rules; the group chooses an outbound node or policy. Renaming a group from Proxy to Auto requires updating the third field of every affected RULE-SET. Renaming the provider identifier requires updating the first field. Keeping a small naming convention, such as lowercase kebab-case for providers and title case for groups, makes these two roles visually distinct.

Test Updates Without Losing Control

Changing a provider is not complete when GitHub accepts the commit. First confirm that the raw URL returns the new content. Then open the Clash client’s providers or rule-provider panel and run a manual update. A successful download does not necessarily mean successful matching: the YAML can be valid while a domain is written with the wrong suffix, placed in the wrong provider, or intercepted by an earlier rule.

Use a small test matrix for every important provider. Include an exact domain, a subdomain, a domain that should not match, and one unrelated local service. Record the expected policy before testing. For example, an AI provider test may include api.example.ai, console.example.ai, example.ai.evil.test, and a local intranet hostname. This catches accidental keyword matches and verifies that suffix rules do not overreach.

1. Commit the change on a branch or open a pull request.
2. Inspect the raw response and confirm that it contains YAML rather than an HTML error page.
3. Update the provider manually in Clash and check its last-updated status.
4. Open the connection or log view and note the matched rule, provider name, and selected policy.
5. Test a negative case to ensure unrelated traffic still follows the intended route.
6. Merge the change only after the positive and negative cases behave correctly.

Version control is most useful when commits explain intent. A message such as “add three domains” is less helpful than “route package registry API through Proxy because direct TLS fails.” In the README, document the provider URL, behavior, update interval, expected policy, and any known exceptions. If a domain is temporary, include a review date so that obsolete entries do not remain forever.

Be thoughtful with update intervals. A very short interval creates unnecessary requests and can make failures look more frequent, while a very long interval delays important changes. Daily updates are reasonable for most personal domain lists. Rules that change rarely can refresh weekly. Remember that clients may apply their own limits or update only when running, so an interval is a preference rather than a guarantee.

Troubleshoot Download and Matching Failures

A provider that shows as unavailable usually has a transport, URL, syntax, or permission problem. Start with the raw URL outside Clash. If it cannot be opened in a browser or fetched with a command-line tool, fix the hosting or network problem first. If it returns a GitHub 404 page, check the repository owner, branch name, directory path, and filename. If it returns a rate-limit message, consider a different host or a controlled mirror rather than repeatedly forcing updates.

If the download succeeds but parsing fails, compare the declared behavior with the actual file. A classical provider should contain complete rules such as DOMAIN-SUFFIX,example.com. A domain provider expects domain entries in the format supported by the core. Also check indentation, file encoding, and whether an editor inserted invisible characters. Removing the local cached file and downloading it again can help distinguish a stale cache from a malformed remote file.

If the provider loads but traffic still uses the wrong policy, inspect rule order before changing DNS or proxy nodes. The log should show which rule matched. A result such as MATCH usually means the provider did not match or its reference was never reached. A result such as an unexpected earlier DOMAIN-SUFFIX or GEOIP rule means the provider may be working correctly but losing the ordering decision.

• Raw URL returns HTML: replace the normal GitHub page URL with a raw-content URL.
• 404 response: verify the repository, branch, directory, and filename character by character.
• Provider parses but has no effect: check behavior, RULE-SET, and rule order.
• Only subdomains fail: use DOMAIN-SUFFIX instead of an exact DOMAIN entry when appropriate.
• Unexpected domains match: replace broad DOMAIN-KEYWORD rules with explicit suffixes.
• Old behavior remains: manually refresh the provider and inspect the local cache timestamp.
• One client works while another fails: compare core versions and supported provider behaviors.

Do not solve every mismatch by adding an exception at the top of the rules list. Exceptions are sometimes necessary, but too many make the policy impossible to reason about. First identify whether the domain is genuinely misclassified, whether the application uses a different hostname, or whether DNS and IP rules are taking precedence. A connection log, a DNS lookup, and a simple test from the affected application usually provide more evidence than repeated YAML edits.

Some applications use multiple endpoints, content delivery networks, or dynamically generated hostnames. In that case, a single domain may not describe the complete traffic pattern. Capture the relevant hostnames from the client connection view, group them by service, and add only the domains you can justify. Avoid copying an enormous third-party list into your project without understanding its scope; large lists increase update time, memory use, and the chance of unrelated routing changes.

A Reliable Workflow for Long-Term Use

A robust custom rule-provider setup has four layers: a readable repository, valid provider files, explicit declarations in the Clash profile, and observable tests. GitHub handles history and publication, but it does not decide whether a rule is correct. Clash handles downloading and matching, but it cannot explain an unclear policy design. Your workflow should connect both sides with documentation and repeatable checks.

Start with one small provider and a handful of domains. Confirm that the raw file downloads, the provider status becomes healthy, and the connection log displays the expected RULE-SET. Only then divide the list into categories. This incremental approach avoids the common failure where a large imported ruleset contains several unrelated syntax and ordering problems that are difficult to isolate.

For shared projects, protect the default branch and require review for provider changes. Consider adding a lightweight validation step that parses YAML and rejects empty payloads or malformed rule lines. Even without automated CI, a documented checklist prevents many regressions. Keep a rollback commit available, especially before changing rules used by several devices or by a router serving an entire household.

Remember that rule-providers affect routing decisions, not the quality of the selected proxy node. If a provider matches correctly but the destination remains slow, inspect the proxy group, latency, DNS mode, and transport protocol separately. Separating classification from connectivity keeps troubleshooting focused: first ask “Which rule matched?” and then ask “Can the selected outbound reach the destination?”

Many alternative proxy tools offer quick list imports, but they often hide rule precedence, cache locations, or update failures behind a simplified interface. That convenience can become a problem when you need versioned GitHub YAML, reproducible routing, or application-level exceptions. Clash exposes the provider declaration, matching order, cached files, and connection decisions in a way that is easier to audit and automate. If you want reusable rules that remain understandable as your setup grows, Download Clash for free and manage your providers with a workflow you can inspect, test, and roll back.