Configuration September 3, 2026

Clash Rule-Providers: Advanced YAML Ruleset Setup With GitHub

Learn how to design, host, and update custom Clash rulesets with rule-providers. The guide covers YAML structure, matching order, GitHub version control, and production-ready routing patterns for AI platforms and developer tools.

Docker Proxy GitHub Acceleration Advanced Config YAML

1. What rule-providers solve in a serious Clash profile

A small Clash configuration can keep every rule in one rules: list, but that approach becomes difficult to maintain once you route AI platforms, developer tools, cloud services, streaming sites, and internal domains at the same time. A long inline list mixes business decisions with data that changes frequently. It also makes review harder: one pull request may change a routing policy, add hundreds of hostnames, and reorder unrelated rules in the same file.

Rule-providers separate the rule data from the main Mihomo or Clash configuration. Your primary profile defines how a ruleset is fetched, what format it uses, how often it is refreshed, and which policy group receives a match. The provider file then contains only routing entries such as domains, IP ranges, or classical Clash rules. This separation is useful for both personal profiles and teams that manage configuration in GitHub.

A provider is not a proxy subscription and it is not a magic hostname database. It is a remotely available rules file that Clash downloads and parses locally. The final routing decision still depends on four things: whether the provider loaded successfully, whether the rule syntax is valid, where the RULE-SET line appears in the global rule order, and whether the selected proxy group is usable. Treating these as separate layers makes troubleshooting considerably faster.

A reliable ruleset should be small enough to review, specific enough to avoid collateral routing, and boring enough that a failed update does not stop ordinary traffic.

This guide targets Clash Verge Rev and other Mihomo-compatible clients, including profiles edited manually or generated by a subscription converter. Field names can vary slightly between legacy Clash builds and current Mihomo releases, so validate the syntax against the core bundled with your client. The examples use YAML and assume that you already have a working proxy group named AI, a developer-oriented group named Developer, and a normal fallback group named Proxy.

2. Design provider boundaries before writing YAML

The first design decision is not the GitHub repository or the refresh interval. It is the boundary of each provider. A useful provider represents one understandable routing intention. For example, an ai-platforms provider can contain model APIs and AI web applications, while a separate developer-tools provider can contain package registries, source-control services, container registries, and documentation platforms. Keeping those concerns separate lets you send them to different groups and review changes without guessing why an unrelated domain was added.

Avoid creating a provider called foreign-sites or all-proxy unless you have a very specific operational reason. Broad names encourage broad rules, and broad rules are difficult to audit. A domain that is currently used by an AI application may later serve account login, analytics, downloads, or a completely different Google or Microsoft product. A narrow provider makes that ambiguity visible.

Provider type Typical content Best behavior Common risk
AI services Model APIs, AI consoles, streaming endpoints domain or classical Missing authentication or upload hosts
Developer tools Git hosting, registries, package downloads domain or classical Routing internal mirrors through a relay
Private networks Office CIDRs, VPN ranges, lab networks ipcidr Overlapping ranges and incorrect gateways
Exceptions Domains that must remain direct domain or classical Placing the exception below a catch-all rule

Use the narrowest rule type that expresses the requirement. A domain provider normally contains entries such as DOMAIN,api.example.com or DOMAIN-SUFFIX,example.com. An ipcidr provider is appropriate for actual network ranges, not for hostnames. A classical provider supports the familiar full rule syntax and is useful when one file must combine domain, IP, port, or process-related rules.

The difference between DOMAIN and DOMAIN-SUFFIX deserves deliberate attention. DOMAIN,api.example.com matches that exact hostname, while DOMAIN-SUFFIX,example.com also matches subdomains beneath it. A suffix rule is convenient for a service family, but it may capture unrelated services such as status pages, login systems, or regional endpoints. Start with exact hostnames observed in logs, then widen to a suffix only when the service architecture justifies it.

3. Write valid YAML and host it safely on GitHub

A practical repository can contain one directory for providers, a short README, and an optional validation workflow. Keep provider filenames stable because the local path in your Clash configuration becomes part of your operational interface. Do not rename ai-platforms.yaml casually if several machines share the same profile or if scripts expect that path.

