INSTALLATION / CONFIGURATION

Clash for Every Platform: Setup Guide

Find installation, subscription import, and traffic routing steps for your platform. Get connected first, then fine-tune rules and DNS.

New users can follow the quick-start guide in the user documentation to get connected. Use this page as a reference for architecture choices, permissions, configuration examples, and rollback options. Jump to the relevant section for platform-specific help.

Clients and Cores
Subscriptions and Local Configuration
System Proxy / TUN

01 / BEFORE INSTALLATION

Getting Started: Clients, Subscriptions, and Traffic Routing

Understand the roles of the client and core

The Clash ecosystem includes graphical clients and cores that handle traffic forwarding. Clients manage subscriptions, the system tray, permissions, and settings; the core reads the configuration and handles connections. Similar-looking interfaces don't guarantee support for the same fields, especially between legacy Clash configurations and mihomo extensions. When choosing a client, first check platform support, then verify that its core supports the protocols used by your subscription. This guide prioritizes Clash Plus on supported platforms. For a different interface or desktop management features, choose a client such as Clash Verge Rev or FlClash from the downloads page.

Before you begin, note your operating system, processor architecture, and installation permissions. Desktop packages commonly distinguish x64 from ARM64. For Apple Silicon and Intel, don't rely on “macOS” in the filename alone; Android devices may also use ARM64 or older ARM architectures. Installation is only the first step: background services or virtual network interfaces may require separate authorization. If a work device restricts drivers, network extensions, or administrator access, follow its management policies. Don't bypass them by disabling system protections.

Prepare your subscription and keep a rollback option

The client itself does not provide ready-to-use remote proxy services. You need a subscription URL you are authorized to use, an individual connection profile, or a local configuration file—and it must be compatible with your client. Subscription links may contain access credentials, so never include them in public screenshots, logs, or online conversion tools. Before importing, note the current client's mode, selected proxy groups, and custom rules. During migration, don't overwrite the new client's entire data directory; that can bring in incompatible databases and paths.

A remote subscription and the configuration that ultimately takes effect are separate layers. Updating a subscription fetches its contents again, so edits made directly to its body—such as port or rule changes—may be overwritten. Keep persistent changes in the client's override, merge, or extension configuration. Merge behavior varies between clients, so check whether rule order and proxy groups were replaced. For your first import, keep the original configuration and confirm it works before saving a local copy. After that, change one category of settings at a time.

Separate routing modes from traffic entry points

Rule, Global, and Direct modes determine how the core handles connections after they enter it. System proxy and TUN determine how connections reach the core. Rule mode does not automatically route traffic from every app through the proxy, and TUN does not mean every connection goes to a remote server. System proxy works well for browsers and desktop apps that honor system proxy settings. TUN receives more traffic through a virtual network interface and involves routing, DNS, and permissions. For initial troubleshooting, start with the simpler entry point and avoid running multiple clients or traffic-capture mechanisms at once.

Entry point	Best for	What to check
System proxy	Apps that follow system settings	Proxy address, port, and app-specific settings
Explicit HTTP / SOCKS	Tools with manual proxy settings	Protocol and listening address
TUN / platform VPN interface	Connections routed through a virtual interface	Permissions, routes, DNS, and exclusions

The following example shows basic mihomo fields. It does not include remote proxies and is not a substitute for a complete subscription. The mixed port accepts both HTTP and SOCKS requests; binding to the loopback address limits access to this device. If the client manages the listening port or DNS, use its final generated configuration as the source of truth. Don't split fields with the same name across multiple override locations. YAML uses spaces for indentation, and keys at the same level must be unique. Run the client's configuration check before reloading the core.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query

Verify each layer in order: check that the core is running, the configuration has loaded, and the proxy groups have selectable options. Then visit your target and inspect the connection log for the matched rule. A connectivity test only reports the result for a specific test destination; it doesn't prove that every site, UDP connection, or sign-in flow works. Note the network conditions and time of any error so you can distinguish configuration changes from remote outages or local network issues. For a first connection, return to the user guide and follow its steps in order.

02 / WINDOWS

Windows: Installation, System Proxy, and Service Mode

Choose the right installer and launch the client

