Clash FAQ
Installation, setup, and connection troubleshooting

The client loads configurations, forwards proxy traffic, and applies rules, but it does not provide usable remote servers. Subscriptions usually come from a service provider and contain server addresses, authentication details, proxy groups, and routing rules. After importing one on the Config or Profiles page, select it, then choose an available proxy on the Proxies page. Installing the client, saving a subscription URL, or importing a configuration without activating it does not establish a connection. Treat subscription URLs as sensitive information; never post a complete URL in public comments or screenshots.

The core reads configurations, matches rules, and establishes proxy connections. A GUI client displays configuration lists, system proxy controls, logs, and installation settings. mihomo is an actively developed core in the Clash ecosystem, but not every client branded with Clash uses the same core or supports the same configuration fields. To troubleshoot compatibility, note the client name, core type, and failing field on the About or Core Information page. Button locations vary between clients, so look for setting names in the interface rather than relying on a tutorial’s screenshots.

Rule mode matches traffic against the configuration’s rules and routes each destination directly, through a proxy group, or to a reject policy. It’s suited to everyday use. Global mode sends traffic handled by the core through the global policy group; you still need to select an available proxy in that group, and it does not automatically capture traffic from every app. Direct mode connects destinations without a proxy and is useful for comparison and troubleshooting. Existing long-lived connections may keep using their previous route after a mode change, so reload the page or restart the affected app. To change which traffic is captured, check the system proxy or TUN settings—not just the mode.

An older client may still read its existing configuration, but with development discontinued, future OS compatibility, protocol support, and bug fixes are not guaranteed. Before migrating, export your local rules, overrides, and subscription source, then choose a maintained client that supports the configuration syntax you need. Don’t copy the entire old program folder over the new client’s directory. Import the original subscription first and confirm it loads and connects; then migrate custom DNS settings, ports, and rules one at a time. If you encounter unknown fields or unsupported protocols, check the new client’s logs and ask the configuration provider which format is compatible.

First, determine whether fetching or parsing failed. For a 401 or 403 error, check whether the subscription expired, its URL was reset, or the provider restricts access. For a timeout, check your network and the client’s proxy settings for subscription updates. A YAML parsing error may mean the response is a login page, an error page, or an incompatible configuration. Copy the full subscription URL again and make sure it contains no extra spaces. Keep the working configuration before updating; don’t repeatedly delete and recreate it after a failure. Avoid submitting URLs containing authentication details to unfamiliar online subscription converters.

In the client settings, first confirm that service mode, helper programs, or virtual network adapter components installed successfully, then grant permissions as prompted. Windows usually requires installing a service with the appropriate permissions; macOS may require approval for network-related permissions; Linux permissions depend on the package and service configuration. Don’t mask a service installation problem by permanently granting excessive permissions to the entire app. For the first test, disable other VPNs or virtual network tools. After enabling TUN, check the logs for adapter or routing errors. If your connection drops, disable TUN to restore network access, then investigate the specific error.

Close any duplicate client instances, then identify the process listening on the port. Check what it does before stopping it; don’t terminate an unfamiliar system service. You can also change mixed-port in the client’s port settings, apply the change, and check the logs to confirm the new port is listening. Then toggle the system proxy off and on, and update any browser proxy settings, terminal environment variables, and in-app proxy addresses. external-controller is a control interface, not a proxy port for browsers—don’t use it as one. Subscription overrides may replace the port value, so make sure your change persists after updates.

Some Windows apps restricted by app containers can’t connect directly to a loopback proxy on the same device. First confirm that a regular browser can connect through the same client. Then use the client’s UWP loopback tool to enable exemptions only for apps that need the local proxy; administrator approval may be required. If there’s no built-in tool, manage exemptions by app package identity with Windows’ CheckNetIsolation tool. Don’t enable loopback access indiscriminately for every app. If the client uses TUN to capture traffic, routing or DNS may be the cause instead. Check the logs to distinguish these issues rather than attributing every Store app problem to loopback.

