Choose a client for your system and import a subscription step by step. Explore cross-platform client picks, rule configuration, and Chinese-language guides.
TUN ModeRoute traffic through a virtual network interface
Allow LAN Connections
IPv6
Mixed Port
7897
Proxy Mode
RuleGlobalDirect
mihomo coreGPL-3.05 platformsYAML configuration
Clash Core Configuration
First, understand how traffic reaches the core; then decide where the rules should send it. The client provides the controls, while the core applies the configuration. Similar interfaces don't mean every configuration field is interchangeable.
Rule-Based Routing: Choose an Outbound Route by Destination
Rule mode works well for everyday use: the core checks domains, addresses, and rule sets in configuration order, then sends each match to its assigned outbound. Put specific domains first and catch-all rules last so broad conditions don't intercept requests too early. To troubleshoot, check the connection log for the rule that actually matched instead of relying on whether a page opens in your browser. The snippet below demonstrates direct-routing rules only; it does not include a proxy service. To use a proxy outbound, define the relevant nodes or proxy groups in the full configuration first, then reference them in your rules.
Switching Proxy Groups: Manual Selection and Automatic Testing
A proxy group bundles multiple outbounds into a target that rules can reference. Use select for manual choice, url-test to choose based on test results, or consider fallback for failover. Automatic tests measure response to a specified URL, not download bandwidth; the test URL, timeout, and network conditions all affect the result. The example uses direct as a sample member and defines an “Auto Select” group for rules to reference. In practice, replace it with node names present in your full configuration. Copying only the group name won't create a proxy connection.
proxy-groups:
- name: Auto Select
type: url-test
proxies:
- DIRECT
url: https://www.gstatic.com/generate_204
interval: 300
rules:
- MATCH,Auto Select
TUN Mode: Route Traffic That Bypasses the System Proxy
Some apps ignore system proxy settings, so enabling the system proxy alone won't capture their connections. TUN extends coverage by routing traffic through a virtual network interface, usually requiring administrator privileges or support from a client service. It changes how traffic enters the core; it does not automatically switch rule mode to global mode. First confirm that ordinary connections work, then enable TUN and check for conflicts with routes, DNS, and other virtual interfaces. The snippet below is for mihomo; adjust the network stack and permissions for your client and operating system.
Subscription Management: Full Configurations vs. Node Collections
A full-configuration subscription usually includes nodes, proxy groups, and rules. After importing it, you still need to select that configuration for it to take effect. proxy-providers load node collections and are not a substitute for a full configuration. Before updating, preserve local rules and overrides so they aren't overwritten by the next subscription update. The example shows a local provider structure: the file at the specified path must exist and contain a proxies list in the provider's expected format. You must also reference it with use in a proxy group in the full configuration. Remote subscription URLs may contain access credentials; don't share them publicly.
The controller API lets you inspect connections, switch proxy groups, and manage runtime status. It's useful for servers or standalone core deployments. Desktop clients usually include a management interface, so there's no need to expose an API for everyday use. Keep the listen address on the local loopback interface whenever possible. If remote access is essential, protect it with authentication and a controlled network path. The example listens locally; its port must not conflict with the mixed port. Configuring the controller API does not install a web dashboard: dashboard files, access, and authentication must be set up separately.
external-controller: 127.0.0.1:9090
log-level: info
System Proxy, Proxy Mode, and Ports: Know the Difference
The system proxy determines whether an app sends requests to the client. Rule, global, and direct modes determine how the core handles requests it receives. The mixed port is the local listening endpoint for HTTP and SOCKS connections. These settings solve different problems. If your browser isn't using the system proxy, switching proxy groups may have no effect. If a rule specifies direct, changing nodes won't change that request's route. Troubleshoot one layer at a time, from traffic entry to outbound, instead of changing several switches at once.
The settings window shown here is a static illustration. Port 7897 is a common example for a mixed port, not a value fixed across all clients. Use the port configured in your client. When setting a proxy manually in a browser or another app, the address is usually the local loopback address, and the port must match the client. After changing the port, check both system proxy settings and any proxy settings saved separately in apps. Sharing access over a LAN also involves the listen address and firewall; ordinary local use doesn't require enabling sharing.
Start by matching your operating system and processor architecture, then consider the features you need. Clash Plus is our top cross-platform recommendation; desktop users can also compare Clash Verge Rev and FlClash. The download page lists installers and system requirements.
Start with the system proxy for browsers and typical desktop apps. If an app ignores proxy settings, check client service support and TUN permissions. Try Clash Plus, or compare how Clash Verge Rev, FlClash, and Clash Nyanpasu handle configuration management.
Check your system architecture before installing, and don't confuse a desktop installer with a standalone core archive. The old Clash for Windows download is an archived option that is no longer maintained. Before migrating, back up subscriptions, rules, and scripts, then verify that the new client supports the fields you use.
Check About This Mac to see whether your Mac has Apple silicon or an Intel processor, then choose the matching installer. Clash Plus, Clash Verge Rev, and FlClash are worth comparing. System proxy settings are a good starting point for testing browser connections; TUN requires additional checks for permissions and routing.
Read the system's warning about the app's source before running it, and follow the project's release instructions. Don't leave system protections disabled just to open an app. If you're migrating from ClashX Meta, the download page indicates its archived status. Focus on subscription format, proxy group selection, and local overrides rather than copying every switch from the old interface.
Mobile devices usually route traffic through the system VPN interface, which requires your approval the first time you connect. Start by considering Clash Plus, then compare it with Clash Meta for Android and FlClash. Match the installer architecture to your device, and keep in mind that background operation may be affected by battery management settings.
If your phone already has another VPN app, check which app currently owns the connection to avoid mistaking a routing conflict for a node failure. Surfboard is another option on the download page, but its configuration format differs from Clash YAML. Check the provider's format to see whether a subscription can be imported; the URL suffix alone doesn't establish compatibility.
Clash Plus is our top pick, with an App Store link and the official site at clashplus.io on the download page. After installing, import your subscription and follow the app's prompts to authorize the VPN configuration. Seeing VPN as connected in system settings only confirms that traffic capture is active; it doesn't mean every outbound in your subscription is reachable.
Mobile permission models differ from desktop, so there's no need to copy desktop mixed-port and system-proxy steps. To test a connection, start with a specific destination, then check the app's connection log and proxy selection. Troubleshoot subscription update failures separately from connection failures: first check the URL and service status; for connection issues, inspect rules and outbounds.
Desktop users can choose between Clash Verge Rev and FlClash, installing the package that matches their distribution and package format. Desktop environments vary in their support for system proxies, and terminal programs may not use desktop proxy settings. Check environment variables, app-specific proxy settings, or TUN coverage as appropriate.
Consider the standalone mihomo core for servers and routers. A core deployment requires you to manage configuration paths, service startup, permissions, and logs yourself; there is no desktop interface to handle these tasks. First verify that the configuration loads in the foreground, then connect it to a service manager. Keeping startup logs is more useful than repeatedly reinstalling when troubleshooting.
Installing the app doesn't mean your connection is ready. Import your configuration, choose how traffic will be routed, then verify the result in the connection log. For your initial setup, keep the default settings and change one thing at a time.
01 / Configuration Source
Import a Subscription and Select the Configuration
Open the client's subscription or configuration page, paste your subscription URL, save it, and wait for the download to finish. When the configuration appears, set it as the active one and check that its proxy groups have loaded. Get subscription URLs from a trusted provider; a client cannot create a working proxy service on its own.
If you have a local YAML file, use the file import option. If the download fails, first check that the URL is complete and still valid, and that the response contains a configuration. Don't treat a login page or error page as a configuration file. Keep a copy of the original file so you can restore it if needed.
02 / Traffic Entry
Choose Rule Mode and Enable Traffic Routing
Start with rule mode, then choose an available outbound in any proxy group that requires manual selection. On desktop, enable the system proxy; on mobile, approve the VPN connection when prompted. Unless you have a specific need, leave LAN sharing off to avoid exposing an additional listener or widening access.
If an app doesn't appear in the connection list, check whether it ignores the system proxy. Enable TUN only if needed, and confirm administrator permissions, client service support, and DNS settings. Global mode can help with temporary comparisons while troubleshooting, but it shouldn't be the default fix for every problem.
03 / Verify the Connection
Check Connections and Troubleshoot Step by Step
Open the destination page while checking the client's connection log. Confirm that the request reached the core, matched the expected rule, and used the correct outbound. A latency test only indicates responsiveness to a particular test URL; it can't replace testing the actual site, download, or meeting app.
If it fails, note the time, destination, and relevant log details. Check in order: subscription loading, proxy entry point, DNS, rules, and outbound. Turn off the system proxy before closing the client; otherwise, apps may keep sending traffic to a local port that is no longer listening, leaving you without a network connection even after the client exits.
The Clash Open-Source Ecosystem and Configuration Sources
Assess whether a client is right for long-term use by looking at its public code, maintenance history, and predictable configuration behavior. This guide separates project history, core implementations, graphical clients, and subscription services so they aren't mistaken for a single product.
Project History: Legacy Names and Active Forks
The Clash ecosystem grew around rule-based proxies, leading to multiple core forks and graphical clients. After the original Clash project and some early clients stopped receiving updates, actively maintained forks continued to develop protocol support, DNS, and routing features. mihomo carries on the technical direction of Clash.Meta, so documentation may use names such as Clash, Clash Meta, and mihomo. Before following a guide, identify the core it describes and check whether its configuration fields apply to your client.
Screenshots in older guides can help you find a setting, but they don't confirm that a feature is still supported. Client menus, service installation methods, and default ports may have changed. When migrating from discontinued software, back up subscriptions, local rules, scripts, and settings separately. Verify a basic connection in the new client first, then restore advanced features step by step. Moving all the old configuration at once makes differences harder to track down.
How the Core and Client Work Together
The mihomo core parses configuration, matches rules, handles DNS, and establishes connections. The graphical client handles installation, subscription management, system proxy settings, and the user interface. A client offering a particular switch is not the same as the core supporting a particular field. Desktop apps may use a service process for privileged features, while mobile platforms are limited by network extensions or the system VPN interface.
The same YAML file may need adjustments in different clients. In addition to core differences, check whether the client overrides DNS, ports, or TUN settings, and how it resolves provider paths. Troubleshoot using the final active configuration, not just the original subscription file. When reporting an issue, include the client name, operating system, traffic-routing method, and relevant fields. This is more useful for reproduction than simply saying “Clash doesn't work.”
Open-Source Community: Verify Behavior in Code and Documentation
mihomo is released under the GPL-3.0 license, and its code, issues, and release history are available in the project repository. The license sets conditions for using and distributing the code; it doesn't mean every third-party client uses the same license or tell you whether a project is actively maintained. For a configuration field, start with the current core documentation. If you suspect a bug, search public issues for the same scenario.
This site doesn't publish download counts, ratings, or connection performance figures that can't be verified. Recommendations are based on platform, configuration, and usage needs—not fabricated statistics. Issues reported in a repository also shouldn't be treated as a software quality ranking: devices, configurations, and network conditions vary. Reproduction steps, a log timeline, and a minimal configuration are the best way to determine whether a problem lies with the core, client interface, or service provider.
Updates: Keep the App, Subscription, and Rule Sets Separate
Software updates change the client or core; subscription updates change nodes and configuration; rule-set updates change matching conditions. They are separate operations and may follow different schedules. Before upgrading, save a working configuration and local overrides, read the release notes, then check that DNS, TUN, and providers still work as expected. Changes to proxy group options after a subscription refresh don't necessarily mean the client was upgraded.
Subscription URLs may contain account credentials. Remove complete URLs and sensitive fields before sharing screenshots or logs. When asking someone to troubleshoot, share only the configuration snippets relevant to the issue. Don't post a full subscription in a public issue or replace your configuration with a stranger's. Referenced proxy groups, provider files, and scripts must all be present; copying a small syntax snippet alone won't make a working setup.
Get the mihomo Source Code
These commands are for reading or developing the core, not for installing a graphical client. For everyday use, go to the download page. If you need to compile from source, prepare the toolchain and target architecture according to the repository documentation.
git clone https://github.com/MetaCubeX/mihomo.git
Common Concepts: Understand the Terms Before Changing Settings
Does rule mode proxy only some websites? That depends on the active rules, not the mode name itself. Does TUN mean every request goes through a proxy? TUN captures traffic, but rules and proxy groups still determine its route. Does a responsive node test prove an app will work? The test and actual destination differ, so check the real connection too. Are a subscription and a configuration file the same thing? A subscription is a way to fetch content, which may be a full configuration or just a node collection. For help distinguishing these concepts, use the Concepts at a Glance, then return to your configuration.
Clash Configuration and Troubleshooting Guides
Explore three practical topics: migration, port conflicts, and traffic routing. First identify which layer is causing the issue, then follow the relevant steps. Avoid mixing a software switch, rule changes, and a system network reset into one troubleshooting attempt.
Review the risks of using a discontinued client, compare actively maintained alternatives by platform, and learn how to migrate subscriptions, override scripts, and custom rules intact.
Use system commands to identify processes occupying ports such as 7890 and 7897, check whether they are leftover instances, then change the port in the client and configuration file and update the system proxy.
Learn how a virtual network interface captures traffic from apps that ignore the system proxy. Compare the system and gvisor network stacks, with platform-specific permissions and setup steps for enabling TUN.