Check the system type in Settings under “System Information,” then choose the matching architecture from the Windows downloads. Clash Plus is a good first choice; you can also use Clash Verge Rev, FlClash, or Clash Nyanpasu. Clash for Windows is no longer maintained, so archived builds are mainly for compatibility with and migration from older setups—not recommended for new installations. Client choice and core protocol compatibility are separate issues. If an older configuration won't load, check core support before reinstalling the interface.

When running the installer, verify the file source and review any system prompts. The installation directory may be separate from the user data directory, and uninstalling may not remove subscriptions, logs, or services. If no window appears at first launch, check whether the client is already running in the system tray, then check Task Manager and the client logs. Don't click the launch icon repeatedly or delete the data directory outright. If you use another client, turn off its system proxy, startup entry, and background services before quitting it, so two sets of automatic traffic-routing settings aren't left behind.

Import the subscription and verify that it loaded

In the subscription or configuration manager, choose the option to import from a URL, paste the full address, save it, and update. Then set it as the active configuration and check the logs for a successful load. A subscription appearing in the list doesn't mean the core is using it. Open the proxy page too and confirm that proxy groups and their members are present. If import fails, distinguish a download failure from a parsing failure. For the former, check the URL, network, and server response. For the latter, make sure the response is a supported configuration—not a sign-in page or error page.

Switch to Rule mode and select an available member for the main proxy group. For your first connection, don't add custom rules, scripts, and DNS overrides all at once. Visit a target site and check its domain, matched rule, and final outbound route in the connection log. If just one app fails, check whether it has its own proxy, built-in secure DNS, or an existing connection. After saving the configuration or changing proxy groups, existing long-lived connections may keep using the old route. Close those connections or restart the app before testing again.

Test the system proxy before enabling TUN

After enabling the system proxy, check the local address and listening port in Windows proxy settings. If the client uses a different port from the example, update the test command too. If a browser works but a command-line tool doesn't, the tool may not follow system proxy settings. Try specifying an HTTP proxy explicitly to test it. The command below accesses an example site only to check whether the local port accepts requests. Repeat the test with your actual destination; a single response doesn't prove that all services work.

curl.exe -I --proxy http://127.0.0.1:7890 https://example.com

TUN is useful for apps that ignore system proxy settings, but it requires the client to support the necessary service and permissions. Install or start the service through the client's interface before enabling TUN; the exact option varies by client. Don't treat launching the interface as an administrator every time as a long-term substitute for installing the service. After enabling TUN, check the virtual adapter, core logs, and connection records to confirm traffic is passing through the core. If the core stops because of a configuration error but routes remain, turn off TUN and quit the client normally, then check whether network access recovers.

You can check for a port conflict in PowerShell. If the port is already listening, identify the process first; a common cause is an old client still running in the background. Don't force-quit an unknown system process just because it is using the port. You can choose another local port and update the system proxy and any manually configured app proxies to match. Reload the core after changing the port, or the value saved in the interface may temporarily differ from the port actually in use.

Get-NetTCPConnection -LocalPort 7890 -State Listen -ErrorAction SilentlyContinue
netsh winhttp show proxy

The second command checks the WinHTTP proxy, which is separate from the desktop user's proxy settings. Some services and update components use WinHTTP, so a working browser doesn't mean those components are configured correctly. Don't import or reset WinHTTP settings system-wide to fix a single app. First find out which proxy source that app uses. On a managed network, preserve existing corporate proxy and certificate settings to avoid disrupting other services.

Handle sleep, startup, and leftover settings

Starting the client at boot doesn't guarantee that the subscription has loaded, services are ready, or TUN is routing traffic. After enabling autostart, restart once and check the tray icon, mode, and logs—not just whether the startup entry exists. If connections fail after waking from sleep or changing networks, close old connections and reload the core. If that doesn't help, check system proxy, TUN, and DNS in that order. If your browser still reports an unreachable proxy after the client exits, check whether the system proxy points to a local port that is no longer listening. For crashes on launch, see how to troubleshoot a crashing client.

03 / MACOS

macOS: Architecture and Network Permissions

Choose a client for your Mac and install it in Applications

Open About This Mac and check whether it lists Apple silicon or an Intel processor. Then choose the matching file from the macOS downloads. Clash Plus is a good first choice; Clash Verge Rev and FlClash are also options depending on your interface preferences. ClashX Meta is no longer maintained and is mainly retained for compatibility with existing setups. Don't copy an old client's entire configuration directory into a new client's folder. Migrate subscriptions, rules, and settings separately, paying particular attention to absolute paths and obsolete scripts.

