Clash Meta Setup Guide for Every Platform

CHAPTER 01 / PREPARATION

General preparation: clients, subscriptions, and permission boundaries

Understand the client, kernel, and subscription first

Clash Meta runs through three separate components. mihomo handles protocol connections, rule matching, DNS processing, and traffic forwarding. Clash Plus, Clash Verge Rev, and FlClash are graphical clients that manage the kernel. A subscription is a remote configuration generated by a service provider, usually containing proxy nodes, policy groups, and basic rules. Installing a client does not provide a working route by itself, and a subscription link is not an installer. They must be obtained separately and combined inside the client.

Choose a client based first on the operating system and processor architecture. Typical Windows PCs use x64 installers; ARM devices require a matching build. macOS downloads must distinguish between Intel and Apple Silicon. Android packages may be offered for arm64, arm, or universal architectures. Recent devices generally use arm64, but choose the universal build when the architecture is uncertain. On Linux, also check the distribution package format, CPU architecture, and whether a desktop environment is available.

Graphical clients are best suited to everyday desktop and mobile use. Running mihomo directly is more appropriate for servers, routers, containers, or environments where you write your own service-management scripts. Both approaches use similar core configuration semantics, but graphical clients may expose system proxy, TUN, overrides, and subscription updates as separate switches. When troubleshooting, identify whether the problem is in the interface, the kernel, or the upstream subscription instead of repeatedly reinstalling without addressing the actual cause.

Inspect the subscription response before importing

Copy the subscription link from the service provider’s account portal. Do not manually reconstruct a URL that was broken across lines in a chat window. Subscription links often contain access credentials, so treat them as private data and keep them out of public screenshots, repositories, and shared documents. If importing fails, open the link directly in a browser: a YAML response or configuration download shows that the address is at least reachable. A login page, expiration notice, access denial, or empty response points to a subscription-side problem.

A single service may offer Clash YAML, a generic share link, and formats for other clients. mihomo clients generally require a Clash- or mihomo-compatible configuration. Choosing the wrong format may cause a parse error, or may import nodes without any policy groups. Before switching formats, keep the working configuration. Give the new import a different name and verify that its proxy groups, rules, and DNS section are complete before replacing the old one.

Establish a configuration baseline you can revert to

After the first launch, keep the default port and operating mode. Import one configuration, select one proxy node, and test a browser connection. This creates a useful baseline: if the default setup works, later failures are more likely to come from TUN, overrides, DNS, or multiple active configurations. Do not enable system proxy, TUN, LAN sharing, and custom DNS all at once during the first test; otherwise it becomes difficult to identify which layer changed the traffic path.

System proxy and TUN are different entry points. A system proxy normally affects only applications that honor the operating system’s proxy settings, commonly through an HTTP or SOCKS port. TUN creates a virtual network interface and can capture traffic from more applications that ignore system proxy settings. The VPN switch on mobile systems generally serves a similar interception role. Both are useful in different situations: start with the system proxy for normal desktop browsing, and consider TUN for games, command-line tools, or applications that behave inconsistently.

CHAPTER 02 / WINDOWS

Windows: installation, system proxy, and TUN capture

Installation and first launch

Windows users can choose Clash Plus in the Windows downloads section, or select Clash Verge Rev, FlClash, or Clash Nyanpasu based on their preferred interface. Clash for Windows is no longer maintained and is listed only as an archived option. Before downloading, check the system type under “Settings → System → About”; standard Intel and AMD PCs usually require an x64 build. Installer and portable packages may store data in different locations. If you need to keep your configuration long term, avoid moving the portable directory after setup.

If Windows Security or the firewall prompts you during the first launch, grant access according to how you plan to use the client. Local-only use does not require public network access for proxy features; allow private network access only when devices on your LAN need to connect to this computer’s ports. Whether the client remains in the system tray after its window closes depends on its settings. Check the tray icon or Task Manager to confirm that it is still running rather than relying only on whether the window is visible.

If the installer cannot write to its target directory, first make sure the download reached the computer completely, then run it from a location where the user has write access. Administrator privileges are mainly needed to install drivers, register services, or create a TUN interface; do not treat “always run as administrator” as the default fix for every issue. Normal system proxy mode generally does not require persistent elevation, and excessive privileges can change the execution boundary between the client and the browser.

Import the subscription and verify that the configuration is active

