Understand clients, cores, and configuration sources separately. When something goes wrong, identify the component responsible before choosing the right documentation and troubleshooting steps.
CLIENT / CORE
How Clash, mihomo, and clients fit together
The Clash ecosystem is not a single app with unified updates. The original Clash core, its later forks, and different graphical clients each have their own releases and maintenance scope. mihomo is an actively developed core project in this ecosystem. Popular desktop clients add configuration management, proxy switching, and system integration interfaces on top of it. Similar-looking interfaces do not guarantee identical core capabilities or defaults. When migrating a configuration, check the documentation for the client and core actually in use.
Toggles in a graphical client can change the core configuration or operating system state. For example, the system proxy toggle changes the system proxy settings, while TUN involves a virtual network interface and routing. Some clients generate the final configuration at startup, so editing a YAML file on disk may not change what the interface is using. To confirm a change took effect, check the selected configuration, override results, and reload logs—not just whether the file saved successfully.
Open-source code can help you understand implementation details and how configuration evolves, but browsing a source repository is not required to install the app. For a first setup, choose a client for your system on the downloads page. Check the mihomo project documentation, release notes, or source code when you need to verify core behavior. This site offers Chinese-language documentation and field explanations; it does not treat different clients as one unified product or make compatibility guarantees on behalf of project maintainers.
HISTORY / MIGRATION
Deciding whether to migrate from an unmaintained client
Clash for Windows may still run in an existing setup after development stops, but that does not mean it will keep supporting new operating systems, protocols, or configuration fields. When choosing a replacement, check its maintenance status, core, device architecture, and support for features your configuration needs. Replacing an app just because its name looks similar can leave you with differences in system services, configuration directories, and startup items—or duplicate proxy processes still running.
Before migrating, export or back up your current configuration and note the local listening ports, active proxy groups, and custom rules. On the new client’s first launch, import the configuration without enabling every traffic-capture feature right away. After checking the syntax, choose a specific test destination and confirm that the connection appears in the client with the expected rule and exit. Once that path works, move on to overrides, LAN access, or TUN settings.
If a port is already in use, first check whether the old client or a background service is still listening. Then decide whether to stop the process or change the port. Do not delete the old configuration directory to resolve a conflict. If you change mixed-port, update any apps where you entered a proxy address manually. Otherwise, the core may start successfully while those apps continue trying the old port. For common differences, see the FAQ. For step-by-step instructions, see the Clash setup guide.
SOURCE / PRIVACY
Configuration sources and sharing boundaries
Open-source code lets you inspect how software works; it does not mean every subscription, conversion service, or network exit is trustworthy. Clients, configuration providers, and exit services have different roles. Downloading a client does not give you access to a remote service. Before adding a subscription, check its source and intended use, and understand which proxies, rules, and DNS upstreams the configuration contains. An unfamiliar full configuration can change where your traffic goes, so check its key fields and proxy groups after importing it.
Subscription URLs may contain access credentials, and configuration files may include account details, passwords, or private server information. When asking for help, share the client name, operating system, error text, and a minimal redacted snippet instead of uploading a full configuration. Check screenshots for sensitive details in address bars, QR codes, and logs too. To explain a routing issue, you usually only need to share the rule order, relevant proxy group names, and which rule matched the target connection.
Keep test conditions stable while troubleshooting. Start with one destination, one traffic-capture method, and one exit, then check DNS, rules, and connection results. Changing the subscription, node, mode, and DNS setup all at once makes it hard to identify the cause, even if access starts working again. Keep a working baseline and change one thing at a time, recording each result. This is easier to maintain than copying a large set of unverified settings. Follow the network-use policies that apply to your workplace or managed device.
UPDATE / VERIFICATION
Update the app and configuration separately
Client updates, core updates, subscription updates, and rule resource updates are separate processes. Updating the app does not necessarily refresh a remote subscription, and updating a subscription does not mean the core supports newly added fields. If a setting cannot be parsed, first check which core it belongs to and where it applies, then confirm which core the client is running. Do not assume a configuration parsing error means a node is unreachable: they happen at different stages and require different troubleshooting evidence.
For GeoIP or rule resources, check which data format and file location the configuration uses, and where it gets updates. Changing a filename does not guarantee the core will read the file, and a file being present does not mean the active rules are using it. After making changes, reload the configuration, check logs for resource loading errors, and see which rule matches the target connection. For remote rule providers, distinguish download failures from format errors and rules in the wrong order.
A webpage loading successfully is only the first test. Also check LAN services that should connect directly, apps that ignore system proxy settings, and connectivity after the device wakes from sleep. Node speed tests only show how a specific test request performs; they cannot replace testing the actual services you use. If something goes wrong, note the conditions, error, and most recent changes, then narrow it down by checking ports, DNS, rules, and exits in that order. Field explanations and YAML examples are in the configuration reference.