Open-source ecosystem · Cross-platform clients and configuration guides
Start on the device you are using: choose the right Clash client, import your subscription, and verify rule matches and proxy groups. If the connection fails, check the system proxy, DNS, and core logs layer by layer.
CONFIG TRIAGE
Clash interfaces, cores, subscriptions, rules, and system network settings are separate layers. When something goes wrong, narrow the scope before changing configuration; change one variable at a time so you know what actually fixed it.
DOMAIN-SUFFIX
Routing rules determine which proxy group should handle a request. During troubleshooting, find the target domain in the connection log, then check the matched rule type and selected policy. If a request matches a broad rule too early, later specific rules will not run. Put more specific domain rules before broader GEOIP or MATCH rules, and confirm that every referenced proxy group exists. If the rules are correct but the exit still is not what you expect, the issue is usually at the proxy-group layer, so repeatedly editing domain rules will not help.
DOMAIN-SUFFIX,youtube.com,PROXY
PROXY-GROUP
Proxy groups receive traffic assigned by the rules, then choose direct connection, a fixed node, automatic selection, or failover. If a webpage will not load, first confirm in the connection log that the request reached the expected proxy group, then switch exits within that group for comparison. If only one node fails, the problem is probably with that node or route; if every node in the group fails, check the subscription, protocol parameters, and local network. If a proxy group was renamed, update rule references as well, or requests may fall through to the final catch-all policy.
- name: PROXY · type: select · proxies: [AUTO, DIRECT]
PROFILE
Subscription management fetches remote configuration and saves it as a local config file. When an update fails, check the subscription expiry and make sure the URL is complete, then test it over a direct connection. If the URL works in a browser but not in the client, check whether the client is trying to update through an expired proxy, whether the system clock is accurate, and whether the config directory is writable. After a successful update, confirm that the new config is enabled; downloading it without switching configs leaves the old nodes and rules active.
profiles → update → activate → reload
CLIENT / CORE
Clients on Windows, macOS, Android, iOS, and Linux have different interfaces, but the core workflow is the same: import a config, start the core, choose a mode, and enable the system proxy or VPN tunnel. When moving between platforms, do not copy button locations from another interface. First check the supported core and config fields, then grant the required network permissions on the new platform. Desktop issues usually involve system proxies and firewalls; mobile issues more often involve VPN permission, battery restrictions, and background execution.
client UI → mihomo core → system proxy / VPN
PLATFORM ROUTES
Confirm the operating system and processor architecture first, then open the matching platform guide. Desktop installers, mobile apps, and command-line cores serve different purposes; do not mix them just because their filenames look similar.
DESKTOP / 01
Best for desktop users who need tray controls, system-proxy switching, and graphical subscription management. Before downloading, open “Settings → System → About” and confirm that the device is x64. If installation is blocked, review the file source and security warning instead of disabling all system protection.
DESKTOP / 02
Open “About This Mac” to check whether the computer uses Apple silicon or an Intel processor, then choose the matching installer. The first launch may require approval in System Settings. If the system proxy is enabled but the browser still connects directly, check whether the client core is actually running.
Go to downloadsMOBILE / 03
Android clients use the system VPN interface to handle traffic. On the first connection, approve the VPN request and exclude the client from battery optimization. If it disconnects after the screen locks, the background process was usually reclaimed by the system; changing the subscription or rules should not be the first step.
Go to downloadsMOBILE / 04
On the first iOS connection, the client asks to add a VPN configuration, which is required to create the system network tunnel. If no nodes appear after importing a subscription, first check compatibility with the current client, then verify cellular-data permission and VPN status.
Go to downloadsDESKTOP / SERVER / 05
On desktop Linux, choose a graphical client; servers, routers, and containers usually run the Mihomo core directly. Before installing, confirm the distribution, CPU architecture, and package format. After the service starts, read the logs and check listening ports before configuring system services and startup, so a stopped process is not mistaken for a routing-rule problem.
FIRST CONNECTION
Initial setup should cover only the main path: configuration source, exit policy, and system traffic capture. Adjust advanced DNS, TUN, and rule overrides only after the basic connection works.
Open the client’s config or subscription page, paste the complete subscription URL, and run an update. Once the config name, proxy groups, and node list appear, set that config as active. If the update fails, check that the subscription has not expired, then test the URL with the system proxy disabled. Do not import the same URL repeatedly and create duplicate configs; it becomes difficult to tell which one is in use.
RULE CORE
PROFILE → IMPORT → ACTIVATE
A new config usually includes a rule mode and several proxy groups. Keep the rule mode initially and choose an available exit in the main group; if node status is unclear, switch between nodes and run brief connection tests. Global mode is useful for temporarily checking whether rules are the problem, but it should not be treated as a long-term troubleshooting conclusion. If global mode works while rule mode does not, inspect the connection log to see which rule matched the request.
MODE: RULE · GROUP: PROXY
Enable the system proxy on desktop, and approve VPN access on mobile. Use TUN mode only when you need to capture apps that ignore the system proxy. After connecting, visit one direct-access site and one site that requires a proxy, then check both request types in the client’s connection log. If only one app still fails, check whether it uses its own proxy or DNS before reinstalling the client.
SYSTEM PROXY / VPN → CONNECTIONS
OPEN SOURCE CONTEXT
Clash is not the name of a single installer. In practice, it consists of a graphical client, proxy core, subscription config, and system network interface. Knowing what each layer does prevents repeated attempts in the wrong place.
git clone https://github.com/MetaCubeX/mihomo.git
Early Clash provided core capabilities such as rule matching, proxy groups, proxy protocols, and a control interface. As the original project’s status changed, the community produced maintained core forks and a range of graphical clients. Today, “Clash” often refers to the wider configuration and client ecosystem rather than one specific program. When choosing software, check the client’s maintenance status, the core it uses, and the target platform—not just whether its name contains Clash.
Clients reorganize controls for subscriptions, proxy groups, logs, and system proxies, but the underlying workflow still revolves around YAML configuration, rule matching, and control interfaces. This lets desktop, mobile, and server environments use different shells, but it also means a click-by-click guide for one interface cannot be applied to every client. When moving across platforms, understand the fields and traffic path first, then find their counterparts in the new interface.
Mihomo is a commonly used, actively maintained core in the current Clash ecosystem. The graphical client downloads configs, displays policies, calls the control interface, and manages system permissions; the core actually establishes connections, applies rules, handles DNS, and forwards traffic. A client opening successfully does not mean the core started correctly, and a visible node list does not prove that the proxy path works. When troubleshooting, core logs usually pinpoint the issue more closely than generic messages in the interface.
Client updates address interface features and platform compatibility; core updates affect protocols, rules, and network handling; subscription updates replace nodes and provider-supplied policy content. These are separate update channels. When troubleshooting a failure after an update, record which layer changed and keep the last working config for comparison. If config fields become incompatible, read the client’s notes first, then migrate local overrides one by one.
FAULT ORDER
First verify the subscription: check its expiry, update result, and currently active config. Second verify the core: confirm it started, check for port conflicts, and look for config parsing errors in the logs. Third verify the policy: use the connection log to identify the matched rule and proxy group. Fourth verify system traffic capture: check the system proxy on desktop, VPN authorization on mobile, and the virtual interface and permissions for TUN users. Only then investigate DNS, distinguishing resolution failures, unexpected answers, and failures during connection.
Run the same test after each step and record the result. If the direct network itself is unavailable, restore basic connectivity first. If only a few nodes time out, try different nodes. If every node fails but the subscription still updates, check the system clock, protocol parameters, and network restrictions. If a browser works but a specific app does not, check whether that app bypasses the system proxy. This order turns one vague symptom into a series of verifiable questions.
QUICK ANSWERS
Check the subscription expiry and make sure the URL is complete, then disable the current system proxy and test the URL over a direct connection. If it works in a browser but still fails in the client, check the system clock, write permission for the config directory, and whether the client is trying to update through an expired proxy. See the glossary to review related fields.
Some apps do not read the system proxy, or use their own network stack and DNS. First check the connection log to see whether the client received requests from the app. If there are no records at all, the issue is in the system-capture layer, and TUN mode may be appropriate. If requests appear but use the wrong policy, check the rules and process matching.
Timeouts on individual nodes usually point to node status or a specific route. Simultaneous timeouts across all nodes are more likely related to an expired subscription, local network, system clock, a core that never started, or protocol parameters. Confirm that ordinary webpages work over a direct connection, then inspect the core logs instead of changing DNS and rules immediately.
This usually means the basic proxy path is already established. Next, inspect the rule and proxy group matched by the target domain in rule mode. Check whether a broad rule captures the request too early, whether every referenced proxy group exists, and whether the selected exit in that group is available.
FIELD NOTES
Each article focuses on a specific symptom, starting with diagnostic clues and then a practical sequence of checks. Go straight to the relevant scenario for node timeouts, first-time installation, or mobile subscription imports.
First distinguish between all nodes timing out and only individual nodes timing out, then check the subscription, direct connectivity, system clock, core status, and protocol parameters in order. Each step has a clear stopping point, so you avoid changing several settings at once.
Read the full article →Covers the complete order for obtaining the client, approving the first VPN connection, and importing a subscription, with separate paths for subscription URLs and local config files. If no nodes appear after import, continue troubleshooting compatibility and network permissions.
Read the full article →Covers the shared setup path across five platforms, from choosing an installer and importing a subscription to enabling the system proxy. Installation blocks, failed subscription imports, and inactive proxies are handled at their respective layers.
Read the full article →