Clash Developer Routing: Advanced Rule-Providers YAML Guide

Routing Goal: Keep Developer Services Reachable

Developer traffic rarely fits a simple “all direct” or “all proxy” switch. A normal workday may include GitHub repositories, package registries, container image layers, documentation sites, issue trackers, cloud APIs, SSH hosts, and an internal company network. Some of these destinations work best through a proxy, some must stay direct, and some should be rejected when they are known telemetry or unwanted update endpoints. Clash becomes predictable only when these decisions are expressed as ordered rules instead of a collection of GUI toggles.

In mihomo, every connection is evaluated from the top of the rules list downward. The first matching rule selects an outbound policy. A rule-provider does not create a proxy by itself; it supplies a maintained list of matching entries that a RULE-SET rule can consume. This separation is useful for developer routing because the list of domains can change independently from the main profile, while the policy structure remains stable.

A practical design usually has at least four policies: DIRECT for local networks and services that should bypass the tunnel, a selectable Developer-Proxy group for code-hosting and registry traffic, a general Proxy group for other international destinations, and REJECT for explicitly blocked categories. The names are arbitrary, but they must match the proxy-group names exactly, including capitalization and punctuation.

• Local and private traffic: keep loopback, private address ranges, office domains, and internal DNS direct unless your network policy says otherwise.
• Code-hosting services: route Git hosting, release downloads, raw file endpoints, and collaboration APIs through a stable proxy group when direct access is unreliable.
• Package registries: route registry metadata and tarball domains consistently. Mixing direct metadata requests with proxied downloads can produce authentication, timeout, or integrity failures.
• Fallback traffic: send unmatched destinations to a general policy rather than relying on the operating system's proxy behavior.

Rule-Provider Architecture: Separate Data from Decisions

The main profile should describe stable routing decisions, while providers should contain lists that need regular maintenance. For example, the profile can say “all entries from the developer provider use Developer-Proxy,” while the provider file contains the actual Git hosting and registry domains. This keeps the main YAML readable and makes it possible to update a domain list without editing every rule manually.

mihomo supports several provider types. A http provider downloads a remote file, a file provider reads a local file, and the provider's behavior tells mihomo how to interpret its entries. Use domain for domain-oriented lists, ipcidr for IP networks, and classical when the file contains complete Clash rule lines such as DOMAIN-SUFFIX, IP-CIDR, or PROCESS-NAME.

Provider names are local identifiers. A name such as developer-domain is referenced later, but it does not need to match the file name or the URL. Choose short, descriptive names and use one naming convention throughout the profile. Separating providers by function is usually easier to debug than creating one enormous list: for example, use developer-code, developer-registry, and developer-internal.

Provider File Formats

A domain provider can be a YAML document containing a payload list. Each item is commonly a domain, a domain suffix, or another format accepted by the selected mihomo behavior. A classical provider instead contains complete rule strings, so it can express more than a bare domain list. The following example uses a classical YAML provider because it makes the intended match type explicit:

payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN-SUFFIX,githubassets.com
  - DOMAIN-SUFFIX,registry.npmjs.org
  - DOMAIN-SUFFIX,pypi.org
  - DOMAIN-SUFFIX,files.pythonhosted.org

If the source is a plain text list containing one domain per line, use the provider behavior and format expected by that file rather than copying a YAML example. A parser mismatch is one of the most common reasons a provider appears to update successfully but never matches traffic.

Build the YAML: Groups, Providers, and Ordered RULE-SET Entries

The following profile fragment demonstrates the relationship between proxy groups, provider definitions, and rules. The node names are placeholders; replace them with names that already exist in the imported subscription. The example deliberately keeps local rules above provider rules and places the catch-all rule last.

proxy-groups:
  - name: Developer-Proxy
    type: select
    proxies:
      - Auto-Developer
      - Proxy
      - DIRECT

  - name: Auto-Developer
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - Node-A
      - Node-B
      - Node-C

  - name: Proxy
    type: select
    proxies:
      - Node-A
      - Node-B
      - DIRECT