For a disk image installer, drag the app into Applications and launch it from there rather than running it long-term from the mounted image. If a security prompt appears on first launch, verify the source and use the system's normal approval flow. Don't run bulk quarantine-removal commands from unknown sources or disable macOS security protections to launch the client. If no main window appears, check the menu bar icon; menu bar apps can be running without an open window.

Import the subscription and check the configuration and proxy groups

Import a subscription URL or local YAML file in the configuration manager. After the update, explicitly select it as the active configuration. Then open the proxy page and confirm that the selection groups and automatic proxy groups have been created. If the imported content contains connection details but isn't a complete Clash configuration, use the client's appropriate import option. Don't just rename a different file format to YAML. Proxy group names must match the names referenced by your rules. In particular, remove references to target groups that don't exist in the new subscription when copying custom rules.

For your first test, keep Rule mode enabled, select a known working member, and check the connection log while visiting a site. If a speed test succeeds but a site won't open, find out whether the failure occurs during DNS resolution, connection setup, or TLS negotiation. Each points to a different issue; don't dismiss them all as a “slow proxy.” Probe intervals and tolerance settings affect how often an automatic proxy group switches members, but they won't fix an expired subscription or a broken local proxy entry point. See proxy group types and when to use them for guidance.

System proxy settings apply per network service

After enabling the system proxy, check the proxy settings for the active network service. macOS can store separate proxy settings for Wi-Fi, Ethernet, and other services, so results may differ when you switch interfaces. The commands below list service names, then check the HTTP and SOCKS proxies for Wi-Fi. If your service has a different name, use the name returned by the list command. These commands only read settings; they don't change your network configuration.

networksetup -listallnetworkservices
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"

Set the HTTP, HTTPS, and SOCKS proxy options to match an endpoint supported by the client. If it provides a mixed port, several proxy protocols can share one port, but verify the actual configuration. Terminal tools may not use the system network proxy. Use the tool's own proxy options or set proxy environment variables for the current terminal session. Don't put a one-off test setting in every shell startup file; otherwise, new terminals may keep trying to use a local port after the client has stopped.

TUN, background helper services, and other network tools

Enabling TUN in a desktop client may require a privileged helper service, network extension approval, or a background component, depending on how the client works. Make sure each authorization request matches the action you're taking. After granting permission, reload the core and check the logs for virtual interface and route status. A lit TUN toggle doesn't prove that traffic is being captured. Test an app that previously ignored the system proxy and check whether its connections appear in the log.

If your device also runs a corporate VPN, content filter, or another virtual network tool, their default routes and DNS settings may conflict. Troubleshoot by disabling one component at a time when possible and recording the result. Don't uninstall software that your organization requires. If a local printer, shared folder, or development service becomes unreachable after enabling TUN, check the address range and routes first, then consider adding a precise Direct rule. Don't route every intranet domain through the proxy or disable all DNS features to mask the cause.

After waking from sleep or switching Wi-Fi networks, old TCP connections and DNS cache entries may still reflect the previous network. Close the affected app connections and reload the client configuration. If the system proxy is still set but the core isn't running, start the client normally or turn off the proxy before testing again. Before uninstalling, turn off the system proxy and TUN, then remove helper services through the client's own controls. Moving the app to the Trash may not remove background components or current network settings.

04 / ANDROID

Android: VPN Permissions and Background Operation

Choose the right architecture and keep your old configuration

On the Android downloads page, Clash Plus is a good first choice. You can also use Clash Meta for Android, FlClash, or Surfboard depending on configuration compatibility and your preferred interface. Most newer devices use ARM64, but don't guess from the phone's age or model; check system information or the device specifications. Surfboard uses a different configuration system from Clash YAML. Supporting subscriptions from the same provider doesn't mean it can use an entire Clash configuration as-is. Before installing, make sure the subscription format works with the client's import options.

When installing an APK, grant permission to install unknown apps only to the file manager or browser you're actually using to open the installer. Revoke it afterward if you no longer need it. A signature conflict usually means that the installed app and the APK have different signing keys. Don't uninstall the old app right away: first export your subscriptions, configurations, and custom rules, and make sure you can restore them. An in-place update usually preserves data, but uninstalling may delete configurations in internal storage. Files stored elsewhere may remain, but that doesn't mean the app can restore its settings automatically.