The following is a minimal domain provider. The behavior value describes the contents of the file; it does not select a proxy group. The interval is measured in seconds, and the local path is where Mihomo stores the downloaded copy.

rule-providers:
  ai-platforms:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/ai-platforms.yaml
    url: https://raw.githubusercontent.com/example-org/clash-rules/main/providers/ai-platforms.yaml
    interval: 86400
    proxy: Proxy

rules:
  - RULE-SET,ai-platforms,AI
  - MATCH,Proxy

The provider file itself can be written in the compact format below:

payload:
  - DOMAIN,api.openai.com
  - DOMAIN,platform.openai.com
  - DOMAIN-SUFFIX,anthropic.com
  - DOMAIN-SUFFIX,ai.google.dev

Some cores and rule collections use a plain list or a provider-specific format. Do not assume that every file named “YAML rules” has the same schema. The combination of behavior and format must match the actual file. If you publish a classical provider, for example, declare it explicitly and retain complete rule lines:

payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN,registry.npmjs.org
  - IP-CIDR,192.168.50.0/24,DIRECT,no-resolve

GitHub hosting introduces a few operational details. A raw URL must point to the exact branch, path, and filename. A repository page URL is not a provider URL; Clash needs the raw file response rather than an HTML document. Public repositories are convenient, but remember that anyone who can alter the file can influence the traffic destinations of every client using it. Protect the default branch, require review for changes, and restrict who can publish releases or modify workflow files.

If the repository is private, a normal raw GitHub URL may return an authentication page instead of the provider body. Avoid placing long-lived personal access tokens directly in a profile, because subscription files are frequently shared, backed up, or exposed in screenshots. For sensitive rules, use an authenticated distribution layer designed for machine access, or keep the provider local. A public ruleset should contain routing metadata only, never API keys, cookies, internal hostnames, or confidential network ranges.

Use predictable formatting. Quote values that contain characters YAML may interpret unexpectedly, keep indentation consistent, and avoid tabs. A malformed provider may not break the main profile syntax, yet it can silently fail to load. In production, a repository check should parse every provider and report duplicate entries, invalid CIDRs, unsupported rule types, and accidental empty files before a commit is merged.

4. Connect providers and control matching order

Loading a provider is only half of the configuration. The provider becomes active when a global rule references it with RULE-SET,name,policy. The rules are evaluated from top to bottom, and the first matching rule normally wins. This is why order matters more than the apparent completeness of a provider.

Place local and security-sensitive exceptions before broad service providers. Then place narrowly targeted providers, followed by regional or category rules, and leave GEOIP or MATCH near the end. A common mistake is to put GEOIP,CN,DIRECT above an AI provider. If the destination resolves to an address classified as local, the request may exit directly before the AI ruleset is ever considered.

rules:
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - RULE-SET,private-networks,DIRECT
  - RULE-SET,ai-platforms,AI
  - RULE-SET,developer-tools,Developer
  - RULE-SET,local-domains,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

The order of exceptions inside a provider also deserves thought when you use a classical file. Put an exact exception above a suffix rule that would otherwise capture it. For example, a direct package mirror should appear before a broad registry suffix. If your core supports a no-resolve option, use it thoughtfully on IP rules where DNS resolution would create unwanted side effects; do not add it mechanically to every line.

DNS mode can make an apparently correct ruleset look broken. In fake-IP mode, applications may display synthetic addresses, and an IP-based rule may behave differently from a domain rule. Domain providers are generally easier to reason about for HTTPS services because the original hostname remains the meaningful routing signal. For applications that connect directly to a resolved IP, inspect logs and test whether an IP-CIDR provider is genuinely required.

Also remember that a provider refresh does not necessarily mean an existing connection changes immediately. Long-lived HTTP/2 streams, WebSockets, and connection pools can continue using the route selected when they were opened. Close the affected application or clear its connection state after a ruleset update, then test a new request. This matters for AI streaming clients, IDE extension hosts, and background package managers that remain alive for hours.

5. Version, refresh, and troubleshoot like production configuration

