Clash Open-Source Ecosystem: The mihomo core and Mac Clients

The Three Layers of the Clash Ecosystem

Search for Clash on Mac and you’ll find names like mihomo, Clash Meta, ClashX Meta, and Clash Verge Rev. They serve different roles: some handle network traffic, some provide a settings interface, and others supply domain and IP rules. Start by separating these layers to determine whether you need a different client, a newer core, or a configuration change.

A typical traffic path is “app traffic → system proxy or TUN → core → rules and policy groups → outbound.” The GUI controls this path, but it does not implement the proxy protocols itself. Even with the same core, different clients may offer different settings, subscription overrides, and permission management.

Original Clash, Clash Meta, and mihomo

The Original Core and Its Forks

The original Clash public repository stopped receiving public maintenance in 2023. Older references may also mention Clash Premium, whose feature set is not identical to that of the original open-source core. Don’t assume a feature marked “Premium” in an old guide is supported by today’s core just because it’s called “Clash.”

Clash Meta began as a fork of Clash and later adopted the name mihomo. As a result, “Meta core” in configuration guides and “mihomo” in project documentation often refer to the same line of development. Older client names may still include “Meta”; that alone doesn’t tell you how up to date the bundled core is.

Similar Names Don’t Mean Compatible Fields

mihomo retains many Clash YAML conventions, including proxies, proxy-groups, and rules, while extending protocol and rule support. Compatibility is not one-way: common basic configurations may still work, but configurations using mihomo-specific fields may not run on an older core.

• If a subscription fails to import, check the logs for an unknown proxy type, an invalid field, or a reference to a missing policy group.
• A successful configuration load only confirms that parsing passed its current stage. You still need to verify which rule and outbound handle actual requests.
• For specific protocols, rule formats, or TUN features, consult the documentation for the core you’re using and verify what its actual build supports.

Don’t assume that switching GUIs will automatically add features. A newly installed client may use a different core or retain an old runtime configuration, leaving the same problem in place. When troubleshooting, note the client name, core name, and configuration source separately.

What Mac GUI Clients Do—and Don’t Do

Projects such as ClashX Meta, Clash Verge Rev, and FlClash have offered GUI clients for macOS, but their interaction patterns and configuration management differ. The table below explains their roles; it is not a live maintenance-status report or a complete feature list. Check each project’s release notes and system requirements before installing.

System Proxy Settings Depend on Both the Client and macOS

The macOS system proxy typically directs apps that honor the setting to a local listening port. On macOS Ventura and later, for example, go to System Settings → Network → your current network service → Details → Proxies to check HTTP, HTTPS, and SOCKS. The port must match the one the core is actually listening on; don’t copy settings from another device.

For example, if the core is configured with mixed-port: 7890, the local proxy address could be 127.0.0.1:7890. 7890 is just an example, not a default shared by every client. Whether command-line tools use the system proxy depends on each tool, so a successful browser test alone doesn’t confirm the terminal’s traffic path.

TUN Requires Core Support and System Permissions

TUN uses a virtual network interface to capture routed IP traffic, so it covers different traffic from the system proxy. On a Mac, the client also needs permission, routing configuration, and DNS coordination. Core-level TUN support doesn’t mean every GUI offers the same toggle, service installation process, or recovery options.

How Subscriptions, Rule Sets, and Policy Groups Fit Together

A subscription link is a way to distribute configuration, not a fixed content format. It may return a complete YAML file, proxy-provider data, or another format that needs conversion. One client being able to recognize a subscription doesn’t mean another can import it the same way.

Proxy providers proxy-providers

Load a collection of nodes from a local file or remote source for policy groups to reference. The protocol parameters determine how each node connects.

Rule providers rule-providers

Load a set of matching conditions. Rules identify request characteristics; they don’t provide proxy nodes.

Policy groups proxy-groups

Organize nodes or other policy groups and provide outbound selection options such as manual selection, automatic testing, or failover.

For example, a domain rule set might contain domains for work services. RULE-SET sends matching requests to the “Work” policy group, which then selects a node. Downloading a rule set does not provide a proxy route; without a corresponding policy group or node, the traffic path is still incomplete.

Rule-Set Formats Must Match