In the client’s Config, Subscription, or Profiles page, find the “Import from URL” option, paste the subscription address, and give the configuration a recognizable name. After importing, explicitly select that configuration; appearing in the list does not mean it has been loaded. Open the Proxy or Proxies page, confirm that at least one policy group exists, and choose a node in the final outbound group. If you see only a node list without the usual selection group, the subscription may be incomplete or the client may not have loaded the correct configuration.

After selecting a node, enable the system proxy first. Windows should show a proxy server pointing to the local loopback address, with a port matching the client’s active listener. Never enter the subscription server address in Windows system proxy settings; the system proxy should point to the local client, which then connects to the remote service according to its configuration. Test in a newly opened browser window to avoid reusing an earlier connection. If webpages stop working after the client closes, check whether the system proxy was left enabled.

Common port fields include port, socks-port, and mixed-port. Graphical clients often use a mixed port that accepts both HTTP and SOCKS requests. When another program occupies the port, logs show a listener failure. The client may still appear to have started but cannot process connections. Exit other proxy software, choose an unused local port, and verify that the system proxy target was updated as well.

When to enable TUN

Some game platforms, command-line programs, store apps, and software with its own network stack do not read the Windows system proxy. If a browser works but a specific application always connects directly, enable TUN. The first activation may require a virtual adapter or service, so approve the system permission request explicitly initiated by the client. Afterward, check the logs for successful interface creation and inspect the system routing table for the corresponding route instead of relying only on the switch color in the interface.

TUN can conflict with other VPNs, virtual machine adapters, network accelerators, and corporate security software that also modify routes. During testing, keep only one traffic-capture tool active, then restore the others one at a time after basic connectivity works. If enabling TUN breaks LAN sharing, printers, or corporate intranet access, check that private addresses remain DIRECT in the rules and that the bypass list includes the actual internal subnets. After disabling TUN, wait for the interface and old connections to be released before testing again.

netsh winhttp show proxy
ipconfig /flushdns
netstat -ano | findstr LISTENING

CHAPTER 03 / MACOS

macOS: architecture, network services, and system extensions

Choose an Apple Silicon or Intel build

Before downloading on macOS, open “About This Mac” and check the chip information. Choose an Apple Silicon or arm64 build for Apple chips, and an x64 build for Intel processors. In the macOS downloads section, Clash Plus is the preferred option, with Clash Verge Rev and FlClash also available. ClashX Meta is no longer maintained and is best reserved for setups that need to keep an existing configuration temporarily. Choosing the wrong architecture may prevent the app from launching or make it rely on translation with additional behavioral differences.

Move the app to the Applications folder after downloading, then launch it from there. Running directly from a mounted disk image or temporary directory can make updates, data locations, and permissions unreliable. When macOS first opens an app downloaded from the internet, review the security prompt and confirm that its source matches the client linked from this site. If macOS blocks it, check the record under “System Settings → Privacy & Security” and use the system-provided approval option.

Client data is usually stored within the user Library, and uninstalling the app itself does not necessarily remove subscriptions and settings. Before changing clients, record the subscription source, active policies, and custom overrides, then quit the old client. Do not let two clients manage the system proxy simultaneously: the later program may overwrite the proxy port, and quitting it may restore values that belong to an already inactive client.

System proxy and network services

macOS stores system proxy settings per network service, so Wi-Fi, Ethernet, and other interfaces may maintain separate values. When a client enables the system proxy, it generally configures web proxy, secure web proxy, and SOCKS proxy settings for the current service. If the connection behaves differently after switching from Wi-Fi to Ethernet, check whether the new service is also managed by the client. Enterprise automatic proxy configuration files may coexist with manual settings, so first determine which source should take effect.

Check proxy status in the system network details, or use a command to read the current settings. The proxy server should be 127.0.0.1 or another local loopback address, with a port matching the client. If the network breaks after the client exits, reopen it and disable the system proxy, or remove the leftover settings in System Settings. Deleting the app without restoring the system proxy leaves browsers sending requests to a local port with no process listening.

scutil --proxy
networksetup -listallnetworkservices
lsof -nP -iTCP -sTCP:LISTEN

Terminal tools such as curl, package managers, and development tools do not always follow the graphical system proxy. For a temporary test, set proxy environment variables only for the current terminal session and clear them afterward. Replace the port with the client’s actual mixed port; example values are not universal requirements.

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_PROXY

TUN, system extensions, and local networks

