Clash Rule-Providers: Advanced YAML Routing for AI and Dev Tools

Why rule-providers matter once a Clash profile starts growing

Searches such as Clash rule-providers, GitHub-hosted YAML rules, and “how do I route OpenAI, Claude, or developer tools with Clash?” usually appear after a profile has outgrown a single hand-written rule list. At first, adding a few DOMAIN-SUFFIX entries feels harmless. A month later, the same file may contain AI platforms, package registries, code-hosting services, telemetry endpoints, local exceptions, streaming domains, and several duplicated rules copied from different guides. The profile still loads, but nobody can confidently explain which rule wins or whether a remote list is current.

A rule-provider turns that growing list into a separately maintained data source. Instead of embedding every domain directly in the main profile, you define a provider with a URL, a format, and an update policy, then reference it from rules. GitHub is convenient for this model because a repository can hold focused lists such as AI APIs, developer platforms, package registries, or internal test domains. The important distinction is that a provider is not a magic VPN list. It is an input to Clash’s policy engine, so its syntax, availability, freshness, and position in the final rule chain still determine the result.

This guide focuses on Mihomo-compatible Clash clients, including Clash Verge Rev and other clients that expose rule-provider support. The examples use public HTTPS URLs and ordinary domain rules. Replace them with sources you are authorized to use, review repository history before trusting a list, and avoid placing subscription tokens or private hostnames in a public GitHub repository.

How providers fit into Clash’s routing model

Clash evaluates traffic against the assembled rule list from top to bottom. A matching rule selects a policy group such as AI, Developer, Proxy, or DIRECT. A rule-provider does not automatically become active merely because it appears under rule-providers; it becomes part of routing only when you reference it with a RULE-SET rule.

That separation is useful because it gives you two layers to reason about:

• Provider definition: where the list lives, which format it uses, how often Clash refreshes it, and whether the content is a classical rule list or a domain-only list.
• Policy reference: where the provider is placed in the ordered rules section and which proxy group receives matching requests.

For example, a request to api.openai.com might match an AI provider and enter the AI group. A request to your company’s internal Git server might match a local DOMAIN-SUFFIX exception earlier in the file and stay DIRECT. If the internal exception appears after a broad provider reference, it may never be reached. This is why “the domain is in my list” is not enough evidence. You must also inspect ordering, the selected policy, DNS behavior, and the actual connection log.

Classical, domain, and behavior-based providers

Mihomo commonly supports several provider styles. A classical provider contains complete Clash rules, such as DOMAIN-SUFFIX,example.com or IP-CIDR,203.0.113.0/24. A domain provider contains domain values that are interpreted according to the provider’s behavior. A mrs provider uses a binary format generated for Mihomo and can be efficient for large lists, but it requires a compatible source and client version.

Use classical format when the repository intentionally publishes complete rules and may later add different rule types. Use a domain provider when you want a narrow, readable list of hostnames and subdomains. Do not label a plain text domain file as classical unless each line really follows classical rule syntax. A format mismatch can produce an apparently successful download that contributes few or no useful matches.

Designing a maintainable GitHub rule source

A useful GitHub provider is deliberately small. Do not create one enormous file called proxy.list containing every service your household has ever visited. Split lists by policy intent so that a change has a predictable effect. For example, one repository could contain ai-domains.list, developer-domains.list, and package-registries.list. A team can then send AI traffic through one group while keeping package mirrors or public documentation on a different path.

Keep the repository readable for humans as well as machines. Use a README to state the purpose, supported format, maintainer, update frequency, and known exclusions. In the list itself, use comments only when the selected format allows them and keep entries normalized. Prefer stable service domains over temporary regional hostnames, tracking endpoints, or IP addresses copied from a single connection. AI vendors frequently separate authentication, inference, file upload, model listing, and console traffic, so validate a workflow rather than testing only one obvious API hostname.

GitHub URLs also deserve care. A browser page URL such as https://github.com/example/project/blob/main/ai.list is HTML, not the raw rule file. The provider should point to a raw file URL, for example https://raw.githubusercontent.com/example/project/main/ai.list. Pinning to a commit makes deployments more reproducible, while a branch such as main gives you automatic updates. The trade-off is straightforward: branches are convenient but can change unexpectedly; commit URLs are stable but require a deliberate update process.