The system proxy affects only apps that read that setting. Browser extensions, a browser’s own proxy settings, and terminal environment variables can all change the route traffic takes. Temporarily disable proxy extensions, check that the proxy address in system settings points to a port the client is listening on, then test the browser on its own. In the terminal, check HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, along with their lowercase forms; reopen the terminal after changing them. Don’t enter a control interface port as a proxy. If an app doesn’t use the system proxy, try its built-in proxy settings or, after checking routes and permissions, use TUN.

A speed test reports the result of one request from the client to a specific test address. It doesn’t prove that every site, protocol, or connection method will work. First check which proxy group the current rule matches and which proxy that group actually selected, then review the logs for the failed request. If the test address works but the target site doesn’t, the cause may be site restrictions, DNS, the server’s exit route, or protocol compatibility. Don’t keep switching nodes based only on latency. Compare proxies against the same destination in the same mode, closing existing connections after each switch, to tell whether the selected node made a difference.

Use the client’s override, configuration merge, or rule extension features whenever possible. Don’t edit a cached subscription file that the next update will replace. Note the domain to match and the desired policy, then put the rule before broader rules that could match first; MATCH is usually the final fallback. The policy name must exactly match a proxy group in the configuration. After applying the rule, check the connection details or logs to see which rule matched, then update the subscription and confirm the rule is still there. Rules such as GEOSITE also require the relevant data files and core support; copying a rule alone won’t meet those runtime requirements.

Enable startup at login in the client settings, then check your system’s startup or login items to confirm the app is allowed to run. Startup at login, automatic system proxy activation, and automatic TUN startup are often separate settings; enabling one doesn’t configure the others. After restarting, check that the client is running, the intended configuration is enabled, and the port is listening, then test a webpage. If the client didn’t exit cleanly before shutdown, the system may retain proxy settings pointing to the local machine. Network access will fail while the client is stopped. Turn off the system proxy to restore access, then check startup permissions and service status.

Turn off the proxy first and confirm your local network can reach sites that normally connect directly. Then check the system clock, subscription status, and whether the current configuration is loaded. Re-enable the proxy, select a single proxy, and test the same destination. Check the logs to see whether the failure is a timeout connecting to the server, an authentication error, or a failure connecting to the destination. Trying another network can show whether your current network restricts the connection, but keep all other settings unchanged. If several proxies fail on different networks, ask the provider to check their status. Increasing the timeout only makes you wait longer; it won’t fix an invalid address, incorrect credentials, or an unreachable server.

First determine whether DNS resolution is failing or taking an unexpected route. Check the active configuration’s dns settings and whether client overrides changed nameserver, fallback, or the enhanced mode. How these fields work also depends on core support. Browser Secure DNS, encrypted DNS in the OS, and other VPNs may use separate resolution paths; record and test them one at a time. With TUN enabled, confirm that DNS hijacking and routing are working. The resolver location shown by a DNS test site is only a clue, not proof of how every app resolves names. After making changes, verify them against logs and actual requests.

Don’t bypass the error by disabling certificate verification or installing a root certificate from an unknown source. First make sure your system date, time, and time zone are correct. Then compare results with the proxy off, a different proxy selected, and another network. If only one proxy causes certificate errors, stop using it and report the issue to the provider. Corporate networks, public Wi-Fi sign-in pages, and security software that inspects HTTPS can also affect certificate chains; follow the requirements for your network. When reporting the issue, include the error code and destination domain, but avoid sharing screenshots or logs that contain account details, subscription URLs, or full request parameters.

First turn off any leftover manual proxy in your system’s network settings and confirm that your basic connection works. If TUN was enabled, restart the client and shut TUN down normally; if needed, restart the system to clear temporary routes. Before reinstalling, back up the configuration directory, override rules, and logs from the time of the failure. Remove subscription URLs and authentication details before sharing anything. Then start with a minimal configuration and restore features one at a time to see whether a setting or permission change triggers the crash. On mobile, also check VPN permissions, background battery restrictions, and conflicts with other VPNs. Don’t clear app data and lose useful troubleshooting information.