Enable TUN in the client when you need to capture applications that ignore system proxy settings. macOS may request administrator credentials, approval for a network extension, or permission to add a VPN configuration. Confirm each request according to the object named in the system dialog. If permission was previously denied, review Privacy & Security, Network Extensions, or VPN settings. When the switch is on but interface creation fails, logs usually identify a permission, service, or routing error.

Running a corporate VPN, container network, or virtual machine software alongside Clash on macOS can make multiple virtual interfaces compete over the default route or DNS. Close other traffic-capture tools first and verify the result with Clash running alone, then restore only the software you need. If the corporate intranet depends on a specific DNS server or search domain, TUN DNS capture may change the resolution path. Keep internal domains and subnets on DIRECT and send their queries to a server that can resolve internal names.

When LAN access fails, do not send every private address through the proxy. Home routers, printers, file shares, and development devices usually belong on DIRECT. The allow-lan setting controls whether other devices can connect to the local proxy port; it does not determine whether this computer can access the LAN. LAN routing is primarily controlled by rules and routes. Enable LAN listening only when proxy sharing is intentional, and restrict the network scope with the system firewall.

CHAPTER 04 / ANDROID

Android: app installation, VPN capture, and background operation

Installation and subscription import

On Android, use the Android downloads section to choose Clash Plus first, or use Clash Meta for Android, FlClash, or Surfboard. When packages are separated by architecture, recent mainstream devices usually use arm64, while older devices may require an arm build. If you cannot confirm the architecture, choose the universal package when available. If Android asks the browser or file manager for permission to install apps, grant it only to the source used for this installation and disable it afterward if appropriate.

After the first launch, choose Import from URL on the configuration page, paste the subscription link, and wait for it to parse. Mobile networks may briefly switch during the initial request, so test over both Wi-Fi and cellular data if importing fails. After the configuration downloads successfully, set it as the active profile and choose a node in the proxy group. Seeing a profile name alone does not mean the VPN is connected. Traffic capture is established only after the status bar shows a VPN indicator and the client logs begin processing connections.

When importing through a QR code, verify that it contains a subscription URL rather than a single-node share link. A single-node link may be recognized by the client but usually lacks complete rules and policy groups. Scanning requires camera access, while recognizing a code from the photo library requires photo access. If you prefer not to grant those permissions, copying the URL directly is clearer. Delete temporary screenshots containing subscription QR codes after importing to avoid retaining them in synced photo libraries.

Android VPN and per-app routing

Android clients generally capture traffic through the system VPN interface. On the first connection, Android displays a VPN authorization dialog; the client cannot create the interface until you approve it. The system usually permits only one ordinary VPN at a time, so another VPN, filter, or firewall using the local VPN interface will be disconnected. If the connection button repeatedly returns to the stopped state, check whether another app is continuously competing for VPN access.

Some clients provide per-app proxying or bypass lists. Rule mode decides the outbound path based on domains, IPs, and rule sets; per-app routing decides which apps enter the VPN. They operate at different layers. An app placed on the bypass list never enters mihomo, so its traffic cannot be processed by subsequent domain rules. When troubleshooting one unavailable app, check the per-app list first, then rule matches, and finally whether the selected node supports the app’s protocol and network environment.

LAN device discovery, casting, and printing rely on multicast or local subnets and may be restricted after VPN capture is enabled. First verify that private addresses use DIRECT and allow LAN access if the client supports it. Even with correct rules, some apps change their discovery behavior based on Android VPN state. Temporarily disconnect the VPN to compare results and determine whether the issue is a rule error or an application limitation involving the virtual network.

Background operation, battery saving, and network changes

Android manufacturers’ battery-saving policies may stop a client’s background process after the screen turns off. Typical symptoms are a working connection immediately after setup, followed by a disappearing VPN icon or direct connectivity after the phone has been locked for a while. In system app settings, allow background activity and change the battery policy to Unrestricted or its equivalent. Lock the app in recent tasks if the system supports it. Names vary by vendor; the practical test is whether the VPN service survives screen-off and network changes.

When switching from Wi-Fi to cellular data, existing TCP connections cannot continue over the old network path, so a brief interruption is normal. If service does not recover, reconnect from the client instead of repeatedly toggling airplane mode. With “Always-on VPN” enabled, Android may also block connections that do not use the VPN. If the client fails to start, all networking can be blocked. Before enabling this policy, confirm that the client starts reliably after a reboot.