• For personal experimentation: a branch URL with a moderate update interval is convenient.
• For a team profile: review changes and pin known-good commits before production rollout.
• For regulated or sensitive environments: mirror approved content internally and avoid depending on an unreviewed public repository at runtime.

Never publish access tokens inside a provider URL. A private GitHub URL containing a token can leak through configuration backups, screenshots, logs, browser history, or support tickets. If a private source is required, use an access method supported by your deployment process, or serve a sanitized mirror from infrastructure you control.

Hands-on setup: add AI and developer providers to YAML

Before editing, export or copy your current profile. Make one functional change at a time so that a failed update can be attributed to the provider rather than to an unrelated proxy-group modification. The following example assumes that your profile already defines AI and Developer groups. If those groups do not exist, replace them with a group that is present in your profile.

1. Prepare the source files. Publish a reviewed list such as ai-domains.list and developer-domains.list. Confirm that the raw URLs return plain text with an HTTP 200 response, not a GitHub login page or repository HTML.
2. Add provider definitions. Put the providers at the top level of the profile, alongside proxies, proxy-groups, and rules. The indentation must remain consistent because YAML treats whitespace as structure.
3. Reference each provider. Add RULE-SET entries above broad fallback rules such as GEOIP,CN,DIRECT or MATCH,Proxy.
4. Validate and reload. Use the client’s profile parser or reload action. A provider download error should be treated separately from a YAML syntax error.
5. Test representative workflows. Check an AI API request, a developer login or repository operation, and a local service that should remain direct.

rule-providers:
  ai-platforms:
    type: http
    behavior: domain
    url: https://raw.githubusercontent.com/example/routing/main/ai-domains.list
    path: ./providers/ai-platforms.yaml
    interval: 86400
    format: yaml

  developer-services:
    type: http
    behavior: domain
    url: https://raw.githubusercontent.com/example/routing/main/developer-domains.list
    path: ./providers/developer-services.yaml
    interval: 86400
    format: yaml

rules:
  - RULE-SET,ai-platforms,AI
  - RULE-SET,developer-services,Developer
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

The exact content format must match the provider declaration. A domain provider may be served as a plain list, while a YAML provider commonly contains a payload such as payload: followed by domain entries. Some clients accept a format automatically, but explicit configuration is easier to audit across machines. If your client rejects format: yaml or handles the source differently, follow the syntax supported by that client’s Mihomo build rather than copying an option from an unrelated Clash fork.

The local path is not the public URL. It is where the client caches the downloaded provider. Use separate, descriptive paths; accidentally assigning two providers the same path can make troubleshooting extremely confusing. The interval is expressed in seconds. A daily refresh is often sufficient for a curated list. A short interval does not repair a bad source, and frequent polling can create unnecessary load or trigger rate limits.

Precedence, exceptions, and the rules that most often surprise developers

Provider references are powerful because they can match many domains at once, but that is also where accidental over-routing begins. Suppose your AI provider includes github.com because an AI coding service uses GitHub OAuth. That entry may send ordinary repository browsing, release downloads, and enterprise GitHub traffic into the AI group. A narrower exception placed before the provider can correct the behavior, but only if the exception reflects your actual policy.

Use a deliberate order rather than a collection of “more rules until it works” edits:

• Private and local exceptions first: internal domains, LAN ranges, printer hosts, and corporate portals should be protected from broad remote lists.
• Specialized service providers next: AI, developer, package, or collaboration lists should map to their intended groups.
• Regional or geographic rules after service rules: a broad GEOIP rule should not steal traffic that a specialized provider already classified.
• Final catch-all last: MATCH should be the last policy decision unless your profile has a documented alternative.

Remember that a domain provider may cover a parent domain and therefore match more than the one hostname you tested. If a list contains DOMAIN-SUFFIX,example.com, it can include api.example.com, login.example.com, and other subdomains. When you need only one endpoint, a precise DOMAIN rule may be safer. Conversely, manually adding every current subdomain creates maintenance debt and may fail when a vendor introduces a new API surface.

DNS mode can make the result look inconsistent. Fake-IP, redirection, and resolver settings affect what appears in the Connections view and whether a hostname is available for domain matching. When a rule seems ignored, check the original hostname in the log, not only the resolved address. Also verify that TUN or system proxy mode actually captures the application. A command-line tool with its own proxy settings, a container, and a browser can all reach the same service through different paths.

