Clash FAQ
Subscriptions, Proxies & TUN

The client is the graphical interface for importing configurations, switching policies, and managing connections. mihomo is the core that handles proxy protocols and routing rules. A subscription is a remote URL that provides configuration or node details. After installing a client, you still need to import a working configuration and select a policy before traffic can be routed according to its rules. This site provides installation and configuration guides; it does not provide proxy accounts. When troubleshooting, first identify whether the issue is the client failing to launch, the configuration failing to download, or a node failing to connect. Treating these as separate steps makes it easier to find the cause.

For everyday use, start with Rule mode. The core routes traffic according to conditions in your configuration, such as domain names and IP addresses. Global mode sends connections handled by the core to the global policy group, but you still need to select an available policy within that group; it does not automatically proxy every app. Direct mode connects traffic handled by the core straight to its destination. After switching modes, start a new request—existing long-lived connections may continue using their previous route. If only one website is affected, briefly switch to Global mode for comparison, then switch back to Rule mode and check which rule matched.

A system proxy writes the proxy address to your operating system settings and mainly affects apps that respect those settings. TUN uses a virtual network interface to capture more traffic at the network layer, though the actual scope still depends on routing, exclusions, and DNS settings. It usually also requires permission to install a helper service. Start by testing your configuration with the system proxy for web browsing; consider TUN only if terminals, games, or other apps do not follow it. When troubleshooting, avoid running multiple proxy tools at once, or it may be hard to identify the route and actual exit point.

Open About This Mac from the Apple menu and check Chip or Processor. If it shows an Apple M-series chip, choose Apple Silicon or arm64. If it shows an Intel processor, choose Intel or x64. A Universal build usually includes both architectures, but check the app’s system requirements too. Don’t rely on your Mac’s purchase year to determine which installer to use. If the app says it isn’t supported after installation, check the minimum macOS version. Choosing a different architecture won’t fix an outdated operating system.

Compatibility depends on the configuration fields, proxy protocols, and core in use; discontinuation doesn’t mean every old configuration stops working immediately. Before migrating, save your current configuration and policy selections. Then reimport your subscription in a maintained client and check its rules, DNS, and TUN settings. Don’t overwrite the new client’s entire data directory. An older core may not recognize newer protocols or fields. If configuration parsing fails, use the error to identify the unsupported field and ask your subscription provider for a compatible configuration.

After opening the DMG, drag the app to the Applications folder and launch it from there rather than running it from the disk image. Make sure the installer’s architecture matches your system requirements. If macOS blocks the app, verify the download source, then check the alert in System Settings → Privacy & Security and follow the option macOS provides. Don’t disable system-wide security to launch a single app. If you see a damaged-app or signing error, download it again and check the client’s release notes for known issues.

Open the client’s Configuration or Subscription page, choose the option to import from a URL, paste the full subscription URL, and save it. Once the download finishes, make sure the new configuration is selected. Then open the proxy page, choose a policy, enable the system proxy, and visit a website you know is reachable. Import local YAML files through the file import option, not the URL field. Subscription URLs may contain account credentials, so hide sensitive parts of the full URL before sharing screenshots, logs, or support requests.

Start with the line number and field name in the error. The response might be a login page, a subscription-expired notice, or a Base64-encoded node list instead of the Clash YAML configuration the client expects. Ask your provider which subscription format to use; changing the file extension alone won’t help. If it is YAML, check that indentation uses spaces, that there’s a space after each colon, and that the current core supports the fields. Save a copy before editing. Don’t upload configurations containing private node details to unfamiliar online conversion services.

Turn off TUN first. In the client settings, find the option to install the helper service or service mode, then grant permission as prompted by the system. Restart the client after installation, enable TUN, and check the core logs for virtual interface or route creation errors. The option may have a different name in other clients; refer to the documentation for your version. If your device is managed by an organization, its permission policies may block installation, so check with your administrator. Verify the app’s source before granting permission, and don’t run privilege-escalation commands from untrusted sources.

First confirm that the client core is running, the intended configuration is selected, and the current policy is available. Then check the proxy settings for your current macOS network service and make sure the address and port match what the client shows—especially after switching between Wi-Fi and Ethernet. Browser extensions, custom proxy settings, and other proxy apps can override system settings; pause them and try again. Finally, check the connection log: if the request doesn’t appear, investigate how traffic is being captured; if it does, check the matched rule, selected policy, and node status.