Git history is the main advantage of hosting providers on GitHub. Make each commit explain the observed behavior rather than merely listing a hostname. “Add upload endpoint seen in API trace” is more useful than “update domains.” Pull requests should show the old and new entries, the reason for the change, and the expected policy group. This turns a personal YAML file into a maintainable routing artifact.

Choose refresh intervals according to change frequency. A daily interval such as 86400 is reasonable for a manually reviewed provider. A frequently changing feed may need a shorter interval, but refreshing every few minutes adds load and can make transient GitHub failures more visible. The interval is not a substitute for cache control or release discipline. If you need an urgent correction, commit it, validate it, and restart or refresh the provider from the client interface instead of waiting for the scheduled timer.

Symptom Likely cause Useful check
Provider shows an error Bad URL, HTTP failure, private repository, or invalid YAML Open the raw URL and inspect the client log
Provider loads but traffic stays direct Missing RULE-SET line or earlier match Move the rule temporarily near the top and retest
Only one app fails Different DNS, proxy environment, or process behavior Compare Clash connections with application logs
Some subdomains work and others fail Exact domain entry is too narrow Inspect the failing hostname before widening a suffix
Old behavior remains after update Persistent connection, local cache, or stale profile Refresh provider, restart the process, and test a new session

Test from the client that matters. A browser success does not prove that a Python SDK, Node process, Docker daemon, or IDE extension uses the same proxy path. Check the Clash connection panel for the actual hostname, selected rule, policy group, and final node. For command-line tools, verify HTTP_PROXY, HTTPS_PROXY, and NO_PROXY separately, because an application may bypass Clash even when the desktop client is in Rule mode.

For AI and developer workflows, test more than the landing page. Open an authenticated console, make a small API request, stream a response, upload a modest file if the workflow requires it, and download a package or repository artifact. These actions often use different hostnames. Record timestamps and the provider commit used during the test so a later failure can be correlated with a concrete change.

Finally, design a failure policy. If a provider cannot be fetched, should the previous cached copy remain active, or should the client fall back to the main rules? A cached ruleset may preserve service continuity but can become stale; an empty or missing provider may send traffic to a broad fallback unexpectedly. Keep a conservative local baseline for essential domains, monitor provider availability, and avoid making a remote GitHub file the single point of failure for corporate access or security controls.

6. Production patterns for AI platforms and developer tools

A useful production layout separates destination data from routing intent. The AI provider lists verified model, console, authentication, and upload endpoints; the AI policy group decides which relay is used. The developer provider lists Git hosting, package registries, container distribution, and documentation endpoints; the Developer group can select a lower-latency node or a direct route for approved mirrors. This lets you replace a node without rewriting every hostname.

Do not automatically place all of a vendor’s domain suffix behind the same group. An AI vendor may use one parent domain for an API, billing portal, status page, and static assets. Route only the surfaces that need the relay, and leave account systems or company SSO on the path required by your organization. Likewise, a broad github.com rule can accidentally proxy private repositories that your company expects to reach through a corporate VPN.

For team use, pin the provider to a reviewed branch or release tag rather than an unprotected moving branch. A moving branch is easy to update, but it also makes every client consume an unreviewed change at the next interval. Use a staging provider for experiments, test it from Windows, macOS, Linux, and Android where relevant, then promote the validated file. Keep a rollback commit ready and document how to refresh or remove the provider in Clash Verge Rev.

Compared with single-switch VPN clients, which often tunnel every browser tab and development process through one opaque path, Clash gives you visible rule order, per-provider ownership, and separate policy groups. That does mean you must maintain YAML carefully: a stale hostname list or misplaced catch-all rule can be more confusing than a binary toggle. Once the boundaries, GitHub review process, refresh behavior, and logs are documented, however, rule-providers make routing changes smaller, reversible, and much easier to diagnose. If you want that workflow across Windows, macOS, Linux, and Android, Clash-compatible clients provide the practical starting point without forcing your package managers, internal services, and AI traffic into one undifferentiated route.

Download Clash clients →

Ready to get started?

Use a Mihomo-compatible Clash client to test rule-providers, GitHub updates, and policy-group routing across your devices.