Import a subscription and start the platform VPN interface

In the subscription or configuration screen, import the link, update it, and set it as the active configuration. Make sure the main proxy groups are present and select an available member before connecting. Android clients typically use the platform VPN interface to create a local virtual network. The first time you connect, Android asks for permission. This allows the app to route matching traffic; it doesn't mean the remote proxy service is working. After granting permission, check the core status, proxy groups, and actual connectivity.

Android's VPN interface is not quite the same as the desktop System Proxy toggle. Some interfaces offer a Start button without a separate TUN label; don't look for desktop options with the same names. An active VPN usually replaces another VPN in the same user or profile, so other VPNs, some firewalls, and filtering tools that use a local VPN may conflict. Check which service is active before connecting. Repeatedly starting two tools can make it look as though a connection was established before another service immediately replaced it.

Check per-app routing and DNS behavior

If only your browser can access the internet, check the per-app proxy settings. An allowlist usually means only selected apps are routed through the proxy; an exclusion list means those apps bypass it. The two work in opposite ways. You may need to reconnect the VPN for changes to take effect. Work-profile apps run in a separate environment and may not share the same routing scope as personal apps. For troubleshooting, start with a simple scope and test one target app, then add exclusions gradually. Don't select every app without understanding what the list means.

The following example shows a domain-specific Direct rule in mihomo. It is for clients that use this core and allow rule overrides. It controls the outbound route after traffic enters the core; it doesn't determine whether Android routes an app's traffic to the client. Merge it into the existing rule list and place it before any catch-all rule that would match first. Don't replace a complete subscription with this snippet, and don't paste Clash YAML into Surfboard's configuration screen.

rules:
  - DOMAIN-SUFFIX,lan,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve

Android Private DNS, browser secure DNS, and the client's DNS settings can all affect name resolution. If a site behaves unexpectedly, note your original Private DNS setting and compare results in a temporary test before changing it. Don't assume that enabling Fake-IP means every app uses the same resolver. Some apps handle resolution and connections themselves, so check the connection log. If local network domains won't resolve, also check whether the current Wi-Fi network's local DNS can resolve them instead of changing only the remote proxy group.

Background restrictions, network changes, and hotspot sharing

If the connection stops when the screen locks, first check battery optimization, background activity, and the manufacturer's app startup controls. Allowing background operation doesn't mean granting every permission; enable only what's needed to keep the network service running. If you turn on Android's Always-on VPN, understand the effect of blocking connections without a VPN: if the client isn't running or the core fails to load, the entire network may become unavailable. Avoid enabling the blocking option during initial setup. Decide whether to use it only after testing restarts, screen locks, and network changes.

After switching from Wi-Fi to mobile data, old connections may need to be re-established. Reload the client or disconnect and reconnect, then compare the connection logs instead of assuming a brief interruption means the subscription has expired. If only mobile data fails, check whether Android restricts the app's data access and whether the current network allows the remote connection. Other devices connected to your hotspot don't necessarily use your phone's VPN interface. Your phone working doesn't prove that tethered devices are routed too; this depends on the system's forwarding path and the client's capabilities. Test it separately rather than assuming that “Allow LAN” is enough.

When moving to a new device, export your subscription and necessary overrides rather than backing up the entire app directory. After importing, check the per-app list again because installed apps, work profiles, and system permissions may have changed. Before sharing troubleshooting logs, remove subscription URLs, connection credentials, and unnecessary destination domains. If the client exits as soon as it opens, follow the steps in the client crash troubleshooting guide to check the configuration and data before reinstalling.

05 / IOS

iOS: Import and Test a Connection with Clash Plus

Install from the App Store and find the import option

Clash Plus is available for iOS from the Clash Plus page on the App Store. Product information is available at clashplus.io. The iOS downloads section on this site links to the same app. After installing, make sure it opens normally before preparing your subscription details. Interface labels may change with updates. Look for the configuration, subscription, and connection features rather than searching for desktop menus with identical names.