Mobile DNS problems often appear as apps reaching an IP address while domain names fail, or as different results for the same site over Wi-Fi and cellular data. Temporarily disable Private DNS and browser secure DNS to remove extra variables, then check the client’s DNS mode. Once the source of the conflict is clear, decide which layer to keep. Avoid permanently stacking system Private DNS, in-app DNS, and multiple filtering tools that all attempt to rewrite queries.

CHAPTER 05 / IOS

iOS: Clash Plus, VPN configuration, and on-demand connections

Installation and configuration entry points

On iPhone and iPad, open the Clash Plus App Store page from the iOS downloads section. Client information is also available at the official site clashplus.io. After installation, confirm that the device date, network connection, and App Store sign-in are working normally in System Settings. iOS manages network capture through its system VPN framework; the client cannot bypass system authorization to modify connections belonging to other apps.

After opening Clash Plus, choose subscription import on the configuration page and paste the Clash-compatible link supplied by the service provider. If the link arrives through the clipboard, iOS may show a paste-permission prompt; if you deny it, return to the input field and paste manually. After importing, verify that policy groups and nodes appear, then set the profile as active. The update time shown in the subscription list reflects only the latest request result and does not verify node connectivity.

When connecting for the first time, iOS asks to add a VPN configuration and confirms it with the device passcode or biometric authentication. The system handles this step. After approval, check the VPN state in the status bar or Control Center. If another VPN configuration already exists, starting Clash Plus will usually switch the active configuration. Managed devices may restrict adding VPNs through administrative policy; only the device administrator can change that, and reinstalling the app will not override it.

Rule mode, policy groups, and on-demand connections

For everyday use, start with rule mode. It uses configured domains, IPs, rule sets, and the final MATCH rule to choose DIRECT or a proxy policy. Global mode sends connections to one proxy group and is useful for temporarily testing a node, but it should not be the permanent workaround for every problem. If a site fails in rule mode but works globally, inspect the matched rule in the connection log instead of assuming that the node is broken.

Policy groups may include automatic selection, fallback, manual selection, and DIRECT. Automatic selection depends on the test URL and interval defined by the subscription, and does not mean that one node is ideal for every service at every moment. For greater stability, pin a verified node in a manual group to eliminate automatic switching. Restore the automatic policy after confirming the connection is stable. Changing nodes affects new connections; existing sessions may continue over the old path, so fully close and reopen the target app when testing.

On-demand connections can enable the VPN automatically under specified network conditions, but overly broad rules may cause repeated reconnects when you arrive home, enter the office, or switch to cellular data. During initial setup, use manual connections until the subscription and rules are stable. Then create on-demand policies for trusted Wi-Fi networks, cellular data, and other conditions as needed. Test locking and unlocking the device, recovering from airplane mode, and switching networks instead of judging success from the switch state alone.

iOS DNS and local network permissions

iOS restricts app access to the local network. To reach a NAS, casting device, or LAN control page, allow the client or relevant app to access the local network in Privacy settings, and ensure that private addresses use DIRECT in the configuration. Permission granted to the client does not automatically grant it to other apps; actual access also depends on the target app and system networking policy.

In fake-ip mode, the DNS address returned by the kernel maps back to the domain before rules are applied. This works well for most ordinary webpages, but apps that rely on LAN discovery, special domain resolution, or direct IP validation may need entries in the fake-ip filter. After changing the filter, reload the configuration and create new connections because old DNS cache entries do not disappear immediately. If the issue occurs only on one Wi-Fi network, also check whether that network requires captive-portal authentication.

If the connection appears normal but webpages do not load, open a regular HTTP page in Safari to check for a hotel, airport, or campus captive-portal login. The VPN may not establish a usable external connection until authentication is complete. After signing in, reconnect and inspect the logs for DNS timeouts, route failures, or node handshake errors. If cellular data works but one Wi-Fi network does not, investigate that network’s authentication, DNS, and IPv6 conditions before replacing the subscription.

CHAPTER 06 / LINUX

Linux: desktop clients, mihomo services, and environment variables

Desktop clients and package selection

Linux users with a desktop environment can choose Clash Verge Rev or FlClash in the Linux downloads section. Run uname -m before downloading to confirm the architecture: common desktop computers report x86_64, while ARM devices may report aarch64. Also check the distribution’s package format. Debian and Ubuntu systems generally use deb packages; other distributions should use a clearly supported format or an installation method suited to the local system.

