Clash Rule-Providers: Advanced GitHub YAML Setup Guide

What Rule-Providers Solve in Clash

Clash rule-providers are a way to move frequently changing routing rules out of your main profile. Instead of placing hundreds or thousands of DOMAIN, DOMAIN-SUFFIX, IP-CIDR, and PROCESS-NAME entries directly under rules, you store those entries in separate files and reference them by name. The main YAML file then describes the policy structure, while each provider owns one focused ruleset.

This separation is especially useful when you maintain a profile for several devices, publish custom rules for a development team, or use GitHub as a versioned source for DNS, advertising, streaming, and private-service policies. A small change to a GitHub YAML file can be downloaded by Clash on its next provider update without requiring you to edit or replace the complete subscription profile.

A provider does not automatically make a rule active. It has two parts: a provider definition, which tells Clash where and how to fetch the file, and a rule reference, which inserts that provider into the ordered rule list. If either part is missing, the file may download successfully while none of its rules affect traffic.

Rule-providers are not the same as proxy providers. A proxy provider returns nodes and proxy groups, while a rule-provider returns matching rules. Both can have an update interval, but they serve different sections of the configuration. Confusing the two is a common reason for invalid YAML or an apparently empty provider list.

Choose a Compatible Provider Format

Before creating a GitHub file, identify the core used by your client. Clash Verge Rev and Mihomo-based clients generally support modern provider options, but exact fields can differ between Mihomo, older Clash Meta builds, and legacy Clash clients. A configuration that works in one client may fail if it uses a provider format the installed core does not understand.

The safest starting point is a plain YAML provider with a payload list. This format is readable, easy to validate, and suitable for small or medium custom rulesets. A provider file should contain rules only, not a complete Clash profile. Do not paste mixed-port, proxies, proxy-groups, or another top-level profile section into a rule-provider file.

Use DOMAIN-SUFFIX carefully. A suffix such as example.com can match the root domain and many subdomains, which is normally convenient. It can also match services you did not intend to proxy. When the rule is for a single endpoint, use DOMAIN instead. For CIDR rules, add no-resolve when you already know the address range and do not want Clash to perform an extra DNS lookup.

Keep each provider narrow. For example, use separate files for development services, regional direct rules, advertising domains, and private infrastructure. A single “everything” file becomes difficult to audit, and a broad provider can accidentally override a more precise rule later in the chain.

Create and Publish a GitHub YAML Provider

Start with a repository that is either public or reachable by the environment where Clash runs. Public repositories are the simplest option because the client can fetch a raw HTTPS URL without authentication. Create a directory such as rules/ and give each provider a descriptive filename. Names like developer-proxy.yaml or local-services.yaml are easier to understand than generic names such as rules1.yaml.

A minimal provider file can look like this:

payload:
  - DOMAIN,registry.npmjs.org
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN,packages.example.com

Commit the file to a branch that you intend to keep stable. For personal use, the default branch is usually adequate. For a team or a production-like environment, consider publishing from a release branch or pinning a known commit. A moving branch is convenient for automatic updates, while a commit-specific URL gives reproducibility and prevents an unexpected change from entering every client at once.

On the GitHub file page, use the Raw button and copy the resulting HTTPS address. It should point to the raw content rather than the normal HTML file view. A typical URL has this shape:

https://raw.githubusercontent.com/your-account/your-repository/main/rules/developer-proxy.yaml

Test that URL in a browser or with a command-line HTTP client. The response should contain the YAML text directly. If you see a GitHub webpage, a login screen, a 404 response, or an HTML error document, Clash will not be able to parse it as a rule-provider.

GitHub is useful for version control, but it is not an unlimited configuration delivery service. Raw content can be unavailable because of network filtering, rate limits, repository changes, or transient CDN behavior. If the provider is important, keep a local backup and consider a reliable mirror that you control. Never place subscription tokens, private API keys, or credentials in a public repository.

Add the Provider Definition to Clash

After publishing the file, add a provider entry under rule-providers in the main Clash profile. The key is the local name that you will later use in the rule list. The type should normally be http for a remote GitHub file, and behavior should describe the returned content.

rule-providers:
  developer-proxy:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/your-account/your-repository/main/rules/developer-proxy.yaml
    path: ./providers/developer-proxy.yaml
    interval: 86400
    proxy: DIRECT

Here, behavior: classical tells the core that the payload contains complete rule lines such as DOMAIN or IP-CIDR. Some large community providers use behavior: domain or behavior: ipcidr with a different payload format. The behavior must match the provider file; it is not a label that can be selected arbitrarily.