rule-providers:
  developer-code:
    type: http
    behavior: classical
    format: yaml
    path: ./providers/developer-code.yaml
    url: https://rules.example.invalid/developer-code.yaml
    interval: 86400
    proxy: Developer-Proxy

  developer-registry:
    type: http
    behavior: classical
    format: yaml
    path: ./providers/developer-registry.yaml
    url: https://rules.example.invalid/developer-registry.yaml
    interval: 86400
    proxy: Developer-Proxy

rules:
  - DOMAIN-SUFFIX,localhost,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,developer-code,Developer-Proxy
  - RULE-SET,developer-registry,Developer-Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

The proxy field under an HTTP provider controls the connection used to download the provider itself. It does not route the developer traffic matched by that provider. The matched traffic is controlled by the third argument of RULE-SET. These two paths are easy to confuse: a provider may download through Developer-Proxy, while its entries could still be assigned to DIRECT if the rule says so.

The url-test group is optional. A selectable group is safer during initial testing because it lets you switch nodes manually and compare results. Once the configuration is stable, an automatic group can reduce the impact of a slow or unavailable node. Keep a direct option available only if bypassing the proxy is acceptable for the service and your network.

Rule Order Is the Control Plane

Rule providers are evaluated at the position of their RULE-SET entries. A broad rule placed earlier can hide a more specific provider. For example, placing GEOIP,CN,DIRECT above a provider may send a developer service directly when its address is geolocated in China, even though the domain should use the developer proxy. Placing MATCH,Proxy before any provider makes every later rule unreachable.

• Put loopback, LAN, and explicit internal exceptions first.
• Put narrow service-specific rules before broad category rules.
• Put developer providers before general regional rules when developer services have special routing requirements.
• Use no-resolve on IP rules when DNS resolution is unnecessary and you want to avoid an extra lookup.
• Keep MATCH as the final rule, with no entries after it.

Cover Git Hosting, Registries, and Developer APIs Correctly

One visible website often depends on several different domains. A Git repository page may load assets from a separate static-content host, fetch raw files from another hostname, and call an API endpoint for authentication or issue data. A package manager behaves similarly: the registry returns metadata, the package tarball may come from a storage domain, and a signature or release tool may contact an additional endpoint. Routing only the homepage is therefore not enough.

Start with domains observed in the failing application rather than blindly adding keywords. Browser developer tools can show request hostnames, while package-manager verbose logs reveal registry redirects and download URLs. Add stable suffixes only when they belong to the same service and policy. Avoid a rule such as DOMAIN-KEYWORD,git; it can match unrelated corporate hosts, software names, or internal systems containing the same characters.

Do not assume that a successful browser test proves command-line tools will work. Git, npm, pip, Docker, language package managers, and SSH clients may use their own proxy variables, certificate behavior, or DNS path. In system proxy mode, many command-line tools remain direct unless HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY are configured. TUN mode can capture more applications, but it does not automatically fix an incorrectly ordered rule list or an unsupported protocol.

Automated Updates Without Losing Reproducibility

The interval value lets mihomo refresh an HTTP provider periodically, measured in seconds. A value of 86400 refreshes once per day; 21600 refreshes every six hours. Daily updates are sufficient for most developer domain lists. Very short intervals increase bandwidth and can create unnecessary load on the provider server, while very long intervals leave stale entries in place after a service changes its infrastructure.

Keep the downloaded provider at a stable local path. This gives the core a cache to use after a temporary network failure and makes the currently loaded data inspectable from the client's profile or configuration directory. A provider update should not be treated as a configuration backup: preserve a version-controlled copy of your main YAML and document why each custom provider exists. Never commit subscription URLs, access tokens, private proxy credentials, or internal hostnames to a public repository.