After a graphical client starts, subscription import, policy selection, and system proxy behavior are broadly similar to other desktop platforms. The main difference is the desktop environment: GNOME, KDE, and lightweight window managers do not implement system proxy settings identically, and some command-line tools ignore desktop proxies entirely. Confirm that the client is listening on its mixed port, then test the browser, terminal, and proxy-dependent apps separately. Do not treat one browser’s result as proof of the entire system’s behavior.

If an installed package will not launch, run the program from a terminal to capture missing-dependency, permission, or graphical-session errors. Tray icons, window scaling, and autostart behavior may differ between Wayland and X11, but these interface issues do not necessarily affect the kernel. Use listening ports, the process list, and logs to verify that the proxy service works, then troubleshoot desktop integration separately.

Run the mihomo kernel directly

Servers, routers, and headless systems typically run mihomo directly. The kernel section of the downloads page provides builds for different architectures; choose one based on the output of uname -m. Store configuration files in a directory with controlled permissions because they may contain credentials expanded from the subscription. On the first run, load the configuration in the foreground and check syntax validation, port listeners, and rule loading before creating a systemd service. This prevents repeated service restarts from hiding the first error.

mkdir -p ~/.config/mihomo
mihomo -d ~/.config/mihomo

ss -lntp
journalctl --user -u mihomo --no-pager -n 100

For a systemd user service, write the working directory, executable path, and configuration directory as absolute paths. The service account must be able to read the configuration and write to its cache directory. If binding a low-numbered port, changing routes, or creating TUN requires additional privileges, use a system service and grant only the necessary capabilities. Do not make unrelated directories permanently writable by everyone just to avoid configuring permissions.

[Unit]
Description=mihomo proxy core
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

Terminal proxy, TUN, and firewall

The clearest way to connect command-line tools is to set environment variables for the current session. HTTP tools commonly read http_proxy and https_proxy; for SOCKS, use all_proxy when supported by the tool. Case sensitivity varies by program, so scripts should explicitly set the required forms. Do not write proxy variables permanently into the global environment of every system service, or software updates, internal network access, and local administration tasks may be redirected unintentionally.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890

curl -I https://example.com
env | grep -i proxy

Linux TUN requires the kernel TUN device, route permissions, and firewall rules to work together. Containers may additionally need access to /dev/net/tun and network-management capabilities. Before enabling it, record the current default route, policy routes, and DNS settings so you can roll back if needed. When using nftables, iptables, firewalld, or a distribution network manager, avoid having multiple tools manage the same forwarding rules.

Enabling allow-lan or listening on all addresses on a server exposes the proxy port through network interfaces. Do this only when other devices explicitly need access, and restrict source addresses with the host firewall. For local-only use, listening on 127.0.0.1 is sufficient. When checking a port, inspect the bind address as well: an existing port does not mean that its access scope is correct. A loopback listener and a listener on every interface have completely different boundaries.

When DNS is managed by systemd-resolved, NetworkManager, a container runtime, or a manually maintained resolv.conf, TUN capture may be overridden by another layer. First use resolvectl status to inspect DNS on each interface, then determine whether queries are reaching mihomo. If resolution fails only inside a container, inspect the host DNS, container DNS, and forwarding rules separately instead of changing the host browser’s proxy settings.

CHAPTER 07 / CONFIGURATION

General configuration: ports, DNS, rules, and subscription updates

Minimal readable configuration and listener boundaries

Graphical clients usually generate configurations from subscriptions, so users do not need to write YAML from scratch. Understanding the key fields nevertheless helps explain what interface switches actually change. The example below shows the basic relationship between a local mixed port, rule mode, log level, control interface, and DNS. It is not a complete subscription: without proxies and proxy-groups, it cannot create a working route. In practice, let the subscription provide nodes and apply overrides without removing the overall structure.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

rules:
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

mixed-port accepts both HTTP and SOCKS connections, allowing desktop proxy settings and command-line tools to share one entry point. allow-lan: false combined with loopback binding limits access to the local machine. To let phones or other devices on the same LAN use the port, you must adjust the bind address, firewall, and access rules together. Changing only one switch may still prevent connections or may accidentally widen exposure.

external-controller is a management interface, not a regular proxy port. Graphical clients may use it to read connections and switch policies. If exposed to the LAN, protect it with authentication and restrict the allowed sources; for a local client, keep it bound to loopback. Do not remove the control interface casually when ports conflict, because the UI may lose communication with the kernel. First determine whether the conflict involves the mixed, DNS, or controller port.

