Clash FAQ
Configuration & Connection Troubleshooting

The client manages subscriptions, proxy groups, and system proxy settings. The mihomo core listens on ports, resolves DNS, and applies routing rules. Linux desktop users can start with Clash Verge Rev; server users can run the core directly. The two may store configuration in different locations, and graphical clients may generate a runtime configuration. Before troubleshooting, check which binary is running and which config directory it uses. Don’t edit an unused config.yaml. Command-line setups typically use ~/.config/mihomo/, but the -d or -f startup argument is authoritative.

For everyday use, start with Rule mode (mode: rule), then check which rule and proxy group match your traffic. Global mode sends general connections to the GLOBAL group, but that group can still select DIRECT. It also won’t capture traffic from apps that never reach the core. Direct mode sends connections that do reach the core straight to their destinations, making it useful for comparison tests. After switching modes, start a new connection; existing long-lived connections may keep using the old route. If an app behaves the same, first check whether it uses the system proxy or is captured by TUN, then review the mode setting.

The client and core provide connection and traffic-routing features, but they don’t provide a working remote proxy by themselves. A subscription usually includes nodes, proxy groups, or rules, though some provide only a node list. Before importing, confirm that the provider offers a format supported by Clash or mihomo; a Provider file containing only nodes can’t replace a complete config. After importing, activate the config, choose an available exit in the relevant proxy group, and check your plan’s expiry date and traffic allowance. Subscription URLs often contain credentials, so don’t post them in public logs, screenshots, or online conversion tools.

Not necessarily. The system proxy works well with browsers and apps that honor desktop proxy settings. TUN uses a virtual network interface and routing to capture more connections. For a first-time setup, leave TUN off and verify the node and port with an explicit proxy, then test TUN separately. This helps distinguish config issues from system permission problems. If you enable both, check the client’s route exclusions and DNS settings to prevent duplicate capture or connection loops. TUN doesn’t guarantee that all traffic will be proxied; the final route still depends on rules, proxy groups, and bypass settings.

First make sure the imported config is active, not just saved in the config list. Then check the subscription update log to see whether the response was actually a login page, an error page, or an empty file. If the config uses proxy-providers, a successful load of the main config doesn’t mean the node list was fetched; check the relevant Provider’s status, path, and remote response too. For a command-line setup, run mihomo -t -d ~/.config/mihomo to validate the config, then check the runtime logs for download errors. Don’t post subscription URLs containing credentials in public support forums.

A 401 usually means authentication is missing or the credentials have expired. Get a fresh link from your provider. A 403 may also be caused by access policies, request headers, or usage limits; check the response body. For timeouts, first confirm that your network can reach the subscription URL. If needed, check whether the proxy used to fetch the subscription depends on nodes that haven’t loaded yet. For certificate errors, check the system clock with timedatectl, then verify that your distribution’s CA certificates are installed. Don’t permanently bypass the error by disabling certificate verification. If the URL has changed, replace the old one, refresh manually, and review the HTTP status and logs.

Run ls -l /dev/net/tun to check whether the device exists. If it’s missing, check the tun module and, if needed, run sudo modprobe tun. Then confirm that the running core has permission to create a virtual network interface and change routes. If available, use the graphical client’s service installation option. For a direct setup, some environments can grant capabilities with sudo setcap cap_net_admin,cap_net_bind_service=+ep /usr/local/bin/mihomo, but the path must match the actual binary. You may need to grant them again after replacing the binary. Containers also need the device and network capabilities passed through, and systemd capability restrictions can prevent the permissions from taking effect.

Run systemctl --user cat mihomo and check ExecStart. Make sure the binary and config directory exist. Use explicit paths in the service; for the config directory, you can use %h/.config/mihomo. Don’t rely on the shell expanding ~ or on environment variables from an interactive terminal. Test the same directory with mihomo -t -d ~/.config/mihomo, then run journalctl --user -u mihomo -b -n 80 --no-pager to see why the service exited. After editing the service file, run systemctl --user daemon-reload and restart the service. Don’t mix user-service and system-service commands.

