Clash FAQs and Troubleshooting

Graphical clients handle subscription imports, menus, system proxy settings, and logs. The core handles protocol connections, DNS, and rule matching. ClashX is the name of a macOS client; that does not mean every client with the same name, or every fork, uses the mihomo core. To troubleshoot compatibility, check the About page or startup logs to identify the core in use, then review which configuration features it supports. Changing the interface does not necessarily change the core, and replacing the core does not guarantee an older client can manage new features.

The client provides connection and traffic-routing features; the configuration supplies the actual settings, including nodes, proxy groups, DNS, and rules. An installer without a usable configuration usually cannot establish a proxy connection. Use a subscription URL from a trusted provider or import a YAML file you maintain yourself. After importing, select the configuration and check its proxy groups. Subscription links may contain account credentials, so don’t post them on public forums, include them in screenshots, or submit them to online converters. This site’s client installation guides are not a node service.

For everyday use, start with Rule mode, which matches requests against the ruleset in order. Global mode generally sends requests that reach the core to the global proxy group; you still need to choose an available node in that group. Direct mode connects those requests without a proxy. These modes only control how the core handles requests it receives—they don’t mean every app is using the proxy. If an app never appears in the connection list, check the system proxy, the app’s own proxy settings, or TUN routing instead of repeatedly switching modes.

mixed-port is the local port where the client listens for both HTTP and SOCKS connections. 7890 is a common example, not a fixed value across all setups. A node’s port belongs to the remote server and is set by its node configuration; the two are not interchangeable. When configuring a browser or command-line tool to use the local proxy, use the client’s current listening address and port, such as 127.0.0.1 and 7890. If UI settings or overrides take precedence over the configuration, trust the running client’s ports page and startup logs.

A node will connect only if its format is compatible and its server is still available. Free does not mean trustworthy or reliable. Public subscriptions may be shared, throttled, or withdrawn without notice, and may include settings unsupported by your core. Check the source before importing, and don’t submit account subscriptions to unfamiliar conversion services. Keep HTTPS certificate verification enabled when connected. Never install an unknown root certificate just to use a node, and don’t assume a successful client installation says anything about node quality.

In the client’s configuration or subscription page, choose the option to import from a URL, paste the full address, and save. For a local file, use the file import option. Menu names vary by client; in ClashX, manage configurations from the menu bar’s configuration menu. After the download completes, select that configuration, confirm its proxy groups include nodes, enable the system proxy, and test a known website. If the download appears in the history but no nodes show up, check which configuration is selected and what format the server returned. Don’t change ports or enable TUN right away.

Start with the line number and error type in the logs, then inspect indentation, colons, and list markers on and around that line. YAML uses spaces for indentation; don’t mix in tabs. Strings containing special characters may need quotes. If the response starts with HTML, a login prompt, or an access-denied message, you didn’t receive a configuration file—changing indentation won’t help. Keep a copy of the original, make one change at a time, and reload. Also check that the subscription outputs a format supported by your core.

First confirm that your client supports TUN, then use its settings page to install or repair the service component. Windows clients typically need administrator privileges to install the service; macOS may require approval for a helper component, while Linux requires the appropriate network permissions. Don’t loosen permissions on every file. After granting access, check the logs to confirm the virtual network adapter was created and routes were set successfully. If it still fails, close other VPN or TUN clients and use the specific log error to continue troubleshooting.

Launch at startup usually means only that the client opens—not that the system proxy or TUN turns on automatically. Check the settings for launching at login, enabling the proxy on startup, service mode, and the selected configuration. On Windows, check Startup apps in Task Manager; on macOS, check Login Items and extensions in System Settings. If the network isn’t ready when the client starts, a subscription update may fail. Keep a working local configuration and update it manually once the network is back; don’t rely on downloading a fresh configuration every time you start the client.

Migrate subscription URLs, your own nodes, and rules confirmed to be compatible. Don’t copy the entire application data folder. System proxy state, service components, TUN adapters, and UI overrides usually belong to the client and can’t be migrated just by copying YAML. Close the old client and turn off its system proxy first. Then import the configuration into the new client, check the ports and proxy group names, and test the connection. Clean up the old data only after the new setup is stable, so the clients don’t modify routes at the same time or compete for the same listening port.