DNS modes and fake-ip filtering

DNS determines how domains are resolved and provides the basis for domain rules. In fake-ip mode, the client first returns a reserved address, then maps the connection back to the original domain so domain-based rules remain available even when an app connects by IP. redir-host follows a more traditional resolution path and may be more compatible with certain special applications, but its domain mapping and caching behavior differ. Choose the mode based on application behavior rather than switching solely for perceived speed.

LAN domains, connectivity-check domains, time synchronization, and some apps that require specific returned addresses may need entries in fake-ip-filter. Filtering gives these domains real DNS results; it does not automatically make them DIRECT. The final outbound path is still determined by rules. After changing the filter, clear the system DNS cache, reload the configuration, and create new connections. Refreshing a webpage alone may leave browser cache in use and make the change appear ineffective.

When encrypted system DNS, browser-specific DNS, and client DNS are enabled together, a query may bypass the intended entry point. During troubleshooting, temporarily disable the extra layers and keep only mihomo DNS active, then check whether logs show the domain and matched rule. Once the basic path works, restore only the secure DNS settings you need. For leak testing and configuration validation, see Clash DNS Leak Testing and Leak-Prevention Configuration.

Rule order and policy groups

Rules are evaluated from top to bottom, and evaluation stops at the first match. Specific domains, processes, or rule sets generally belong near the top, while broad GEOIP, GEOSET, and final MATCH rules belong later. If MATCH appears first, no subsequent rule will ever run. After changing rules, inspect the connection log for the request domain, matched rule, and target policy instead of checking only whether the final webpage loads.

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - DOMAIN-KEYWORD,example,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

RULE-SET references an independent rule collection for easier updates and reuse. If a provider download fails, an existing cache may continue working, but a fresh installation or cleared cache will expose the issue. Check provider reachability, behavior type, and rule content, and verify that the policy name actually exists. A rule that matches a nonexistent policy group will usually cause a configuration-load error.

Policy group names come from the subscription, so PROXY in examples is not guaranteed to exist in every configuration. Overrides must use the actual group names in the active configuration. Global mode bypasses most rule decisions and sends traffic to the selected global group; DIRECT skips the proxy outbound path. For an explanation of the three modes, see Rules, Global, and DIRECT Modes Explained.

How subscription updates interact with overrides

A subscription update usually downloads and replaces the remote configuration. Direct edits to subscription-generated YAML may be overwritten at the next update. Clients that support overrides, scripts, or Mixins should keep local ports, DNS settings, and additional rules in a dedicated override layer. Without that support, keep a record of your changes and review them after each update. Do not disable updates permanently to preserve one change, because that also prevents normal updates to nodes, policies, and rules.

The automatic update interval should not be so short that it generates constant requests, nor so long that important provider changes are delayed. When an update fails, distinguish between an HTTP request failure, changed response content, a parse error, and a proxy loop. If the client uses the current proxy to fetch the subscription and a faulty rule sends the subscription domain through an unusable node, updates can loop. See Troubleshooting Subscription Update Failures and Setting Up Automatic Updates for detailed steps.

CHAPTER 08 / TROUBLESHOOTING

Common configuration problems: trace the traffic path layer by layer

The client starts but there is no network access

Troubleshoot along the actual traffic path: does the target app send requests to the local proxy, is the local port listening, did the kernel load the active configuration, do the rules send the connection to the expected policy, can the node establish a remote connection, and does DNS return usable results? A main window showing “Running” proves only that the process exists; it does not prove that every layer is working.

Disable TUN first, keep only the system proxy enabled, and use a browser to visit a regular site. If the browser fails, check that the system proxy points to the local machine and that its port matches the client, then inspect the logs for connection entries. No log entries usually mean traffic never reached the client. An immediate refusal usually indicates a wrong port or a kernel that did not start. If a rule matches but the remote handshake fails, continue with the node and network checks.

If webpages remain inaccessible after disabling the system proxy, a leftover proxy setting, DNS cache, or another VPN route may be involved. On Windows, check system proxy settings; on macOS, check the active network service; on mobile systems, check VPN status; on Linux, check environment variables and the default route. Restarting can clear some temporary state, but record settings and logs first so you know which layer changed if the problem returns.

The subscription will not update or fails to parse

