Platform Guides · Installation and Setup
Clash on Every Platform
Setup Guide
Find installation steps by device and troubleshoot connection issues by network layer. This guide covers platform differences, permission requirements, and configuration details. To get connected first, start with the Quick Start Guide, then return to the relevant section for details.
1. Before Installing Clash
Know the Difference Between Clients, Cores, and Subscriptions
The client provides the interface, stores configuration, starts the core, and requests system permissions. The core processes rules, establishes proxy connections, and handles DNS. A subscription delivers configuration, usually including nodes, proxy groups, and rules, though it may contain only a proxy list. These are three different things. Installing a client does not provide a working proxy, and importing a link does not mean the current core supports every field it contains.
For a new installation, choose Clash Plus on the Download page first, then compare other clients based on your needs. Clash for Windows is no longer maintained and is best treated as an archived reference for existing setups. Don’t overlook its maintenance status just because you’re familiar with an older guide. Button labels vary between clients; this guide describes actions in terms of configuration management, proxy selection, and traffic routing. Look for equivalent controls if your interface uses labels such as Profiles or Proxies.
Check Your Device Architecture and Configuration Source
Before downloading, check your operating system, processor architecture, and software requirements. Don’t infer a desktop device’s architecture from its brand, or a phone’s installer type from its Android version alone. Match the platform and architecture listed on the download page to your device. Before upgrading an existing client, note its name, configuration source, and traffic-routing method, and export any settings you want to keep. This helps distinguish migration issues from network problems.
Subscription links often contain credentials, so get yours from your own service account. Don’t post the full link in public comments, screenshots, or shared logs. Before importing, confirm that the service provides a Clash-compatible format or one supported by your target client—not a regular webpage URL, login page, or link intended for another app. An expired service, exhausted data allowance, or reset link can also cause import or connection failures; reinstalling the client won’t fix them.
Understand the Limits of Three Traffic Routing Methods
| Method | Works With | Keep in Mind |
|---|---|---|
| System proxy | Apps that follow the system proxy settings | Not all apps use it |
| Explicit proxy | Individual apps that let you enter a proxy address | The address, port, and proxy protocol must match |
| TUN | Traffic routed through a virtual network interface | Requires the right permissions, routes, and DNS setup |
For your first setup, start with the simplest option. On desktop, verify the local proxy port and system proxy first; consider TUN only if an app ignores the system proxy. Mobile clients typically route traffic through the system VPN interface. The VPN icon indicates local traffic routing—it doesn’t mean the client provides a remote service. TUN is not a proxy mode: after enabling it, Rule, Global, or Direct still determines how traffic is handled.
Follow a Consistent Order for Your First Test
Recommended order: install and launch the client, import and select a configuration, check the proxy groups, enable one traffic-routing method, then test with an app. Check for an observable result at each step: the configuration appears by name, proxy groups are selectable, the core is running, and the request appears in the connection log. A tray icon or VPN indicator alone doesn’t prove the remote connection works. Don’t run multiple clients at once to “improve your chances.”
First, visit a site that normally works without a proxy to confirm your basic network connection. Then try a destination that requires a proxy. Check which rule matched the request and which proxy group handled it. Selecting a proxy doesn’t guarantee DNS resolution, and a working browser doesn’t mean command-line tools are using the proxy. Test each part separately to narrow down the issue instead of changing DNS, ports, and nodes all at once.
Before quitting the client, turn off any system proxy or traffic routing it enabled—especially before switching to another client. A note of the working port, proxy group, and routing method is more useful for troubleshooting than a full-screen screenshot of your nodes. The following sections use the same verification steps, with platform-specific details on installation, permissions, and background operation.
2. Windows: Installation, System Proxy, and TUN
Choose an Installer and Launch the Client
On the Windows downloads page, Clash Plus is the recommended choice. Other options include Clash Verge Rev, FlClash, and Clash Nyanpasu. Clash for Windows remains available as an archived, discontinued client. Check your system type under Settings → System → About, then choose an architecture listed on the download page. x64 and ARM64 are not interchangeable labels.
Follow the installer wizard for an installer package. For an archive, extract it to a permanent folder before launching the main program; don’t run it from a temporary archive location. If a security warning appears on first launch, verify the file’s source and publisher rather than disabling system protection. You don’t normally need to run the regular interface as an administrator, but installing services, virtual adapters, or routes may require separate authorization.
Import a Subscription and Select the Active Configuration
Open the configuration manager, paste the subscription URL provided by your service, and import it. In Clash for Windows, use the download control under Profiles. When the import finishes, select the configuration and wait for the core to load it. If you see a configuration name but no proxy groups, check the parsing log. Make sure the response isn’t a login page or a proxy-only list being used as a complete configuration. Repeated imports won’t fix an error.
Open the Proxies or proxy groups page. Rule mode is usually the best choice for everyday use; select an available proxy in the manual selection group. The results of an automatic group depend on its test URL and settings, and don’t guarantee that every site will work. Open a target app, then check the connection log for the matched rule and outbound proxy. If no new entry appears, first check whether the app is reaching the local proxy before switching nodes.
Verify the Local Port with the System Proxy
Check the HTTP or mixed-port listener shown in the client, then enable System Proxy. The commonly used example port 7890 is not universal; use the value shown in your settings. Windows system proxy settings, browser proxy extensions, and app-specific proxies can all be active at once, so use just one clearly defined route when testing. LAN access is not required for local browsing; leave it disabled unless you need to share the proxy with other devices.
curl.exe --proxy http://127.0.0.1:7890 https://example.com/
Use the command above only if the local listener is actually on 7890 and supports HTTP proxying. Specifying the proxy explicitly avoids differences in whether an app reads system settings. If the local port refuses the connection, check that the core is running, the listen address is correct, and the port is not already in use. If the local proxy connects but the remote request fails, check the proxy group, service status, and DNS. Whether a terminal tool follows the system proxy depends on the tool.
Check the Service and Permissions Before Enabling TUN
Enable TUN only if a target app ignores the system proxy or you need to route specific UDP traffic, and follow the client’s instructions to install its service. In older versions of Clash for Windows, check Service Mode and TUN Mode separately; other clients may use their own service mechanisms. After authorizing, confirm that the virtual interface, routes, and DNS settings are active. An enabled switch is only an interface status, not proof of a working connection.
Corporate VPNs, virtual machines, container networks, and other proxies can all modify routes. If LAN devices become unreachable after enabling TUN, turn TUN off and compare, then check private-network bypass settings and existing routes. Don’t delete an unfamiliar virtual adapter. If the connection fails after waking from sleep, restart the core and re-enable traffic routing. If the issue keeps returning, check the logs for interface changes.
Fix Lingering Proxy Settings and Migrate from Older Clients
If the client exits unexpectedly and your browser says the proxy server can’t be reached, open Windows network and Internet proxy settings and check whether they still point to a local port that is no longer listening. Restore your network connection before restarting the client. Don’t switch auto-detect, setup script, and manual proxy settings at random. Record the original values, especially on managed devices, so you don’t overwrite organization policies.
When migrating from Clash for Windows, reimport the original subscription, then migrate rules and overrides one at a time. Don’t copy the old client’s entire data directory over the new one. Core differences may make older fields invalid, and TUN settings may have changed. First confirm the new client works with its default routing method, then restore convenience settings such as launch at startup. If you keep both clients installed, ensure only one controls the system proxy or TUN at a time.
3. macOS: Installation, Permissions, and Network Extensions
Choose a Client for Your Mac’s Processor
Open About This Mac from the Apple menu to check whether your device has Apple silicon or an Intel processor, then choose the corresponding build on the macOS downloads page. Clash Plus is the recommended choice; Clash Verge Rev and FlClash are also available. ClashX Meta is discontinued and kept for reference. Don’t apply an older guide’s steps to every client just because you recognize the interface.
If the download is a disk image, open it and follow the prompts to move the app to the Applications folder, then launch it from there. Running directly from the disk image or a temporary downloads folder can affect updates, helper paths, and permission records. If macOS blocks the app on first launch, verify its source and identity, then check the relevant notice under System Settings → Privacy & Security. Don’t start with recursive permission changes or commands that disable system security.
Understand Proxy Permissions, Helper Services, and Network Extensions
A macOS client may request permission to change network proxy settings, install a helper service, or add a network extension. These are separate capabilities, and not every client uses all of them. The permissions needed for TUN may differ from those needed for the system proxy alone. An authorization prompt should appear after you perform the related action and name the app. If a prompt appears unexpectedly, cancel it and repeat the action in the client to confirm what triggered it.
Where to approve a network extension varies by macOS version and client, so follow the app’s instructions to find it in System Settings. Some services need to reconnect after approval; others require an app restart. Don’t confuse “extension allowed” with “proxy connected.” On managed Macs, a configuration profile may restrict network extensions. Follow your organization’s device policy instead of repeatedly reinstalling or trying to bypass permissions.
Import a Configuration and Check Proxy Selection
Add the subscription link on the configuration page and explicitly select the configuration you want to use. If the client supports both remote subscriptions and local files, make sure you know which one you’re editing; otherwise, you may change a local file while the client is still using a remote configuration. After importing, check that proxy groups appear, Rule mode is selected, and an available proxy is chosen. Keeping the existing configuration when an update fails helps distinguish an existing connection issue from an update request problem.
Start by opening a target site in a browser, then check the connection log. Some apps have their own network settings, and browser extensions may override the system proxy. If the browser works but the terminal doesn’t, test by specifying a proxy for the command. If only one app fails, check its own proxy, certificates, and network permissions. Don’t change system-wide DNS or reorder every network service because one app can’t connect.
Test the System Proxy and TUN Separately
After enabling the system proxy, check the proxy address and port in the settings for the active network service. Switching Wi-Fi, Ethernet, or dock connections may change the active service, so the proxy settings that worked before may not apply to the new one. Check the current network instead of relying only on the client’s toggle. The system proxy works for apps that follow it; it can’t guarantee that every process or protocol is routed.
Before enabling TUN, turn off other tools that route traffic and confirm the client’s helper service or extension is running. If TUN fails, compare the network with TUN disabled, then check DNS and route logs. If remote desktop, LAN printing, or network storage stops working, check LAN bypass and private-network rules. Don’t route all local network traffic through a remote proxy just to make one site load.
Handle App Errors and Network Changes
“App is damaged” is a system notice; it doesn’t prove the file is damaged or safe. First check that you chose the right architecture, the download completed, and the app came from a verified source, then review the developer’s release notes. Before changing quarantine attributes or system extensions, make sure you understand the scope. For more, see macOS Network Extensions and Keychain Permissions. Don’t treat a command you found online as a universal fix.
Export your configuration and custom overrides before upgrading or migrating. When switching clients, turn off the old client’s system proxy and traffic routing before enabling the new one. After waking from sleep, switching hotspots, or joining a corporate network, check basic connectivity and complete any captive portal sign-in first. If needed, temporarily disconnect the proxy to sign in, then reconnect. This avoids mistaking a network that hasn’t been authorized yet for a broken subscription node.
4. Android: Installation, VPN Permission, and Background Use
Choose an Installer and Client
On the Android downloads page, Clash Plus is the recommended choice. Other options include Clash Meta for Android, FlClash, and Surfboard. Installer compatibility depends on your device’s ABI, not just its appearance or the marketing name of its processor. If an installer isn’t compatible, check your device information and the build types on the download page. Don’t repeatedly download the same package or assume an installation failure means the network is blocking it.
When installing from a browser or file manager, Android may ask you to allow installs from that source. Grant permission only to the source you’re using, and disable it afterward if you prefer. If the installer reports a conflict, check whether an app with the same package name but a different signature is already installed. Uninstalling an older app may also delete its configuration and local settings, so back them up first. Don’t clear app data blindly to resolve every installation warning.
Check the Subscription Format Before Importing
Open the configuration manager, choose import from URL, paste your subscription, and save it. Once downloaded, select and enable the configuration; don’t leave it sitting in the download list. Clash Meta for Android, FlClash, and Surfboard don’t use exactly the same configuration formats. In particular, don’t assume a Clash YAML file can be imported into Surfboard. Get a compatible format from your service provider and follow Surfboard’s own import steps.
If import fails, first check that the link is complete, contains no extra spaces, and returns the expected configuration. Different results on mobile data and Wi-Fi may point to DNS, captive portal sign-in, or network restrictions. Keep the error message, then compare using another trusted network. Don’t paste your subscription into a public online converter for troubleshooting. If the link is exposed, reset it in your service account.
Understand VpnService Permission and System Status
The first time you enable traffic routing, Android asks for permission to set up a VPN connection. Clash clients often use VpnService to create a local virtual interface and pass traffic to the core. Once approved, the VPN icon in the status bar indicates that the interface is active—not that the remote proxy is working. Check that the configuration loaded, the right proxy was selected, and a request to your target gets a response.
For a typical personal setup, only one VPN service can be active at a time. A corporate VPN, another proxy app, or certain network-filtering tools may replace or conflict with the current client. If it stops immediately after launch, check whether another VPN is connected. Don’t run several apps and let them compete for the interface. If you need corporate network access, check your organization’s VPN requirements before choosing a traffic-routing setup.
Allow Background Use Without Removing Every Restriction
If the connection drops after the screen has been off for a while, check battery optimization, background activity, and auto-start permissions in system app settings. Menu names vary by manufacturer, so look in the app’s battery management settings rather than copying another phone’s exact menu path. You can relax background restrictions for the client you use. Also check that Data Saver doesn’t prevent it from using the network in the background.
Foreground service notifications help maintain traffic routing, so don’t disable the service just to hide its status notification. Locking the app in recent tasks is only an extra measure on some systems; it doesn’t replace background permissions. If disconnections continue, note whether they happen after the screen turns off, a network switch, or system cleanup, then check the logs. For more tips, see Android VpnService and Battery Optimization Guide. Address the symptom instead of disabling every system restriction.
Per-App Routing and Network Changes
If your client supports per-app routing, read the difference between “only selected apps” and “bypass selected apps”—they do the opposite. You may need to reconnect after changing the selection to refresh the interface configuration. If one app can’t connect, first check whether it’s excluded, then check its rules and DNS. System download components, browsers, and in-app web views may run in separate processes, so an app icon alone doesn’t tell you how every request is routed.
After switching from Wi-Fi to mobile data, existing connections may need to be re-established. Wait for the network to stabilize, reconnect the client, and check whether new requests work. On hotel, airport, and other captive networks, sign in through the portal first. If Always-on VPN and Block connections without VPN are enabled, you may not be able to open the sign-in page while the client is disconnected. Understand the effect on the whole device before changing these settings.
Don’t follow desktop tutorials for Android’s System Proxy toggle. Android uses different traffic-routing methods, permission prompts, and background lifecycle rules. After setup, test in the foreground, after waking the screen, and after switching networks. Once everything works, add customizations such as per-app routing one at a time so you can identify what changes the behavior.
5. iOS: Installation, Subscriptions, and VPN Tunnels
Install Clash Plus from the App Store
Clash Plus is the recommended choice for iPhone and iPad. Start with the iOS client page, then visit Clash Plus on the App Store. The developer’s website is clashplus.io. Review the system requirements and app description on the store page before installing and setting up the app. Don’t rely on a similar-looking search result to identify the right app.
iOS manages network extensions and VPN configurations itself, so desktop steps for installing services or routing traffic through a port don’t apply directly to phones. Think of the process as importing a compatible configuration, choosing a proxy, approving the system tunnel, and testing a real request. The interface may change with updates; use the current feature labels instead of looking for the exact position or icon in an old screenshot.
Import a Subscription and Protect Your Account
Copy a compatible subscription from your service account, then paste and save it in the app’s configuration or subscription manager. Some websites try to open the app to import a configuration. After the redirect, check the source, configuration name, and contents; the app opening doesn’t mean the import is complete. If iOS asks to access the clipboard, make sure you copied your own link before allowing access, so unrelated text isn’t saved as a configuration.
A subscription URL is usually different from a website login URL. Copying a page that requires you to sign in will often download the webpage rather than a configuration. If import fails, check the format and account status before trying again. Full links may contain credentials; don’t put them in public notes or shared screenshots. When asking for help, describe the error and steps, but hide personal identifiers and credentials in the URL.
Approve the VPN Configuration and Connect
When you connect for the first time, iOS may ask to add a VPN configuration and authenticate the device. This registers a network-routing configuration with the system; it doesn’t ask you to give your device password to the subscription service. After approval, return to the app, check the active configuration and proxy group, then connect. Managed devices, restricted profiles, or another active VPN may affect the connection.
The VPN icon in the status bar or Control Center shows that the system tunnel is active, but it doesn’t by itself confirm that rules, DNS, and the remote service are working. Verify by opening a target, checking the connection log, and confirming the selected proxy. If the connection keeps spinning, check the app’s error first, then look for conflicting configurations in iOS VPN settings. Don’t keep adding duplicate entries for the same purpose; they make troubleshooting harder.
Understand Rule Mode and Mobile Traffic Routing
For everyday use, start with Rule mode so the configuration decides which requests go direct and which use a proxy. Global mode generally sends requests handled by the core through the global policy, but it doesn’t control every system request or fix an unavailable node. Direct mode is useful for comparison tests. For details, see Rule, Global, and Direct Modes Explained. After switching, make a new connection rather than just refreshing a page that may still be reusing an old one.
iOS network extensions are subject to system lifecycle and permission constraints, so don’t expect them to behave exactly like a desktop background process. Closing the app interface and stopping the tunnel are not the same thing; check the system and client status to confirm whether the connection is active. If the battery is low, the network changes, or the extension has a problem, check the connection in the app and reconnect the tunnel instead of repeatedly force-quitting the app.
Handle Hotspots, Captive Portals, and App-Specific Issues
When switching from Wi-Fi to cellular, existing connections may need to be rebuilt. First confirm cellular data works and the client has the necessary network permissions, then reconnect. Whether other devices’ traffic goes through your phone’s tunnel when using Personal Hotspot depends on the system and app. A working connection on the phone doesn’t mean hotspot devices are also proxied. Test each device separately and, if needed, configure a client on the device itself.
On public networks that require a web sign-in, complete the captive portal login before reconnecting the tunnel. If only one app won’t open, check its network permissions, account status, and matched rule rather than relying on a mode change. iCloud Private Relay, existing encrypted DNS settings, and organization management policies may also affect request routing. Change one setting at a time and record its original value so you can restore a known-good setup.
Before moving a configuration to another device, check the new device’s service authorization and system requirements. Reimporting the subscription is easier to verify than copying an entire app data folder from an unknown source. Then check proxy selection and on-demand connection settings; don’t assume local preferences come with the subscription. A subscription delivers configuration, but system permissions must still be approved on each device.
6. Linux: Installation, Desktop Proxy, and Services
Choose Between Desktop Use and Server Deployment
For desktop use, choose Clash Verge Rev or FlClash on the Linux downloads page, using a package format supported by your distribution. For servers, routers, or setups where you manage the process yourself, see the Mihomo Core downloads. A graphical client handles configuration paths, process startup, and some permissions for you; a direct core deployment requires you to manage these yourself. The troubleshooting steps differ.
Run uname -m to check the machine architecture, then verify the distribution, package format, and dependencies. The same file extension doesn’t mean a package works on every distribution; an RPM package cannot be installed as a Debian package. Run desktop apps as a regular user when possible. If network management permissions are needed, use the authorization method provided by the client instead of running the entire desktop interface as root.
Install with Your Package Manager and Review the Output
Go to the directory containing the package, verify its name and architecture, then use a package manager supported by your distribution. Read dependency warnings before acting; don’t download libraries from unknown sources and overwrite system directories. If the app installs but won’t open, the problem may be with the display session, graphics dependencies, or runtime environment—not the subscription. Launch it from a terminal and keep the exact error message for troubleshooting.
uname -m
cat /etc/os-release
ss -lntp
These commands help identify the architecture, distribution, and TCP listeners; they don’t configure the proxy. As a regular user, ss may show limited process information, but you can still check whether the local port is listening. Before sharing output, redact personal paths, hostnames, and sensitive addresses. If a port is already in use, identify the process first and then decide whether to change the client’s port. Don’t terminate an unfamiliar system process.
Import a Configuration and Set the Desktop Proxy
In the graphical client, add a compatible subscription, select the configuration, check the proxy groups, and then enable the traffic-routing method you need. Linux desktop environments don’t all handle system proxies the same way. Some apps follow desktop settings, some read environment variables, and others have their own proxy controls. A desktop proxy toggle therefore won’t necessarily configure terminal commands, package managers, and background services.
curl --proxy http://127.0.0.1:7890 https://example.com/
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
Use these examples only if the local port is 7890 and supports HTTP proxying. Environment variables affect only supported processes started from the current shell after they’re set; they don’t change apps that are already running. The proxy URL for https_proxy can still use HTTP because it describes the connection to the proxy. When you’re done testing, run unset http_proxy https_proxy to clear the variables for the current session.
For TUN, Check Permissions, Routes, and DNS Management
Linux TUN typically requires a virtual interface, routing table entries, and appropriate network permissions. A graphical client may provide a service mode; when running the core directly, configure permissions for your deployment environment. Don’t copy settings wholesale from another operating system. After enabling TUN, confirm that the interface and routes were created, then check where DNS requests go. A container, network namespace, and host are separate environments: starting TUN in a container doesn’t route host traffic.
NetworkManager, systemd-resolved, or distribution-specific tools may manage DNS. Directly overwriting /etc/resolv.conf may be undone when the network changes and can break existing symlinks. First find out what manages the file, then change DNS using the appropriate mechanism. Be especially careful over SSH: before changing the default route or firewall, keep the existing session open and have a separate recovery method ready so you don’t cut off your own management connection.
Set the Configuration Directory When Running the Core Directly
With Mihomo, keep configuration files, rule data, and runtime directories clearly organized. Put the core in an executable path, save your configuration in a fixed directory, and test it in the foreground first. The example below uses a user configuration directory; it assumes you’ve created that directory and prepared a valid config.yaml. Set up a service only after the test succeeds, so a background restart doesn’t hide parsing errors.
mihomo -t -d "$HOME/.config/mihomo"
mihomo -d "$HOME/.config/mihomo"
For long-running use, a system service can manage the process, but specify the run user, working directory, configuration path, and required permissions. A successful service start only confirms that the process was launched; check the core logs to confirm the configuration loaded. Validate the syntax before reloading after a change, using the method appropriate for your deployment. When stopping the service, also restore any routes or proxy settings it created. Deleting the executable alone won’t restore the network.
7. Configuration, DNS, and Connection Troubleshooting
Understand Configuration Fields with a Minimal Example
When a configuration fails, first distinguish syntax errors from unsupported fields or behavior. YAML relies on indentation; use spaces, not tabs, and keep fields at the same level consistently indented. List items start with a hyphen. A successful parse doesn’t mean the current core supports every feature. The example below illustrates the local listener, mode, and final rule. It routes traffic directly and contains no remote proxy, so it isn’t a working node configuration.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
mixed-port provides a local listener compatible with HTTP and SOCKS. allow-lan controls whether other devices on the LAN can access the listener; actual reachability also depends on the bind address and firewall. mode sets how policies are applied. Rules are evaluated in order, and MATCH,DIRECT is the final direct-connection fallback. Add custom rules before the fallback; rules after it won’t get a chance to handle matched requests.
Manage Subscription Updates Separately from Mixin Overrides
Keep remote subscriptions as the upstream source and manage custom fields with the client’s supported Mixin, merge, or override feature. Clients don’t all handle arrays the same way: they may append, replace, or merge them specially. Don’t infer behavior from a feature’s name. Rule lists and proxy groups are especially sensitive: an incorrect merge can refer to a nonexistent group, move the fallback, or replace an entire group. Check the final active configuration, not just the contents of the editor.
If a problem starts after an update, compare the previous and current configuration and overrides before clearing all data. The subscription may have changed a proxy group’s name, leaving custom rules that refer to the old one. For how to choose automatic proxy groups, see url-test, fallback, and load-balance compared. To recover, disable the most recently added override first, then check changes one at a time to isolate the issue.
Check the DNS Resolution Path Before Changing Servers
DNS failures can occur at the system, app, core, or remote-service level. If a domain won’t open but a known IP address connects, that’s a clue—not proof that a particular DNS server is failing. Check the logs to see whether the failure is in name resolution, the local listener, or a remote timeout, then confirm whether DNS requests reach the core. An app’s encrypted DNS may use a separate path, and TUN DNS hijacking doesn’t automatically capture every encrypted DNS request.
fake-ip uses synthetic addresses so the core can keep track of domain names; they aren’t the remote site’s real IP addresses. redir-host uses a different mapping method, with different compatibility characteristics. If a LAN domain or specific app has issues, check filtering and resolution settings that match the symptom instead of cycling through public DNS servers. See Clash DNS Configuration Explained for how nameserver, fallback, and filtering rules work together. Before editing, confirm the current core supports the fields you plan to use.
Troubleshoot in the Order Requests Flow Through the Network
| Symptom | Check First | How to Verify |
|---|---|---|
| Local proxy connection refused | Core, listen address, and port | Check the listener and test by specifying the proxy explicitly |
| No requests in the connection log | App traffic path, system proxy, and routes | Switch to a single routing method and make a new request |
| Request matched the wrong proxy | Rule order and proxy group name | Check the matched rule and final outbound proxy |
| Times out after reaching the proxy | Service status, remote connection, and DNS | Select a known-working proxy and compare the logs |
Confirm basic network access first, then check the local listener, configuration load, rules, remote connection, and DNS—in that order. Change one variable at a time and retest the same destination. Browsers cache DNS results and reuse connections, so make a new connection after switching modes; otherwise, you may still be seeing the old route. Restore the log level when you’re done troubleshooting, and remove subscription links, credentials, and identifying browsing details before sharing logs.
Quick Fixes for Common Configuration Issues
Subscription Downloaded Successfully—Why Can’t I Connect?
A successful download only confirms that content was retrieved. Check that the configuration is selected, the core parsed it successfully, proxy groups have an available outbound, and the right traffic-routing method is enabled for your platform. Finally, check the request path in the connection log; don’t rely only on the subscription list’s update time.
Why Didn’t Global Mode Fix the Problem?
Global mode changes proxy selection for requests that reach the core. It won’t fix an app that isn’t using the proxy, an unavailable service, or a local port error. Test the listener explicitly first, then check which proxy the global policy selected. Switch back to Rule mode when you want normal traffic routing.
The Internet Stops Working After I Quit the Client. What Should I Check First?
On desktop, check whether the system proxy still points to a local port, then check whether TUN, routes, and DNS have been restored. On mobile, check the VPN status and whether connections that bypass the VPN are blocked. Preserve your organization’s original network settings; don’t reset the entire network configuration.
To rebuild a clear verification sequence, follow the Quick Start Guide in order. To switch clients, first check platform support and maintenance status on the Download page. Adjust configuration step by step, and keep a clear rollback path: preserve the original subscription, record local changes, stop the old traffic routing, then enable the new settings.