Rules are matched from top to bottom. Place custom rules before any broader rule that would match first, including MATCH. For example, DOMAIN-SUFFIX,example.com,DIRECT sends the domain and its subdomains directly. The target policy must be a built-in policy or an existing proxy group; check capitalization too. Prefer the client’s override or persistent-rules feature. Editing a file generated from a remote subscription may work only until the next update. Save and reload, then check the matched rule in the connection details.

Connect the devices to a trusted local network where they can reach each other. In the computer client, enable LAN access and confirm the listening address accepts connections from other devices. Then enter the computer’s LAN IP and actual mixed port in the phone or TV’s proxy settings—not 127.0.0.1. Allow that port through the computer’s firewall only for the local network segments that need it; don’t expose it on public networks. Whether a device uses the proxy depends on the app, and a manual HTTP proxy usually can’t handle all UDP traffic.

Many command-line tools don’t read the desktop system proxy, so you need to set proxy options or environment variables separately. For example, test an explicit proxy with curl -x http://127.0.0.1:7890 https://example.com, replacing the port with the client’s actual value. If it works, check whether the tool supports HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY. Environment variables affect only processes that read them; existing terminals or background services may need to be restarted. Remove the variables too when you’re done testing.

Some apps isolated by AppContainer can’t access a local loopback proxy directly. First confirm that a browser can connect through the same port. Then use the client’s UWP loopback tool to enable loopback exemption only for the apps that need it; the tool may require administrator privileges. If the client has no built-in option, use Windows CheckNetIsolation to check the package’s exemption status. Don’t enable exemptions for every app. Loopback exemptions won’t fix problems caused by DNS, app sign-in, or the firewall.

Manage provider-maintained nodes separately from local settings you want to keep. If the client supports overrides, configuration merging, or scripts, put mixed-port, DNS, and custom rules in the appropriate persistent settings, then inspect the final runtime configuration. Merge order and array handling vary between clients, so don’t assume rules will be appended automatically. After setting this up, update the subscription manually and confirm that the nodes update while your local changes remain. If the client can’t preserve settings, back up a separate configuration and document how you maintain it.

First check the configuration page to see which subscription failed, then look at the status code in the logs. A 401 or 403 may relate to authorization, expiration, or access policy; a 404 may mean the URL changed. The status code alone doesn’t prove the cause. Check that the URL is complete, the account is active, and the response is a compatible configuration. Updates may rely on the current proxy, so try the client’s direct-update option. Contact the provider if only one subscription fails. If all subscriptions fail, check your local network, DNS, and system clock first.

A timeout only means the test didn’t finish within the allotted time. It may be caused by your local network, DNS, the test URL, protocol settings, or the server. Try another node from the same subscription, then test on another network, and confirm the test URL is reachable through that node. If the latency test fails but websites still load, check the test URL settings. If all nodes and direct connections fail, restore your basic network connection first. For authentication errors in the logs, check the subscription and credentials; for connection timeouts, check server reachability. Don’t treat these as the same error.

First check whether the browser’s requests appear in the client’s connection list. If they don’t, make sure the system proxy address and listening port match, and disable browser proxy extensions that override system settings. If requests appear but connect directly, check the matched rule and target policy to make sure they aren’t set to DIRECT. Also distinguish the browser’s HTTP proxy traffic from other traffic the proxy doesn’t capture. Test the local port with an explicit proxy command. If the port itself is unreachable, troubleshoot core startup failures or port conflicts first.

Turn off TUN first and confirm that your basic network connection is back. Then check one thing at a time; don’t keep stacking route changes. Save the error logs, check whether another VPN, virtual adapter, or security app is also handling network traffic, and review DNS and auto-route settings. If IP connections work but domain names don’t resolve, focus on the DNS listener, upstream reachability, and routing loops. If needed, quit the client normally and reconnect to the network; restart the device only if that doesn’t restore access. On a managed work device, follow your administrator’s policies and don’t remove system network adapters yourself.

If you lose internet after quitting the client, check for leftover system proxy settings pointing to your local machine and turn them off. Then check terminal environment variables and browser extensions. Certificate warnings are a separate issue: correct the system date and time, check the certificate issuer and domain, and look for HTTPS inspection or MITM settings. Don’t bypass warnings or install root certificates indiscriminately. If a warning occurs only with one node, stop using it and report the issue to the provider. If it also happens on a direct connection, keep investigating the device or website.