Open-source ecosystem · Cross-platform setup manual
A focused guide to clients for every platform, subscription imports, and mihomo configuration. Start by choosing an installer, then configure proxy modes, rules, DNS, system proxies, and TUN step by step.
CONFIGURATION BROWSER
Clash focuses on loading configuration, identifying traffic, and applying proxy policies. The sections below follow real configuration structures, making it easier to decide whether to start with subscriptions, rules, or system-level traffic handling.
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
MATCH,PROXY
Rule mode checks connection targets from top to bottom. Domain-suffix rules work well for known sites, GEOIP can classify destinations by address, and MATCH belongs at the end to catch connections that matched nothing earlier. In practice, put narrow, clearly defined rules first, followed by general rules and the final policy. This reduces unintended matches and makes it easier to trace a decision from the rule name in the logs back to the configuration. After editing, validate the syntax and reload the configuration so stale rules do not continue running in the core.
proxy-providers:
remote-set:
type: http
path: ./providers/remote.yaml
interval: 3600
Subscriptions provide proxy nodes; local configuration controls groups, rules, and DNS behavior. Clients that support providers can place remote sources under proxy-providers and define cache paths and update intervals. Graphical clients usually present these actions as import links and update buttons. If an update fails, first check whether the subscription URL is reachable, then inspect the local cache directory and system time instead of deleting the entire configuration. Separating sources from custom rules also prevents remote updates from overwriting personal routing settings.
System proxies work well with browsers and desktop apps that follow the operating system proxy settings. They are straightforward to configure and easy to disable. TUN mode uses a virtual network interface to handle more traffic, which helps with apps that ignore system proxies but requires the right permissions, drivers, and routing. Enable LAN access only when other devices on the same network need to use this device's port, and check the listen address and firewall scope. When connectivity fails, turn off TUN first and test the system proxy separately to narrow down the cause.
Windows → mihomo
macOS → mihomo
Android → mihomo
iOS → mihomo compatible
Linux → mihomo
Client interfaces, menu locations, and system integration differ, but mihomo-based clients generally share core configuration concepts such as rules, proxy groups, DNS, and ports. Desktop clients are better suited to editing complete YAML files and reviewing logs, while mobile clients emphasize subscription switching and background connectivity. Before moving between platforms, confirm the client's core family and check whether the configuration contains extension fields unsupported on the target platform. Keeping one clearly structured base configuration reduces repeated adjustments across devices.
PLATFORM DOWNLOADS
The installer must match both the operating system and processor architecture. The download page lists available clients, use cases, and system requirements by platform; start with the relevant platform group before comparing individual clients.
Best for desktop users who need tray controls, system proxies, TUN mode, and graphical rule management. On the download page, compare Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, and archived clients. Confirm the system architecture before installation, and handle the permission prompt when enabling TUN for the first time.
Go to downloadsFor Apple Silicon and Intel Macs. Each processor family requires a different installer, so do not rely on the macOS label in the filename alone. Desktop clients provide menu bar controls, system proxy settings, and rule switching; after enabling a network extension or TUN, confirm in System Settings that the permission has taken effect.
Go to downloadsFor phones, tablets, and some Android devices. After importing a subscription, grant VPN permission and adjust background behavior to match the system's restrictions. If connectivity drops after switching networks, check battery optimization, persistent notifications, and DNS settings before deciding whether to replace the configuration.
Go to downloadsInstall the appropriate client on iPhone and iPad through the App Store. When establishing a connection for the first time, confirm the system VPN configuration, then import a subscription, choose a policy group, and review connection logs in the client. DNS behavior may differ between cellular data and Wi-Fi, so test them separately when troubleshooting.
Go to downloadsFor desktop Linux, servers, and devices that need to run the core directly. Graphical clients simplify subscription and policy management, while the mihomo core can be managed by systemd, containers, or other tools. Before deployment, define the configuration directory, listen address, log location, and service-account permissions.
Go to downloadsQUICK START
You do not need to change every option during the first setup. First make sure the client loads its configuration and establishes a connection, then handle rules, DNS, TUN, and LAN sharing. This keeps troubleshooting clearer.
Open the download page, choose a client matching your platform and processor architecture, and launch it after installation. Check that the configuration directory, core status, and log access are available. Windows and macOS may request permission when system integration is enabled for the first time; Android and iOS display a VPN configuration prompt. At this stage, verify only that the program starts normally—do not enable TUN, LAN sharing, or advanced DNS options yet. If the client exits immediately, check configuration syntax, port conflicts, and system permissions first.
Paste the subscription URL provided by your service provider into the subscription or configuration page, then download or update it. After a successful import, proxy groups, nodes, and rules should be visible. Choose an available policy first, then check the client logs for configuration-loading errors. The provider maintains the subscription URL and node content; the Clash client reads and executes the configuration, so assess the two separately. If an update fails, check the URL, network connectivity, system time, and local cache in that order. Do not repeatedly overwrite a base configuration that still works.
Set the proxy mode to Rule, enable the system proxy, and test both a direct destination and one that requires a proxy policy. Rule mode selects a policy based on the connection target; it does not mean every connection follows the same path. If the browser works but a particular app does not, first check whether the app reads the system proxy. If it does not, consider TUN mode. Only after verification should you adjust DNS, Fake-IP, health checks, or startup behavior. Change one category of settings at a time and keep the previous configuration so you can roll back accurately.
First confirm that the client core is running, then check that the system proxy port matches the configured mixed-port. A browser proxy setting or extension may override the operating system settings. See Troubleshooting for complete steps.
For everyday use, start with Rule mode so different destinations follow direct or proxy policies as defined by the rules. Global mode is useful for briefly testing the proxy path, while Direct mode helps determine whether the proxy settings cause the problem. Test the same destination again after switching modes.
Consider TUN when a target program ignores the system proxy or you need to handle a broader range of traffic. Record the existing DNS and routing state before enabling it. If the network goes down or you encounter resolution or LAN access problems, turn off TUN and compare the result using the system proxy.
That depends on how the client organizes its configuration. A complete configuration generated directly from a subscription may be replaced during an update; proxy-providers, overrides, or separate rule files can keep remote sources and local changes apart. Export a working configuration before making changes.
OPEN SOURCE CONTEXT
The Clash ecosystem combines proxy cores, configuration formats, and graphical clients for different platforms. The core parses configuration, establishes connections, matches rules, and produces logs; the graphical client handles installation, updates, subscriptions, system proxies, permission requests, and visual controls. Understanding this division makes troubleshooting more direct: check core logs for configuration parsing errors, the client interface for tray or menu issues, and operating system integration when system traffic is not entering the proxy.
Different clients may use similar cores, but their interface capabilities are not identical. Some focus on desktop rule editing, others are designed for cross-platform use, and some remain archived for legacy environments. Do not compare interfaces alone: also check maintenance status, target platform, processor architecture, configuration compatibility, and support for TUN, scripts, and overrides.
mihomo continues the Clash Meta feature path, with ongoing maintenance for rule types, proxy protocols, enhanced DNS modes, TUN, and providers. Many modern Clash graphical clients use mihomo as their core, allowing the same YAML configuration to be reused across platforms. However, a client may add its own override files, database entries, or interface fields. Before migrating, export the original configuration and verify the target client's supported features.
Protocols and cores are not the same thing. A protocol defines how the client establishes a connection with the server; the core implements that protocol and applies local routing logic. When choosing a protocol, consider server support, network conditions, connection setup, and device resources. When choosing a core or client, focus on configuration syntax, platform integration, and maintenance status. For a systematic comparison of SS, VMess, Trojan, VLESS, Hysteria2, TUIC, and core families, see the protocol manual.
A reliable configuration workflow keeps three layers: a recoverable base configuration, subscription sources that can be updated independently, and traceable local rule changes. Before updating a client, read the release notes and back up the configuration directory. When updating a subscription, check whether proxy group names changed. When editing rules, use clear names and confirm matches in the logs. Changing the core, subscription, DNS, and TUN at the same time makes the source of an error difficult to identify.
Logs are the main evidence when diagnosing connection problems. During configuration loading, check YAML syntax, field types, and file paths. During runtime, check DNS resolution, rule matches, connection timeouts, and listening ports. During system integration, check proxy settings, virtual interfaces, permissions, and the firewall. Recording symptoms by layer is more effective than repeatedly switching nodes. Technical notes will continue to cover frequent errors, mobile background behavior, and LAN sharing scenarios.
TECHNICAL NOTES
Actionable steps for LAN sharing, mobile background operation, and startup failures. Each article explains the symptoms and scope first, then provides an inspection order, making it useful after basic configuration is complete.
Explains the relationship between mixed-port, allow-lan, listen addresses, and firewalls, then shows how other devices on the same Wi-Fi network can use this device's proxy. After setup, restrict access to trusted networks so the listening port is not exposed on unnecessary interfaces.
Read the full article →Analyzes the main sources of battery use during background connections on Android and iOS, including health-check frequency, DNS queries, TUN, persistent notifications, and system battery optimization. The goal is to reduce unnecessary wakeups and repeated checks while keeping the connection available.
Read the full article →When the client does nothing after a double-click or exits immediately after launch, check four leads in order: configuration syntax, listening ports, TUN permissions, and core files. The article distinguishes the interface process from the core process instead of attributing every startup problem to the subscription.
Read the full article →