Clash Ecosystem Guide: Cores, Clients and Rule Sets

Three Layers: Cores, Clients and Rule Sets

Projects in the Clash ecosystem fall into three layers. The core parses configuration, opens connections and enforces routing — it is the only part that actually handles traffic. Clients provide the window, tray icon, subscription management and process supervision, but do not parse rules themselves. Rule sets and data files are just lists, read by the core at runtime. The three layers interact through two kinds of files: one YAML configuration and a set of rule data.

The point of separating the layers is locating problems. Failed subscription updates, connections that never establish, and domains routed down the wrong branch each belong to a different layer — client, core and rule set respectively. Work out which layer a fault sits in, then look for answers in the matching repository; that beats flipping switches in the client over and over.

The Core Lineage: Original Clash, Clash Premium and mihomo

The original core and where its maintenance ended

The original core means Dreamacro/clash, written in Go. The familiar YAML structure of proxies, proxy-groups and rules was defined here, and every client's config format traces back to it. Around November 2023 the original core stopped receiving updates and the repository went read-only; Clash for Windows was pulled from GitHub in the same period.

Its limits are worth remembering: no rule-providers, proxy-providers or tun; outbound protocols are mainly Shadowsocks, VMess, Trojan and Snell; rule types centre on DOMAIN, DOMAIN-SUFFIX, IP-CIDR, GEOIP and MATCH. If a config contains a tun: field at all, the original core exits with an error.

Clash Premium: a closed-source binary that went offline with the mainline

Clash Premium was the original author's closed-source, free core. It added four capabilities — tun, script, rule-providers and proxy-providers — and was for a while the main way to get TUN mode on macOS. Distribution stopped along with the original mainline, so it now has historical value only: if a tutorial says “use the Premium core”, that document almost certainly predates 2023.

Clash.Meta and mihomo: today's de facto mainline

MetaCubeX's Clash.Meta built on the original to fill in protocols and configuration features, and was renamed mihomo in early 2024. The repository is MetaCubeX/mihomo, and the executable name and default config directory changed to mihomo along with it. Clients that still ship updates almost all bundle it or a downstream fork.

Compared with the original, mihomo's additions fall into four groups:

• Outbound protocols: VLESS, Hysteria, Hysteria2, TUIC, WireGuard, SSH, ShadowTLS;
• Configuration features: sub-rule, logical rules (AND / OR / NOT), listeners, sniffer, find-process-mode, geox-url;
• Rule-set formats: alongside YAML and text, the smaller and faster-loading binary mrs format;
• Data files: geoip.metadb as an alternative to geoip.dat, with ASN-based matching.

Compatibility runs one way only: configs that run on the original will generally run on mihomo, but not the reverse. When migrating, validate first with mihomo -t -f config.yaml and any out-of-scope fields become obvious.

The Client Layer: Who Still Maintains, Who Stopped in 2023

Clients do not define the config format; they decide three things: which core is bundled, where the config file lives, and which switches the interface exposes. So the first thing to check when choosing a client is where its core comes from, and only the second is interface habits.

After the original Clash Verge repository stopped updating, the community took it over as Clash Verge Rev, swapped the core for mihomo, and kept the subscription management and profile organisation. On desktop, if you are still on Clash for Windows, moving to a mihomo-based client is the smallest possible change: the YAML itself stays as it is, you just import the config again.

iOS is a different path

No client on iOS reuses the Clash core directly. Apps such as Stash on the App Store implement their own rule engine and only read Clash-style YAML. “iOS can import Clash configs” describes format compatibility, not a shared core. The way to judge is straightforward: how far fields such as tun, script and rule-providers are supported on iOS depends on each app's own documentation, and desktop experience does not carry over.

Config directories: core defaults vs client-managed

Run the core on its own and the original reads ~/.config/clash/ by default, which expands to %USERPROFILE%\.config\clash\ on Windows; mihomo uses ~/.config/mihomo/. Clients with a GUI usually take this over — Clash Verge Rev, for example, keeps profiles and rule caches in its own application data directory (%APPDATA%\io.github.clash-verge-rev.clash-verge-rev\ on Windows), so installing over the top does not wipe subscriptions. When troubleshooting, confirm which file the core is actually reading; that is more useful than re-reading the YAML.

Rule sets and data files: the layer that updates most often

