Choose a client for your operating system, then check each setting—from subscription import to rule updates—against your configuration and connection needs.
Trace settings from configuration source to connection destination.
Paste the subscription URL into the client's profile page. After importing, select it as the active profile. Profile updates fetch the YAML again, while proxy providers and rule providers can refresh on their own schedules; these are three distinct update mechanisms. Local files are useful for offline backups but usually don't track remote changes automatically. Direct edits to a downloaded profile may be overwritten on the next refresh. For persistent changes, use the client's override or merge features. If an update fails, first check that the URL is still valid, then review the request logs and the network path used to fetch the subscription.
See the subscription import steps →# Proxy provider snippet for the configuration file
# interval is measured in seconds
proxy-providers:
remote:
type: http
url: "https://example.com/proxies.yaml"
path: ./providers/remote.yaml
interval: 86400Rule mode checks the configured list from top to bottom and applies the policy for the first match. Put specific domain rules before broader ones, and keep the fallback rule last. A rule can point to Direct, Reject, or a defined policy group—not arbitrary text. Unlike Global mode, rule-based routing lets different app requests take different paths, but the result depends on domain identification, DNS resolution, and available rule resources. After making changes, start a new connection and check the matched rule on the Connections page; don't rely only on whether a webpage loads. Also verify the final merged order of subscription rules and local overrides.
See the rules and overrides guide →mode: rule
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- DOMAIN-SUFFIX,example.org,REJECT
- MATCH,DIRECTRule mode routes traffic according to the rule list. Global mode sends connections that have entered the core through the global policy, while Direct mode connects them straight to their destinations. These modes control what happens after a connection reaches the core; they don't determine whether an app uses the client in the first place. The system proxy affects apps that honor system proxy settings, while TUN uses a virtual network adapter to capture more traffic. If a webpage won't load, first check whether the app's request appears on the Connections page, then review the mode and policy group. Repeatedly switching to Global mode won't fix requests that never reached the core. Once testing is done, restore your usual Rule mode instead of leaving temporary troubleshooting settings in place.
Understand proxy modes and traffic capture →# Choose one of the three modes
mode: rule
# System proxy and TUN are separate client settings
# Global mode corresponds to mode: global
# Direct mode corresponds to mode: directSome games, command-line tools, and background services don't use the system proxy. TUN can route their requests through the core using a virtual network adapter and routing configuration. Before enabling it, make sure the client has the required permissions and that no other VPN is changing the default route. Automatic routing and DNS capture are related, but switching on TUN alone doesn't guarantee that every protocol will work. Compared with setting a proxy port manually in each app, TUN covers more traffic and is more likely to be affected by network adapters, LAN routes, and security software. First verify that regular web browsing works, then enable TUN and test one thing at a time. If a conflict occurs, turn off traffic capture to restore network access, then use the logs to find the cause.
Read the TUN setup and troubleshooting steps →# mihomo configuration snippet; requires the relevant system permissions
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53DNS maps domain names to addresses, and the resolution path can affect whether the core identifies domains correctly and matches the right rules. Fake-IP maps domains to reserved addresses; it doesn't provide a new network exit. It needs to be used with an appropriate traffic capture method. Compared with resolving to real addresses, Fake-IP helps preserve domain associations, though some LAN services and apps may need to be excluded. If DNS is behaving unexpectedly, first check whether DNS requests reach the core and whether the upstream server is available. Then check app caches and the system's encrypted DNS settings. Avoid changing the upstream server, switching modes, and editing the filter list all at once, or it will be hard to tell which change made a difference.
See the DNS settings guide →dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
- "localhost"Filter by operating system first, then check the processor architecture and package format. The client provides the interface, system integration, and configuration management; the core handles protocols and rule execution. Similar-looking interfaces don't guarantee support for the same configuration fields. Before migrating, keep a copy of your subscription source and override files, and don't overwrite your working configuration.
Manage subscriptions, the system proxy, and startup settings on your desktop. Compare the interfaces and core support of clients such as Clash Plus and Clash Verge Rev, then install the one that fits your operating system.
On first launch, import a profile and verify browser traffic before setting up service permissions or TUN. If you keep your old client installed, don't let both apps change the system proxy or listen on the same port.
Go to downloadsBefore downloading, check whether your Mac has Apple silicon or an Intel processor. System proxy support, menu bar controls, and background services vary by client, so choose a package that matches your device's architecture.
After switching clients, check the system's network proxy settings instead of assuming the old settings were cleared. If you need to route terminal or other app traffic, separately verify that app's proxy environment or TUN status.
Go to downloadsChoose a package for your processor architecture, and check how the client captures traffic through the VPN. When you connect for the first time, grant the permissions requested by the system, then confirm that the profile is selected—not just imported.
Background updates can be affected by battery optimization, background network permissions, and process state. If subscriptions aren't refreshing on schedule, try a manual update in the foreground first, then check whether the system restricts the client's background activity.
Go to downloadsFind the Clash Plus App Store listing and official information. Mobile network extensions are managed by the client; check the app's own instructions for subscription imports, update options, and configuration compatibility.
After importing, select the profile and allow the VPN connection when prompted by the system. If access stops working after a network change, first check the extension's connection status and whether configuration resources have updated, then adjust routing settings.
Go to downloadsFor desktop Linux, compare Clash Verge Rev and FlClash, and choose a package format such as DEB or RPM for your distribution. Headless servers and routers typically run the core directly, with services and permissions configured separately.
A successful installation only means the program can run. Check dependencies, listening ports, and whether the system proxy is configured. For a service-based setup, verify the working directory, configuration path, and write permissions for resource files.
Go to downloadsPlatform icons: Windows, Apple, and Android use Simple Icons vectors; the Linux Tux icon uses a Font Awesome vector, CC BY 4.0.
Installing the client, importing a configuration, and capturing traffic are three separate steps. Follow the sequence below to distinguish subscription retrieval issues from app connection issues, without changing every advanced setting at the outset.
Open the Profiles or Subscriptions page and paste the URL from your configuration provider. If you only have a local YAML file, import it from disk instead. Once the client finishes parsing it, select the profile and check for syntax errors or unsupported fields. A successful import doesn't mean the profile is active; confirm it in the active profile indicator and logs.
Keep the existing policy group structure in your configuration and start with Rule mode. On desktop, begin with the system proxy; on mobile, allow the VPN connection when prompted. For apps that ignore the system proxy, consider TUN or the app's own proxy settings. Change one setting at a time and note its original state so you can revert it if something goes wrong.
Reopen the target webpage or app, confirm its request reaches the core on the Connections page, and check the matched rule and policy. Then manually update the subscription once to verify that it can be fetched, before enabling automatic updates if the client supports them. Check units carefully: the interface may use minutes while configuration fields use seconds. Avoid setting resource updates to run too frequently.
The original Clash established the YAML configuration and rule syntax commonly used across this ecosystem. Clash Meta extended it with support for more protocols, rules, and networking features, and continued development under the name mihomo. Older names may still appear in guides, but check the documentation for the core you're actually running to confirm whether a field is supported—not just the client name.
Desktop clients typically bundle a core with platform features: the core handles requests, while the client manages subscriptions, the system proxy, logs, and permissions. The same configuration may import differently across clients, and some clients generate or merge a runtime configuration. When troubleshooting, note the client name, core type, and fields that are actually in effect.
Clash Resource Hub organizes download links, setup steps, and terminology; it isn't affiliated with the development teams behind individual clients. Check upstream documentation for feature changes and platform restrictions. The download directory helps you choose an operating system and package format, while the guides explain configuration fields and how common operations fit together. Clients across the ecosystem aren't all the same software.
A client update may change the interface, system integration, or bundled core. A core update affects protocol handling and configuration compatibility. A subscription update fetches configuration or resource content again. Updating the program doesn't extend a subscription's validity, and refreshing a subscription won't give an old core new protocol support. When troubleshooting, identify which layer is failing before choosing what to update.
Before updating, back up local overrides and settings you've verified work, then review the release notes for configuration changes. After the update, check startup logs, then verify DNS, rule matches, and app connections. If something goes wrong, compare against the original configuration instead of piling on temporary changes. Keep track of where rule resources come from, too, so the final configuration remains understandable.
To learn more about how the original core, Meta, and mihomo relate, read Core evolution and feature comparison. If you're preparing to deploy on a router or server, also check the networking and permission requirements for that platform.
Browse source code, release notes, and issue discussions at MetaCubeX/mihomo. Cloning the repository for review or development doesn't install a client. If you just need a graphical interface, choose an installer for your platform.
git clone https://github.com/MetaCubeX/mihomo.gitAfter the basics are in place, choose a guide for the specific issue. For slow speeds, start with comparison tests; for router deployment, identify where traffic enters; for beginner issues, check the system proxy, mode, and ports first. Each problem calls for different evidence—repeatedly trying the same settings won't help.
Break down slow speeds across three areas—nodes, network routes, and local settings—with a practical order for speed comparisons, route changes, rule and DNS checks, and reviewing system proxy and TUN settings.
Read article →An overview of ways to run the mihomo core on a main router or side router, covering architecture choices, transparent proxying versus TUN, DNS capture, and gateway settings for LAN devices.
Read article →Answers to ten common beginner questions, including how to choose a client, how the system proxy differs from TUN, what Rule mode does, how to resolve port conflicts, and what to check when webpages won't load—with practical steps for each.
Read article →Subscription update failed: First check whether the link returns a configuration, then review the fetch request logs. Follow the subscription update troubleshooting guide to distinguish access, parsing, and resource update errors.
DNS and Fake-IP: First find out where DNS requests originate, then decide whether to adjust traffic capture or the filter list. If the concepts aren't clear, start with the Fake-IP definition before changing settings in the full manual.