In mihomo, common behavior values for rule providers include domain, ipcidr, and classical. Domain lists, IP range lists, and lists with rule types are not interchangeable. format describes the storage format, such as YAML, text, or MRS. MRS also limits which behavior types it supports, so check the documentation for your core.

• Review the rule repository’s file contents and usage instructions before filling in the provider fields.
• Categories in a rule repository are organizational labels, not a guarantee that they fit your needs.
• Rules are evaluated in order. A broad rule near the top can prevent a more specific rule later from matching.
• The final MATCH rule determines where requests that matched no earlier rule go, so specify its target explicitly.

Understand the Core and Client Roles in One Configuration

Here’s a minimal structure for testing locally. It uses only DIRECT and does not create a remote proxy connection, making it useful for seeing how listening ports, policy groups, and rules fit together. To route traffic through a remote server, add real nodes from a trusted configuration; don’t treat this example as a working subscription.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxy-groups:
  - name: Manual
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Manual
  - MATCH,DIRECT

1. The core listens on mixed-port for both HTTP and SOCKS proxy requests on the same port; it does not change the macOS system proxy on its own.
2. allow-lan: false restricts access to the proxy entry point from your local network. If you need to share it, also check the listening address and firewall.
3. mode: rule selects an outbound based on rules. After changing modes in the client, the running state may differ from the original file.
4. “Manual” is the policy group’s name. Rule references must match it exactly, or the configuration may fail to load.
5. MATCH,DIRECT is a fallback rule that sends all other requests directly; it is not a general-purpose remote proxy setup.

Before launch, a client may merge the subscription, local overrides, and UI settings, so the downloaded YAML may differ from the YAML ultimately passed to the core. When troubleshooting, look for the client’s runtime configuration preview or export option and compare it with the logs instead of checking only the original subscription. For field definitions, see the YAML Configuration Guide.

Choosing a Mac Client and Checking Before Migration

Choose Based on How You’ll Use It

• Mostly browsing: First test the system proxy, configuration switching, and whether the proxy is restored when the client exits. You may not need TUN.
• Lots of command-line and developer tools: Check each tool’s proxy options and environment-variable support before deciding whether TUN should route all traffic.
• Multiple subscriptions and complex routing: Focus on local overrides, rule-provider management, runtime configuration views, and log filtering.
• Prefer menu bar controls: Make sure you can switch common policy groups and configurations directly, while retaining a way to inspect core details.

Validate a Migration in Four Steps

1. Back up the original configuration and local changes. Record rule order, policy-group selections, ports, and DNS settings. Remove subscription tokens and node credentials before sharing diagnostic data.
2. Check the architecture and system requirements. Open About This Mac from the Apple menu to check the chip and macOS version, then choose the Apple Silicon, Intel, or Universal build specified by the project.
3. Prevent two cores from competing for the same entry point. Quit the old client and turn off its system proxy or TUN before launching the new one. If the logs say an address is already in use, check whether an old process is still listening.
4. Start with the basics, then add features. First verify configuration loading and the system proxy, then enable TUN, DNS overrides, and automatic updates. Change one category of settings at a time and keep a configuration you can roll back to.

What a subscription update replaces depends on how the client manages configuration. Direct edits to a downloaded file may be lost on the next update. For local rules you want to keep, use an override layer the client explicitly supports and check the merge order.

Open-Source Project Origins and Where to Report Issues

Open-source repositories, client installers, and subscription services are three separate sources. Being able to inspect the core’s source code doesn’t mean an installer with the same name comes from that project. Likewise, a subscription importing successfully doesn’t imply any relationship between its provider and the client developers. Before downloading, verify the project organization, repository link, release notes, and the operating system supported by the installer.

A minimal reproduction is more useful than a complete configuration. Keep one policy group and the necessary rules, remove unrelated overrides, and try again. Before sharing logs publicly, check for subscription links, credentials, local network addresses, or browsing history; these usually don’t need to be disclosed in full.

The final choice comes down to three questions: Can the core handle the protocols and rules you need? Can the client manage that configuration reliably? Is macOS handing off traffic as expected? Testing each layer separately makes it easier to build a configuration you can reuse than comparing client names alone.