When a subscription update fails, open the original URL in a browser and confirm the response. If the link is unreachable, expired, or returns a login page, obtain an updated URL from the service provider. If the browser can access it but the client cannot, check client network permissions, current proxy rules, and system time. Certificate connections depend on accurate time, so a large clock discrepancy can appear as a network failure or secure-connection error.

A parse failure usually means the response is not compatible YAML, its field structure is not recognized by the current client, or an authentication or error page replaced the configuration. Do not check only the HTTP status code; a successful response may still be HTML. Save the response locally, inspect whether it begins with configuration fields, and verify indentation and encoding. For a complete checklist, see Subscription Expiration and Parse Failure Self-Check.

If no nodes appear after import, first confirm that you selected a Clash or mihomo format rather than a subscription intended only for another tool. If nodes exist but policy groups are empty, the conversion may have omitted proxy-groups. Do not copy a large node list into a new file by hand. Obtain the correct format from the subscription source instead, avoiding damage to credentials and protocol parameters during copying.

Only some websites or apps fail

When some sites fail, inspect the domain, matched rule, and policy in the connection log. If traffic incorrectly matches DIRECT, adjust the specific rule and place it before broader rules. If it already reaches the proxy but fails, pin a verified node and retry to eliminate automatic policy switching. If the browser works but one app does not, check whether that app honors the system proxy; test TUN or per-app routing on mobile when necessary.

When a site loads but images, login, or video fails, the main domain and resource domains may be using different policies. Developer tools or the connection list can reveal related domains, which you can then evaluate for a consistent policy. Avoid covering every similar name with an overly broad DOMAIN-KEYWORD rule, as it may alter unrelated services. A maintained rule set or rules for clearly defined domain suffixes are safer choices.

A problem that briefly persists after switching nodes may come from DNS, HTTP/2, QUIC, or an application session cache. Fully quit the target app, clear relevant caches, and establish a new connection before testing again. A private browser window reduces some caching but does not replace a system DNS flush. Change one variable at a time and record the mode, node, network, and matched rule for each comparison.

DNS, port, and TUN conflicts

Typical DNS failures include reachable IPs with failing domain names, repeated query timeouts in the logs, or contradictory results for the same domain across apps. Check whether the local DNS listener port is occupied, then temporarily disable browser-specific DNS and extra system DNS tools for comparison. In fake-ip mode, seeing a reserved address is expected behavior; do not mistake that address itself for a remote-server failure.

A port conflict prevents a proxy or control interface from listening. Look for messages such as bind or address already in use, then use system tools to identify the process holding the port. After changing a port, update system proxy settings, terminal environment variables, browser extensions, and LAN devices as well. Changing only the client field while leaving the old system proxy in place creates a state where the kernel runs normally but receives no requests.

If the entire network goes down after enabling TUN, disable TUN to restore the baseline, then inspect virtual-interface permissions, the default route, DNS interception, and other VPNs. Desktop virtualization, containers, game accelerators, and enterprise networking software may all install filtering drivers. Disable conflicting tools in sequence and restore them one at a time. If the issue appears only after sleep and wake, recreate the TUN interface and check for stale routes.

How to read logs and when to roll back

Info-level logging is sufficient for routine troubleshooting. Enable debug logging only for short-term detail collection because it produces many connection records. Focus on configuration-load errors, listener failures, DNS timeouts, rule matches, remote handshakes, and route creation. Before sharing logs, remove subscription URLs, authentication fields, node credentials, and access domains that should remain private.

When several changes make the cause unclear, return to the minimum state: disable TUN and overrides, load one original subscription, use the default local port, pin one node, and test a browser through the system proxy. Once the baseline works, restore changes one at a time in this order: custom DNS, additional rules, TUN, then LAN sharing. If the issue returns immediately after one step, the investigation can focus on that layer.

If the original subscription cannot connect across multiple networks and clients even though its response content is normal, contact the subscription provider to confirm node status. If the same subscription works on other devices, focus first on local permissions, ports, DNS, and routing. Reinstalling the client can repair damaged program files or system integration, but it will not automatically fix subscription formatting, rule logic, or remote node status.

After troubleshooting, record the final working client, configuration name, proxy mode, DNS choice, and any necessary overrides locally. Compare future updates against this baseline instead of retracing the entire traffic path. If you need to reinstall or switch platforms, return to the client downloads page to check the system architecture and available clients.