Before importing, identify what you have: a web dashboard URL, subscription URL, single connection profile, and complete configuration are not interchangeable. Copy the entire link, including its parameters, and make sure messaging apps haven't truncated it or added punctuation at the end. If you import using the system share sheet or a link from another app, verify the content and name before saving. Subscription URLs may contain credentials. Don't paste them into public notes or share the full URL when asking for help.

Activate the configuration and connect to the VPN

Add the subscription or configuration in the client, fetch its contents, and set it as the active profile. Then check which proxy options are available. A successful import usually means only that the content was saved; you still need to activate it and start the connection. When the client first starts routing network traffic, iOS asks permission to add a VPN configuration. Follow the system prompts to authorize it. Then return to the client, check the connection status, open a target app, and review the logs. A VPN indicator in iOS means a tunnel session exists; it doesn't prove that a particular remote route, domain, or service works.

If the connection stops immediately after you start it, check the client's error message and the iOS VPN status instead of repeatedly tapping Connect. Possible causes include a configuration parsing error, incompatible remote settings, a network that can't establish the connection, or another VPN configuration taking over. Keep a copy of the current configuration and test one change at a time. Removing the VPN configuration in iOS may prompt the client to request permission again, but it won't fix invalid subscription fields. Repeatedly deleting the profile is not a general solution.

Understand mobile traffic routing and rule limitations

iOS traffic routing relies on the platform's network extension capabilities and isn't equivalent to the desktop HTTP system proxy toggle. If the client offers routing, rules, or mode options, configure them as it supports them. Rule mode selects different outbound routes for different destinations; Global mode sends connections within its handling scope through the selected policy. Even in Global mode, the system or client may exclude some traffic, so don't assume every system service follows the same path.

For your first test, select a specific proxy group member, visit an actual destination, and check the domain, matched rule, and final route in the log. If a site loads but app sign-in fails, consider the sign-in API, CAPTCHA, asset domains, and UDP requirements separately. Some services also depend on account status and server-side regional policies; network connectivity doesn't change those conditions. Don't keep changing every rule based only on a browser test. First find out whether the failed request reached the client and matched the expected policy.

What you see	Check first	Next step
No proxy groups in the configuration	Subscription format and import result	Check the content and fetch it again
Connection stops immediately	Configuration error and system permission	Read the error and fix one issue at a time
Only one app fails	Matched rule and app-specific request	Close existing connections and test again

Subscription updates, DNS, and network changes

Subscription updates can change available members and proxy group references. Before updating, check whether local edits could be overwritten. If the client provides separate rule or override settings, keep persistent changes there. If it only lets you edit imported content, save a copy first and compare it again after the next update. The interface may still show a proxy group that references a deleted member, even though it can't connect. After updating, check the active selection and test an actual destination—don't rely on the update timestamp alone.

Wi-Fi, cellular networks, and public hotspots have different DNS and access requirements. Existing connections may stop working after you switch networks and need to be re-established. On hotel or airport Wi-Fi that requires a sign-in page, complete the network's normal login before connecting the client; otherwise, the captive portal may block both subscription updates and remote connections. If a particular network keeps failing, check whether basic pages load with the client disconnected and note where the failure occurs. Don't mistake a network access problem for a broken client configuration.

For DNS settings, follow the configuration options Clash Plus actually supports. The mihomo examples in other sections explain individual fields and aren't guaranteed to work as a complete configuration in every mobile client. Custom resolvers, system network settings, and browser features may all affect the result, so change one thing at a time while troubleshooting. To understand Fake-IP mappings and their limits, read DNS leak testing and leak-prevention settings, then adapt the guidance to your client.

For long-term use, check that your subscription is valid and your selected proxy group works instead of repeatedly clearing all settings. When moving to another device, grant the necessary network permissions again; restoring a subscription won't restore every connection setting from your old device. Before deleting the client, disconnect and confirm that normal network access has resumed. Keep only the necessary timestamps, error types, and redacted configuration in your troubleshooting notes. Don't expose subscription URLs or connection credentials in screenshots.

06 / LINUX

Linux: Desktop Clients and Core Deployment

Choose a package format for your Linux distribution

Desktop users can choose Clash Verge Rev or FlClash from the Linux downloads; Clash Verge Rev is the recommended starting point. Check your distribution and architecture in System Information first. Debian- and Ubuntu-based systems generally use DEB packages; RPM-based distributions use formats supported by their package manager. Don't mix package managers from other distributions just to install a client. Desktop apps may also depend on desktop components and system libraries, so a package that extracts successfully won't necessarily run on every distribution.

