Why Use Custom Rule Providers?
As a Clash configuration grows, the rules: section often becomes the least manageable part of the file. A few services can quickly turn into hundreds of domain, keyword, and IP rules. AI platforms add several changing domains, while developer tools may rely on APIs, package registries, authentication services, container registries, and content delivery networks. Keeping every rule in one oversized YAML file makes routine maintenance slower and increases the risk of breaking an otherwise working profile.
Custom rule providers solve this problem by moving related rules into separate YAML files. Your main configuration only defines where those files are stored, how they should be downloaded, and which policy group should receive matching traffic. You can therefore maintain one provider for AI services, another for developer platforms, and a third for local or private domains without mixing unrelated routing logic.
This guide uses a Mihomo-compatible configuration, which is supported by current clients such as Clash Verge Rev and other clients built around the Mihomo core. The same design principles apply to Clash Verge and mobile clients when their selected core supports external rule providers. The goal is not to proxy everything. Instead, it is to create a predictable routing system in which specific traffic is matched early, assigned to an intentional policy group, and updated independently from the rest of your profile.
Target Architecture
A small main configuration, separate YAML providers for different services, explicit rule precedence, and a repeatable update process that is easy to test and roll back.
1Designing a Modular Provider System
A rule provider is a named collection of rules. The provider can be hosted remotely over HTTPS or stored locally as a file. The main profile references the provider by name, and the RULE-SET rule connects it to a policy group such as AI, Developer, Proxy, or DIRECT.
Before writing YAML, decide how traffic should be divided. A useful first version has three layers: service-specific providers, broad fallback rules, and a final catch-all rule. For example, AI domains may use an AI-optimized group, developer services may use a stable work group, and ordinary local websites may go directly through the local connection.
Choosing Provider Boundaries
Do not create one provider for every individual domain. That produces unnecessary files and makes debugging harder. A provider should represent a meaningful routing decision. Good boundaries include:
- AI services: ChatGPT, OpenAI APIs, Claude, Gemini, and related authentication or model endpoints that need a consistent proxy policy.
- Developer services: GitHub, GitLab, npm, PyPI, Docker Hub, language registries, and documentation platforms.
- Local or private services: company domains, intranet records, home laboratory hosts, and internal IP ranges that should never leave the local network.
- Block lists: advertising, telemetry, or tracking domains routed to
REJECT, provided that the list is maintained carefully.
Start with service names that you can verify. A short, accurate provider is more valuable than a huge list copied from an unknown source. Overly broad keyword rules such as DOMAIN-KEYWORD,cloud,PROXY may unexpectedly capture unrelated services, so prefer DOMAIN-SUFFIX whenever the service has a stable domain suffix.
Writing the Provider Files
For a plain domain provider, use the domain behavior and place one rule on each line. The file must contain valid YAML, including the top-level payload: key. The following example is suitable for an AI provider stored in a public Git repository:
The provider contains match conditions only; it does not contain the final policy name. This separation lets you reuse the same service list with different groups on different devices. A work laptop might send the provider to an enterprise proxy, while a home profile could send it to a manually selected group.
A developer provider can be organized in the same way:
Pro Tip: Keep Providers Reviewable
Use one rule per line, avoid compressed or generated formats during initial development, and add a short comment above each logical group when your provider becomes large. Readability makes accidental routing changes much easier to detect.
2Connecting Providers to the Main YAML
The main configuration has two important sections: rule-providers defines the provider and rules decides when it is evaluated. The provider definition controls the download URL, file format, refresh behavior, and cache behavior.
Defining Remote Providers
Here is a practical remote-provider setup. Replace the example URLs with repositories that you control or trust. The format: yaml and type: http fields tell Mihomo how to retrieve and parse the file. The interval value is measured in seconds, so 86400 means once every 24 hours.
The path is a local cache path relative to the profile or working directory used by the client. Caching is important because the profile can continue using the last successful provider when the remote host is temporarily unavailable. The optional proxy field determines how the provider itself is downloaded. If your repository is inaccessible through the direct connection, a dedicated policy group can fetch it through a proxy.
Be careful with the provider download policy. If RuleProviders is itself a group that depends on a rule matching the provider URL, you can create a circular dependency. A simple group containing stable nodes is usually safer. If the repository is reliably reachable without a proxy, omit the proxy field or use DIRECT according to your environment.
Using Local Providers for Private Rules
Local providers are useful for rules that should not be hosted publicly. They are also convenient while testing a new service list. A local provider normally uses type: file and points to a file next to the profile:
Its file can contain complete classical rules, including the final policy:
Use behavior: classical when the provider contains complete Clash rules. Use behavior: domain when it contains domain match entries that will be paired with a RULE-SET action in the main configuration. Mixing these two models without understanding the difference can cause parsing errors or rules that never match.
Controlling Rule Precedence
Clash evaluates the rules: list from top to bottom. The first matching rule wins. This is the most important detail in a provider-based design. A correct provider placed below a broad rule may appear broken even though its YAML is valid.
Put private and security-sensitive exceptions first, followed by specific service providers. Broad country rules, keyword rules, and catch-all rules should come later. The final MATCH rule is a safety net; without it, unmatched traffic may not follow the policy you expect.
Common Precedence Mistake
Placing GEOIP,CN,DIRECT or a broad DOMAIN-SUFFIX,google.com,DIRECT rule before the AI provider can send a service to the wrong policy. Move specific providers above broad geographic or vendor rules.
3Automating Updates and Verifying Matches
A modular configuration only stays useful if its providers are maintained. Treat rule files as small software projects: keep them in version control, review changes, and test before publishing. Git makes it possible to see exactly which domain was added or removed and to restore a previous version when a provider causes an outage.
A Safe Git Workflow
Create a repository with a clear directory structure, for example:
Make changes on a branch instead of editing the default file directly. In the commit message, describe the routing reason rather than simply writing “update rules.” For example, “Add API endpoint required by model uploads” gives you useful context later. Before merging, check that every line uses a supported rule type, that indentation is consistent, and that no private hostname or token was accidentally committed.
Use a raw HTTPS URL for the published file and keep the repository history available. If a new domain causes a failure, you can temporarily pin the provider to an earlier commit or revert the latest change. Avoid URL shorteners and unreviewed third-party lists because a provider is executable routing logic: whoever controls the file can change where your traffic goes.
Updating Providers in Clash Clients
After saving the main profile, open the profile or rule-provider management panel in your client and trigger an update. Clash Verge Rev commonly exposes provider updates near the active profile, while other Mihomo clients may place them under rules, resources, or subscriptions. The exact label differs between clients, but the diagnostic goal is the same: confirm that the provider was downloaded, parsed, and loaded.
- Save a backup of the working profile before changing provider definitions.
- Validate the YAML indentation and ensure the URL returns the expected file rather than an HTML error page.
- Update the provider manually once and inspect its status, timestamp, and rule count.
- Open the connection or rules log and visit a domain that should match the provider.
- Confirm that the selected policy group and actual node are the ones you intended.
- Only after successful testing should you rely on the automatic refresh interval.
Diagnosing Unmatched or Incorrectly Proxied Domains
When traffic is not routed correctly, begin with the exact hostname shown in the client log. A browser may contact several related domains, so testing only the visible website address is not enough. Check whether the failing request is an API endpoint, an image host, an authentication host, or a content delivery domain.
- No provider match: The hostname may not be listed, the provider may not have updated, or the request may use an IP address instead of a domain.
- Wrong provider match: A broad suffix or keyword rule may capture the request before the intended provider is reached.
- Provider shows zero rules: The remote URL may require authentication, return a 404 page, or use a format that does not match the declared behavior.
- Correct rule, failed connection: The policy group may contain unavailable nodes, the selected node may be blocked, or UDP support may be required.
- Different result between browsers: DNS cache, QUIC, IPv6, or an application-specific proxy setting may be bypassing the path you are testing.
For a temporary test, add a precise rule above the provider or use the client’s rule editor if available. Do not permanently solve every problem with a broad keyword rule. Once the exact hostname is known, add the narrowest reliable entry to the appropriate provider and remove the temporary override.
Testing Principle
Change one variable at a time. First verify provider loading, then rule order, then policy-group availability, and finally DNS or protocol behavior. Changing all four at once makes the original fault difficult to identify.
4Frequently Asked Questions
Do all Clash clients support custom rule providers?
Support depends on the core rather than the visual interface. Mihomo-based clients generally provide broad support for HTTP and file rule providers, while older Clash cores may lack newer fields or behaviors. Check the active core version in the client before copying a configuration. If a provider fails to load, first confirm whether the client is using Mihomo, not only whether the application is branded as Clash.
Should I use domain or classical behavior?
Use domain when the file is a reusable list of domain match entries and the main profile supplies the policy through RULE-SET. Use classical when each line already contains a complete rule such as DOMAIN-SUFFIX,example.com,Proxy or IP-CIDR,203.0.113.0/24,DIRECT. Domain behavior is usually easier to reuse; classical behavior is more expressive for mixed domain, IP, port, and process rules.
How often should a provider refresh?
For a personal provider that changes occasionally, 86400 seconds is a sensible starting point. Very frequent refreshes create unnecessary requests and may make a repository appear abusive. If a provider is updated several times each day, use a shorter interval only when there is a clear operational reason. Remember that the interval controls checking for updates; it does not guarantee that a remote server is available.
Are remote rule providers safe?
They are safe only when you trust and review the source. A provider can redirect traffic to a proxy, reject connections, or override routing assumptions. Prefer repositories with transparent history, HTTPS hosting, clear ownership, and documented changes. Never place passwords, subscription tokens, private hostnames, or sensitive company rules in a public provider. For confidential entries, use a local provider or a private repository with access control.
Custom rule providers are most effective when they remain focused, explicit, and observable. Separate AI and developer traffic into meaningful files, put specific RULE-SET entries before broad fallbacks, update providers through a controlled Git workflow, and use logs to verify the exact hostname being matched. This approach keeps your main Clash YAML readable while giving you the flexibility to adapt routing as services and endpoints change.