Check your operating system and processor architecture before choosing a package. Desktop GUI clients are suited to everyday use; core packages are for users who want to manage configuration and services themselves.
Install packages, clients, and subscriptions are three separate parts of the setup. Installing a client provides local configuration and traffic forwarding; connecting also requires a working service configuration. If you already have a subscription, check that its format is compatible with the selected core before importing it. For your first setup, keep the default ports and routing mode until the connection works, then adjust advanced options.
When migrating from an older client, avoid replacing the entire data directory. Back up your subscription URL, local rules, and proxy group selections first, then restore them one at a time in the new client. Scripts, override fields, and client-specific settings from an old configuration may not carry over unchanged. If errors occur, test the original subscription before adding local modifications.
These interface snippets explain settings; they are not interactive client windows. Menu locations vary by client, but the troubleshooting order can stay the same: configuration, core, listening ports, traffic entry point, and matching rules.
Network Settings
System Proxy
Listen Address127.0.0.1
Mixed Port7890
Route apps that follow system settings through the proxy
The system proxy points Windows to the client’s local listening port, making it suitable for browsers and apps that follow system settings. Import a working configuration and make sure the core is running before enabling it. If only some apps connect, that does not necessarily mean the subscription is invalid; some programs use their own network stack and need a separate proxy setting or TUN. The client toggle makes it easier to enable or disable the proxy than changing system settings manually. When troubleshooting, close other proxy tools first to prevent them from repeatedly overwriting the same setting.
Capture traffic from apps that ignore the system proxy
TUN routes traffic through a virtual network adapter and system routes, making it useful for command-line tools, games, and apps with their own network stack. On Windows, you may need to install the client service or grant the required permissions before enabling TUN. TUN changes the traffic entry point, not the routing policy; once traffic reaches the core, it is still handled according to the current mode and rules. After enabling it, check DNS, routes, and LAN access. If the connection has issues, disable other VPNs and test TUN on its own. Avoid changing multiple network settings at once, so the cause remains easier to identify.
Rule-based routing maps domains, destination IPs, and other match conditions to direct connections or proxy groups. Rules are usually checked from top to bottom, and the first match determines the route, so specific exceptions should come before fallback rules. PROXY in this example must be the name of a proxy group that actually exists in your configuration; it is not a built-in name. Unlike Global mode, Rule mode can handle different destinations separately; unlike Direct mode, it retains proxy routing. To test a rule, check the connection log for the matched rule and final policy instead of judging only by whether a webpage loads.
Keep remote subscriptions separate from local changes
Importing a subscription retrieves a configuration; selecting a configuration tells the core to use it. These are separate steps. After pasting a link, make sure it downloads and parses successfully, then activate that configuration and check its proxy groups. Remote updates may replace the original file, so local changes to ports or rules are better handled with the client's override or merge features. This is easier to maintain than editing the subscription file by hand each time. If an update fails, check the response and error message to distinguish an expired link, an incompatible format, or a failed request. Subscription URLs may contain access credentials, so do not share them publicly.
A mixed port accepts both HTTP and SOCKS proxy connections through the same listening endpoint. 7890 is a common example, but use the value in your current configuration. If a port is already in use, identify the process using it before deciding whether to close a duplicate client or choose another port. After changing it, update the system proxy and any app-specific settings too. LAN sharing requires additional checks for the LAN access option, listen address, firewall, and access controls. Sharing expands who can reach the service, unlike local-only use; restrict it to trusted networks and configure authentication. Never expose a listening service directly to the public internet.
The GUI client handles subscription management and system integration; the core handles protocol connections, DNS, and rule processing. Some clients let you switch cores or update channels, while others update the core with the installer. Check the actual client interface. Unlike changing a theme, switching cores can affect protocol support and configuration fields. Back up a working configuration first, read the relevant release notes, then confirm that the configuration parses and the core starts normally. For everyday use, prefer the stable channel. If a new field causes an error, check core compatibility instead of repeatedly importing the same subscription.
Verify the connection: check the entry point, then the destination
An enabled toggle only shows that the client tried to apply a setting; it does not mean every app is using the proxy. First, test a destination in a browser that follows the system proxy, then check whether the request appears in the connection log. If nothing appears, check the system proxy, app-specific settings, and listening port first. If a request appears but fails, check the proxy group selection, DNS resolution, and service configuration. This order separates local entry-point issues from problems connecting to the remote service.
Latency tests reflect results for a particular test address and method; they cannot replace testing in the apps you actually use. Browsing, downloads, and real-time communication have different requirements, and passing one test does not guarantee access to every destination. Note the failing app, time, current mode, and matched rule, then change one setting at a time. This is usually more effective than reinstalling the client, changing ports, and editing DNS all at once. Learn about node latency and connection testing →
Open-source ecosystem
How Clash, Meta, and mihomo are related
Client names, core names, and subscription formats often come up together. Understanding what each one does makes it easier to choose the right software and figure out where to start troubleshooting.
Core development and configuration compatibility
The Clash ecosystem includes a core and multiple independently maintained GUI clients. After the original Clash project was discontinued, community development continued; the Clash.Meta fork later adopted the name mihomo. Meta in older guides and mihomo in newer documentation are often related, but that does not mean every old configuration works with current clients. When reading a guide, check which core family and environment it refers to.
Configuration compatibility is about more than whether a YAML file can be read. Support for a protocol, DNS option, or rule type depends on the core implementation; subscription imports, service mode, and startup behavior depend on the client. If a feature is missing, first identify which layer provides it. Changing the GUI does not necessarily change core capabilities, and updating the core does not necessarily move the client's menus.
When comparing protocols, focus on what your service supports, whether your device has the resources to run them, and how well they fit your network conditions. A protocol's name alone does not predict connection performance, and no single protocol is the right choice for every situation. On mobile devices, consider background operation and battery use as well. Read the protocol and core reference →
Source code and release notes
Open-source repositories help you review a project's implementation, license, and issue discussions. The mihomo community maintains its source code and documentation, while release notes describe feature changes and fixes. This site provides download links and Chinese-language guides; it does not replace upstream release notes or treat clients maintained by different teams as the same product. When choosing a client, check its current maintenance status and compatibility with your system.
Before updating, save your local rules, override settings, and a working configuration. After installation, check that the core starts, then test the system proxy or TUN. If the update affects DNS, routes, or configuration syntax, retest each one separately. For everyday use, prefer stable releases; consider other channels when you need a specific fix. Do not assume a newer installer is the right choice without checking migration notes and support for your current system.
The commands below fetch mihomo source code for development or review; they are not steps for installing a GUI client. Git must already be installed on your device. If you just want to use the software, go to the downloads page and choose a client. Copying the commands does not run them or change your local proxy settings.
After installing the client, you still need to import and activate a working configuration. First check that it parses successfully and that its proxy groups are available, then verify the traffic entry point through the system proxy or TUN. Subscription download failures and proxy connection failures are separate issues with different error messages. Resolve import problems before testing the connection. See the subscription import steps →
Do I need to enable both the system proxy and TUN?
You do not need to enable both by default. Start by testing the system proxy with apps such as browsers that follow system settings; enable TUN from the guide if you need to capture traffic from other apps. How the two work together depends on the client and routing setup. Test them one at a time while watching for interference from other VPNs or virtual adapters. See the TUN setup steps →
Why did my local rules change after updating the subscription?
A remote subscription update usually fetches the original configuration again. If you put local rules directly in that file, an update may replace them. Store exceptions in the client's supported override or merge area, and check the order of the merged rules. When moving to another client, confirm how its override feature works instead of simply copying the file. See how to maintain rules →
Configuration and troubleshooting guides
Guides to subscription updates, app routing, and TUN
Once the basic connection works, dig into the issue you're facing. Before troubleshooting, note the client name, current mode, and error message. Remove subscription URLs and connection credentials before sharing logs.
Learn why subscription updates fail, including expired links, incompatible responses, and requests blocked by the proxy itself. Find out how to set an automatic update interval or force a manual refresh.
Loopback restrictions on Microsoft Store apps can prevent them from using the system proxy. Learn three ways to address this: the client's built-in tool, the CheckNetIsolation command, and TUN mode.
Learn how TUN virtual adapters differ from the system proxy, what to check for Windows service mode, DNS interception, and traffic capture, and which apps may need additional configuration.
