From importing subscriptions to rule-based routing, follow your phone’s steps for permissions and background settings, or explore desktop setup.
01 / CLIENTS
Start with your device’s operating system, then check which core engines and configuration formats each client supports. Clash is an ecosystem, not a single app, so different interfaces may not offer identical features. After importing the same subscription on a new device, check proxy group names, DNS settings, and how the app routes system traffic. New users can follow the Clash Plus guide; if you already have a configuration, back it up before considering a switch.
A good fit for browsers, office apps, and desktop software. Start by testing the connection with the system proxy. If you need to route traffic from apps that ignore system proxy settings, consider TUN mode, which uses a virtual network interface. Before downloading, check your processor architecture. Quit the old client before enabling another proxy to avoid multiple apps repeatedly changing system settings.
Go to downloadsOn Android, first grant VpnService permission. This Android system VPN interface lets the client route device traffic; it does not mean you are connected to a remote node. After importing a subscription, allow the app to run in the background. If the connection drops when the screen locks, check battery optimization, auto-start permissions, and conflicts with other VPN apps.
Go to downloadsOpen Clash Plus in the app store from the downloads page, or visit its official website at clashplus.io. After importing a configuration, follow the app’s prompts to add a VPN configuration and approve it through iOS. This system VPN configuration is different from a manually installed profile. If you encounter an unfamiliar profile, verify its source and purpose first.
Go to downloadsCheck About This Mac to see whether your Mac has Apple silicon or an Intel processor, then choose the matching installer. System proxy and TUN have different permission requirements; verify the app’s source before installing helper services. If websites stop loading after you switch clients, check for leftover ports in your network settings before adding another proxy configuration.
Go to downloadsFor desktop use, start with a graphical client; consider deploying the mihomo core separately for servers and routers. Match the package format, processor architecture, and service permissions to your system. Command-line tools may not use desktop proxy settings, so check environment variables separately. Before enabling TUN, understand which routes and DNS requests it will handle.
Go to downloads02 / SETTINGS
Before changing settings, understand what each one controls. The sections below cover common options: rules determine where traffic goes, proxy groups choose an outbound connection, and TUN plus system permissions determine which traffic reaches the core engine. The snippets illustrate syntax; they are not complete configurations with nodes. Setting names may also vary between client interfaces.
In rule mode, the client checks conditions such as domains and addresses from top to bottom, then sends matching traffic to the assigned policy. Put specific domains that should connect directly first and the fallback MATCH rule last; the referenced policy must exist. Unlike global mode, rule mode doesn’t send every connection through the same outbound route. If one app misbehaves on your phone, check the connection log to see which rule matched before changing it. Subscription updates may overwrite rules edited directly, so use the client’s supported override or merge feature for lasting changes.
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,DIRECTThis snippet uses a direct connection as its fallback and demonstrates rule order only. Set proxy policies to match names in your own configuration.
A subscription URL is a configuration address from your service provider, not a webpage share link. Open the configuration page, choose import from URL, save it, and confirm that it’s active. A complete Clash YAML file is not the same as a nodes-only subscription, so a successful import doesn’t guarantee that all rules are present. Before updating, check whether local changes will be overwritten and back up important overrides separately. Subscriptions make it easier to sync changes than entering nodes one at a time, but their URLs can contain account details—hide the full address in screenshots and logs.
Configuration → New configuration → Import from URL
Save configuration → Set as current configuration
Update subscription → Check rules and proxy groupsTUN is a virtual network interface that routes traffic to the core engine. Android clients typically use VpnService to create a local VPN tunnel. On the first connection, approve the system permission. A VPN icon in the status bar means the tunnel is up; it doesn’t confirm that a node is working. TUN covers more traffic than app-level proxy settings and relies more heavily on system permissions and background operation. Phones generally can’t run two standard VPN tunnels at once, so disconnect conflicting apps first. If the connection drops when the screen locks, check battery optimization instead of repeatedly switching nodes.
Android system VPN: Allow connection
App battery settings: Allow background activity
Other VPN apps: Disconnect before testing
After locking the screen: Check the client is still runningA proxy group selects an outbound route: select lets you choose manually, url-test chooses based on test results, fallback switches to the next option in order when one fails, and load-balance distributes connections. Start with a manual group and confirm an outbound route works before trying automatic selection. Automatic tests aren’t real download-speed tests, and switching routes doesn’t guarantee that existing connections will move immediately. Proxy groups are easier to manage than a single fixed node, but group references, rule targets, and subscription node names must match.
proxy-groups:
- name: Manual
type: select
proxies:
- DIRECT
rules:
- MATCH,ManualThis example includes only the built-in DIRECT outbound. To use a proxy, add a node or policy name that actually exists in your configuration.
A node latency test usually sends a request to a test address through a selected outbound route. Results depend on the handshake, DNS resolution, target site, and current network. Use the test to check basic connectivity, not to predict bandwidth, video quality, or whether every app will work. For a fair comparison, use the same test address on the same network; don’t compare Wi-Fi results with cellular data. If a test times out, first check that the subscription is valid and the node is available, then verify access in the app you actually use. Avoid running frequent batch tests on your phone, as they increase background network activity.
Choose the same test address
Run a manual test on the same network
Check real access in the target app
Recheck after switching networksDNS resolves domain names to addresses. An override replaces or merges the DNS settings in a subscription with local settings. If a website won’t load but direct connections work, start by checking the DNS logs. Avoid changing private DNS on the device, client DNS, and router settings all at once, or it will be hard to pinpoint the problem. fake-ip uses virtual addresses to maintain domain mappings and isn’t suitable for every app. Understanding where DNS requests go matters more than simply switching resolvers; on mobile, also consider VPN coverage and app compatibility.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- 1.1.1.1This illustrates the fields; it isn’t a universal recommendation. Keep a copy of the original configuration and make sure your current network can reach the selected DNS resolver before making changes.
03 / QUICK START
For your first setup, get one complete path working: load a usable configuration, establish the system tunnel, and confirm that your target app can connect. Keep the subscription’s DNS and rules for now. Don’t combine snippets from multiple guides in one configuration at once. Test after each change so you can track down issues later.
Copy the subscription URL from a trusted provider. In the client’s configuration page, import it from URL and set it as the current configuration. If the client reports a format error, check that the response is a supported configuration—not a login page or an expired-subscription notice. Never post your subscription URL in a public discussion.
Use rule mode, choose a working outbound route in a proxy group, and start the connection. On a phone, approve the VPN configuration when prompted; on Android, also allow background activity. System proxy, TUN, and rule mode are separate settings. You don’t need to enable every switch “just in case.”
First, open a site or app you use regularly and check the connection log to confirm the expected policy matched. Then switch between Wi-Fi and cellular data, and test again after locking and waking the screen. If the connection drops only while locked, check battery restrictions first. If only one domain has a problem, inspect its rules and DNS before reinstalling the client.
04 / OPEN SOURCE
When choosing a client, it’s more useful to understand the project, core engine, and configuration source than to judge by the interface alone. This site brings together download links and Chinese-language guides; it doesn’t replace upstream release notes or provide proxy nodes. A client’s capabilities depend on its core engine, system limitations, and configuration.
The original Clash established a common configuration approach for rule-based proxies. Clash.Meta expanded on it, and its related core engines later continued under the mihomo name. So “supports Clash configuration” doesn’t mean every field is interchangeable. Check core engine support for newer protocols, rule types, and network stack options.
When migrating an older configuration, keep the original subscription and check startup logs for the specific field causing an error. Get the basic configuration to load before restoring custom rules. Don’t delete an entire DNS or routing section just to clear one error; the client may start, but traffic could take a different route.
See how the core engines differ →Graphical clients provide an interface for importing subscriptions, choosing policies, setting system proxies, and managing permissions. Core engines such as mihomo execute the network configuration. The same core engine can work with different interfaces, and a client may change its core engine or defaults in an update. Screenshots alone can’t confirm that two setups behave identically.
Phones have additional system constraints. Android battery management may stop background services, iOS VPN configurations require system approval, and desktop clients may rely on helper services. To troubleshoot, first distinguish between an interface that won’t start, a core engine that can’t load its configuration, and a system tunnel that hasn’t been established.
Browse networking and system terminology →The mihomo project is licensed under GPL-3.0. Its public repository includes source code, issue discussions, and release history. An open-source license sets the terms for using and distributing code; it doesn’t mean every client using the core engine has the same interface, features, or maintenance schedule. Read the relevant project’s license file before modifying or redistributing its code.
Most users don’t need to compile the source code to use the client. Cloning the repository makes sense if you want to study configuration behavior, reproduce a bug, or contribute to development. Before reporting an issue, remove subscription URLs, node passwords, and personal network details. Include only the smallest configuration and logs needed to reproduce it.
Browse the mihomo project repository ↗Client updates, core engine updates, and subscription updates are three different things. A client update may change system integration, a core engine update may change how fields behave, and a subscription update may replace nodes and rules. If something breaks, first identify which layer changed recently. Don’t roll back the app, reset the network, and reimport every configuration all at once.
Keep a working configuration and a separate record of overrides. After an upgrade, check startup, DNS resolution, proxy groups, and your target app in order. A client that’s no longer maintained is better treated as a migration source than a default choice for a new device. Once the migration is complete and stable, remove the old app and any leftover proxy settings.
See migration paths from discontinued clients →Git must already be installed locally. This command downloads the source code only; it doesn’t install a graphical client or create a proxy configuration. See the repository documentation for build instructions and development dependencies.
git clone https://github.com/MetaCubeX/mihomo.git05 / NOTES
Once your basic connection works, explore client selection, migration, and proxy group setup. Each article focuses on a specific issue, helping you avoid rebuilding your whole setup to fix one problem. Keep your original configuration before making changes, and adapt examples to your client, core engine, and subscription.
When the original client is no longer updated, export your subscription and overrides first. Then choose a maintained alternative based on your device and needs. Finally, check the rules, DNS, and system permissions, and compare the settings between the old and new clients.
Read the guide →Explore how the select, url-test, fallback, and load-balance proxy groups work. Learn what interval and tolerance mean, and use YAML examples to compare automatic selection with failover.
Read the guide →Compare mobile clients by core engine, subscription imports, rule editing, TUN support, and interface. First decide whether you’re setting things up for the first time or migrating an existing subscription, then choose based on how you plan to use it.
Read the guide →