Many command-line tools don’t read the macOS system proxy. Check which HTTP or mixed port the client is actually listening on, then set environment variables such as HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY as described in the tool’s documentation. HTTPS_PROXY usually specifies the proxy to use for HTTPS destinations; it doesn’t mean the proxy address itself must use the https protocol. Test in a single terminal session first. Once confirmed, you can consider adding the setting to your shell configuration. Clear the variables after testing so commands don’t keep pointing to a local port after the client exits.

Follow your subscription provider’s recommendation; frequent updates aren’t needed to keep a subscription working. If the configuration changes infrequently, start with an interval of a few hours to a day and update manually when needed. Time units and catch-up behavior after sleep vary by client, so check the interface before saving. If an update fails, keep the current working configuration rather than repeatedly deleting and recreating it. Subscription updates only fetch configuration; node connectivity also depends on your account, network route, and the node service itself.

Open the client’s connection page, visit the website, and find the new connection by domain or process. Check the matched rule, policy group, and actual exit point. If needed, temporarily increase the log level, reproduce the issue once, then restore it to prevent logs from growing indefinitely. Rules are generally matched in order, so an overly broad rule placed too early can take precedence over more specific rules. After editing the configuration, reload it and start a new request. Browser caching, connection reuse, and encrypted DNS can all make the results differ from what you expect.

Check the connection log to confirm that the website is using the selected policy, rather than matching Direct mode or another policy group. Close the relevant page and reconnect; if needed, close only the existing connection for that site. A website may also infer your location from your account region, cookies, location permissions, or browsing history, so its language alone doesn’t tell you whether your exit point changed. To test your network exit, use a reputable IP lookup service. Note that different domains on the same website may match different rules.

First make sure the current network can reach essential services directly. Complete any public Wi-Fi sign-in, then restore the proxy. Test the node again. If the problem persists, toggle the system proxy off and on; on devices using TUN, restart TUN and check the logs for routing or DNS errors. Existing connections may stop working after a network change, so reopen the affected app to test. If the issue recurs, note the network type and steps that trigger it, then test with only the system proxy and only TUN enabled to narrow down the cause.

Check that you copied the full URL, your account hasn’t expired, and the provider hasn’t changed the subscription endpoint. Check the status code in the update log: 401 or 403 often indicate an authentication or access-policy issue; 404 may mean the URL or resource has changed; 429 means the request is being rate-limited. Follow your provider’s guidance for the specific error. For timeouts or DNS lookup failures, check the network and DNS first. If the update relies on a proxy that’s no longer working, use the client’s direct-update option if available, or test from another working network.

Not necessarily. Latency tests often send a request to a specific test URL. A timeout can result from that URL being unreachable, a DNS issue, or a timeout threshold that’s too short. Compare with another node, then try visiting the target website in a browser and check the connection log. If all nodes fail at once, check your account status, subscription updates, system clock, and local network. If only one node fails, contact your provider. A latency test isn’t a bandwidth test, and a single result can’t establish whether every service is available.

Turn off TUN first and confirm that your basic network connection is back. Check whether other VPNs, virtual network interfaces, or proxy tools are running, and temporarily use only one traffic-capture tool. Look for route conflicts, DNS listener failures, and permission errors in the logs, then address each reported issue. Don’t replace your entire DNS configuration by copying in a different one. If the problem persists after closing the client, check for leftover system VPN or proxy settings, then reconnect to the network or restart the device if needed. Once connectivity is restored, re-enable TUN with a minimal configuration to test it.

Some Windows apps isolated with AppContainer may be restricted from accessing a local proxy address. First confirm that a regular browser can connect through the same proxy. Then use the client’s loopback exemption tool to exempt only the affected app, granting administrator permission when prompted. UWP means Universal Windows Platform, but loopback restrictions don’t affect every Store app. If the app still can’t connect, check its network permissions, firewall settings, and proxy method. When removing an exemption, remove it only for the affected app.

If you lose connectivity after quitting, check your system network settings for a manual proxy still pointing to a local port that’s no longer running. Disable the leftover setting and try again. If startup reports that a port is in use, quit other proxy clients and check whether an old core process is still running, then use the logs to identify the conflicting port. After changing the listening port, also check the system proxy, terminal variables, and browser settings. Don’t randomly terminate unfamiliar system processes. If you still can’t identify the cause, save the logs and note the steps you took before asking for help.