Understand the traffic path through configuration options. Select a topic to see what it does, how to enable it, and a YAML snippet. Examples show partial structures and must be merged into an existing configuration. Proxy group names must match the targets used by rules.
Match rules in order; route traffic by policy
In rule mode, rules are checked from top to bottom. The first match selects a policy, and no further rules are evaluated. Domain suffixes work well for covering a service's subdomains; IP rules are useful for known address ranges, while MATCH catches everything else. Put rules that need special handling first, followed by regional rules and a final policy. mihomo retains familiar Clash rule syntax and extends its capabilities. When migrating an older configuration, check that the rule types and data files you use are still supported. In the example, PROXY is a proxy group name that must be defined in the configuration before use; copying the rule alone is not enough to start the client.
Proxy groups separate rule targets from specific egress options, so you can change an exit without editing rules one by one. Use select for manual selection, url-test to choose based on probe results, and fallback to try available options in order. Decide whether you need manual control or automatic switching, then configure the group type and candidate list. mihomo supports common legacy proxy group structures, but older cores may not recognize newer fields. Check the documentation for the core you are actually running before migrating. The example uses DIRECT to create a minimal, valid group. After importing a subscription, connect actual exits through proxies or use; the PROXY rule target can then select an exit.
config.yaml · proxy-groups
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
Preserve domain mappings and check the DNS resolution path
fake-ip assigns virtual addresses to domains, allowing the core to retain domain information for later rule matching. After enabling dns, make sure DNS requests from your apps actually reach the core; changing enhanced-mode alone does not redirect all system DNS traffic. mihomo offers more DNS policy options than older cores, so avoid reusing an entire bundle of settings from an unknown source when migrating. If a LAN service or specific app has compatibility issues, configure fake-ip-filter for the affected domains and check the cache. This example shows only the basics; choose upstream resolvers that are reachable from your network.
Handle traffic from apps that ignore system proxy settings
TUN routes traffic through a virtual network interface, making it useful for apps that ignore system proxy settings. Desktop clients typically need administrator privileges or a client service; on phones, the system VPN interface handles the connection. Before enabling TUN, confirm that a regular proxy works, then enable automatic routing and DNS hijacking step by step. This helps avoid mistaking an egress failure for a routing issue. TUN support varies across older cores, clients, and operating systems; having tun in a configuration file does not guarantee that the current app can load it. If LAN access breaks after startup, check routes, network adapters, and conflicts with other VPNs instead of repeatedly reinstalling the client.
Update subscription exits and rule sets separately
A full configuration subscription, proxy-providers, and rule-providers are different things. A full subscription may replace proxies, groups, and rules; a proxy collection provides exits only; a rule collection provides match conditions only. Managing them separately lets you keep local policies while updating only the data that changes. mihomo supports several rule set formats, but older cores may not recognize every format or field. Before migrating, check behavior and format. The example uses a local classical rule file referenced through RULE-SET. The file must already exist and contain a payload list. Remote subscription URLs may contain access credentials; remove them before sharing logs or configuration files.
Inspect connections and policies through the local API
The external controller API lets dashboards read connections, switch policies, and change runtime settings; it is not a proxy port for browsers. After enabling external-controller, enter the matching address in your dashboard. external-ui points to a dashboard folder placed in the configuration directory. mihomo retains familiar controller API usage, but dashboard support for newer features depends on the dashboard itself. Bind the API to the loopback address first so only local apps can access it. If remote management is necessary, configure authentication and restrict network access. Some graphical clients manage the controller address and credentials themselves; use the client settings where possible to avoid conflicts between manual configuration and runtime overrides.
config.yaml · controller
external-controller: 127.0.0.1:9090
external-ui: ./ui
log-level: info
Choose a client for your operating system
Graphical clients handle subscriptions, system proxy settings, and everyday controls; the core handles protocols, DNS resolution, and rule execution. Choose a client that fits your device, then check its CPU architecture, system requirements, and configuration support.
Start with a maintained graphical client such as Clash Plus. Import a subscription, enable the system proxy, and test a browser connection. If you need to route games or store apps, learn about TUN and loopback restrictions next.
Before moving from Clash for Windows, back up your subscriptions, custom rules, and overrides. The new client's configuration directory and service mode may differ, so don't overwrite the entire old directory. Check the system proxy port shown by the new client rather than assuming it is unchanged.
Check whether your Mac has Apple silicon or an Intel processor, then choose the matching installer. Clients such as Clash Plus and Clash Verge Rev can manage subscriptions and rules. Follow the system prompts to grant network permissions after installation.
System proxy and TUN use different permission models. If your browser connects but your terminal does not, first check whether command-line tools read proxy environment variables. Enable TUN only when transparent routing is necessary, and avoid changing the default route alongside another VPN.
Options include Clash Plus and Clash Meta for Android. Import a configuration, allow the VPN connection, and test app access. Match the installer architecture to your device; if you are unsure, check the device's processor information first.
Background disconnections do not necessarily mean your subscription has expired. Check battery optimization, background activity, and auto-start permissions first, then see whether switching Wi-Fi networks restores the connection. Change one setting at a time to identify whether the cause is system background management or a change in the connection path.
The download page links to Clash Plus on the App Store and lists the official site, clashplus.io. After installation, import a subscription in a supported format, allow the VPN configuration, and confirm the connection status in system settings.
Different clients may support different fields in the same subscription. If import fails, check whether the link returns a full configuration or a proxy collection, then review the specific error. Do not copy desktop listener addresses, file paths, or TUN settings directly to a phone.
For desktop Linux, consider Clash Verge Rev or FlClash; server and router users can look for mihomo core packages. Before installing, check the distribution's package format and CPU architecture, then set the configuration directory and permissions.
When running from the command line, start in the foreground and inspect the logs before handing the process to a service manager. Listening on ports as a regular user, creating a TUN device, and changing routes require different permissions. Diagnose configuration errors separately from permission errors.
Keep the core, client, and configuration source distinct. Source code explains implementation, release notes document changes, and the client interface determines the steps you take.
Clash Meta and mihomo: what's the connection?
Clash Meta was an earlier name for this core project, which is now actively developed as mihomo. Tutorials may still use the old name, old repository paths, or screenshots from different clients. To determine whether a configuration applies, check the core actually running and its documentation—not just whether the client name includes Meta. Graphical client updates and core updates may also happen at different times.
A client is not a subscription service
mihomo handles proxy protocols, DNS resolution, and routing rules. Graphical clients provide configuration management, system integration, and an interface on top of it. Subscriptions come from a service you choose or a configuration you create yourself. Installing a client does not provide a working egress route, and open-source code does not mean subscription contents are public. This site provides download listings and Chinese-language guides; each project’s maintainers handle its development, releases, and support.
Check changes in source code and release notes
Browse the core source in the MetaCubeX/mihomo repository; the LICENSE file in that repository specifies the license. Commits, issue discussions, and release notes can help confirm whether a field is supported or behavior has changed. Run the command below to fetch the source for review. This is not required to install a graphical client, and it does not replace importing a subscription or configuring your network.
Record your configuration before updating; verify the traffic path afterward
Before updating a client or core, back up your current configuration and local overrides, then read the release notes. After updating, confirm the configuration loads, then check DNS, rule matches, and egress separately. When reporting an issue, include the operating system, client name, core details, and minimal reproduction steps. Remove subscription URLs, credentials, and private domains before sharing logs. A clear reproduction is more useful than a screenshot of the entire configuration.
Open source
MetaCubeX / mihomo
Explore the core implementation, configuration changes, and community discussions. Check desktop and mobile client support separately.
For your first setup, follow this order: import a subscription, choose a rule mode, enable the proxy, and test the connection. You do not need to turn on every network feature at once. Once your browser works, configure support for terminal apps, store apps, or LAN devices as needed.
If you cannot connect, first determine whether the subscription could not be fetched, the configuration failed to load, or the egress connection failed. Each points to a different part of the connection path. Start a systematic check with the first meaningful error in the logs.
Routing rules and global mode, system proxy and TUN, HTTP and controller ports are easy to mix up. Before changing anything, check which layer each setting controls; expanding the scope of traffic interception can hide the original problem.
Start with common scenarios: first-time setup, migrating from an older client, and Windows app loopback restrictions. Each article walks through the relevant steps and explains when they apply.
Learn why UWP apps are blocked from accessing the local loopback address by default. Follow two ways to lift the restriction—using a graphical exemption tool or the CheckNetIsolation command—and compare TUN mode as an alternative.
Review the status and risks of discontinued clients, compare mihomo-based alternatives by platform, and follow step-by-step instructions to migrate subscriptions, custom rules, and override scripts.
Answers to 10 common beginner questions: where subscriptions come from, how to choose between rule and global modes, what port 7890 does, how mihomo relates to older cores, and where to find each setting.