The path is the local cache location. A relative path is portable across desktop clients, but the exact storage behavior varies by fork. Avoid using an absolute Windows or macOS path unless the profile is intentionally tied to one machine. The interval is measured in seconds, so 86400 means approximately one day. A shorter interval does not guarantee fresher content if an upstream CDN or GitHub cache has not changed.

The optional proxy field controls how Clash fetches the provider. Use DIRECT when GitHub is reachable from the local network. If GitHub is inaccessible without a tunnel, you may route the update request through a suitable proxy policy available in your client. Test this carefully: a provider that depends on itself can create a startup or update loop.

Once the definition is present, reference it under rules:

rules:
  - RULE-SET,developer-proxy,PROXY
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - GEOIP,PRIVATE,DIRECT
  - MATCH,PROXY

Rule order is decisive. Clash evaluates rules from top to bottom and stops at the first match. Put a custom provider above broad rules such as GEOIP or MATCH. If a private domain should bypass the provider, place its direct exception before the provider reference. If you put the provider after MATCH,DIRECT, it will never be reached.

Update, Validate, and Debug the Provider

After saving the profile, open the client’s providers or rule-providers panel and run a manual update. Do not rely only on the profile’s successful reload message. A profile can parse correctly while a remote provider remains unavailable. Look for the provider’s last update time, download status, rule count, and error message.

When a provider does not update, troubleshoot in layers. First open the raw GitHub URL from the same device. Next check whether the response is actually YAML and whether the server returns a successful HTTP status. Then check Clash logs for TLS, DNS, timeout, redirect, or permission errors. Finally inspect the cached file path and reload the provider after correcting the source.

• 404 or empty response: verify the account, repository, branch, directory, and filename. GitHub paths are case-sensitive.
• YAML parse error: inspect indentation, commas, unexpected tabs, and invisible characters. A rule line should be plain text under payload.
• Provider loads but matches nothing: confirm the behavior, the RULE-SET name, and the exact rule order.
• Rules match the wrong traffic: narrow broad suffixes and place exceptions above the provider reference.
• Updates fail only on one network: test DNS, TLS interception, GitHub reachability, and the provider fetch policy.

Use the client’s connection log to verify behavior with real requests. A domain appearing in the provider file does not prove that the application sends that hostname to Clash. Some applications connect directly to hard-coded IP addresses, use their own DNS-over-HTTPS implementation, or open connections through a separate helper process. In those cases, a domain rule may not be enough; TUN mode, process rules, IP rules, or application-specific settings may be required.

For IP providers, pay attention to DNS resolution. A domain may resolve to an address that changes frequently, while a stale IP-CIDR provider can send traffic to the wrong policy. Refresh schedules should reflect how quickly the source changes, but excessive updates create unnecessary requests and make failures harder to diagnose. A daily schedule is a sensible starting point for most personal providers.

When editing a provider, change one logical group at a time. Commit a clear message such as “Add package registry domains” rather than replacing the file without explanation. If a new commit causes routing problems, revert it in GitHub, manually update the provider, and confirm that the previous behavior returns. This is much safer than repeatedly editing the main subscription profile and losing track of which change caused the failure.

Maintain a Reusable GitHub Ruleset

A maintainable provider has a clear scope, predictable ownership, and a documented update process. Add a short README beside the YAML file explaining its purpose, expected behavior, update frequency, and the policy name that should consume it. This matters when you return to the configuration months later or share it with another device.

Use naming conventions consistently. For example, reserve direct- for traffic that should bypass the proxy, proxy- for traffic that should use a proxy group, and block- for rejected traffic. Keep provider keys stable even if the GitHub filename changes; the key is referenced by the main YAML profile and changing it creates an unnecessary second edit.

Separate sensitive and general-purpose rules. A public repository may contain common service domains, but private company hostnames, internal address ranges, and customer-specific routing should remain in a private repository or a local provider. Even when a domain seems harmless, its name can reveal infrastructure, project names, or business relationships.

Remember that rule-providers improve organization, not security by themselves. GitHub HTTPS protects transport between the client and the repository, but it does not make an untrusted ruleset safe. Review third-party lists, pin sources when reproducibility matters, and keep a fallback profile that does not depend on a single external provider. If a provider disappears, Clash should still have a usable final rule such as MATCH,DIRECT or MATCH,PROXY according to your intended policy.

Compared with clients that require every custom rule to be pasted into one large profile, Clash offers a cleaner workflow: GitHub provides history and rollback, rule-providers provide modular updates, and Clash Verge Rev or Mihomo can inspect provider status without rebuilding the entire YAML file. Some competing tools hide remote rules behind proprietary dashboards or make per-device updates difficult to audit, while this setup keeps the source, policy reference, and update schedule visible. If you want that practical balance of reusable routing and transparent configuration, Download Clash and start with a small provider before expanding your ruleset.