• Use explicit ownership. Record whether a provider is maintained locally, supplied by a trusted administrator, or fetched from an external service.
• Choose conservative refresh intervals. Update daily unless the service changes frequently enough to justify a shorter interval.
• Test after changes. A provider update can add a broad domain or alter a rule type, changing traffic that previously matched another policy.
• Keep a rollback copy. If a newly downloaded file causes failures, restore the last known-good provider or temporarily disable its RULE-SET entry.
• Prefer minimal lists. Smaller providers are easier to audit, faster to parse, and less likely to capture unrelated services.

If the provider URL itself is only reachable through the proxy, set its proxy field to a policy that is already available during startup. Avoid a circular design in which the provider must download through a group whose node definitions depend on that same provider. When using a profile converter or subscription remote configuration, confirm that local overrides are preserved; some clients replace the generated profile when the subscription is updated.

Debug Failed Matches: A Repeatable Engineering Workflow

When a developer service fails, separate the problem into four layers: the application, the Clash inbound, rule matching, and the selected outbound. This prevents a slow node from being mistaken for a YAML error. Start with one hostname and one command, then inspect the result instead of changing several settings at once.

1. Confirm that the application is entering Clash. Check the client connection panel or logs while opening the exact URL. If no connection appears, verify system proxy variables, TUN permissions, firewall access, and whether the application bypasses the system proxy.
2. Record the actual destination hostname. Use browser network tools or verbose output such as curl -v, npm --loglevel verbose, pip -vv, or docker -D. Follow redirects because the first hostname may not be the one that times out.
3. Check the provider status and local cache path. A successful profile load does not guarantee that the remote provider downloaded or parsed correctly. Look for HTTP errors, DNS errors, YAML parse errors, and “provider not found” messages.
4. Inspect the matched rule in the Clash connection detail or debug log. The expected result should show the provider's RULE-SET and the intended policy group. If it shows GEOIP, MATCH, or another provider, a previous rule is winning.
5. Test the selected outbound independently. Switch the developer group to a known working node, retry the request, and compare latency. If the rule matches but every node fails, the issue is probably connectivity, TLS, authentication, or service-side blocking rather than rule order.
6. Test DNS separately. A correct domain rule may still fail if the resolver returns an unusable address, the application uses its own DNS, or fake-IP and sniffing behavior do not cooperate with that application.

For a controlled test, temporarily add an exact rule above the provider, such as DOMAIN,api.example.invalid,Developer-Proxy. If the exact rule works, the inbound and outbound are functional and the provider list or behavior is the problem. Remove the temporary rule after testing. If the exact rule also fails, continue investigating the application path, DNS, node, and TLS layers instead of editing the provider.

Production Checklist for a Maintainable Developer Profile

A developer routing profile is ready for daily use when its behavior is understandable without opening the GUI. The YAML should show which traffic is local, which provider owns each service category, which group handles the match, and what happens to everything else. Avoid treating a large downloaded rule list as a substitute for documentation: write a short comment beside custom sections and keep provider names consistent across machines.

• Use mihomo or another kernel version that supports the provider behavior and format used by the profile.
• Declare every provider before referencing it in rules, and verify that the identifier is spelled identically.
• Match behavior and format to the real provider file, not to the file extension alone.
• Place internal, loopback, and explicit exceptions before broad developer or geographic providers.
• Place developer service providers before GEOIP and keep MATCH last.
• Include redirected storage and asset domains when a registry or code-hosting service uses multiple endpoints.
• Test both GUI applications and command-line tools, because system proxy and TUN coverage are different.
• Set a practical provider refresh interval and retain a rollback copy of known-good data.
• Protect subscription URLs and private configuration values; use clearly fake values in examples and shared documentation.

For a clean installation workflow, the view the tutorial page covers profile import, mode selection, and system proxy basics. When the client itself is missing or the bundled kernel is outdated, use the download center to choose a maintained build. Once the profile loads, rule-provider routing becomes a small, testable system: providers describe destinations, RULE-SET entries assign policies, and ordered rules explain the final result.