FAQs and Troubleshooting

Clash commonly refers both to a proxy core and to graphical clients built around that core. The core reads configuration, matches rules, and forwards connections, while the client provides interface features such as subscription management, system proxy controls, and log viewing. Before choosing an installer, confirm that the client supports your operating system and check which core it uses and whether it is actively maintained.

The client mainly loads configuration and forwards traffic; it usually does not provide usable proxy nodes directly. Before first use, prepare a valid subscription URL or a local YAML configuration file. A successful import only means the configuration can be read. Whether nodes connect depends on the subscription, server status, network environment, and configuration contents.

A subscription URL retrieves a remotely hosted configuration that can be updated; a configuration file stores ports, DNS, proxy nodes, proxy groups, and rules; a node is an individual proxy server entry within that configuration. Updating a subscription usually regenerates the configuration, so manual edits to a generated file may be overwritten during the next update.

Rule mode chooses direct or proxied connections according to the order of rules in the configuration and suits everyday use. Global mode sends all connections through the selected proxy group, which is useful for temporarily testing nodes or troubleshooting rules. Direct mode bypasses the proxy and helps determine whether the client is causing the problem. Switching modes does not repair unavailable nodes or invalid subscriptions.

A system proxy uses the operating system's proxy settings to handle traffic from apps that support them. It is simple to configure but has limited coverage. TUN mode creates a virtual network device that can handle more programs that ignore system proxy settings and some UDP traffic, but it requires additional permissions and is more susceptible to interference from firewalls, virtual adapters, and other networking software.

On the client's subscription or configuration page, choose Import from URL, paste the complete address, and save it. Wait for the client to download and parse the configuration, then set the new configuration as active and choose a proxy group on the proxy or group page. Do not paste the subscription URL into a browser search box or publicly share links containing personal parameters.

First confirm that the imported item is set as the active configuration rather than merely saved in the subscription list. If it is still empty, check the logs for YAML syntax errors, invalid field types, or download failures. The subscription may also have returned a web page, a login prompt, or empty content. Check that the URL is complete and the account is active, then try updating it manually from the subscription page.

Disable the system proxy and try again, so the client does not attempt to update the subscription through its own proxy before a working connection is available. Then check the device time, DNS, and access to the subscription domain. If the URL also fails in a browser, the problem is usually the network or subscription server. If only the client fails, inspect the status code and certificate messages in its logs.

Do not run the client long-term from a protected system directory. Move it to a folder where the current user has write access. Check whether the configuration directory is read-only and whether security software is blocking file creation. If the client needs to modify the system proxy, services, or virtual network adapter, exit it and restart it once with administrator privileges.

On Windows, try launching the client as an administrator and confirm that the required service or virtual network adapter is installed correctly. On macOS, allow the network extension in the system prompt or enter administrator credentials. On Linux, confirm that the TUN device exists and configure the required capabilities for the core, or run it as a privileged service. Fully exit and restart the client after making changes.

Android clients typically use VpnService to handle traffic, and the system must authorize the first connection. If the prompt appears every time, check whether the system is clearing app data, another VPN app is running, or the manufacturer's battery-saving policy is terminating the background process. Normally, only one app can occupy the system VPN channel at a time.

First confirm in the system network settings that the proxy address and port were applied, and verify that the port matches the active configuration. Some browsers, command-line tools, and sandboxed apps do not read system proxy settings; configure a proxy for them separately or use TUN mode. If an unexpected exit left an old proxy behind, disable the system proxy and enable it again.

Some UWP apps are restricted from loopback access and cannot connect directly to a local proxy port. Use the client's UWP loopback tool to enable Loopback Exempt for the apps that need the proxy, then restart those apps. If the client has no such tool, try TUN mode, while still confirming that the virtual adapter and firewall rules are working correctly.

Rules are matched from top to bottom, so more specific domain, process, or network-range rules should come before broader GEOIP, GEOSITE, or MATCH rules. Subscription-generated configurations may overwrite manual edits during updates. For long-term use, maintain custom rules through the client's overrides, configuration merging, or rule-provider features.

Enable LAN access in the configuration and confirm that the listen address accepts connections from the local network rather than listening only on the loopback address. Then allow the relevant HTTP, SOCKS, or mixed port through the firewall. Other devices should use the LAN address of the device running Clash as their proxy server. Expose it only on trusted networks and never to the public internet.

Startup launch usually only starts the client; it may not automatically load a configuration, connect to a proxy group, or enable the system proxy. Check the client's options for restoring the connection at startup, the system proxy, and background services. Also confirm that the active configuration remains readable after reboot. If the system starts slowly, open the client manually after login to check for a startup-order issue.

Switch to Direct mode first to confirm that the local network works, then update the subscription and check the system time and DNS. If the speed-test endpoint is unreachable, every node may appear to time out, so also try opening a real webpage. Log messages such as connection refused, handshake failure, or domain-resolution failure can distinguish offline nodes, incorrect protocol parameters, and DNS problems.

Disable the system proxy or TUN first and confirm that basic connectivity returns. Then select a known-working node, check whether the active proxy group still points to an unavailable node, and look for proxy loops, port conflicts, or DNS errors in the logs. Running the system proxy and TUN mode together can also conflict with other VPNs, accelerators, or security software.

Unauthorized usually means that the credentials in the subscription URL have expired, the account status has changed, or the server rejected the request. Copy the original URL from the subscription manager and check for missing characters, then obtain a new valid URL from the subscription provider. Repeatedly refreshing the client will not fix a server-side authorization problem; an old configuration may stop connecting at any time even if it still contains nodes.

Check the logs first to determine whether the failure occurs during domain resolution or during the subsequent connection. Temporarily disable enhanced DNS, fake-ip, or a custom nameserver to see whether the DNS configuration is responsible. Also check whether rules are sending DNS requests to an unavailable node and whether another DNS-filtering app is active on the system. Clear the cache and reconnect after changing the configuration.