Updates, observability, and safe rollback

Remote providers reduce manual editing but introduce a supply-chain boundary. Treat every update as a configuration change. Before increasing the refresh frequency, decide what happens if GitHub is unavailable, the file becomes empty, or a maintainer adds a broad domain by mistake. Many clients keep the last successful provider locally, but you should not assume that behavior without checking the client documentation and logs.

After a refresh, inspect at least four signals:

• Download status: confirm the provider returned a successful response and was parsed, not merely cached from an old run.
• Rule count: a sudden drop to zero or a dramatic increase deserves investigation before normal use.
• Connection policy: verify that the intended hostname selected AI or Developer, rather than DIRECT or an unrelated group.
• Application behavior: test authentication, streaming, uploads, and ordinary repository operations separately because they may use different domains.

Keep a known-good copy of the complete profile and record provider revisions in a change log. If a new GitHub commit causes failures, pin the provider URL to the previous commit or restore the cached file, then reload the profile. A rollback should not require reconstructing a long YAML file from memory. For teams, review pull requests for rule changes and test them against a small matrix of hostnames before merging.

Use tools that isolate policy from credentials. A simple curl request can confirm whether a hostname is reachable through the configured proxy, while the Clash connection log can confirm which rule and group were selected. Do not paste API keys into shell history or public issue reports while collecting evidence. For a reproducible bug report, record the provider revision, client version, selected group, hostname, timestamp, and sanitized error class.

Common provider failures and a practical diagnosis sequence

A provider that “does not work” can fail at several independent layers. Start with the profile parser. If the YAML cannot be loaded, inspect indentation, duplicate keys, quotation marks, and whether the provider is placed at the correct top-level location. If the profile loads but the provider cannot update, open the provider status panel and test the raw URL outside Clash. A 404, redirect to HTML, authentication page, or GitHub rate-limit response is a source problem rather than a routing-rule problem.

If the download succeeds but no traffic matches, compare the provider behavior with the file contents. A list containing full classical rules should not be interpreted as an unstructured domain file, and a YAML payload should not be treated as arbitrary text. Then inspect the RULE-SET spelling, provider key name, target group name, and rule order. YAML keys are easy to mistype, and a valid-looking profile can still reference a provider that is not the one you intended.

If some requests match and others fail, map the complete application workflow. An AI coding extension may contact an API endpoint, an OAuth identity provider, a model catalog, a file-upload host, and a telemetry service. A developer tool may use separate hosts for Git operations, package downloads, container registries, and documentation. Add only confirmed domains to the appropriate provider, then test again. Avoid solving one missing hostname by routing the vendor’s entire top-level domain unless the broader policy is genuinely acceptable.

Finally, compare Rule mode with Global mode only as a diagnostic experiment. If Global mode works while Rule mode fails, the profile likely has a precedence, coverage, DNS, or capture issue. That experiment does not prove that Global mode is the best permanent configuration; it simply narrows the search. Restore Rule mode, fix the specific classification, and confirm that local services still bypass the proxy.

A sustainable operating pattern for AI and developer routing

The strongest long-term arrangement is modular but conservative: one provider per policy family, a clearly documented raw source, explicit update intervals, specialized groups, local exceptions above remote lists, and a final catch-all that is easy to identify. Keep the main profile responsible for policy decisions and keep provider files responsible for membership. This division lets you update a domain list without rewriting proxy groups, while still making the final routing graph understandable to the next person who opens the YAML.

Do not equate a larger provider with better coverage. A short list of verified AI endpoints can be more reliable than an abandoned mega-list that routes unrelated analytics, media, and login traffic through an expensive relay. Review entries when vendors change infrastructure, remove stale domains, and note why an exception exists. If a service is business-critical, consider an internally mirrored provider and a controlled release process instead of depending on an anonymous repository that can change without notice.

Compared with clients that offer only a single global switch or opaque application toggles, Clash gives you visible rule precedence, reusable YAML modules, per-service policy groups, cached providers, and connection logs that show whether an AI or developer request actually took the intended path. Those capabilities do require discipline: you must review GitHub sources, test updates, and preserve rollback copies. If you want that balance of granular routing and practical observability rather than another all-or-nothing tunnel, Download Clash for free and browse freely →