Run the installation command from the directory where you downloaded the file, replacing the filename in the example with the actual downloaded filename. Installing a local package through the system package manager usually handles dependencies and later removal more cleanly. If installation fails, keep the full error message and determine whether the cause is a mismatched architecture, missing dependencies, or insufficient permissions. Don't recursively grant write access to an entire directory. Launch the interface as a regular user. For virtual networking, use the permission or service mechanism supported by the client rather than running the whole desktop application as root.

Import a subscription and distinguish desktop proxy from terminal proxy

Import the subscription in the client and set it as the active configuration, then check the proxy groups and runtime logs. System proxy integration varies across Linux desktops; GNOME, KDE, and individual apps may handle it differently. If a browser works but a command-line tool doesn't, specify the proxy explicitly in the tool and confirm the listening port is available. Make sure the port in the example matches the client. These commands are for testing only; don't add them to global environment files or service settings until you've verified the results.

curl -I --proxy http://127.0.0.1:7890 https://example.com
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com
ss -lntp

socks5h means the SOCKS proxy resolves the destination hostname. This is useful for comparison with the local DNS resolution path, but it doesn't change DNS for the entire system. Proxy environment variables affect only processes that honor them; already-running desktop apps and systemd services won't automatically inherit settings from a new terminal session. To configure an app long-term, use its own proxy settings where possible and note how to revert them. Otherwise, system updates or background tasks may keep trying to reach a local port after the client stops.

TUN, routing, and local DNS services

TUN requires the right permissions and system networking support. First confirm that the standard proxy path works before enabling it. The following is a mihomo TUN snippet to merge into a complete configuration that already has a working proxy and rules. The client may manage these fields itself; adding duplicate overrides can make behavior difficult to diagnose. Automatic routing doesn't account for existing VPNs, container networks, or policy routing. After enabling TUN, inspect the actual routing table and test both local network and external connections.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

DNS hijacking also requires the core's DNS feature to be enabled in the complete configuration. It won't automatically cover every encrypted DNS connection or app-specific resolver. Distributions using systemd-resolved may provide DNS through a local stub; don't overwrite /etc/resolv.conf without understanding how your system manages it. Use the commands below to check addresses, routes, and DNS status. The last command applies only to systems that provide the corresponding tool. If problems start after a network change, compare the default route and DNS servers before and after enabling TUN, then address the specific difference.

ip address show
ip route show
resolvectl status

Manage the core as a service on servers and routers

For a server or router without a desktop environment, choose a mihomo binary from the core section of the downloads page that matches your processor and runtime environment. This approach is for users who can manage services, permissions, and network rules; desktop users don't need to bypass the GUI. Set up separate configuration and writable data directories, place the binary in a controlled location, and test the configuration first. The commands below assume the binary is in the specified location and a complete configuration has been saved. A successful test checks basic syntax and references, not whether connections actually work.

/usr/local/bin/mihomo -t -d /etc/mihomo -f /etc/mihomo/config.yaml

After the configuration passes its test, run it under a service manager with an explicit working directory, startup arguments, account, and restart policy. Standard HTTP and SOCKS listeners usually don't need full root privileges. TUN and route changes require additional capabilities, so grant only what's necessary for your deployment. Keep the management interface bound to localhost and use a controlled channel for remote administration. Don't expose a control port or unauthenticated proxy listener to the public internet. Before allowing LAN connections, also configure the listening address, firewall scope, and required authentication.

Before changing TUN, the default route, or firewall rules over SSH, keep a second session open and prepare an out-of-band or local recovery method. Start the basic proxy first, then add route and DNS handling in stages to avoid losing remote access after one change. Containers also involve network namespaces, device access, and permission mapping, so don't apply host-level instructions unchanged. Keep the old binary and a configuration backup when upgrading, then test compatibility with the new core. For field changes, see how mihomo differs from the original Clash core.

07 / DIAGNOSTICS

Configuration Troubleshooting: Diagnose by Connection Stage

Subscription Update and Configuration Parsing Failures