The desktop system proxy isn’t a universal way to capture traffic. Some command-line programs only read environment variables, while some apps use their own proxy settings. First verify the explicit proxy path with curl -I -x http://127.0.0.1:7890 https://example.com. Then configure http_proxy, https_proxy, or ALL_PROXY as documented by the program. Support for uppercase and lowercase variable names varies, and NO_PROXY may bypass the proxy for a destination. If you need to capture traffic from an app that doesn’t support proxy settings, consider TUN after confirming the explicit proxy works. Don’t assume terminal traffic is proxied just because the desktop proxy is enabled.

First confirm that a regular desktop browser can connect through the same port. Then check whether the app is affected by container loopback restrictions. Some UWP apps need a loopback exemption to access a proxy at 127.0.0.1. If available, use the client’s UWP loopback settings and select only the apps that need access. In an administrator terminal, CheckNetIsolation LoopbackExempt -s lists existing exemptions. Before making manual changes, verify the exact package family name. Grant access only to the apps that need it; don’t modify unknown apps in bulk. If TUN is enabled, also check whether the app’s traffic is actually reaching the core instead of assuming every failure is a loopback issue.

You need the right listening address, allow-lan setting, and firewall rules. After setting allow-lan: true, check that bind-address allows your LAN address and use ss -lntp to confirm where the proxy is listening. Other devices should use this computer’s LAN IP and mixed-port, not 127.0.0.1. Open the proxy port in the firewall only to trusted networks, and enable proxy authentication if needed. Keep the external-controller management interface restricted to localhost unless you’ve explicitly configured access controls. Sharing an HTTP proxy and setting up a transparent gateway are different deployments; opening a proxy port alone doesn’t make this computer a gateway.

For HTTP-type proxy-providers, set interval in seconds to control update frequency. For example, interval: 3600 checks once an hour. Give each Provider its own cache path and make sure the service user can write to it. health-check.interval controls node health checks, not subscription refreshes. Lowering it won’t fetch new nodes sooner and will increase requests and power use. A graphical client may schedule config updates separately from the core’s Provider updates, so first determine whether you’re refreshing the whole config or just the node list. Back up the config before making changes, then check the logs to confirm what was fetched.

Make sure the subscription is valid and the selected proxy group is using a remote node. Then check that the node’s server address resolves and the system clock is correct. If one node fails but others work, focus on that node or the test target. If all nodes fail, check the local network, firewall, subscription status, and core logs. A latency test reports the connection result for its specific test address; it doesn’t prove that every website is unreachable. For comparison, try an explicit proxy request to an HTTPS site you actually need and note which connection stage fails. Don’t change DNS, ports, and mode all at once. Change one thing at a time so you can identify what fixed it.

First check that mixed-port is listening, then compare a request through an explicit HTTP proxy with a browser request. Try curl -I -x http://127.0.0.1:7890 https://example.com. If the request succeeds but the browser fails, check the browser’s proxy settings, extensions, and secure DNS. If the logs show a name-resolution error, verify dns.enable, access to the upstream DNS server, and TUN DNS capture. In fake-ip mode, receiving a mapped address is usually expected and doesn’t by itself indicate a problem. If an app has cached an old result, restart it and make a new connection; check both system and browser caches if needed.

Run ss -lntp to see TCP listening ports, especially the ports used by mixed-port and external-controller. Use sudo to inspect processes owned by other users. Common causes include a graphical client and a manually started core running at the same time, or duplicate user and system services. Identify which process owns the port before stopping an instance; don’t kill every process with the same name. You can also change the conflicting port, but update the system proxy, environment variables, and dashboard connection address as well. If the error involves UDP, also check ss -lnup so you don’t assume a port is free based only on TCP.

Run systemctl --user is-enabled mihomo and systemctl --user status mihomo to tell whether the service is disabled or failed to start. To start it with the user manager at boot, run systemctl --user enable --now mihomo. Whether a user service keeps running after logout also depends on linger; check with loginctl show-user "$USER" -p Linger. If it needs to run without an active login, assess the implications before running loginctl enable-linger. If TUN needs extra permissions, check separately that an upgrade hasn’t removed them. Finally, make sure the desktop proxy or terminal variables still point to a listening port, rather than checking only the service status.