A rule set is a plain list with no network implementation. The core pulls lists through rule-providers and references them with RULE-SET, or reads compiled dat files through GEOSITE and GEOIP. This layer updates most often and is the one most easily mistaken for part of the core.

A few repositories worth knowing:

• Loyalsoldier/clash-rules: rule-providers grouped by domain and ipcidr, with the release branch offering reject.txt, direct.txt, proxy.txt, gfw.txt, cncidr.txt and more, ready to be written straight into rule-providers;
• blackmatrix7/ios_rule_script: rule sets split by service, with paths like rule/Clash/<service>/<service>.yaml, covering detailed lists for streaming and AI services;
• MetaCubeX/meta-rules-dat: geosite.dat, geoip.dat, geoip.metadb and country.mmdb compiled for mihomo, plus individual rule sets in mrs format; the upstream data comes from v2fly's domain-list-community;
• ACL4SSR/ACL4SSR: rule templates represented by ACL4SSR_Online.ini, usually used together with a subscription conversion tool;
• tindy2013/subconverter: converts subscription links in non-Clash formats into Clash YAML; it only handles format conversion and takes no part in running.

rule-providers:
  reject:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/Loyalsoldier/clash-rules/release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400
  cn-domain:
    type: http
    behavior: domain
    format: mrs
    url: "https://github.com/MetaCubeX/meta-rules-dat/raw/meta/geo/geosite/cn.mrs"
    path: ./ruleset/cn.mrs
    interval: 86400

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,cn-domain,DIRECT
  - GEOSITE,geolocation-!cn,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

In this snippet, format: mrs can only be read by mihomo; the unit of interval: 86400 is seconds, i.e. the list is checked for updates every 24 hours. The rules section is ordered from specific to broad and stops at the first match, with a final MATCH as the catch-all — that is also the minimum requirement for judging whether a config is complete.

GEOSITE / GEOIP vs RULE-SET: Choosing Between Them

• GEOSITE and GEOIP read local dat files and match in memory, which is fast; the trade-off is a large bundle and updates at the granularity of the whole database;
• RULE-SET pulls an individual list per provider, giving fine granularity and easy replacement; the trade-off is one HTTP request and one local cache per provider;
• In mihomo, with geodata-mode: true GEOIP rules read geoip.dat, and by default they use country.mmdb; paired with geox-url you can point the data source at a mirror to avoid failed downloads.

Config Compatibility: A Check Order You Can Actually Run

1. Start with the core name and version. If the client settings show mihomo or Clash.Meta, it is on the Meta branch; if they only say Clash and the last update is from 2023, it is the original core.
2. Then check the advanced fields. If a config contains any of tun, rule-providers, proxy-providers, script, listeners or sub-rule, the original core exits with an error.
3. Run the core's own validation flag: mihomo -t -f config.yaml parses without starting, and the original core supports -t as well.
4. Read the first error in the log. unsupported proxy type points at a protocol, unsupported rule type at a rule; both are core-version problems, and rewriting the config will not help.
5. Finally, check the ports. Make sure mixed-port (commonly 7890) and external-controller (commonly 127.0.0.1:9090) are not already taken; if the dashboard opens, the core started correctly and anything left is a rule-layer issue.

Which Repository to Follow

Map your use case to a specific repository:

• Everyday desktop use: follow the client's own release cadence; core updates come with the client. If you need to upgrade the core separately, find the core version section in the client settings and update it manually.
• If you need TUN, VLESS, Hysteria2 or logical rules: go by the MetaCubeX/mihomo repository and its official documentation; treat the docs, not old tutorials, as the reference for config fields.
• Routers: OpenClash on OpenWrt, or ShellClash deployed over SSH — both bundle mihomo.
• Routing accuracy: Loyalsoldier/clash-rules covers lists pulled on demand, while MetaCubeX/meta-rules-dat covers dat and mrs data; the commit dates of these two repositories determine whether new domains get routed correctly.
• Subscription format conversion: subconverter or Sub-Store — format conversion only, no part in running.

Three things are enough to judge whether a Clash-related repository is still worth following: the date of the last commit, the core dependency stated in the README, and whether maintainers still reply in the issue tracker. When any of the three layers stops updating, the impact stays inside that layer — a stalled core affects protocols and config fields, a stalled client affects system integration and the interface, a stalled rule set affects routing accuracy. Keep the three apart and a single client going offline will not make you doubt the whole config.