If a subscription update fails, start with the fetch stage. Check that the URL is complete, the system clock is correct, the service is still active, and the current network can reach the subscription endpoint. If the URL returns a sign-in page, rate-limit notice, or error text, the client's subsequent parsing error is a symptom—not something to fix by changing YAML indentation. Whether updates use the proxy depends on the client. Some subscriptions require an existing connection to fetch, while an expired proxy can also block updates. Check the client's update network settings and compare results.

If the content downloads but the core refuses to load it, check syntax, fields, and references. Indent YAML with spaces and align list items consistently. Don't rely on duplicate keys in a mapping to override earlier ones. Every proxy group referenced by a rule, and every proxy or proxy provider referenced by a group, must exist. Cores support different protocols and fields; renaming a file with a different format to .yaml doesn't convert it. Revert the latest override first, then restore changes one section at a time. This is easier to diagnose than deleting everything.

Ports, listening addresses, and whether traffic reaches the core

If an app reports that its connection was refused, first check that the core is running, the local port is listening, and the app uses the right proxy address. A service listening on 127.0.0.1 is available only on that machine; another device can't use its own loopback address to reach this computer. To connect from another device, configure the server's LAN address, allowed listening interfaces, and firewall rules explicitly. Don't open every interface to troubleshoot. First confirm that an explicit proxy test works locally, then expand access to a controlled LAN range if needed.

If the connection log doesn't change at all when you visit a destination, check the traffic entry point before changing outbound rules. The app may ignore the system proxy, use its own proxy settings, or fall outside the mobile client's routing scope. If a log entry appears but uses Direct, check the matched rule and rule order. If it uses the expected proxy but still fails, investigate remote connectivity, authentication, and the destination service. This layered approach avoids blaming every issue on an unavailable proxy node and needlessly re-importing subscriptions.

DNS, Fake-IP, and Rule Order

Fake-IP maps a domain to a reserved address so later connections can still be associated with the domain for rule matching. Seeing one of these addresses doesn't mean DNS is broken, but software that needs the real resolved address may require a precise exception. Keep exceptions specific to individual domains. Broad exclusions can prevent domain-based rules from working as intended. Internal domains also need access to a local DNS resolver that can resolve them; public resolvers generally don't know private names on corporate or home networks.

Rules are evaluated in order. Put specific rules before broad ones and keep MATCH as the final fallback. The following example is meant to be added to a complete configuration and uses the built-in Direct policy rather than a custom group name. It demonstrates syntax and order, not a complete traffic-routing setup. Keep the remote proxies and selection groups from your subscription. After making changes, reload the configuration and use the connection log to confirm the matched rule; don't just check that the file was saved.

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,DIRECT

The resolver location shown in a DNS test doesn't by itself prove whether application traffic is taking the expected route. Check the DNS request path, destination connection, and rule logs together. Browser secure DNS, app-specific resolvers, and caching can all affect the comparison. For a deeper guide, read practical DNS leak testing and prevention. Enabling more DNS options won't automatically improve reliability. Understand what each field does, then test one change at a time.

Proxy Selection, Connection Reuse, and Rollbacks After Updates

Automatic proxy groups select routes based on their probe target and selection logic. Different group types focus on latency, availability, or load balancing. A successful probe doesn't guarantee a particular app will work, and a failed probe may simply mean its test destination is unreachable. Select a member manually and test the actual destination before changing probe settings. After switching proxies, existing long-lived connections may keep using the old route. Close them or restart the app before comparing results, or it may look like the switch had no effect.

If problems start after upgrading the client or core, save the logs and current configuration first, then compare them with a backup. Custom extension fields, old paths, cached rule sets, and permission changes can all affect startup. Don't upgrade, clear data, and rewrite the configuration at the same time without a backup; you won't know which change fixed or caused the problem. For migration from an older client, see alternatives and migration options after Clash for Windows was discontinued. Move subscriptions and rules first rather than copying all runtime data.

Keep troubleshooting notes concise and preserve a way to recover

For further troubleshooting, record the operating system and architecture, client name, traffic-routing method, type of destination that failed, and error time. Include only the relevant redacted logs. Raise the log level temporarily only to reproduce the issue, then restore the normal level to avoid collecting excessive browsing records. Don't share connection credentials, subscription parameters, or control interface credentials. Roll back in the reverse order of setup: disable newly added routes or TUN first, restore proxy and DNS settings, then check that the client exits cleanly. Find platform-specific options in the relevant section of this page. For basic setup, return to the quick-start guide.