General Preparation Before Installation
Confirm the operating system architecture, configuration source, and network entry point first. This prevents package selection, subscription, and system proxy issues from being mistaken for one another.
Identify the OS, Architecture, and Client Role
Before downloading, note the operating system, version, and processor architecture. Most Windows devices use x64, while some newer devices use ARM64. On macOS, distinguish Intel from Apple Silicon. Android packages may be offered for ARM64, ARM, or universal architectures. On Linux, choose both the correct architecture and package type, such as deb, rpm, or an archive. A mismatched architecture commonly causes the installer to refuse to run, an unsupported-system warning, or an immediate exit after launch. Do not assume a file is compatible merely because its name contains “64.” Check the processor type in system information, then return to the download page and select the matching package.
The Clash ecosystem generally has two layers: a core and a graphical client. The core reads YAML configurations, establishes connections, applies rules, and exposes proxy ports. The graphical client manages subscriptions, switches modes, controls the system proxy, and displays logs. A graphical client is the best choice for most desktop and mobile devices. Deploy the Mihomo core directly only on servers, routers, or Linux systems that require service-based operation. Clash Plus is the primary recommendation for every platform. Windows and macOS users can also choose Clash Verge Rev or FlClash, while Android users can choose Clash Meta for Android, FlClash, or Surfboard. Clash for Windows and ClashX Meta are no longer maintained. Use them only to migrate existing environments, not for new long-term setups.
Prepare a Subscription or Local YAML Configuration
Installing the client does not provide a working connection by itself; a configuration must also be imported. The two common inputs are a subscription URL and a local YAML file. A configuration provider generates the subscription URL, which the client uses to retrieve nodes, policy groups, and rules. Local files are useful for offline editing, rule experiments, or fixed configurations in controlled environments. Before importing, verify that the URL is complete and contains no extra spaces, line breaks, or nonstandard punctuation. Treat subscription URLs as sensitive data. Do not include them in public screenshots, forum posts, public browser bookmarks, or shared documents.
For initial testing, keep a simple configuration that has loaded successfully before. Complex configurations may include proxy providers, rule providers, scripts, sniffing, DNS overrides, and nested policy groups. Any unreachable remote resource can disrupt loading. First verify the client, system permissions, and proxy entry point with a basic configuration, then add advanced rules gradually. This is much easier to troubleshoot than importing every feature at once. Before updating a subscription, note the name of the current working configuration. If the new one fails to parse, you can switch back immediately instead of editing while the network is unavailable.
Understand the Difference Between System Proxy and TUN
System proxy mode usually writes HTTP and SOCKS proxy addresses to the operating system. Browsers and applications that honor those settings send requests to Clash. It is easy to deploy and toggle, but command-line tools, games, store apps, and software with its own network stack may bypass it. TUN mode creates a virtual network interface, allowing more TCP and UDP traffic—including applications that ignore system proxy settings—to enter the rule-processing pipeline. It provides broader coverage but requires elevated permissions and is more likely to conflict with other VPNs, virtual adapters, endpoint security software, and enterprise network policies.
| Check | System Proxy | TUN Mode | Recommended First Step |
|---|---|---|---|
| Required permissions | Modify system proxy settings | Create a virtual interface or service | Verify the system proxy first |
| Application coverage | Programs that honor proxy settings | More system traffic and UDP | Enable only when an app requires it |
| Common conflicts | Browser extensions and manual proxy settings | Other VPNs, virtual adapters, and firewalls | Use one traffic entry point at a time |
Create an Installation Record and Baseline
Before installation, temporarily exit other proxy or VPN tools and record whether the system can access common websites directly. After installation, leave TUN disabled. Import a configuration, select Rule mode, enable the system proxy, visit a regular webpage, and inspect the logs. This creates a clear baseline: whether the client starts, the configuration parses, the proxy port listens, the system proxy is written, and rules match. Complete one step before moving to the next so any failure can be isolated. Enterprise, campus, and managed devices may restrict service installation, VPN profiles, or network-setting changes, so confirm that the current account has the required permissions in advance.
Windows: Installation, System Proxy, and TUN
The main Windows variables are package architecture, network permissions, stale system proxy settings, and the virtual adapter service.
Choose a Package and Complete the First Launch
For a new Windows installation, choose Clash Plus first. Clash Verge Rev, FlClash, and Clash Nyanpasu are also available based on interface preference. Clash for Windows is no longer maintained; existing users should export or record their settings before migrating to an actively maintained client. Open Settings → System → About and check whether the system type is x64 or ARM64. Follow the architecture information shown on the current download cards. Do not mistake macOS or Linux archives, or Mihomo core files, for a Windows graphical client.
Windows may display a User Account Control prompt when you run the installer. Install the app in a standard application directory, launch it, and confirm that the main window opens fully before handling any firewall prompt. Allowing access on private networks is usually sufficient for home or office LAN use. Whether to permit public networks depends on the device’s environment. If double-clicking produces no window, check Task Manager for an existing process and inspect the system tray, since some clients start minimized. If no interface appears, check whether a security policy blocked the app instead of repeatedly installing several different clients.
Import a Subscription and Select a Policy
Open the client’s Configuration, Subscription, or Profiles page, find the import option, paste the complete subscription URL, and download it. A successful import normally displays a configuration name, update time, or policy groups. If the subscription appears but no policies are available, the remote content may not have downloaded, the response may not be Clash YAML, or parsing may have failed. Check the logs for HTTP status codes, YAML line numbers, and provider errors. Do not enable TUN yet, because configuration-level failures are unrelated to the virtual adapter.
After activating the configuration, open the Proxies or Policies page. Rule mode evaluates the configuration’s rules from top to bottom and is best for everyday use. Global mode sends connections through a selected policy and is useful for briefly testing whether a node works. Direct mode confirms whether the local network works without a proxy. For the first test, select Rule mode and explicitly choose a known working node in the main policy group. Automatic groups must complete health checks before selecting a result. If the test URL is unreachable, every item may appear timed out even though some real traffic still works. Compare browser access with connection logs before drawing a conclusion.
Enable the System Proxy and Verify the Port
When System Proxy is enabled, the client writes a loopback address and listening port to the Windows proxy settings. Open the system proxy page and confirm that the setup script or manual proxy state has changed. After visiting a website in the browser, look for its domain, matched rule, and final policy in the client’s connection list. If the browser works but a command-line tool does not, that tool probably does not read the Windows system proxy. In PowerShell, you can set environment variables for the current session. Replace the port with the mixed port shown in the client:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
curl.exe https://example.comClose the terminal window after testing to clear the session variables. Before making them permanent, verify which variables the tool supports so an obsolete local port does not remain in the system environment. You can also run netstat -ano or a PowerShell network connection command to confirm that the port is listening. If the port is occupied, the client log usually reports bind or address in use. Identify the process using it, or change the port consistently in both the configuration and client settings. Do not update only the interface while the configuration continues to declare the old port.
Enable TUN and Resolve Windows-Specific Conflicts
TUN usually requires installing a service or running with elevated permissions. Close other VPNs, game accelerators, and old Clash clients first, then follow the client prompt to install the service and enable TUN. Once active, the corresponding virtual interface should appear in the network adapter list, and connection logs should include more traffic from apps that ignore system proxy settings. If the entire system loses connectivity, disable TUN and confirm that the basic network returns. Then inspect DNS mode, the default route, service status, and the firewall. Do not reset the network, remove drivers, and edit the configuration simultaneously while offline; doing so destroys the baseline needed for comparison.
Windows routes and DNS can change after waking from sleep, switching between Ethernet and Wi-Fi, or joining an enterprise VPN. If connectivity is lost after wake, disable the system proxy, disable TUN, exit the client, then restart it and enable each feature in sequence. If access still fails after the system proxy is off, check the Windows proxy page for a stale address. Inspect the WinHTTP proxy if necessary, but do not confuse it with browser proxy settings. Running the client as administrator is also different from installing its system service: the former elevates only the current process, while the latter lets a background component manage the virtual interface continuously. Prefer the client’s built-in service installation process.
macOS: Chip Architecture, System Extensions, and Network Services
A successful macOS installation requires the correct chip architecture, plus attention to app quarantine, network extension authorization, and per-service proxy settings.
Identify Apple Silicon or Intel
Choose About This Mac from the Apple menu and inspect the Chip or Processor field. If it shows an Apple-series chip, select the Apple Silicon or ARM package. If it shows Intel, select the x64 package. Clash Plus is recommended for new installations, while Clash Verge Rev and FlClash are also available. ClashX Meta is no longer maintained and should be retained only for migrating an older setup, not as the default for a new environment. A mismatched package may refuse to open or run through a compatibility layer with additional resource use, so choose the correct architecture from the start.
Graphical clients are often distributed as disk images or compressed files. After opening the image, drag the app into Applications and launch it from there. Do not run it indefinitely from Downloads or a read-only disk image. If macOS asks you to confirm the source on first launch, open Privacy & Security in System Settings, locate the blocked app, and use the system approval process after confirming that the file came from this site’s download link. Do not disable system-wide security protections to bypass a single app prompt. The normal authorization path is sufficient and makes network extensions and background items easier to manage later.
Import the Configuration and Authorize the System Proxy
After launching the client, open Profiles, Configuration, or Subscriptions, paste the subscription URL, and update it. If macOS transforms special characters in the URL, first paste it into a plain-text editor and verify the entire line, then copy it into the client. Once downloaded, select the configuration as active and inspect its policy groups for nodes and policies such as DIRECT and REJECT. YAML parsing failures usually identify an indentation or data-type problem in the logs. A remote provider failure may affect only one rule set or node group, so distinguish main configuration loading from auxiliary resource updates.
When you enable the system proxy, macOS may request the current user password or biometric authentication to modify network settings. The proxy is normally written to the active network service, such as Wi-Fi or Ethernet. After switching services, the client may still show the toggle as enabled even though the new service has no proxy settings and traffic bypasses it. Turn the system proxy off and back on so the client writes settings for the current network. You can also open System Settings → Network → Current Network → Details → Proxies and verify that Web Proxy and Secure Web Proxy point to a local loopback address.
Terminal Applications and Local Network Access
Terminal tools such as curl, package managers, and development utilities do not always honor the graphical system proxy. Set variables for a single command or session, using the actual client port:
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
curl -I https://example.com
unset http_proxy https_proxyBefore adding proxy variables to a shell profile, decide whether they truly need to persist. If the laptop changes networks and the local Clash client is not running, permanent variables will keep terminal requests pointed at an unused local port. Enabling them per project or terminal session is safer. Treat LAN sharing with similar care. Enable Allow LAN only when other devices must connect, and consider the listening address, firewall, and trusted network range together. For local-only use, binding to the loopback address avoids an unnecessary LAN entry point.
TUN, Network Extensions, and Sleep Recovery
When enabling TUN, the client may request permission to install a helper service or add a VPN configuration. The corresponding network extension should appear in System Settings, and the menu bar may show VPN status. If the toggle immediately switches off after the first approval, check Privacy & Security for another pending item, then restart the client. On company-managed Macs, a configuration profile may restrict network extensions. Standard users cannot remove that restriction and should ask the device administrator which extensions are allowed.
Traffic paths may overlap when macOS runs iCloud Private Relay, an enterprise VPN, another proxy app, or a network filtering extension alongside Clash. For troubleshooting, keep only one traffic-management tool active, disable the other network extensions, and test from system proxy mode. If DNS fails after waking from sleep while direct IP connections still work, check whether the DNS and TUN interfaces were restored. If no connections appear in the log, inspect network service switching and system proxy settings. Disable the system proxy and TUN before quitting the client to reduce the chance of macOS retaining a dead local port after an abnormal exit.
A Connected status only means the local component has started; it does not prove that traffic uses the expected policy. Find the requested domain under Connections or in the logs and confirm the matched rule and policy group. A browser proxy extension can override system settings, so disable it temporarily when establishing a baseline. For more on rules and policy groups, read Policy Group Types Explained. This helps avoid treating an automatic group’s health-check result as a verdict on the entire network.
Android: VPN Permission, Background Operation, and Per-App Routing
Android clients route traffic through the system VPN interface, while stability also depends on battery optimization, background restrictions, and vendor-specific network policies.
Installation and Initial VPN Authorization
For a new Android installation, choose Clash Plus first. Clash Meta for Android, FlClash, and Surfboard are also available. Before downloading, check the Android version and processor architecture in system information. If the download page offers ARM64, ARM, and universal packages, most recent mainstream devices use ARM64, but the device information is authoritative. When installing a package from a browser, Android may ask you to allow that browser or file manager to install unknown apps. Revoke that source permission after installation so temporary installation access does not remain enabled.
The first time you connect, Android displays a VPN confirmation dialog. This is the standard system process for creating a local virtual network interface. After approval, a VPN indicator usually appears in the status bar. If another VPN, a work-profile VPN, an ad-blocking tool, or a private DNS app is already active, Android may allow only one to control the interface. Decide which tool should own the main traffic entry point. Repeatedly switching among several VPN apps can cause toggles to turn off automatically, brief network outages, and inconsistent DNS paths.
Import a Subscription and Update the Configuration
Open configuration management and import by URL or file. After pasting a subscription from the clipboard, verify that the scheme, path, and query parameters are complete. Some keyboards add a trailing space, while messaging apps may truncate long URLs; either can cause the request to fail. After a successful import, explicitly select the new configuration as active. Saving a subscription without activating it is a common reason a configuration appears in the list but contains no visible nodes. Whenever possible, update subscriptions over a stable connection with the VPN temporarily disconnected, preventing rules in the old configuration from routing the update through a broken policy.
Once nodes and policy groups appear, choose Rule mode and an explicit policy before starting the VPN. Visit a webpage, open the logs, and verify which rule matched the domain. Android apps may use QUIC, HTTP/3, or their own DNS, so their behavior can differ from a desktop browser. If one app fails, establish a baseline with the system browser first, then check whether the app is excluded by per-app settings, uses only IPv6, or has its own secure DNS enabled.
Background Operation and Battery Policies
The most common mobile issue is not configuration parsing, but Android restricting the client after the screen locks. In the system battery settings, allow the current Clash client to run in the background and grant any required auto-start or background activity permission. Depending on the manufacturer, these options may be labeled Battery Optimization, Background Usage Limits, Auto-start Management, or App Launch Management. Locking the app in the recent-apps screen does not replace system-level background permission; it generally only reduces the chance of manual cleanup. Also verify that Data Saver does not block the client from using mobile data.
If the connection drops a few minutes after the screen locks and returns immediately after unlocking, check battery optimization and background restrictions first. If Wi-Fi works but mobile data does not, inspect mobile data permission, IPv6, and carrier network behavior. If every network fails after a consistent interval, review node availability and health checks in the subscription. A persistent mobile VPN naturally creates some background activity, while large rule sets, DNS queries, frequent health checks, and high connection counts increase battery use. See Troubleshooting Excessive Mobile Battery Use to distinguish expected consumption from a faulty loop by reducing unnecessary tests, retaining a stable policy, and inspecting background wake-ups.
Per-App Proxying, Bypass Rules, and LAN Access
Android clients commonly support per-app proxying with options such as “Proxy selected apps only” and “Exclude selected apps.” Define the goal before building the list. Use inclusion mode when only a few apps should enter Clash. Use exclusion mode when most apps need rule processing but banking or LAN tools should connect directly. The two modes have opposite meanings, so review the list whenever you switch. App updates or reinstalls may change internal identifiers. If one app suddenly bypasses Clash, reopen the list and verify its selection.
If printers, TVs, router admin pages, or other LAN devices are unreachable, first confirm that private network addresses use DIRECT and check whether the client offers a LAN bypass option. Common private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16, though the network may also use local IPv6 addresses. Do not switch everything to Direct mode just to reach one LAN device and then forget to restore the previous mode. Find the destination address in the log and add an explicit rule or adjust the LAN bypass setting.
If Android says the VPN is connected but there is no internet access, stop the connection and verify that the phone’s base network works. Restart the client and test only with the system browser. If the log contains no requests, check VPN permission and per-app exclusions. If requests appear with DNS errors, inspect DNS configuration and Private DNS. If they match a proxy but time out, check the policy and node. Layered diagnosis is more effective than repeated reinstalls, because reinstalling does not repair a subscription, background policy, or conflicting VPN app.
iOS: Clash Plus, VPN Configuration, and System Restrictions
iOS manages connections through system network extensions. The installation source, VPN authorization, on-demand connections, and system network services are the main areas to verify.
Install Clash Plus from the App Store
The download page links iPhone and iPad users to Clash Plus in the App Store. The official client website is clashplus.io. Open the store listing, install through the standard system process, and launch the app from the Home Screen. iOS does not require selecting a processor architecture or manually installing desktop package formats. If the store page does not load, verify the Apple ID, network connection, and App Store services before treating it as a client issue.
On the first connection, iOS asks to add a VPN configuration and requires the device passcode, biometric authentication, or system confirmation. Once approved, the profile appears under Settings → General → VPN & Device Management or the VPN page used by the current iOS version. This authorization only allows Clash Plus to create a network extension; it does not mean the subscription has loaded or a policy is available. If authorization is denied, the client may still open and display configurations, but it cannot route traffic. Return to the connection toggle to trigger the system prompt again.
Import a Subscription and Check Configuration Status
Open configuration management in Clash Plus and import the subscription by URL. Keep the address complete when copying it, and never post it publicly. After importing, confirm that the configuration appears in the list and explicitly select it as active. If the download fails, use Safari to check whether the current network can reach the subscription domain, but do not expose the subscription contents. If the download succeeds without any policy groups, inspect the client error details and distinguish a YAML parsing failure, remote resource failure, or empty configuration.
Choose Rule mode, select a node in the main policy group, and connect. For the first test, open a regular webpage in Safari, then inspect the client’s connection records. If they show the domain, rule, and policy, the network extension is receiving traffic. If the list is empty, verify that the VPN is truly connected, that no other network extension has taken over, and that on-demand rules have not excluded the current network. Some apps retain old connections. After switching policies, fully close and reopen the affected app so it establishes a connection over the new path.
On-Demand Connections, Cellular Data, and Local Networks
On-demand connections can start the VPN automatically when the network changes or an app makes a request. Use them only after the configuration has proven stable. During initial setup, control the connection manually and verify the configuration, policy, and DNS before enabling automation. Otherwise, repeated automatic connection attempts can hide the real error: the interface may remain stuck on Connecting, making it difficult to tell whether parsing failed, a node timed out, or the system extension failed to start. After enabling on-demand connections, test both Wi-Fi and cellular data because their IPv6, DNS, and access policies may differ.
If Wi-Fi works but cellular data does not, confirm that Clash Plus can use cellular data and that Low Data Mode is not restricting background activity. If cellular data works but a particular Wi-Fi network does not, that network may require a captive portal, block VPN traffic, or have local DNS that conflicts with the configuration. On public Wi-Fi, complete browser authentication with the VPN turned off before starting Clash Plus. Captive portals are usually hosted on the local network and may not appear correctly if proxy rules take over from the beginning.
iOS may request Local Network permission when accessing home devices. Allow it when discovering or connecting to printers, media devices, and LAN services, and confirm that rules send private addresses to DIRECT. If local access is not needed, there is no reason to broaden permissions while troubleshooting internet access. Review the permission independently in system privacy settings. After changing it, restart the relevant app so existing connections are recreated under the new permission state.
Manage Interactions Between System Network Services
iOS may run iCloud Private Relay, Limit IP Address Tracking, enterprise content filtering, or another VPN profile at the same time. Any of these can affect DNS and connection paths. When troubleshooting, create a single-variable environment: temporarily disable other network extensions, keep only Clash Plus active, and test with one manually selected policy. If the base connection returns, re-enable the other features one at a time and note which change causes the issue. Do not rely on the VPN icon in the status bar to identify the app controlling traffic. Open the system VPN page and check the active connection name.
Old connections may need to be rebuilt after leaving Airplane Mode, switching between Wi-Fi and cellular data, or keeping the device locked for a long time. Disconnect and reconnect inside Clash Plus first. If there is still no network, turn off the VPN, verify the base connection, and restart the client. If the logs show DNS timeouts while proxy connections work, check whether the configured DNS servers suit the current network. If the selected policy times out, compare it with a manual node. When only one app fails and Safari works, consider cached connections, regional system services, per-app rules, or the app’s own networking implementation before deleting the entire configuration.
Linux: Graphical Clients and Mihomo as a System Service
Desktop Linux can use Clash Verge Rev or FlClash, while servers and routers are better suited to running the Mihomo core directly.
Choose a Package Format for Desktop Linux
For a graphical Linux client, follow the download page and choose Clash Verge Rev or FlClash. Before installation, run uname -m to identify the architecture. The common output x86_64 corresponds to AMD64, while aarch64 corresponds to ARM64. Debian, Ubuntu, and derivatives normally use deb packages; Fedora and RHEL-based distributions may use rpm. For other distributions, follow the package formats and project instructions listed on the download page. Do not mistake a Mihomo server archive for a graphical desktop client. Their startup methods, configuration directories, and system proxy management are different.
Install a deb package through the system software center or from the terminal. Replace the example filename with the actual downloaded file:
sudo apt install ./clash-client-amd64.deb
uname -m
systemctl --user statusA package manager resolves dependencies as part of installation, making it more suitable for everyday use than invoking a low-level unpacking command directly. On first launch, the desktop may ask about the keyring, background operation, or network permissions. Import the configuration and test the local proxy before enabling TUN. GNOME, KDE, and other desktops differ in their support for system proxy settings, and terminal programs usually do not read desktop proxy settings automatically. Use environment variables or application-specific settings to verify them.
Desktop Proxy and Terminal Environment
After enabling the system proxy in the graphical client, check the desktop network settings and confirm that the HTTP, HTTPS, and SOCKS addresses point to local ports. Visit a page in the browser and inspect the connection log. For terminal testing, set temporary variables:
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"
curl -I https://example.com
unset HTTP_PROXY HTTPS_PROXY ALL_PROXYSupport for uppercase and lowercase variable names depends on the tool. Some read lowercase names, while others read uppercase names. Do not set several protocols to different ports without understanding the application’s behavior, or requests may follow an unexpected path. Package managers, container services, and systemd services do not necessarily inherit variables from an interactive shell. Declare proxy settings separately in the relevant tool or service configuration, and remove them when no longer needed.
Run the Mihomo Core Directly
Servers, secondary routers, and hosts without a desktop environment can run Mihomo directly. Create a dedicated user and configuration directory, place the executable in a controlled path, and save the configuration as YAML. For the first launch, run it in the foreground with a test configuration and inspect the parsing results. Do not hide it in the background immediately. The following commands show the general pattern; adjust paths to match the system:
mkdir -p "$HOME/.config/mihomo"
cp config.yaml "$HOME/.config/mihomo/config.yaml"
chmod 600 "$HOME/.config/mihomo/config.yaml"
mihomo -d "$HOME/.config/mihomo"Foreground logs reveal configuration parsing, listening ports, rule providers, and DNS initialization. After confirming there are no errors, create a systemd service. Specify an explicit working directory, configuration directory, and service user instead of running with unnecessary elevated privileges indefinitely. If TUN is required, the service account needs permission to create network interfaces and modify routes. Configure those capabilities according to the distribution’s security model rather than handing every operation to root.
[Unit]
Description=Mihomo Network Service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=3
[Install]
WantedBy=multi-user.targetFirewall, Listening Addresses, and DNS
For local-only use, bind mixed-port, the controller port, and the API to a loopback address. Enable Allow LAN and permit a defined source range in the firewall only when the proxy must serve other devices on the LAN. Binding the controller to all addresses without access controls unnecessarily exposes the management interface. On a server, distinguish inbound proxy ports, DNS listening ports, and external application ports. Use ss -lntup to inspect the actual listeners and confirm that no ports conflict.
Linux DNS may be managed by systemd-resolved, NetworkManager, a desktop service, or container networking. If domains fail under TUN while direct IP connections work, inspect resolvectl status and the client logs to determine where queries are going. Repeatedly overwriting /etc/resolv.conf is usually temporary because the network manager regenerates it. Instead, assign clear responsibility for DNS: either Mihomo intercepts and resolves queries, or the system resolver handles them before rule processing. Avoid having two services listen on the same address.
Before upgrading the core or replacing a configuration, test the new configuration and retain the currently bootable executable. If the service fails, inspect logs with journalctl -u mihomo, focusing on YAML parsing, permissions, directories, ports, and network capabilities. Router deployments also involve forwarding, policy routing, and LAN DNS. Read Mihomo Router Deployment Overview first, identify whether traffic enters through a primary router, secondary router, or a directly running core, and only then modify the production network.
General Configuration: Ports, Modes, DNS, and Rule Verification
Interfaces differ by platform, but the core workflow is the same: traffic enters through a listener, passes through DNS resolution and rule matching, then exits through a specific item selected by a policy group.
Understand the Minimum Configuration Structure
A working configuration must define a proxy entry point, operating mode, proxy nodes or providers, policy groups, and rules. A graphical client may store some settings in its own database, so interface-level port, TUN, and DNS overrides may not appear in the subscription YAML. When troubleshooting, identify the source of the effective configuration: the original subscription, client overrides, or the final output of a merge script. Looking only at the downloaded source file may not explain the client’s actual behavior.
mixed-port: 7890
mode: rule
allow-lan: false
log-level: info
proxies:
- name: example-proxy
type: socks5
server: 192.0.2.10
port: 1080
proxy-groups:
- name: PROXY
type: select
proxies:
- example-proxy
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- GEOIP,LAN,DIRECT
- MATCH,PROXYThe addresses in the example are for documentation only and are not usable services. mixed-port accepts both HTTP and SOCKS connections, which simplifies desktop app setup. mode: rule lets the rules determine the route. allow-lan: false restricts use to the local device. Rules are evaluated from top to bottom and stop at the first match, so specific domains and LAN rules must appear before the final MATCH rule. If the client keeps using old results after an edit, reload the configuration and test with a new connection. Existing long-lived connections may not switch paths immediately.
A Policy Group Is Not Just Another Name for a Node List
A select group requires a manual choice. url-test chooses based on health checks. fallback uses the first available item in order. load-balance distributes separate connections across multiple exits. Latency shown by an automatic group reflects one probe request at one moment, not the full experience of browsing, downloading, or streaming. Results can be misleading if the probe URL is unreachable, a node restricts test traffic, or the device limits background activity. Use How Clash Latency Tests Work to interpret the numbers, then verify important traffic with real requests.
Policy groups can also reference one another. For example, an App Policy group may point to Auto Select, which then contains several nodes. If a log shows only the final matched group, inspect the group’s current selection. Changing the upper-level group may have no effect if the lower-level group still uses the same node. If an automatic group switches too often, its interval may be too short, its tolerance too small, or the network unstable. The goal is a stable, explainable path—not the largest possible stack of automatic selection layers.
DNS Modes and Resolution Paths
DNS determines which address a domain resolves to and affects whether domain-based rules match accurately. In system proxy mode, some apps send the domain to the proxy while others resolve it locally first. TUN mode may also intercept DNS so queries are handled by the core. In fake-ip mode, the core assigns reserved addresses to domains and stores an internal mapping, making domain recovery and rule matching easier. redir-host behaves more like resolving a real address before processing it. LAN services, game platforms, device discovery, and some security tools may be sensitive to fake-ip. Add affected domains to a filter so they use real resolution instead of disabling the entire DNS feature.
Diagnose DNS by symptoms. If domain requests fail but direct IP access works, focus on resolution. If the logs contain no DNS queries, another app or system service may be handling them. If the returned address is correct but the connection times out, the issue has moved to the routing or exit layer. With encrypted DNS, also consider how the DNS server’s own hostname is resolved; otherwise, you can create a loop in which the proxy needs DNS that itself requires the proxy. Keep at least one basic resolution path compatible with the current network, and use logs to confirm where queries actually go.
Use Logs for Repeatable Verification
To verify a rule, choose one target domain, clear the log or note the current position, and make one new request. Record the source app, destination domain or address, matched rule, policy group, and final node. If nothing is logged, the traffic never entered Clash; check the system proxy, VPN or TUN, and the app’s own settings. If it matches DIRECT when a proxy is expected, inspect rule order, domain format, and rule provider status. If it reaches the expected policy but the connection fails, investigate the node, DNS, IPv6, and destination service.
| Symptom | Check First | Next Step |
|---|---|---|
| Target request absent from logs | System proxy, VPN, TUN, and per-app settings | Confirm the traffic entry point |
| Rule match differs from expectations | Rule order, domain, and provider status | Retest with a more specific rule |
| Correct match, but connection times out | Current policy selection, node, and DNS | Compare with a manually selected node |
| Only a few apps fail | App proxy support, QUIC, and IPv6 | Compare with the system browser |
The info log level is sufficient for everyday use. Increase verbosity briefly while investigating an issue, then restore it to avoid generating excessive records. Before sharing logs, remove subscription URLs, credentials, node addresses, and personal domains. Every configuration change should test a specific hypothesis, such as whether DNS causes the failure, rather than replacing nodes, rules, and network modes at once. One variable and one test request at a time is the most important experimental method in this manual.
Common Configuration Issues and Layered Troubleshooting
Divide failures into six layers—base network, client process, configuration loading, traffic entry point, rules and policies, and destination connection—to avoid unnecessary reinstalls.
No Internet Access After Starting the Client
First, disable the system proxy and TUN, or disconnect the mobile VPN, then confirm whether the device’s base network returns. If access still fails, stale system proxy settings, unrecovered DNS, a network outage, or another active VPN may be responsible. On desktop systems, check whether the proxy page still points to an old 127.0.0.1 port. On mobile devices, inspect the status bar and system VPN page. On Linux, check environment variables, routes, and the resolver. Restart Clash only after the base network works again.
Second, start only the client without routing system traffic through it. Confirm that the configuration loads and the proxy port is listening. Third, enable the system proxy or VPN, open a target in the system browser, and watch the logs. An empty log indicates an entry-point problem. DNS errors point to resolution. A timeout after a policy match points to the selected node, which should be compared with a manual choice. These steps turn “no internet” from a vague outcome into a specific layer. For focused answers organized by question, continue to the FAQ.
Subscription Updates Fail or No Nodes Appear After Import
First, verify that the subscription URL was copied in full and that the base network can reach the subscription service. If the client is using an old configuration, its rules may send the update through a dead node; disconnect the proxy temporarily and try again. An HTTP error means the remote request did not return the expected content. A YAML parsing error means content was downloaded but its format or fields are invalid. A provider error may affect only a remote node group or rule set. These errors require different fixes and should not all be treated as a broken client.
If no nodes appear after import, confirm that the configuration is active and check whether its proxy groups are empty. Some subscriptions return only a base fragment and require client-specific processing. Others return a login page or message instead of YAML. Do not repeatedly save webpage error content as a configuration and import it. If an older configuration still works, keep it as a recovery path and ask the configuration provider to confirm the subscription status. Deleting every configuration also removes the working baseline and makes diagnosis harder.
System Proxy Works, but TUN Will Not Start
If the system proxy works, the configuration, nodes, and basic rules are probably sound. The remaining scope is permissions, services, virtual interfaces, routes, or DNS. On Windows, check whether the client service is installed, the virtual adapter was created, and security software blocked it. On macOS, verify the network extension and VPN profile authorization. On Linux, inspect the service user’s network capabilities, kernel modules, firewall, and policy routing. On mobile devices, the system VPN is the primary traffic entry point, so check whether another VPN has taken control.
If enabling TUN immediately breaks connectivity, disable it to restore the system proxy baseline, then inspect the first startup error. Common causes include a missing default route, a conflicting DNS listener, strict routing that is incompatible with the local network, a broken IPv6 path, or another virtual interface with higher priority. TUN is not a performance switch that must always be enabled. If every required app honors the system proxy, system proxy mode already supports rule-based routing. Resolve TUN permissions and compatibility only when you need to capture apps that ignore proxy settings, UDP, or broader system traffic.
Node Latency Looks Normal, but Websites Are Still Slow
A latency test is usually a short request that covers only part of DNS resolution, connection setup, and access to the probe target. Real webpages also depend on congestion, packet loss, TLS setup, destination location, concurrent assets, and throughput. Do not choose a node from a single number. Compare stability across several tests and validate with real traffic. Frequent switching by an automatic policy group can also interrupt long-lived connections. Sensible tolerance and check intervals matter more than chasing the lowest momentary latency.
If only one website is slow, inspect its matched rule and policy and confirm that it is not assigned to an unsuitable group. If every website is slow, compare DIRECT with a manually selected node to separate local network problems from proxy exit issues. If the browser works but video or downloads are slow, the app may use UDP, QUIC, or multiple parallel connections. Address obvious signs such as repeated retries, DNS timeouts, or frequent policy changes in the logs before switching clients.
Configuration Changes Do Not Take Effect
First, confirm that you edited the active configuration rather than a subscription cache, duplicate, or unselected file. Subscription updates may overwrite direct local edits, so persistent customization should use the client’s supported override, merge, or script mechanism. After saving YAML, reload it and inspect the logs for syntax errors. YAML is sensitive to indentation, list markers, spaces after colons, and data types. Rule targets must also match policy group names exactly; differences in capitalization or characters can prevent loading.
Next, create a new connection. Existing browser pages, long-lived messaging sessions, and downloads may remain on the old path; changing modes does not rebuild every open connection. Close the relevant app or wait for the connection to end before testing again. DNS caches may also retain old results. Try a domain that has not been visited before deciding whether to clear the system cache. Evidence that a change took effect should come from new rules and policies in the logs, not merely the position of a toggle.
Restore a Minimal Working State
When too many changes make the cause unclear, restore the setup in a fixed order. Disable TUN and the system proxy, exit other network tools, and verify the base network. Start Clash and load a simple configuration that has worked before. Manually choose one policy, enable the system proxy or mobile VPN, make a new request in the system browser, and inspect the logs. Once the baseline works, add custom DNS, rule providers, automatic policy groups, per-app routing, and TUN one at a time. Keep a verification result for every addition.
If reinstallation is still necessary, first record the client name, system architecture, configuration source, exact error text, and steps already attempted. Disable the system proxy, TUN, and background service before uninstalling so the system does not keep using a deleted local port. After reinstalling, do not import every old setting immediately; verify a minimal configuration first. For a complete first-install checklist, see How to Configure Clash for the First Time. The goal is not to avoid advanced features, but to reduce the number of variables until the system is observable, then rebuild a reliable setup one step at a time.